Skip to main content

Reuse generic class type arguments at runtime.

Project description

runtime_generics
skeleton Supported Python versions Package version

Tests Coverage Lifted?

Highly into type-safe Python code?

runtime_generics is a niche Python library that allows you to reuse type arguments explicitly passed at runtime to generic classes before instantiation.

The library does four things:

  • exposes utilities that allow to inspect C3-linearized MROs of runtime generics and type-check them with variance support: get_mro(), type_check();
  • makes it possible to retrieve the type arguments passed to the generic class at runtime before the class was instantiated: get_type_arguments(), get_alias();
  • offers facilities to find how parent classes are parametrized ( e.g. if Foo[T] inherits from Dict[str, T], finds that Dict[str, int] is a parent for Foo[int] ): get_parents();
  • given a parametrized generic class (generic alias), makes every class method use generic alias cls instead of the origin class (unless decorated with @no_alias).

A Simple Example

3.12+ (PEP 695 syntax):

from __future__ import annotations

import io
from typing import TYPE_CHECKING

from runtime_generics import get_alias, get_type_arguments, runtime_generic, type_check

if TYPE_CHECKING:
    from typing import IO, Literal, overload


@runtime_generic
class IOWrapper[T: str | bytes]:
    data_type: type[T]

    def __init__(self, stream: IO[T]) -> None:
        (self.data_type,) = get_type_arguments(self)
        self.stream = stream

    if TYPE_CHECKING:
        @overload
        def is_binary(self: IOWrapper[bytes]) -> Literal[True]: ...

        @overload
        def is_binary(self: IOWrapper[str]) -> Literal[False]: ...

    def is_binary(self) -> bool:
        # alternatively here: `self.data_type == bytes`
        return type_check(self, IOWrapper[bytes])

    def __repr__(self) -> str:
        return f"<{get_alias(self)} object at ...>"


my_binary_data = IOWrapper[bytes](io.BytesIO(b"foo"))
assert my_binary_data.data_type is bytes
assert my_binary_data.is_binary()
assert repr(IOWrapper[str](io.StringIO())) == "<__main__.IOWrapper[str] object at ...>"

3.8+:

from __future__ import annotations

import io
from typing import TYPE_CHECKING, Generic, TypeVar

from runtime_generics import get_alias, get_type_arguments, runtime_generic, type_check

if TYPE_CHECKING:
    from typing import IO, Literal, overload

T = TypeVar("T", str, bytes)


@runtime_generic
class IOWrapper(Generic[T]):
    data_type: type[T]

    def __init__(self, stream: IO[T]) -> None:
        (self.data_type,) = get_type_arguments(self)
        self.stream = stream

    if TYPE_CHECKING:
        @overload
        def is_binary(self: IOWrapper[bytes]) -> Literal[True]: ...

        @overload
        def is_binary(self: IOWrapper[str]) -> Literal[False]: ...

    def is_binary(self) -> bool:
        # alternatively here: `self.data_type == bytes`
        return type_check(self, IOWrapper[bytes])

    def __repr__(self) -> str:
        return f"<{get_alias(self)} object at ...>"


my_binary_data = IOWrapper[bytes](io.BytesIO(b"foo"))
assert my_binary_data.data_type is bytes
assert my_binary_data.is_binary()
assert repr(IOWrapper[str](io.StringIO())) == "<__main__.IOWrapper[str] object at ...>"

For Enterprise

Tidelift Available as part of the Tidelift Subscription.
This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use. Learn more here.

To report a security vulnerability, please use the Tidelift security contact.
Tidelift will coordinate the fix and disclosure.

Installation

You might simply install it with pip:

pip install runtime-generics

If you use Poetry, then you might want to run:

poetry add runtime-generics

For Contributors

Poetry Ruff Pre-commit

[!Note] If you use Windows, it is highly recommended to complete the installation in the way presented below through WSL2.

  1. Fork the runtime_generics repository on GitHub.

  2. Install Poetry.
    Poetry is an amazing tool for managing dependencies & virtual environments, building packages and publishing them. You might use pipx to install it globally (recommended):

    pipx install poetry
    

    If you encounter any problems, refer to the official documentation for the most up-to-date installation instructions.

    Be sure to have Python 3.8 installed—if you use pyenv, simply run:

    pyenv install 3.8
    
  3. Clone your fork locally and install dependencies.

    git clone https://github.com/your-username/runtime_generics path/to/runtime_generics
    cd path/to/runtime_generics
    poetry env use $(cat .python-version)
    poetry install
    

    Next up, simply activate the virtual environment and install pre-commit hooks:

    poetry shell
    pre-commit install
    

For more information on how to contribute, check out CONTRIBUTING.md.
Always happy to accept contributions! ❤️

Legal Info

© Copyright by Bartosz Sławecki (@bswck).
This software is licensed under the terms of MIT License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

runtime_generics-3.3.1.tar.gz (13.1 kB view details)

Uploaded Source

Built Distribution

runtime_generics-3.3.1-py3-none-any.whl (10.9 kB view details)

Uploaded Python 3

File details

Details for the file runtime_generics-3.3.1.tar.gz.

File metadata

  • Download URL: runtime_generics-3.3.1.tar.gz
  • Upload date:
  • Size: 13.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for runtime_generics-3.3.1.tar.gz
Algorithm Hash digest
SHA256 1ea40ad2b735aed3cdf567efac980e4dbc9c9e9e76144c4f73d1dd440583ffb1
MD5 ea7ff2acc60658d05ce246e74c0e9d6b
BLAKE2b-256 b934b1b82a4f623d61fccc21361e402dbee87338bc03a018844d51f5c7eb368c

See more details on using hashes here.

Provenance

File details

Details for the file runtime_generics-3.3.1-py3-none-any.whl.

File metadata

File hashes

Hashes for runtime_generics-3.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bf9c74a17cece2f874b3e3f6d1857fd5313c789f8f0854ac4f7669f91ad748ad
MD5 1ee6a6afd6c1bc77fb75e5023adcefc5
BLAKE2b-256 ce5de73ddf67bf269d290413d5805a485856c7abb15fa4a070935fd250f2c3a3

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page