Skip to main content

✒️ simplibs-signature

PyPI Python Licence tests

Say what a wrapper really accepts — and let tools believe it.

A Python library for building, copying and changing the signature of a function. A wrapper that takes (*args, **kwargs) hides everything from your editor, from help() and from documentation generators; this library gives it the signature it really has — copied from the function it wraps, assembled from parameters and other functions, or written by hand — and keeps it valid: the parameters always end up in the order Python requires, a name is never there twice, and a second *args can never sneak in. A wrong call is a structured card that says what and how to fix it.

import inspect
from simplibs.signature import signature_copy

def original(a: int, b: str = "x", *args, **kwargs) -> bool: ...

@signature_copy(original, excepts=["b"])
def wrapper(*args, **kwargs):
    ...

str(inspect.signature(wrapper))     # -> '(a: int, *args, **kwargs) -> bool'

The decorators change only what inspect reports. They do not check or change how the wrapper is called — the call goes through unchanged. The signature describes the call; it does not enforce it.


🧭 The Core Philosophy

Writing a signature by hand means inspect.Parameter("x", inspect.Parameter.KEYWORD_ONLY, ...) four times over, then finding the right place for each parameter — required before optional, *args before the keyword-only ones, never anything after **kwargs — and inspect.Signature itself checks surprisingly little: it accepts (*a, *b) without a word. simplibs-signature takes the chore over:

  • A signature is built, not patched. Every parameter goes through one collector that keeps the order valid whatever the order you add them in. You say what goes in, never where.
  • Sources in, priority by order. A source is an inspect.Parameter or any callable (all its parameters are taken). Sources are merged in the order given, and with the default settings the later one wins a name collision — so the order of your arguments is the priority.
  • One *args, one **kwargs. A signature holds one of each. A second one is a collision even under another name (*a after *args) and is settled by the same rules as any duplicate.
  • Nothing is changed behind your back. The decorators wrap, the modifiers return a new signature, the original stays as it was. The one function that changes an object in place says so in its name: set_signature.
  • Names are filtered by what they are. include_variadic=False leaves out every *args and **kwargs by their kind, however they are called; self and cls, which have no kind of their own, are recognised by name.
  • Functions first, decorators on top. The logic lives in functions you can call on their own; the decorators are thin wrappers over them.
  • Every error is a card. A wrong call is a ParamError from simplibs-exception — what was given, what was expected, how to fix it — and it points at your code, not at the library's insides.
  • Layers that only look left. constants ← collector ← tools ← orchestrators ← decorators — every layer imports only from those before it.
create_signature(f, g, accept_double=False)    # -> raises: DUPLICATE PARAMETER ERROR — 'rest' collides with the already defined variadic positional parameter 'args'
create_signature(f, 5)                         # -> raises: ValidationError — a source must be a Parameter or a callable

📦 Installation

pip install simplibs-signature

Requires Python 3.11+. Runtime dependencies: simplibs-exception (the error cards), simplibs-validate (@validate_call on every public function) and simplibs-sentinels (UNSET, the marker of "not given" — None is a valid return annotation, so it cannot play that part).


🚀 Quick Start in 60 Seconds

Level 1: Give a wrapper the signature it really has

import inspect
from simplibs.signature import signature, signature_copy, signature_set
from simplibs.signature import create_keyword_parameter, create_positional_parameter

def original(a: int, b: str = "x", *args, **kwargs) -> bool: ...

# copy another function's signature, with changes
@signature_copy(original, excepts=["b"])
def wrapper(*args, **kwargs): ...
str(inspect.signature(wrapper))       # -> '(a: int, *args, **kwargs) -> bool'

# start from the function itself and add to it
@signature(create_keyword_parameter("timeout", annotation=float, default=3.0), returns=int)
def fetch(url: str, *, retries: int = 2): ...
str(inspect.signature(fetch))         # -> '(url: str, *, retries: int = 2, timeout: float = 3.0) -> int'

# or attach a finished signature
fixed = inspect.Signature([
    create_positional_parameter("x", annotation=int),
    create_keyword_parameter("verbose", annotation=bool, default=False),
])

@signature_set(fixed)
def anything(*args, **kwargs): ...
str(inspect.signature(anything))      # -> '(x: int, *, verbose: bool = False)'

Level 2: Build a signature from any mix of sources

import inspect
from simplibs.signature import create_signature, copy_signature

def f(a, *args, b=1): ...
def g(c, *rest): ...

create_signature(f, g)                                # -> (a, c, *rest, b=1)      the later *rest replaces *args
create_signature(f, g, replace_double=False)          # -> (a, c, *args, b=1)      the earlier one stays
create_signature(f, g, include_variadic=False)        # -> (a, c, *, b=1)
create_signature(f, g, flat_to_kwargs=True)           # -> (*, a, b=1, c)          everything keyword-only
create_signature(f, return_source=int)                # -> (a, *args, b=1) -> int

copy_signature(g, extra_params=[inspect.Parameter("z", inspect.Parameter.KEYWORD_ONLY)])   # -> (c, *rest, z)

Level 3: Change a signature you already have

import inspect
from simplibs.signature import (
    add_params_to_signature, delete_params_from_signature, replace_return_annotation_in_signature,
    create_keyword_parameter,
)

sig = inspect.signature(original)       # (a: int, b: str = 'x', *args, **kwargs) -> bool

add_params_to_signature(sig, [create_keyword_parameter("dry_run", annotation=bool, default=False)])
# -> (a: int, b: str = 'x', *args, dry_run: bool = False, **kwargs) -> bool

delete_params_from_signature(sig, ["b", "kwargs"])           # -> (a: int, *args) -> bool
replace_return_annotation_in_signature(sig, int)             # -> (a: int, b: str = 'x', *args, **kwargs) -> int

Level 4: The collector, when you want full control

from simplibs.signature import ParameterCollector, compose_signature

collector = ParameterCollector(include_variadic=False)
collector.add_params(inspect.signature(original).parameters.values())

[p.name for p in collector.get_ordered_params()]             # -> ['a', 'b']
compose_signature(collector.get_ordered_params(), int)       # -> (a: int, b: str = 'x') -> int

🛠️ Architecture & Package Structure

src/simplibs/signature/
├── constants/            ◄── ARGS, KWARGS — ready-made *args and **kwargs parameters
├── collector/            ◄── ParameterCollector — one valid, ordered set of parameters
├── tools/                ◄── The small building blocks
│   ├── parameters/       ◄── create_keyword_parameter, create_positional_parameter
│   ├── operations/       ◄── get_signature, set_signature, compose_signature
│   └── modifiers/        ◄── add_params_to_signature, delete_params_from_signature, replace_return_annotation_in_signature
├── orchestrators/        ◄── create_signature, copy_signature — the high-level builders
└── decorators/           ◄── signature, signature_copy, signature_set (+ builders)

Everything public is importable straight from simplibs.signature:

from simplibs.signature import (
    signature, signature_copy, signature_set,        # decorators
    create_signature, copy_signature,                # builders
    ParameterCollector,                              # the collector
    get_signature, set_signature, compose_signature, # operations
    add_params_to_signature, delete_params_from_signature, replace_return_annotation_in_signature,
    create_positional_parameter, create_keyword_parameter,
    apply_signature_to_wraps, create_signature_decorator,
    ARGS, KWARGS,
)

The options every builder shares

The same options mean the same thing in create_signature, copy_signature, the decorators and — where they are offered — the modifiers and the collector itself.

Option Default Meaning
accept_double True If False, a name collision raises a ParamError. If True, replace_double decides.
replace_double True Who wins a collision: the later parameter (True) or the earlier one (False).
include_variadic True If False, every *args and **kwargs is left out, whatever it is called.
include_binding True If False, parameters named self and cls are left out.
flat_to_kwargs False Everything keyword-only; *args dropped, all **kwargs merged into one.
_validate_call True Reserved switch of @validate_call: False skips the validation of the arguments.

Parameters that take several values — excepts, extras, excluded_names, extra_params, params_to_add, parameters — accept any iterable: a list, a tuple, a set or a generator. Every public function with such a parameter is decorated with @validate_call(materialize_iterators=True) (from simplibs-validate), so a generator is read once and the function receives a tuple that it can read again; its items are still validated. With _validate_call=False nothing is validated or converted, so pass a list or a tuple there.


🎀 decorators/ — Give a wrapper its real signature

Three decorators that differ in where the signature comes from, and the two builders they are made of. Each returns a transparent wrapper — sync or async, as the function is — that reports the new signature to inspect, and leaves the original function untouched.

Name Description / Parameters
signature Assembles the signature from sources and, by default, the function itself (*params, returns, excepts, use_func, func_first, + shared options).
signature_copy Copies another callable's signature, with changes (base_func, returns, extras, excepts, + shared options).
signature_set Attaches a finished inspect.Signature (signature).
create_signature_decorator Turns a finished signature into a reusable decorator (signature).
apply_signature_to_wraps Wraps one function in a transparent wrapper with a given signature (function, signature).

➡️ README_SIGNATURE_DECORATORS


🎼 orchestrators/ — Build a whole signature in one call

The high-level builders. They combine the collector with the tools: load the sources, settle the return annotation, compose and validate the result.

Function Description / Parameters
create_signature A signature from any mix of parameters and callables (*param_sources, return_source, excluded_names, + shared options).
copy_signature A changed copy of one callable's signature (function, return_annotation, extra_params, excluded_names, + shared options).

➡️ README_SIGNATURE_ORCHESTRATORS


🧺 collector/ — One valid, ordered set of parameters

The engine behind everything above, and a class you can use yourself. It excludes what you do not want, settles name collisions, keeps the order Python requires and, in flat mode, turns everything into one keyword-only API.

Member Description / Parameters
ParameterCollector The collector (excluded_names, accept_double, replace_double, include_variadic, include_binding, flat_to_kwargs).
add_param Adds one parameter (param).
add_params Adds several, one after another (params).
get_ordered_params Returns the stored parameters in the order Python requires; a tuple.

➡️ README_SIGNATURE_PARAMETER_COLLECTOR


🔧 tools/ — The small building blocks

Independent functions: create a parameter, read, build and attach a signature, change a signature. They know nothing about the orchestrators or the decorators above them.

Function Group Description / Parameters
create_positional_parameter parameters A positional-only or ordinary parameter (name, annotation, default, positional_only).
create_keyword_parameter parameters A keyword-only parameter (name, annotation, default).
get_signature operations Reads a signature, with a readable failure (function).
set_signature operations Attaches a signature through __signature__ — changes the function itself (function, signature).
compose_signature operations Builds an inspect.Signature and always checks its structure (parameters, return_annotation).
add_params_to_signature modifiers A copy of a signature with parameters added (signature, params_to_add, accept_double, replace_double, flat_to_kwargs).
delete_params_from_signature modifiers A copy of a signature without the named parameters (signature, excluded_names).
replace_return_annotation_in_signature modifiers A copy of a signature with another return annotation (signature, new_return_annotation).
ARGS, KWARGS constants Ready-made *args and **kwargs parameters.

➡️ README_SIGNATURE_TOOLS


⚠️ Exceptions

The library defines no exceptions of its own. A wrong call is a structured simplibs.exception ParamError card; its label names the offending part and its value is what was given. Where a card wraps a standard exception, that type is in its MRO, so an existing except ValueError: keeps working. An argument of the wrong type is a ValidationError raised by @validate_call before the function runs.

Error name Wraps Raised when
DUPLICATE PARAMETER ERROR ValueError A name — or a second *args / **kwargs — collides and accept_double=False
INVALID PARAMETER ORDER SyntaxError A required positional parameter would follow an optional one
INVALID PARAMETER KIND ERROR KeyError A parameter has a kind the collector cannot store
INVALID PARAMETER SOURCE TypeError A source of create_signature is neither a Parameter nor a callable
INVALID DEFAULT VALUE TypeError A default value contradicts a plain-class annotation
SIGNATURE INTROSPECTION ERROR ValueError, TypeError get_signature cannot read the signature of an object
SIGNATURE COMPOSITION ERROR ValueError, AttributeError, TypeError compose_signature gets parameters that do not form a signature
SIGNATURE STRUCTURE ERROR ValueError add_params_to_signature produces a structure inspect refuses
SIGNATURE TYPE ERROR TypeError add_params_to_signature meets a parameter of an unusable type

Every card points at your call: all simplibs frames are left out of the reported location, and only if nothing else is left does it fall back to the last one. Each helper README ends with the errors of its own package.


  • simplibs-exception — the structured exception cards behind every error here.
  • simplibs-validate — @validate_call, which checks the arguments of every public function; its reserved _validate_call switch is the one these functions share.
  • simplibs-sentinels — UNSET, the marker of a value that was not given.

☯️ About simplibs

All libraries in the simplibs (Simple Libraries) ecosystem share a common engineering philosophy:

  • Dyslexia-friendly: We actively minimize cognitive load. Code is atomized into small, self-contained units, files are named directly after the logical task they perform, and explanations describe why something is designed, not just what it is.
  • Programmer's Zen: Nothing should be missing, and nothing should be superfluous. We value clean execution paths and robust, understandable code architectures over rushed, messy feature sets.
  • Defensive Style: We actively anticipate edge cases and failure modes so that only safe operational paths remain. Our code is built to degrade gracefully rather than crash unexpectedly.
  • Minimalism: Find the most direct path to the goal in as few operational steps as possible without taking shortcuts on safety, readability, or completeness.
  • Code as Craft: Code should be pleasant to look at, readable at a glance, and evoke structural harmony. We treat software engineering as a precision trade.

🤝 Contributing & Community

This is an open-source project built with love and care. We strongly believe in community collaboration and welcome any feedback, bug reports, or feature ideas!

  • Want to contribute? Feel free to open an Issue or submit a Pull Request.
  • Want to get in touch? If you'd like to discuss the project further, collaborate, or just say hello, feel free to open a GitHub Issue or start a Discussion.

📝 License

This library is released under the MIT License. Build great things!


Metadata

Release files for simplibs-signature 0.3.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 simplibs-signature 0.3.0
File Size Uploaded Provenance Actions
simplibs_signature-0.3.0.tar.gz 49.7 kB Without provenance Details for simplibs_signature-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simplibs-signature 0.3.0
File Interpreter ABI Platform Actions
simplibs_signature-0.3.0-py3-none-any.whl Python 3 none any Details for simplibs_signature-0.3.0-py3-none-any.whl

Total release size: 125.0 kB

Release files / simplibs_signature-0.3.0.tar.gz

Download URL simplibs_signature-0.3.0.tar.gz
Size 49.7 kB
Tags Source
SHA-256 checksum
How to use checksums
1153903ca3708687fb65c7a25720272bb66d9e36c7659f73af0fdbac1a06ff43
BLAKE2b-256 checksum
How to use checksums
d9948484f2cbde22d72cf20be04872e82697d27add7a673d78eaf5b56ffb4d81
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / simplibs_signature-0.3.0-py3-none-any.whl

Download URL simplibs_signature-0.3.0-py3-none-any.whl
Size 75.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bb02bddf5963f8781bea36916ffbffe306547107dc99eec5aa21bc7ae6e44ada
BLAKE2b-256 checksum
How to use checksums
277f975b89c360a91fd39d4eae42def1faf9c49c399bdb5d72aa6eb8eae663e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for simplibs-signature 0.3.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