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 hashes)

Uploaded Source

Built Distribution

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

Uploaded Python 3

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