@@ -243,93 +243,24 @@ more specific type:
243
243
244
244
.. _alternative_union_syntax :
245
245
246
- Alternative union syntax
247
- ------------------------
246
+ X | Y syntax for Unions
247
+ -----------------------
248
248
249
- `PEP 604 <https://www.python.org/dev/peps/pep-0604/ >`_ introduced an alternative way
250
- for writing union types. Starting with **Python 3.10 ** it is possible to write
251
- ``Union[int, str] `` as ``int | str ``. Any of the following options is possible
249
+ :pep: `604 ` introduced an alternative way for spelling union types. In Python
250
+ 3.10 and later, you can write ``Union[int, str] `` as ``int | str ``. It is
251
+ possible to use this syntax in versions of Python where it isn't supported by
252
+ the runtime with some limitations, see :ref: `runtime_troubles `.
252
253
253
254
.. code-block :: python
254
255
255
256
from typing import List
256
257
257
- # Use as Union
258
258
t1: int | str # equivalent to Union[int, str]
259
259
260
- # Use as Optional
261
260
t2: int | None # equivalent to Optional[int]
262
261
263
- # Use in generics
264
- t3: List[int | str ] # equivalent to List[Union[int, str]]
265
-
266
- # Use in type aliases
267
- T4 = int | None
268
- x: T4
269
-
270
- # Quoted variable annotations
271
- t5: " int | str"
272
-
273
- # Quoted function annotations
274
- def f (t6 : " int | str" ) -> None : ...
275
-
276
- # Type comments
277
- t6 = 42 # type: int | str
278
-
279
- It is possible to use most of these even for earlier versions. However there are some
280
- limitations to be aware of.
281
-
282
- .. _alternative_union_syntax_stub_files :
283
-
284
- Stub files
285
- """"""""""
286
-
287
- All options are supported, regardless of the Python version the project uses.
288
-
289
- .. _alternative_union_syntax_37 :
290
-
291
- Python 3.7 - 3.9
292
- """"""""""""""""
293
-
294
- It is necessary to add ``from __future__ import annotations `` to delay the evaluation
295
- of type annotations. Not using it would result in a ``TypeError ``.
296
- This does not apply for **type comments **, **quoted function ** and **quoted variable ** annotations,
297
- as those also work for earlier versions, see :ref: `below <alternative_union_syntax_older_version >`.
298
-
299
- .. warning ::
300
-
301
- Type aliases are **NOT ** supported! Those result in a ``TypeError `` regardless
302
- if the evaluation of type annotations is delayed.
303
-
304
- Dynamic evaluation of annotations is **NOT ** possible (e.g. ``typing.get_type_hints `` and ``eval ``).
305
- See `note PEP 604 <https://www.python.org/dev/peps/pep-0604/#change-only-pep-484-type-hints-to-accept-the-syntax-type1-type2 >`_.
306
- Use ``typing.Union `` or **Python 3.10 ** instead if you need those!
307
-
308
- .. code-block :: python
309
-
310
- from __future__ import annotations
311
-
312
- t1: int | None
313
-
314
- # Type aliases
315
- T2 = int | None # TypeError!
316
-
317
- .. _alternative_union_syntax_older_version :
318
-
319
- Older versions
320
- """"""""""""""
321
-
322
- +------------------------------------------+-----------+-----------+-----------+
323
- | Python Version | 3.6 | 3.0 - 3.5 | 2.7 |
324
- +==========================================+===========+===========+===========+
325
- | Type comments | yes | yes | yes |
326
- +------------------------------------------+-----------+-----------+-----------+
327
- | Quoted function annotations | yes | yes | |
328
- +------------------------------------------+-----------+-----------+-----------+
329
- | Quoted variable annotations | yes | | |
330
- +------------------------------------------+-----------+-----------+-----------+
331
- | Everything else | | | |
332
- +------------------------------------------+-----------+-----------+-----------+
262
+ # Usable in type comments
263
+ t3 = 42 # type: int | str
333
264
334
265
.. _strict_optional :
335
266
@@ -565,82 +496,6 @@ valid for any type, but it's much more
565
496
useful for a programmer who is reading the code. This also makes
566
497
it easier to migrate to strict ``None `` checking in the future.
567
498
568
- Class name forward references
569
- *****************************
570
-
571
- Python does not allow references to a class object before the class is
572
- defined. Thus this code does not work as expected:
573
-
574
- .. code-block :: python
575
-
576
- def f (x : A) -> None : # Error: Name A not defined
577
- ...
578
-
579
- class A :
580
- ...
581
-
582
- In cases like these you can enter the type as a string literal — this
583
- is a *forward reference *:
584
-
585
- .. code-block :: python
586
-
587
- def f (x : ' A' ) -> None : # OK
588
- ...
589
-
590
- class A :
591
- ...
592
-
593
- Starting from Python 3.7 (:pep: `563 `), you can add the special import ``from __future__ import annotations ``,
594
- which makes the use of string literals in annotations unnecessary:
595
-
596
- .. code-block :: python
597
-
598
- from __future__ import annotations
599
-
600
- def f (x : A) -> None : # OK
601
- ...
602
-
603
- class A :
604
- ...
605
-
606
- .. note ::
607
-
608
- Even with the ``__future__ `` import, there are some scenarios that could still
609
- require string literals, typically involving use of forward references or generics in:
610
-
611
- * :ref: `type aliases <type-aliases >`;
612
- * :ref: `casts <casts >`;
613
- * type definitions (see :py:class: `~typing.TypeVar `, :py:func: `~typing.NewType `, :py:class: `~typing.NamedTuple `);
614
- * base classes.
615
-
616
- .. code-block :: python
617
-
618
- # base class example
619
- class A (Tuple[' B' , ' C' ]): ... # OK
620
- class B : ...
621
- class C : ...
622
-
623
- Of course, instead of using a string literal type or special import, you could move the
624
- function definition after the class definition. This is not always
625
- desirable or even possible, though.
626
-
627
- Any type can be entered as a string literal, and you can combine
628
- string-literal types with non-string-literal types freely:
629
-
630
- .. code-block :: python
631
-
632
- def f (a : List[' A' ]) -> None : ... # OK
633
- def g (n : ' int' ) -> None : ... # OK, though not useful
634
-
635
- class A : pass
636
-
637
- String literal types are never needed in ``# type: `` comments and :ref: `stub files <stub-files >`.
638
-
639
- String literal types must be defined (or imported) later *in the same
640
- module *. They cannot be used to leave cross-module references
641
- unresolved. (For dealing with import cycles, see
642
- :ref: `import-cycles `.)
643
-
644
499
.. _type-aliases :
645
500
646
501
Type aliases
0 commit comments