{"author":null,"author_email":"Jay Qi ","bugtrack_url":null,"classifiers":["Intended Audience :: Developers","License :: OSI Approved :: MIT License","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.9"],"description":"# typenames : String representations of type annotations\n\n[![Docs Status](https://img.shields.io/badge/docs-stable-informational)](https://typenames.drivendata.org/)\n[![PyPI](https://img.shields.io/pypi/v/typenames.svg)](https://pypi.org/project/typenames/)\n[![conda-forge](https://img.shields.io/conda/vn/conda-forge/typenames.svg)](https://github.com/conda-forge/typenames-feedstock)\n[![Supported Python versions](https://img.shields.io/pypi/pyversions/typenames)](https://pypi.org/project/typenames/)\n[![tests](https://github.com/drivendataorg/typenames/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/drivendataorg/typenames/actions/workflows/tests.yml?query=branch%3Amain)\n[![codecov](https://codecov.io/gh/drivendataorg/typenames/branch/main/graph/badge.svg)](https://codecov.io/gh/drivendataorg/typenames)\n\n**typenames** is a configurable Python library for creating string representations of type annotations. By default, it produces compact representations by removing standard library module names. Configurable options include standardizing on `|` operator syntax for unions or standard collections classes for generics.\n\n```python\nimport typing\nfrom typenames import typenames\n\ntypenames(int)\n#> 'int'\ntypenames(dict[str, typing.Any])\n#> 'dict[str, Any]'\ntypenames(str | int)\n#> 'str | int'\ntypenames(typing.Optional[str])\n#> 'Optional[str]'\n```\n\n## Why use this library?\n\nString representations of Python type objects, type aliases, and special typing forms are inconsistent and often verbose. Here are some comparisons using default settings against built-in string representations:\n\n| Input | With `str(...)` | With `typenames(...)` |\n| :-: | :-: | :-: |\n| `int` | `` | `int` |\n| `list` | `` | `list` |\n| `typing.Optional[int]` | `typing.Optional[int]` | `Optional[int]` |\n| `collections.abc.Iterator[typing.Any]` | `collections.abc.Iterator[typing.Any]` | `Iterator[Any]` |\n| `typing.Literal[MyEnum.NAME]` | `typing.Literal[]` | `Literal[MyEnum.NAME]` |\n\ntypenames also has handy configurable functionality, such as:\n\n- Forcing standardization on `|` operator union syntax (e.g., `Union[int, str]` to `int | str`) or vice versa\n- Forcing standardization on `|` operator optional syntax (e.g., `Optional[int]` to `int | None`) or vice versa\n- Forcing standardization on standard collection types for generics (e.g., `List[int]` to `list[int]`) or vice versa\n- Controlling exactly which module names to remove using regex patterns.\n\nNo need for string manipulation to get what you want!\n\n## Installation\n\ntypenames is available on [PyPI](https://pypi.org/project/typenames/):\n\n```bash\npip install typenames\n```\n\nIt is also available on [conda-forge](https://github.com/conda-forge/typenames-feedstock):\n\n```bash\nconda install typenames --channel conda-forge\n```\n\n## Basic Usage\n\nThe main way to use the library is the `typenames` function. Calling it on a type annotation renders a string representation:\n\n```python\nimport collections.abc\nimport typing\nfrom typenames import typenames\n\ntypenames(int)\n#> 'int'\ntypenames(typing.Optional[str])\n#> 'Optional[str]'\ntypenames(collections.abc.Callable[[int], tuple[str, ...]])\n#> 'Callable[[int], tuple[str, ...]]\n```\n\nUnder the hood, typenames parses a type annotation as a tree structure. If you need to see the parsed tree, use the `parse_type_tree` function to return the root node. You can get the rendered string representation by calling `str(...)` on root node.\n\n```python\nimport typing\nfrom typenames import parse_type_tree\n\ntree = parse_type_tree(typing.Union[typing.Any, list[typing.Any]])\ntree\n#> , []>]>\nstr(tree)\n#> 'Union[Any, list[Any]]'\n```\n\n## Configurable options\n\nAll configuration options can be passed as keyword arguments to either the `typenames` or `parse_type_tree` functions.\n\n### Union Syntax (`union_syntax`)\n\nThis option controls how unions are rendered. It supports both the `typing.Union` special form and the `|` operator (bitwise or) syntax from [PEP 604](https://peps.python.org/pep-0604/). Valid options are defined by the enum `UnionSyntax` and include:\n\n- **`\"as_given\"` (default)**: render the union as it is given without changing syntax.\n- **`\"or_operator\"`**: render all type unions using the `|` operator.\n- **`\"special_form\"`**: render all type unions using the `typing.Union` special form.\n\n> [!NOTE]\n> Runtime use of the `|` operator between types is new in Python 3.10. To use in earlier versions of Python, you will need to use postponed evaluation of annotations à la [PEP 563](https://peps.python.org/pep-0563/) with `from __future__ import__annotations__`. Support for the `|` operator is only a limitation on providing type annotation inputs to typenames, and not a limitation on output rendering.\n\n> [!IMPORTANT]\n> **Limitations:** Python automatically flattens unions when evaluating them at runtime. Since typenames uses runtime type objects, it will only see the flattened result and not know if your original input was nested. Furthermore, any mixing of `|` operator syntax and any typing module types will result in a `typing.Union` union, so `as_given` will always render such inputs with `typing.Union`.\n\n\n### Optional Syntax (`optional_syntax`)\n\nThis option controls how optional types are rendered. It supports both the `typing.Optional` special form and the `|` operator (bitwise or) syntax from [PEP 604](https://peps.python.org/pep-0604/). Valid options are defined by the enum `OptionalSyntax` and include:\n\n- **`\"as_given\"` (default)**: render the optional type as it is given without changing syntax\n- **`\"or_operator\"`**: render all optional types using the `|` operator\n- **`\"union_special_form\"`**: render all optional types using the `typing.Optional` special form\n- **`\"optional_special_form\"`**: render all optional types using the `typing.Optional` special form\n\n> [!NOTE]\n> Runtime use of the `|` operator between types is new in Python 3.10. To use in earlier versions of Python, you will need to use postponed evaluation of annotations à la [PEP 563](https://peps.python.org/pep-0563/) with `from __future__ import__annotations__`. Support for the `|` operator is only a limitation on providing type annotation inputs to typenames, and not a limitation on output rendering.\n\n> [!IMPORTANT]\n> **Limitations:**\n>\n> - Python automatically converts `typing.Union[..., None]` to `typing.Optional[...]` when evaluating at runtime. Since typenames uses runtime type objects, it will only see the result using `typing.Optional` and not know the form of your original input.\n> - Python automatically flattens unions when evaluating them at runtime. Since typenames uses runtime type objects, it will only see the flattened result and not know if your original input was nested. Furthermore, any mixing of `|` operator syntax and any typing module types will result in a `typing.Union` union, so `as_given` will always render such inputs with typing module special forms.\n> - The `typing.Optional` special form only accepts exactly one parameter. By default, typenames will render cases with multiple parameters with `Optional[Union[...]]`. You can use the `union_syntax` option to control the inner union's syntax.\n\n\n### Standard Collection Syntax (`standard_collection_syntax`)\n\n_Default value changed in v2.0.0_\n\nThis option controls how parameterized standard collection generic types are rendered. It supports both the typing module's generic aliases (e.g., `typing.List[...]`) and the standard class (e.g., `list[...]`) syntax from [PEP 585](https://peps.python.org/pep-0585/). Valid options are defined by the enum `StandardCollectionSyntax` and include:\n\n- **`\"standard_class\"` (default)**: render all parameterized standard collection generic types using their class\n- **`\"as_given\"`**: render the parameterized generic type as it is given without changing syntax\n- **`\"typing_module\"`**: render all parameterized standard collection generic types using the typing module's generic alias\n\n> [!NOTE]\n> The typing module's generic aliases are [deprecated](https://docs.python.org/3/library/typing.html#deprecated-aliases) in favor of parameterizing standard collection classes. Parameterizing standard collection classes was added in Python 3.9 and is available in all currently supported versions of Python.\n\n### Removing Module Names (`remove_modules`)\n\nThis option controls how module names are removed from the rendered output. It takes a list of inputs, which can either be a string of the module name or a `re.Pattern` regex pattern directly (the result of `re.compile`). String inputs are templated into the following regex pattern:\n\n```python\nmodule: str # Given module name\nre.compile(r\"^{}\\.\".format(module.replace(\".\", r\"\\.\")))\n```\n\nNote that module names are removed in the given order, so having entries that are submodules of other entries can potentially lead to the wrong behavior. You can either order them from higher-depth to lower-depth, or directly provide a compiled pattern with optional groups. For example, the pattern `re.compile(r\"^collections\\.(abc\\.)?\")` will match both `\"collections.\"` and `\"collections.abc.\"`.\n\nThe default list of module names include the standard library modules relevant to [PEP 585](https://peps.python.org/pep-0585/) plus `types` and `typing`. It can be accessed at `DEFAULT_REMOVE_MODULES`.\n\n```python\nDEFAULT_REMOVE_MODULES: List[Union[str, re.Pattern]] = [\n \"__main__\",\n \"builtins\",\n re.compile(r\"^collections\\.(abc\\.)?\"),\n \"contextlib\",\n \"re\",\n \"types\",\n \"typing\",\n]\n```\n\nIf you are trying to _add_ additional modules to this option (rather than overriding the defaults), the easiest way to do so is to concatenate with the default list:\n\n```python\nfrom typing import Optional\nfrom typenames import typenames, DEFAULT_REMOVE_MODULES, BaseNode\n\n# Default removals\ntypenames(Optional[BaseNode])\n#> 'Optional[typenames.BaseNode]'\n\n# Replace default with 'typenames'\ntypenames(Optional[BaseNode], remove_modules=[\"typenames\"])\n#> 'typing.Optional[BaseNode]'\n\n# Extend default with 'typenames'\ntypenames(\n Optional[BaseNode],\n remove_modules=DEFAULT_REMOVE_MODULES + [\"typenames\"],\n)\n#> 'Optional[BaseNode]'\n```\n\nTo remove all module names, you can use `REMOVE_ALL_MODULES`, which contains the pattern `re.compile(r\"^(?\\.)+\")`.\n\n### Annotated (`include_extras`)\n\nThis option controls whether to render `Annotated` and the extra metadata. `typing.Annotated` is a [typing special form](https://docs.python.org/3/library/typing.html#typing.Annotated) introduced in Python 3.9 and originally specified by [PEP 593](https://peps.python.org/pep-0593/). Many libraries like [Pydantic](https://docs.pydantic.dev/latest/concepts/fields/#using-annotated), [FastAPI](https://fastapi.tiangolo.com/python-types/#type-hints-with-metadata-annotations), and [Typer](https://typer.tiangolo.com/tutorial/arguments/optional/#an-alternative-cli-argument-declaration) use it to attach metadata to type annotations that are used at runtime.\n\nBy default, typenames will _not_ render `Annotated` and extra metadata. Set `include_extras=True` to render them.\n\n```python\nfrom typing import Annotated\nfrom typenames import typenames\n\ntypenames(Annotated[int, \"some metadata\"])\n#> 'int'\ntypenames(Annotated[int, \"some metadata\"], include_extras=True)\n#> \"Annotated[int, 'some metadata']\"\n```\n\n---\n\n^{Reproducible examples created by reprexlite.}\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"pep 585, pep 604, type annotations, type hints, typing","license":"MIT License\n \n Copyright (c) 2023 Jay Qi\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.","license_expression":null,"license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"typenames","package_url":"https://pypi.org/project/typenames/","platform":null,"project_url":"https://pypi.org/project/typenames/","project_urls":{"Bug Tracker":"https://github.com/drivendataorg/typenames/issues","Changelog":"https://typenames.drivendata.org/stable/changelog/","Documentation":"https://typenames.drivendata.org/","Homepage":"https://typenames.drivendata.org/","Repository":"https://github.com/drivendataorg/typenames"},"provides_extra":["tests"],"release_url":"https://pypi.org/project/typenames/2.0.0/","requires_dist":["pytest>=6; extra == \"tests\""],"requires_python":">=3.9","summary":"String representations of type annotations.","version":"2.0.0","yanked":false,"yanked_reason":null}

Package search

typenames

project_urls

Dependencies

All package metadata

Releases