Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

gh-97797: Mention __metadata__ in docstrings of typing.{_AnnotatedAlias, Annotated} #103405

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.

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
merged 3 commits into from
Apr 10, 2023

Conversation

sobolevn
Copy link
Member

@sobolevn sobolevn commented Apr 10, 2023

New help output:

>>> help(typing._AnnotatedAlias)
Help on class _AnnotatedAlias in module typing:

class _AnnotatedAlias(_NotIterable, _GenericAlias)
 |  _AnnotatedAlias(origin, metadata)
 |
 |  Runtime representation of an annotated type.
 |
 |  At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
 |  with extra annotations. The alias behaves like a normal typing alias,
 |  instantiating is the same as instantiating the underlying type, binding
 |  it to types is also the same.
 |
 |  The metadata itself is storred in '__metadata__' attribute as a tuple.
 |
 |  Method resolution order:
 |      _AnnotatedAlias
 |      _NotIterable
 |      _GenericAlias
 |      _BaseGenericAlias
 |      _Final
 |      builtins.object
 |
 |  Methods defined here:
 |
 |  __eq__(self, other)
 |      Return self==value.
 |
 |  __getattr__(self, attr)
 |
 |  __hash__(self)
 |      Return hash(self).
 |
 |  __init__(self, origin, metadata)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  __mro_entries__(self, bases)
 |
 |  __reduce__(self)
 |      Helper for pickle.
 |
 |  __repr__(self)
 |      Return repr(self).
 |
 |  copy_with(self, params)
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)
 |
 |  ----------------------------------------------------------------------
 |  Data and other attributes inherited from _NotIterable:
 |
 |  __iter__ = None
 |
 |  ----------------------------------------------------------------------
 |  Methods inherited from _GenericAlias:
 |
 |  __getitem__(self, args)
 |
 |  __or__(self, right)
 |      Return self|value.
 |
 |  __ror__(self, left)
 |      Return value|self.
 |
 |  ----------------------------------------------------------------------
 |  Methods inherited from _BaseGenericAlias:
 |
 |  __call__(self, *args, **kwargs)
 |      Call self as a function.
 |
 |  __dir__(self)
 |      Default dir() implementation.
 |
 |  __instancecheck__(self, obj)
 |      Check if an object is an instance.
 |
 |  __setattr__(self, attr, val)
 |      Implement setattr(self, name, value).
 |
 |  __subclasscheck__(self, cls)
 |      Check if a class is a subclass.
 |
 |  ----------------------------------------------------------------------
 |  Class methods inherited from _Final:
 |
 |  __init_subclass__(*args, **kwds) from builtins.type
 |      This method is called when a class is subclassed.
 |
 |      The default implementation does nothing. It may be
 |      overridden to extend subclasses.

and:

>>> help(typing.Annotated)
Help on class Annotated in module typing:

class Annotated(builtins.object)
 |  Annotated(*args, **kwargs)
 |
 |  Add context specific metadata to a type.
 |
 |  Example: Annotated[int, runtime_check.Unsigned] indicates to the
 |  hypothetical runtime_check module that this type is an unsigned int.
 |  Every other consumer of this type can ignore this metadata and treat
 |  this type as int.
 |
 |  The first argument to Annotated must be a valid type.
 |
 |  Details:
 |
 |  - It's an error to call `Annotated` with less than two arguments.
 |  - Metadata can be accessed in runtime with::
 |
 |      Annotated[int, '$'].__metadata__ == ('$',)
 |
 |  - Nested Annotated are flattened::
 |
 |      Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
 |
 |  - Instantiating an annotated type is equivalent to instantiating the
 |  underlying type::
 |
 |      Annotated[C, Ann1](5) == C(5)
 |
 |  - Annotated can be used as a generic type alias::
 |
 |      Optimized = Annotated[T, runtime.Optimize()]
 |      Optimized[int] == Annotated[int, runtime.Optimize()]
 |
 |      OptimizedList = Annotated[List[T], runtime.Optimize()]
 |      OptimizedList[int] == Annotated[List[int], runtime.Optimize()]
 |
 |  - Annotated cannot be used with an unpacked TypeVarTuple::
 |
 |      Annotated[*Ts, Ann1]  # NOT valid
 |
 |    This would be equivalent to
 |
 |      Annotated[T1, T2, T3, ..., Ann1]
 |
 |    where T1, T2 etc. are TypeVars, which would be invalid, because
 |    only one type should be passed to Annotated.
 |
 |  Class methods defined here:
 |
 |  __class_getitem__(params) from builtins.type
 |
 |  __init_subclass__(*args, **kwargs) from builtins.type
 |      This method is called when a class is subclassed.
 |
 |      The default implementation does nothing. It may be
 |      overridden to extend subclasses.
 |
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |
 |  __new__(cls, *args, **kwargs)
 |      Create and return a new object.  See help(type) for accurate signature.

Lib/typing.py Outdated Show resolved Hide resolved
Co-authored-by: Kirill <80244920+Eclips4@users.noreply.github.com>
@Eclips4
Copy link
Member

Eclips4 commented Apr 10, 2023

CI/CD fail unrelated.
Thanks Oleg for the rerun!

Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for picking this up!

Lib/typing.py Outdated Show resolved Hide resolved
Lib/typing.py Outdated Show resolved Hide resolved
@AlexWaygood AlexWaygood added 3.11 only security fixes topic-typing labels Apr 10, 2023
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
@AlexWaygood AlexWaygood added needs backport to 3.11 only security fixes and removed 3.11 only security fixes labels Apr 10, 2023
Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@miss-islington
Copy link
Contributor

Thanks @sobolevn for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

@bedevere-bot
Copy link

GH-103413 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Apr 10, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Apr 10, 2023
…otatedAlias, Annotated}` (pythonGH-103405)

(cherry picked from commit dc604a8)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Kirill <80244920+Eclips4@users.noreply.github.com>
miss-islington added a commit that referenced this pull request Apr 10, 2023
…Alias, Annotated}` (GH-103405)

(cherry picked from commit dc604a8)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Kirill <80244920+Eclips4@users.noreply.github.com>
warsaw pushed a commit to warsaw/cpython that referenced this pull request Apr 11, 2023
…otatedAlias, Annotated}` (python#103405)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Kirill <80244920+Eclips4@users.noreply.github.com>
aisk pushed a commit to aisk/cpython that referenced this pull request Apr 18, 2023
…otatedAlias, Annotated}` (python#103405)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Kirill <80244920+Eclips4@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants
Morty Proxy This is a proxified and sanitized view of the page, visit original site.