Skip to main content

typycal – A handy tool to make type-aware classes

https://img.shields.io/pypi/v/typycal.svg https://img.shields.io/pypi/pyversions/typycal.svg https://travis-ci.org/cardinal-health/typycal.svg?branch=master https://coveralls.io/repos/github/cardinal-health/typycal/badge.svg?branch=master

This lightweight library is for the developer who enjoys the assistance provided by Python’s type annotations.

typed_env

If your Python program relies on a custom os environment, it can be difficult to remember the string names for all those variables. This decorator will provide a means to deal with your environment in an object-oriented fashion.

>>> from typycal import typed_env
>>> import os
>>> import pathlib

For example, say your program obtains database connection info from the environment

>>> os.environ.update({'DB_HOSTNAME': 'localhost', 'DB_PORT': '3306'})
>>> os.getenv('DB_PORT')
'3306'

You can itemize all the environment variables you use in one class

>>> @typed_env
... class Environment:
...     DB_HOSTNAME: str
...     DB_PORT: int
...     DB_USER: str = 'default_user'
...     README_PATH: pathlib.Path = 'README.rst'
...     JSON_DATA: dict = {'foo': 'bar'}

Then you can create a singleton instance for use by the rest of your program

>>> env = Environment()

And your variables will be typed appropriately

>>> (env.DB_HOSTNAME, env.DB_PORT, env.DB_USER)
('localhost', 3306, 'default_user')

And maintained in env properly

>>> os.getenv('JSON_DATA')
'{"foo": "bar"}'

You can do some neat things…

>>> assert env.README_PATH.exists()

If you want to enforce the presence of certain variables in your environment, you can add them this way

>>> @typed_env
... class StricterEnvironment:
...     __required_on_init__ = ('NEED_ME', )
...
...     NEED_ME: str

An error will be thrown immediately when the environment object is instantiated.

>>> stricter_env = StricterEnvironment()
Traceback (most recent call last):
    ...
OSError: Variable 'NEED_ME' is required, but has not been defined.

typed_dict

This decorator offers a simple, declarative means of converting a plain Python dictionary or string object into a type-aware object, with properties to access a defined set of keys.

Developers working with REST APIs or any data loaded as a dictionary can use typycal to effectively design “contracts” with their code, and ideally end up with more readable software

That said, since the release of Python 3.7, you likely will be better served with data classes.

Let’s say you have a settings file sitting somewhere, and it’s loaded into your project as a dictionary (such as json.load, yaml.safe_load, etc…):

{
    "db": {
        "username": "maxwell",
        "password": "SECRET",
        "port": "5432",
        "use_ssl": false
    },
    "log_level": "DEBUG"
}

…let’s say this configuration gets real messy real quick. It can be a real pain to have to remember the names of all your keys for what becomes a Python dict. So, here’s an easy way to wrap your project’s configuration in a type-aware object

>>> from typycal import typed_dict
>>> @typed_dict
... class DBConfig(dict):
...    username: str
...    password: str
...    port: int
...    use_ssl: bool
>>> @typed_dict
... class ProjectConfig(dict):
...     log_level: str
...     db: DBConfig
>>> settings = {
...     "db": {
...             'username': 'maxwell',
...             'password': 'SECRET',
...             'port': '5432',
...         },
...     'log_level': 'DEBUG'
... }
>>> config = ProjectConfig(settings)
>>> config.db.username == 'maxwell'
True
>>> config.db.port == 5432
True

See that? Even though you passed a string for the port, because you explicitly defined the type, it was cast for you! Now, let’s try to access a missing property

>>> config.db.use_ssl is None
True

Note, an AttributeError wasn’t raised because by default, typed_dict will decorate your class so that any unset values which you have declared a type for will be set to None You can disable this as follows

>>> @typed_dict(initialize_with_none=False)
... class StricterConfig(dict):
...        foo: str
...        bar: int
>>> StricterConfig({'foo': 30}).bar
Traceback (most recent call last):
    ...
AttributeError: 'StricterConfig' object has no attribute 'bar'

This makes the object-like treatment of the dict behave closer to how Python would yell at you about accessing missing object attributes.

typed_str

Another handy thing this library gives you is a way to quickly validate a string with a regex, and then store the group match values as attributes on the str, and access them. Here’s a (roughly) complete example

>>> model_pattern = r"([0-9]{4}) (Ford|Toyota) (.+)"
>>> from typycal import typed_str
>>> @typed_str(model_pattern, 'year', 'make', 'name')
... class CarModel(str):
...        year: int
...        make: str
...        name: str
>>> @typed_str(r'(?P<color>[A-Za-z]+) (?P<model>.+)')
... class Car(str):
...     color: str
...     model: CarModel
>>> my_car = Car('Brown 1985 Ford Crown Victoria')

Now we can get attributes for the matches!

>>> my_car.color == "Brown"
True

Nesting and types are honored as well!

>>> my_car.model.year == 1985
True

You can provide a template string as well to support (kinda) mutability.

>>> @typed_str(r'^([0-9]+) things', 'qty', template='{qty} things')
... class Things(str):
...     qty: int
>>> things = Things('20 things')
>>> things.qty = 50
>>> things
50 things

Note however, this only changes the behavior of __str__ and __repr__. See the comparison of the “new” value vs the original string value:

>>> things == '50 things', things == '20 things'
(False, True)

…so you’ll need to explicitly cast

>>> str(things) == '50 things'
True

Change Log

See CHANGELOG.rst

Metadata

Release files for typycal 0.7.0

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

Source distribution (sdist)

Source distribution for typycal 0.7.0
File Size Uploaded Provenance Actions
typycal-0.7.0.tar.gz 8.5 kB Without provenance Details for typycal-0.7.0.tar.gz

Release files / typycal-0.7.0.tar.gz

Download URL typycal-0.7.0.tar.gz
Size 8.5 kB
Tags Source
SHA-256 checksum
How to use checksums
58f6cbb3c13347c411372d8f2949fbce087b12a62cd6af29510d71a9f9191072
BLAKE2b-256 checksum
How to use checksums
aaf1be67262572cd09c55370daefa6e4a0cfae26e0f731b132224c458fba1c80
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/40.4.3 requests-toolbelt/0.8.0 tqdm/4.27.0 CPython/3.6.3

Security for typycal 0.7.0

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.

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