Skip to content

bpo-44353: Document that typing.NewType is now a class #27319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ambv merged 2 commits into from
Jul 24, 2021
Merged

bpo-44353: Document that typing.NewType is now a class #27319

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
99fe351
Document NewType changes
Fidget-Spinner Jul 24, 2021
7439e8d
fix up wording
Fidget-Spinner Jul 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Note that ``None`` as a type hint is a special case and is replaced by
NewType
=======

Use the :func:`NewType` helper function to create distinct types::
Use the :class:`NewType` helper class to create distinct types::

from typing import NewType

Expand Down Expand Up @@ -106,15 +106,14 @@ accidentally creating a ``UserId`` in an invalid way::

Note that these checks are enforced only by the static type checker. At runtime,
the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a
function that immediately returns whatever parameter you pass it. That means
class that immediately returns whatever parameter you pass it. That means
the expression ``Derived(some_value)`` does not create a new class or introduce
any overhead beyond that of a regular function call.
much overhead beyond that of a regular function call.

More precisely, the expression ``some_value is Derived(some_value)`` is always
true at runtime.

This also means that it is not possible to create a subtype of ``Derived``
since it is an identity function at runtime, not an actual type::
It is invalid to create a subtype of ``Derived``::

from typing import NewType

Expand All @@ -123,7 +122,7 @@ since it is an identity function at runtime, not an actual type::
# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

However, it is possible to create a :func:`NewType` based on a 'derived' ``NewType``::
However, it is possible to create a :class:`NewType` based on a 'derived' ``NewType``::

from typing import NewType

Expand Down Expand Up @@ -151,6 +150,12 @@ See :pep:`484` for more details.

.. versionadded:: 3.5.2

.. versionchanged:: 3.10.0
``NewType`` is now a class rather than a function. There is some additional
runtime cost when calling ``NewType`` over a regular function. However, this
cost will be reduced in 3.11.0.


Callable
========

Expand Down Expand Up @@ -1306,17 +1311,21 @@ These are not used in annotations. They are building blocks for declaring types.
Removed the ``_field_types`` attribute in favor of the more
standard ``__annotations__`` attribute which has the same information.

.. function:: NewType(name, tp)
.. class:: NewType(name, tp)

A helper function to indicate a distinct type to a typechecker,
see :ref:`distinct`. At runtime it returns a function that returns
its argument. Usage::
A helper class to indicate a distinct type to a typechecker,
see :ref:`distinct`. At runtime it returns an object that returns
its argument when called.
Usage::

UserId = NewType('UserId', int)
first_user = UserId(1)

.. versionadded:: 3.5.2

.. versionchanged:: 3.10.0
``NewType`` is now a class rather than a function.

.. class:: TypedDict(dict)

Special construct to add type hints to a dictionary.
Expand Down