Integration Cheat Sheet

Use this page as a copy-ready reference while integrating ArgDigest.

It is intentionally compact and practical. Use it while coding, then return to the full User Guide for rationale and migration details.

Minimum files

mylib/
  _argdigest.py
  basic.py
  _private/argdigest/
    argument/          # axis 2: one module per argument name
      selection.py
    function/          # axis 1: one module per function or family
      get.py
    domain/            # axis 1: named sets of admissible keywords
      attribute.py
    normalization/     # argument-name aliases, applied before both axes
      synonyms.py

_argdigest.py

DIGESTION_SOURCE = "mylib._private.argdigest.argument"
DIGESTION_STYLE = "package"
STRICTNESS = "warn"
SKIP_PARAM = "skip_digestion"

FUNCTION_SOURCE = "mylib._private.argdigest.function"
DOMAIN_SOURCE = "mylib._private.argdigest.domain"
UNKNOWN_ARGUMENT = "error"
NORMALIZATION_SOURCE = "mylib._private.argdigest.normalization"

Contract file (only for functions taking **kwargs)

from argdigest import FunctionContract

contract = FunctionContract(caller="mylib.basic.get.get", admits="attribute")

A closed signature needs no file: it is held to its own parameters automatically.

Alias table file

from argdigest import AliasTable

table = AliasTable(aliases={"residue_index": "group_index"})

Scope it with applies_to when the alias only means that in one function, and guard it with when when it depends on another argument.

Domain file

from argdigest import Domain
from mylib.attribute import attributes, is_attribute

domain = Domain(name="attribute", contains=is_attribute,
                members=lambda: tuple(attributes))

Digester file

def digest_selection(selection, caller=None):
    if selection is None:
        return "all"
    if isinstance(selection, str):
        return selection
    raise ValueError(f"Invalid selection in {caller}: {selection!r}")

Decorated function

from argdigest import arg_digest

@arg_digest(config="mylib._argdigest")
def get(molecular_system, selection=None, skip_digestion=False):
    return molecular_system, selection

First tests to run

Start with three checks: selection=None is normalized to "all", invalid selection raises an error, and skip_digestion=True bypasses digestion when that path is enabled.

Immediate benefits

With this minimal integration, you already get shared argument rules across functions, cleaner business logic with less inline checking, and more predictable user-facing errors.