Add reference targets throughout the spec (#1626)

To facilitate cross-linking from the PEPs and the CPython documentation.

Also fix a few instances of "Type[]" that I noticed. My editor removed some trailing whitespace.

Co-authored-by: Sebastian Rittau <[email protected]>

docs/spec/aliases.rst

@@ -1,3 +1,5 @@
+.. _`type-aliases`:
+
 Type aliases
 ============
 
@@ -58,6 +60,8 @@ This is equivalent to::
         return ((x * scale, y * scale) for x, y in v)
     vec: Iterable[tuple[float, float]] = []
 
+.. _`typealias`:
+
 ``TypeAlias``
 -------------
 
@@ -97,6 +101,8 @@ isolation. For the sake of backwards compatibility, type checkers should support
 both simultaneously, meaning an untyped global expression ``x = int`` will
 still be considered a valid type alias.
 
+.. _`type-statement`:
+
 ``type`` statement
 ------------------
 
@@ -126,6 +132,8 @@ should generate an error in this case.
     T = TypeVar("T")
     type MyList = list[T]  # Type checker error: traditional type variable usage
 
+.. _`newtype`:
+
 ``NewType``
 -----------
 

docs/spec/annotations.rst

@@ -1,3 +1,5 @@
+.. _`type-annotations`:
+
 Type annotations
 ================
 
@@ -81,6 +83,8 @@ below may be used: ``None``, ``Any``, ``Union``, ``Tuple``,
 from ``typing`` (e.g. ``Sequence`` and ``Dict``), type variables, and
 type aliases.
 
+.. _`forward-references`:
+
 Forward references
 ------------------
 
@@ -115,7 +119,7 @@ Moreover, the expression should be parseable as a valid type hint, i.e.,
 it is constrained by the rules from the section on :ref:`valid-types`.
 
 If a triple quote is used, the string should be parsed as though it is
-implicitly surrounded by parentheses. This allows newline characters to be 
+implicitly surrounded by parentheses. This allows newline characters to be
 used within the string literal::
 
     value: """

docs/spec/callables.rst

@@ -1,3 +1,5 @@
+.. _`callables`:
+
 Callables
 =========
 
@@ -338,6 +340,8 @@ Therefore, in the context of typing ``**kwargs``, using ``Unpack`` with types
 other than ``TypedDict`` should not be allowed and type checkers should
 generate errors in such cases.
 
+.. _`callable`:
+
 Callable
 --------
 
@@ -372,6 +376,8 @@ specifying callback signatures with a variable number of arguments of a
 specific type. For these use cases, see the section on
 `Callback protocols`_.
 
+.. _`callback-protocols`:
+
 Callback protocols
 ------------------
 

docs/spec/class-compat.rst

@@ -1,6 +1,10 @@
+.. _`class-compat`:
+
 Class type compatibility
 ========================
 
+.. _`classvar`:
+
 ``ClassVar``
 ------------
 
@@ -85,6 +89,8 @@ annotated in ``__init__`` or other methods, rather than in the class::
       def __init__(self, content):
           self.content: T = content
 
+.. _`override`:
+
 ``@override``
 -------------
 

docs/spec/concepts.rst

@@ -1,6 +1,10 @@
+.. _`type-system-concepts`:
+
 Type system concepts
 ====================
 
+.. _`union-types`:
+
 Union types
 -----------
 

docs/spec/dataclasses.rst

@@ -1,3 +1,5 @@
+.. _`dataclasses`:
+
 Dataclasses
 ===========
 
@@ -6,6 +8,8 @@ the :py:mod:`dataclasses` module. In addition, the type system
 contains a mechanism to make third-party classes behave like
 standard dataclasses.
 
+.. _`dataclass-transform`:
+
 The ``dataclass_transform`` decorator
 -------------------------------------
 

docs/spec/directives.rst

@@ -3,6 +3,8 @@
 Type checker directives
 =======================
 
+.. _`assert-type`:
+
 ``assert_type()``
 -----------------
 
@@ -16,6 +18,8 @@ should emit an error if the value is not of the specified type::
         assert_type(name, str)  # OK, inferred type of `name` is `str`
         assert_type(name, int)  # type checker error
 
+.. _`reveal-type`:
+
 ``reveal_type()``
 -----------------
 
@@ -28,6 +32,8 @@ it should emit a diagnostic with the type of the argument. For example::
   x: int = 1
   reveal_type(x)  # Revealed type is "builtins.int"
 
+.. _`type-ignore`:
+
 ``# type: ignore`` comments
 ---------------------------
 
@@ -53,6 +59,8 @@ other comments and linting markers:
 
   # type: ignore # <comment or other marker>
 
+.. _`cast`:
+
 ``cast()``
 ----------
 
@@ -81,6 +89,8 @@ type is consistent with the stated type.  When using a cast, the type
 checker should blindly believe the programmer.  Also, casts can be used
 in expressions, while type comments only apply to assignments.
 
+.. _`if-type-checking`:
+
 ``TYPE_CHECKING``
 -----------------
 
@@ -105,6 +115,8 @@ interpreter runtime.  In the variable annotation no quotes are needed.)
 
 This approach may also be useful to handle import cycles.
 
+.. _`no-type-check`:
+
 ``@no_type_check``
 ------------------
 
@@ -140,6 +152,8 @@ checks, e.g.::
 Don't expect a checker to understand obfuscations like
 ``"".join(reversed(sys.platform)) == "xunil"``.
 
+.. _`deprecated`:
+
 ``@deprecated``
 ---------------
 

docs/spec/generics.rst

@@ -1,3 +1,5 @@
+.. _`generics`:
+
 Generics
 ========
 
@@ -207,6 +209,7 @@ is not generic but implicitly inherits from ``Iterable[Any]``::
 
 Generic metaclasses are not supported.
 
+.. _`typevar-scoping`:
 
 Scoping rules for type variables
 --------------------------------
@@ -464,6 +467,7 @@ A generic class can be an ABC by including abstract methods
 or properties, and generic classes can also have ABCs as base
 classes without a metaclass conflict.
 
+.. _`typevar-bound`:
 
 Type variables with an upper bound
 ----------------------------------
@@ -494,6 +498,7 @@ inferred type to be _exactly_ one of the constraint types, while an
 upper bound just requires that the actual type is a subtype of the
 boundary type.
 
+.. _`variance`:
 
 Variance
 --------
@@ -1003,6 +1008,8 @@ outer ``Callable``.  This has the following semantics:
 
    twice(a_int_b_str, "A", 1)       # Rejected
 
+.. _`typevartuple`:
+
 TypeVarTuple
 ------------
 
@@ -2320,6 +2327,8 @@ avoid confusion, we reject this edge case.
 
     class Foo(metaclass=MyMetaclass): ...
 
+.. _`variance-inference`:
+
 Variance Inference
 ------------------
 

docs/spec/historical.rst

@@ -11,6 +11,8 @@ the older alternatives and treat them as equivalent.
 
 This section lists all of these cases.
 
+.. _`type-comments`:
+
 Type comments
 -------------
 
@@ -78,6 +80,8 @@ assumption here is that other code will ensure that the variable is
 given a value of the proper type, and all uses can assume that the
 variable has the given type.
 
+.. _`type-comments-function`:
+
 Type comments on function definitions
 -------------------------------------
 
@@ -187,6 +191,7 @@ When checking Python 2.7 code, type checkers should treat the ``int`` and
 ``long`` types as equivalent. For parameters typed as ``Text``, arguments of
 type ``str`` as well as ``unicode`` should be acceptable.
 
+.. _`pos-only-double-underscore`:
 
 Positional-only arguments
 -------------------------
@@ -263,6 +268,9 @@ as equivalent to the alias in the ``typing`` module. This includes:
 The generic aliases in the ``typing`` module are considered deprecated
 and type checkers may warn if they are used.
 
+.. _`typing-union`:
+.. _`typing-optional`:
+
 ``Union`` and ``Optional``
 --------------------------
 
@@ -278,6 +286,8 @@ Examples:
 * ``int | str | range`` is the same as ``Union[int, str, range]``
 * ``int | None`` is the same as ``Optional[int]`` and ``Union[int, None]``
 
+.. _`unpack-pep646`:
+
 ``Unpack``
 ----------
 

docs/spec/literal.rst

@@ -1,6 +1,10 @@
+.. _`literal-types`:
+
 Literals
 ========
 
+.. _`literal`:
+
 ``Literal``
 -----------
 
@@ -553,6 +557,8 @@ example, whether or not the following program type checks is left unspecified::
     bar2: Final = 1 + 2
     expects_three(bar2)  # May or may not be accepted by type checkers
 
+.. _`literalstring`:
+
 ``LiteralString``
 -----------------
 

docs/spec/meta.rst

@@ -1,3 +1,5 @@
+.. _`spec-meta`:
+
 Meta-topics
 ===========
 

docs/spec/overload.rst

@@ -1,3 +1,5 @@
+.. _`overload`:
+
 ``@overload``
 =============
 

docs/spec/protocol.rst

@@ -36,8 +36,7 @@ The attributes (variables and methods) of a protocol that are mandatory
 for another class in order to be considered a structural subtype are called
 protocol members.
 
-
-.. _definition:
+.. _protocol-definition:
 
 Defining a protocol
 ^^^^^^^^^^^^^^^^^^^
@@ -458,10 +457,10 @@ Example::
   cached_func((1, 2, 3)) # OK, tuple is both hashable and iterable
 
 
-``Type[]`` and class objects vs protocols
+``type[]`` and class objects vs protocols
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Variables and parameters annotated with ``Type[Proto]`` accept only concrete
+Variables and parameters annotated with ``type[Proto]`` accept only concrete
 (non-protocol) subtypes of ``Proto``. The main reason for this is to allow
 instantiation of parameters with such types. For example::
 
@@ -473,7 +472,7 @@ instantiation of parameters with such types. For example::
       def meth(self) -> int:
           return 42
 
-  def fun(cls: Type[Proto]) -> int:
+  def fun(cls: type[Proto]) -> int:
       return cls().meth() # OK
   fun(Proto)              # Error
   fun(Concrete)           # OK
@@ -487,7 +486,7 @@ The same rule applies to variables::
 
 Assigning an ABC or a protocol class to a variable is allowed if it is
 not explicitly typed, and such assignment creates a type alias.
-For normal (non-abstract) classes, the behavior of ``Type[]`` is
+For normal (non-abstract) classes, the behavior of ``type[]`` is
 not changed.
 
 A class object is considered an implementation of a protocol if accessing
@@ -583,6 +582,8 @@ of the corresponding protocol methods is dropped. For example::
 
   rp: Reporter = callbacks  # Passes type check
 
+.. _`runtime-checkable`:
+
 ``@runtime_checkable`` decorator and narrowing types by ``isinstance()``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/spec/qualifiers.rst

@@ -1,6 +1,10 @@
+.. _`type-qualifiers`:
+
 Type qualifiers
 ===============
 
+.. _`at-final`:
+
 ``@final``
 ----------
 
@@ -56,6 +60,8 @@ implementation (or on the first overload, for stubs)::
 
 It is an error to use ``@final`` on a non-method function.
 
+.. _`uppercase-final`:
+
 ``Final``
 ---------
 
@@ -177,6 +183,8 @@ following should be allowed::
    Y: Final = "y"
    N = NamedTuple("N", [(X, int), (Y, int)])
 
+.. _`annotated`:
+
 ``Annotated``
 -------------