Skip to content

arguments

arguments #

How a plain argument hashes: a tagged canonical encoding, one registered encoder per type.

UnhashableArgumentError #

Bases: TypeError

A recipe argument whose type has no canonical content hash.

Source code in capturegraph-lib/capturegraph/recipes/values/arguments.py 
15
16
17
18
19
20
21
22
23
24
25
26
class UnhashableArgumentError(TypeError):
    """A recipe argument whose type has no canonical content hash."""

    def __init__(self, param_name: str, value_type: type) -> None:
        """The error for ``param_name`` holding a ``value_type`` value."""
        super().__init__(
            f"Argument {param_name!r} of type {value_type.__name__} cannot be hashed for "
            f"memoization. Pass a CGType value or a plain int/float/bool/str/bytes/None, "
            f"datetime/date/timedelta, or a tuple/list/dict/frozenset of those."
        )
        self.param_name = param_name
        self.value_type = value_type

__init__(param_name, value_type) #

The error for param_name holding a value_type value.

Source code in capturegraph-lib/capturegraph/recipes/values/arguments.py 
18
19
20
21
22
23
24
25
26
def __init__(self, param_name: str, value_type: type) -> None:
    """The error for ``param_name`` holding a ``value_type`` value."""
    super().__init__(
        f"Argument {param_name!r} of type {value_type.__name__} cannot be hashed for "
        f"memoization. Pass a CGType value or a plain int/float/bool/str/bytes/None, "
        f"datetime/date/timedelta, or a tuple/list/dict/frozenset of those."
    )
    self.param_name = param_name
    self.value_type = value_type

argument_hash(param_name, value, schema=None) #

The content hash identifying value as the argument to param_name.

Parameters:

Name Type Description Default
param_name str

The parameter the value is bound to.

 required
value object

The argument value.

 required
schema type[CGType] | None

The type the parameter declares, which a broadcast value — schemaless, so unable to store itself — hashes as.

 None

Raises:

Type Description
UnhashableArgumentError

If value, or anything nested in it, has no encoder.
Source code in capturegraph-lib/capturegraph/recipes/values/arguments.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def argument_hash(
    param_name: str,
    value: object,
    schema: type[CGType] | None = None,
) -> ContentHash:
    """The content hash identifying ``value`` as the argument to ``param_name``.

    Args:
        param_name: The parameter the value is bound to.
        value: The argument value.
        schema: The type the parameter declares, which a broadcast value —
            schemaless, so unable to store itself — hashes as.

    Raises:
        UnhashableArgumentError: If ``value``, or anything nested in it, has no encoder.
    """
    if isinstance(value, CGType):
        return value_hash(value, schema)
    try:
        return hash_bytes(canonical(value), ARG_CONTEXT)
    except _NoEncoder as error:
        raise UnhashableArgumentError(param_name, error.value_type) from None

canonical(value) #

The tagged canonical bytes of a plain argument value.

Register an encoder for a new plain type with @canonical.register; a CGType value encodes as its content hash.

Source code in capturegraph-lib/capturegraph/recipes/values/arguments.py 
59
60
61
62
63
64
65
66
67
68
@singledispatch
def canonical(value: object) -> bytes:
    """The tagged canonical bytes of a plain argument value.

    Register an encoder for a new plain type with ``@canonical.register``; a
    ``CGType`` value encodes as its content hash.
    """
    if isinstance(value, CGType):
        return b"C" + value_hash(value).hex.encode()
    raise _NoEncoder(type(value))