Skip to main content

Typical: Take Typing Further. 🦆

image image image image image codecov Code style: black

Take Typing Further with Typical. Make your annotations work for you.

Quickstart

Typical is exceptionally light-weight (<30KB) and has only one dependency - python-dateutil, which it uses to parse date-strings into datetime objects.

In order to install, simply pip3 install typical and annotate to your heart's content! 🦆

Motivations

In the world of web-services development, type-safety becomes necessary for the sanity of your code and your fellow developers. This is not to say that static-typing is the solution - When it comes to the external entrypoints to your code, not even a compiler is going to help you.

With Python3, type annotations were introduced. With Python3.7, the library was completely re-written for performance and ease-of-use. Type annotations are here to stay and I couldn't be happier about it.

However, there is one place where annotations fall down. There is no provided path for ensuring the type-safety of your methods, functions, and classes. This means if you're receiving data from an external source, (such as with a web service) you still need to do this work yourself.

Until now.

Automatic, Guaranteed Duck-Typing

Behold, the power of Typical:

>>> import typic
>>>
>>> @typic.al
>>> def multi(a: int, b: int):
...    return a * b
...
>>> multi('2', '3')
6

Take it further...

>>> import dataclasses
>>> import enum
>>> import typic
>>>
>>> class DuckType(str, enum.Enum):
...     MAL = 'mallard'
...     BLK = 'black'
...     WHT = 'white'
... 
>>> @typic.al
... @dataclasses.dataclass
... class Duck:
...     type: DuckType
...     name: str
...
>>> donald = Duck('white', 'Donald')
>>> donald.type
<DuckType.WHT: 'white'>

This is all fine and dandy, but can we go... further? 🤔

>>> class DuckRegistry:
...     """A Registry for all the ducks"""
...     
...     @typic.al
...     def __init__(self, *duck: Duck):
...         self._reg = {x.name: x for x in duck}
... 
...     @typic.al
...     def add(self, duck: Duck):
...         self._reg[duck.name] = duck
... 
...     @typic.al
...     def find(self, name: str):
...         """Try to find a duck by its name. Otherwise, try with type."""
...         if name not in self._reg:
...             matches = [x for x in self._reg.values() if x.type == name]
...             if matches:
...                 return matches[-1] if len(matches) == 1 else matches
...         return self._reg[name]
... 
>>> registry = DuckRegistry({'type': 'black', 'name': 'Daffy'})
>>> registry.find('Daffy')
Duck(type=<DuckType.BLK: 'black'>, name='Daffy')
>>> registry.add({'type': 'white', 'name': 'Donald'})
>>> registry.find('Donald')
Duck(type=<DuckType.WHT: 'white'>, name='Donald')

>>> registry.add({'type': 'goose', 'name': 'Maynard'})
Traceback (most recent call last):
 ...
ValueError: 'goose' is not a valid DuckType

What Just Happended Here?

When we wrap a callable with @typic.al, the wrapper reads the signature of the callable and automatically coerces the incoming data to the type which is annotated. This includes varargs (*args and **kwargs). This means that you no longer need to do the work of converting incoming data yourself. You just need to signal what you expect the data to be with an annotation and Typical will do the rest.

The ValueError we see in the last operation is what we can expect when attempting to supply an invalid value for the Enum class we used above. Rather than have to write code to cast this data and handle stuff that's invalid, you can rest easy in the guarantee that the data you expect is the data you'll get.

What's Supported?

As of this version, Typical can parse the following inputs into valid Python types and classes:

Limitations

Forward Refs

A "forward reference" is a reference to a type which has either not yet been defined, or is not available within the module which the annotation lives. This is noted by encapsulating the annotation in quotes, e.g.: foo: 'str' = 'bar'. Beware of using such syntax in combination with Typical. Typical makes use of typing.get_type_hints, which scans the namespace(s) available to the given object to resolve annotations. If the annotation is unavailable, a NameError will be raised. This behavior is considered valid. If you wish to make use of Typical for type-coercion, make sure the annotated type is in the namespace of the object you're wrapping and avoid Forward References if at all possible.

Special Forms

There is a subset of type annotations which are 'suscriptable' - meaning you can specify what other types this annotation may resolve to. In a few of those cases, the intended type for the incoming data is too ambiguous to resolve. The following annotations are special forms which cannot be supported:

  • Union
  • Any

Because these signal an unclear resolution, Typical will ignore this flavor of annotation, leaving it to the developer to determine the appropriate action.

Updates

New in version 1.1.0: typing.Optional and typing.ClassVar are now supported.

New in version 1.2.0: Values set to annotated attributes are automagically resolved.

New in version 1.3.0:

  1. Custom coercers may now be registered, e.g.:

    import typic
    
    class MyCustomClass:
    
        def __init__(self, value):
            self.value = value
    
        @classmethod
        def factory(cls, value):
            return cls(value)
    
    
    def custom_class_coercer(value, annotation: MyCustomClass):
        return annotation.factory(value)
    
    
    def ismycustomclass(obj) -> bool:
        return obj is MyCustomClass
    
    
    typic.register(custom_class_coercer, ismycustomclass)
    
  2. Squashed a few bugs:

    • Nested calls of Coercer.coerce_value didn't account for values that didn't need coercion. This sometimes broke evaluation, and definitely resulted in sub-optimal type resolution performance.
    • In the final attempt to coerce a custom class, calling typic.evals.safe_eval could reveal that a value is null. In this case, we should respect whether the annotation was optional.
    • Sometimes people are using a version of PyYAML that's older than 5.1. We should support that.

New in version 1.3.1:

  1. Improved caching strategy and resolution times.

New in version 1.3.2:

  1. Resolution time is better than ever.
  2. Custom Unions are now supported via registering custom coercers with typic.register, as a result of raising the priority of user-registered coercers.

Documentation

Full documentation coming soon!

Happy Typing 🦆

How to Contribute

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
  2. Create a branch on Github for your issue or fork the repository on GitHub to start making your changes to the master branch.
  3. Write a test which shows that the bug was fixed or that the feature works as expected.
  4. Send a pull request and bug the maintainer until it gets merged and published. :)

Metadata

Release files for typical 1.3.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for typical 1.3.4
File Size Uploaded Provenance Actions
typical-1.3.4.tar.gz 17.1 kB Without provenance Details for typical-1.3.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for typical 1.3.4
File Interpreter ABI Platform Actions
typical-1.3.4-py2.py3-none-any.whl Python 3, Python 2 none any Details for typical-1.3.4-py2.py3-none-any.whl

Total release size: 30.8 kB

Release files / typical-1.3.4.tar.gz

Download URL typical-1.3.4.tar.gz
Size 17.1 kB
Tags Source
SHA-256 checksum
How to use checksums
eb15373b7b9b2e8ca3a4aa385ee4f71b60dc8939b20c280aacde4aa62b95c5ae
BLAKE2b-256 checksum
How to use checksums
f1947dad278fb8ba9951ac9af49ccc974a4ba9a87ae8c776901b038e02939591
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/41.0.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.3

Release files / typical-1.3.4-py2.py3-none-any.whl

Download URL typical-1.3.4-py2.py3-none-any.whl
Size 13.6 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
d61d0b7c94bae8af5d20f470554c13c29a406720a9c1580fcb1df7bdf493d696
BLAKE2b-256 checksum
How to use checksums
554af9b623a36b59955317a41b9ab6eeeba4ed3a0f5649a8a364f330f45515bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/41.0.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.3

Security for typical 1.3.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.4 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page