id_translation.types#

Types used for translation.

Hint

Use register_io() to register custom DataStructureIO implementations.

Rules of thumb#

The IdTypes are the only “truly” translatable types. Collections thereof are also supported.
Non-inplace (copy-translation, default) always tries to return a collection of the same type, with all IdTypes converted to str.
In-place translation always returns None, or raises NotInplaceTranslatableError.

Overloads err on the overly-permissive side. Static type checkers (only MyPy is tested) may incorrectly allow things like translator.translate("a-string-id") for int-only Translator instances.

Limitations#

Python does not support generics-of-generics, which is the primary domain in which the Translator.translate-method operates. See python/typing#548 for details on this subject.

Numpy is supported, but not typed.
Pandas typing must be enabled using the ID_TRANSLATION_PANDAS_IS_TYPED-flag.

pip install pandas-stubs
mypy --always-true=ID_TRANSLATION_PANDAS_IS_TYPED /path/to/file.py

All pandas types will be None without stubs, which will break the overloads.

Module Attributes

`ID`	Name of the ID placeholder in the translation `Format`.
`IdTypes`	Type of the value being translated into human-readable labels.
`IdType`	Type variable bound by `IdTypes`.
`NameType`	Type used to label collections of IDs, such as the column names in a DataFrame or the keys of a dict.
`Translatable`	Enumeration of translatable types.
`SourceType`	Type used to describe sources.
`NameToSource`	A mapping from name to source.
`NamesPredicate`	A predicate type on names.
`NameTypes`	A union of a name type, or an iterable thereof.
`Names`	Acceptable name types.
`TranslatableT`	Simplified `Translatable` type.

Classes

HasSources()

Indicates that sources and placeholders are available.

class HasSources[source]#

Bases: ABC, Generic[SourceType]

Indicates that sources and placeholders are available.

abstract property placeholders#

Placeholders for all known Source names, such as id or name.

These are the (possibly unmapped) placeholders that may be used for translation.

Returns:: A dict {source: [placeholders..]}.

property sources#: A list of known Source names, such as cities or languages.

ID = 'id'#

Name of the ID placeholder in the translation Format.

Cannot be changed (yet); see rsundqvist/id-translation#151.

class IdType#

Type variable bound by IdTypes.

alias of TypeVar(‘IdType’, bound=int | str | UUID)

IdTypes = int | str | uuid.UUID#: Type of the value being translated into human-readable labels.

NameToSource#

A mapping from name to source.

alias of dict[NameType, SourceType]

class NameType#

Type used to label collections of IDs, such as the column names in a DataFrame or the keys of a dict.

alias of TypeVar(‘NameType’, bound=Hashable)

NameTypes#

A union of a name type, or an iterable thereof.

alias of NameType | Iterable[NameType]

Names#

Acceptable name types.

alias of NameType | Iterable[NameType] | Callable[[NameType], bool]

NamesPredicate#

A predicate type on names.

alias of Callable[[NameType], bool]

class SourceType#

Type used to describe sources. Typically a string for things like files and database tables.

alias of TypeVar(‘SourceType’, bound=Hashable)

Translatable#

Enumeration of translatable types.

Types int, str, and UUID can be translated, or a collection thereof. Some numpy and pandas types are also supported. The Translator is quite flexible when it comes to the encapsulating data structure, and will do its best to return a data structure of the same type (albeit with elements converted to str).

Note

Dict values are always copied for translation.

Setting copy=False merely controls whether the original dict is modified.

class TranslatableT#

Simplified Translatable type.