Skip to main content

Overloaded

Dynamic runtime dispatch for overloaded functions using @overload: no need to declare your overloads then implement all the dispatch logic separately!

Features

This package provides features to dynamically dispatch functions and methods to overloads declared with the typing.overload decorator, based on their signatures.

  • Uses the typing.overload decorator directly

  • Supports multiple dispatch

  • Supports many kinds of type annotations, including:

    • Any/Never

    • Numeric-tower matching (int matches float)

    • Unions

    • Literal

    • Recognized genericized collections

    • TypedDict

  • Fully compatible with Pyright

    • Pyright will check the return types of overloads
  • Supports Python 3.12+, and tested on CPython, PyPy, and GraalPy.

Installation

Install using pip:

pip install overloaded

Usage

A function or method can be decorated with the @overloaded decorator to mark the function as overloaded. When called, it will dynamically dispatch to registered overloads. The decorator can also be applied to a class, which automatically dispatches all overloaded methods defined in the class.

@overloaded
def overloaded_function(...): ...

class MyClass:
    @overloaded
    def overloaded_method(...): ...

@overloaded
class MyClass:
    def overloaded_method(...): ...

Overloads not shown. See "Example" section for full setup.

Alternatively, for a class, it is possible to inherit from the Overloaded class or the OverloadedMeta metaclass, providing identical functionality, though these will also carry over to subclasses.

class MyClass(Overloaded): ...

class MyClass(metaclass=OverloadedMeta): ...

Example

from typing import Any, overload
from collections.abc import Iterable, Mapping
from overloaded import overloaded, NoMatchingOverloadError

@overload
def deepmin(item: Mapping) -> Any:
    return min(deepmin(val) for val in item.values())
@overload
def deepmin(item: str | bytes) -> Any:
    return item
@overload
def deepmin(item: Iterable) -> Any:
    return min(deepmin(val) for val in item)
@overload
def deepmin(item: Any) -> Any:
    return item

@overloaded
def deepmin(*args, **kwargs) -> Any:
    raise NoMatchingOverloadError(deepmin)

Dispatch notes

  • Overload functions are expected to have executable code.

  • The first matching overload will be selected.

    • In order for an overload to "match", all required arguments must be passed in the required forms (e.g., positional-only arguments must be passed positionally), and all arguments must be of the types indicated in the function signature.

    • If no overloads match, the "implementation" function will be called. It is recommended for this function to raise NoMatchingOverloadError.

  • Generics

    • For heterogeneous tuples, every element of the input tuple will be checked.

    • For homogeneous tuples and all other Collections, only the first element of the collection will be checked (for Mappings, this is the first key-value pair).

    • Generic Iterable and Callable type annotations are supported, but these match against any iterable/callable object, respectively.

Metadata

Release files for overloaded 0.1.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 overloaded 0.1.0
File Size Uploaded Provenance Actions
overloaded-0.1.0.tar.gz 7.0 kB Without provenance Details for overloaded-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for overloaded 0.1.0
File Interpreter ABI Platform Actions
overloaded-0.1.0-py3-none-any.whl Python 3 none any Details for overloaded-0.1.0-py3-none-any.whl

Total release size: 14.6 kB

Release files / overloaded-0.1.0.tar.gz

Download URL overloaded-0.1.0.tar.gz
Size 7.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a4440f445b6399e18fb9ea68dd705e62c83a07c6d847d30788621f9c29c0fc6c
BLAKE2b-256 checksum
How to use checksums
3038e9a0091706ffa46e20c826101fadebbe151a83926bdc07f654a55c0ea358
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / overloaded-0.1.0-py3-none-any.whl

Download URL overloaded-0.1.0-py3-none-any.whl
Size 7.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
efeb9d255bef0c25a70bed57694841429c9d5433c201a292825992d3c815d946
BLAKE2b-256 checksum
How to use checksums
e3e27cd0e83a4f951b3b01df6fd7afaab21b426cf792de1327bfee50948132e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for overloaded 0.1.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.

Release history Release notifications | RSS feed

This release

0.1.0 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