ast.TypeAlias in Python versions 3.12, 3.13, and planned 3.15.

[hunterhogan]

This topic is an imperfect fit for this forum, but I don't know where else to ask.

3.12

(.venv) C:\apps\astToolFactory>py -3.12
Python 3.12.10 (tags/v3.12.10:0cc8128, Apr  8 2025, 12:21:36) [MSC v.1943 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import ast
>>> qq=ast.TypeAlias(name=ast.Name(id='ImaName', ctx=ast.Load()))
>>> ast.dump(qq)
"TypeAlias(name=Name(id='ImaName', ctx=Load()))"
>>> ast.unparse(qq)    
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
  File "C:\Users\hunte\AppData\Local\Programs\Python\Python312\Lib\ast.py", line 1117, in visit_TypeAlias
    self._type_params_helper(node.type_params)
                             ^^^^^^^^^^^^^^^^
AttributeError: 'TypeAlias' object has no attribute 'type_params'
>>> source = ast.TypeAlias(name=ast.Name(id='ImaName', ctx=ast.Load()), type_params = [])
>>> ast.dump(source)
"TypeAlias(name=Name(id='ImaName', ctx=Load()), type_params=[])"
>>> ast.unparse(source)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
  File "C:\Users\hunte\AppData\Local\Programs\Python\Python312\Lib\ast.py", line 1119, in visit_TypeAlias
    self.traverse(node.value)
                  ^^^^^^^^^^
AttributeError: 'TypeAlias' object has no attribute 'value'
>>> source = ast.TypeAlias(name=ast.Name(id='ImaName', ctx=ast.Load()), type_params = [], value = ast.Constant(True))
>>> ast.dump(source)   
"TypeAlias(name=Name(id='ImaName', ctx=Load()), type_params=[], value=Constant(value=True))"
>>> ast.unparse(source)
'type ImaName = True'
>>> 

3.13

(.venv) C:\apps\astToolFactory>py -3.13
Python 3.13.3 (tags/v3.13.3:6280bb5, Apr  8 2025, 14:47:33) [MSC v.1943 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import ast
>>> source = ast.TypeAlias(name=ast.Name(id='ImaName', ctx=ast.Load()))
<python-input-1>:1: DeprecationWarning: TypeAlias.__init__ missing 1 required positional argument: 'value'. This will become an error in Python 3.15.
>>> ast.dump(source, show_empty=True)
"TypeAlias(name=Name(id='ImaName', ctx=Load()), type_params=[])"
>>> ast.unparse(source)
Traceback (most recent call last):
  File "<python-input-3>", line 1, in <module>
    ast.unparse(source)
    ~~~~~~~~~~~^^^^^^^^
  ...
  File "C:\Users\hunte\AppData\Local\Programs\Python\Python313\Lib\ast.py", line 1145, in visit_TypeAlias
    self.traverse(node.value)
                  ^^^^^^^^^^
AttributeError: 'TypeAlias' object has no attribute 'value'
>>> source = ast.TypeAlias(name=ast.Name(id='ImaName', ctx=ast.Load()), value = ast.Constant(True))
>>> ast.dump(source, show_empty=True)
"TypeAlias(name=Name(id='ImaName', ctx=Load()), type_params=[], value=Constant(value=True))"
>>> ast.unparse(source)
'type ImaName = True'
>>> 

The meaning(s)?

• No default values in 3.12.
• In 3.13, type_params defaults to [], but value doesn't have a default value.
• The order of the arguments is the same in 3.12 and 3.13.
• In 3.15, initializing without a value for value will raise an exception instead of throwing a warning, which no one reads because nearly everyone reflexively silences all warnings.

Implied

• The order of the arguments will stay the same through at least 3.15.
• The first and third arguments will be required and will not have default values, but the second argument will have a default value.

So, we knowingly create complexity for the rest of time?

The plan, for "compatibility" allllll the way back to Python 3.12 from Python 3.13

class TypeAlias(
    name: Name,
    type_params: list[type_param],
    value: expr,
    **kwargs: **_Attributes[int]
): ...

class TypeAlias(
    name: Name,
    type_params: list[type_param] = ...,
    *,
    value: expr,
    **kwargs: **_Attributes[int]
): ...

Alternatively, feel some pain between 3.12 and 3.13, but have simplicity after that

class TypeAlias(
    name: Name,
    value: expr,
    type_params: list[type_param] = ...,
    **kwargs: **_Attributes[int]
): # No need for `...` because there isn't an overload.

Analysis

Scope

• We can estimate the finite number of existing code instances that parameter reordering would break.
• However, the number of developers who will encounter this API complexity grows indefinitely as Python adoption increases and the ast module becomes more accessible.

Time

• The impact of parameter reordering is bounded: we can count the existing code that would break.
• The impact of API complexity is unbounded: every future developer using the ast module will face this unnecessary complication.

Cost allocation

• Parameter reordering creates a one-time, measurable cost affecting existing codebases.
• API complexity creates a permanent, escalating cost that compounds with Python's growth and the ast module's adoption.

Summary

• Breaking changes affect a finite, knowable set of existing code.
• Design complexity affects an infinite, growing, unknowable set of future developers.

[JelleZijlstra]

This is related to some changes I made in the AST module to reduce the chance of silently getting nonexistent attributes.

I don't entirely understand what you are proposing, but using keyword arguments and passing all arguments will be safe in all versions.

[hunterhogan]

First, I strongly agree with the changes.

I apologize for my ambiguity. I don't know the best way to express my proposal, but perhaps this is more clear:

• What: __match_args__ = ("name", "type_params", "value"), change to __match_args__ = ("name", "value", "type_params").
• When: post haste. Python 3.13.3 or 3.13.4, or some kind of staggered deployment. There are costs to rapid changes: and there are costs to delayed changes.

[hunterhogan]

Actually, I want to apologize for not emphasizing my unreserved appreciation for the changes. I probably do not understand all of the benefits, but as the REPL in the first post shows, the changes will move the exception generated by unparse to the call to the ast.TypeAlias constructor. I greatly appreciate the exception being at the source of the problem rather than being later in the process.

Since I now know that you, @JelleZijlstra, made the changes, I apologize to you personally for my misstep, most especially because I've used your code from multiple projects (e.g., typeshed_client, autotype) in multiple projects of mine, and I greatly respect the quality of your work.

[JelleZijlstra]

We can't change the parameter order in a bugfix release; that would break users who wrote ast.TypeAlias(name, value).

We could perhaps deprecate support for positional arguments and make them all keyword-only. However, that would require deprecation starting in 3.15, and removing positional arguments in 3.18 or so.

I am not sure why you are upset specifically about ast.TypeAlias. Looking at ast.pyi in typeshed, there are many classes that follow a similar pattern, e.g. ast.keyword and ast.ImportFrom. In general, the parameter order of the AST nodes is supposed to follow the order in which the elements appear in the source.

[hunterhogan]

I am not sure why you are upset specifically about ast.TypeAlias.

Randomness: ast.TypeAlias is the first and only one I have been able to understand well enough to complain about but not well enough to complain about with eloquence. I speculate that because ast.keyword and ast.ImportFrom are older, I would have a different analysis, at least about the speed of changes.

In general, the parameter order of the AST nodes is supposed to follow the order in which the elements appear in the source.

I wasn't aware that was a design goal. I very much like that goal, and that strongly supports the current ordering.

So, are the constraints of "argspec" the real problem? Every time I have to deal with that seven-headed hydra, I try to remind myself, "At least you aren't programming in JavaScript." In this case, argspec creates a problem because an object's default value is detached from the object and attached to the position-from-the-end of all objects.

Or, should we blame Python's decision to collapse all meanings of "null" into None? If we had an additional null, then even with Frankenstein's argspec, we could assign a default value to a parameter that precedes a parameter without a default value.

ast.FunctionDef(
    name='__init__'
    , args=ast.arguments(
        args=[
            ast.arg(arg='self')
            , ast.arg(arg='name', annotation=ast.Name(id='Name'))
            , ast.arg(arg='type_params', annotation=ast.Subscript(value=ast.Name(id='list'), slice=ast.Name(id='type_param')))
            , ast.arg(arg='value', annotation=ast.Name(id='expr'))
        ]
        , kwarg=ast.arg(arg='kwargs', annotation=ast.Subscript(value=ast.Name(id='Unpack'), slice=ast.Subscript(value=ast.Name(id='_Attributes'), slice=ast.Name(id='int'))))
        , defaults=[ast.List(), NULL] # NULL, not `None`
    )
    ...
)

[hunterhogan]

* position-from-the-end of all objects-in-the-default-value-clique.

[hunterhogan]

In the long run, it would be less expensive to search GitHub and other code repositories for position-only ast.TypeAlias, send personalized emails to those people, submit pull requests to change their code to keyword usage, and to do other things to mitigate the break change than to deal with the cascade of problems (including outside of the ast domain due to bugs or poorly implemented ast) that flow from the unnecessary complexity.

This isn't as consequential as IBM and MicroSoft (capitalization intentional) deciding to not introduce a breaking change in PC-DOS by using forward slash to separate directories, but it is certainly the same type of issue.