jgdv.structs.dkey._util._interface

Type Aliases

LitFalse

Protocols

`Expandable_p`	An expandable, like a DKey,
`Expander_p`	Base class for protocol classes.
`ExpansionHooks_p`	Base class for protocol classes.
`InstructionFactory_p`	Base class for protocol classes.

Classes

`ExpInstChain_d`
`ExpInst_d`	The lightweight holder of expansion instructions, passed through the
`SourceChain_d`	The core logic to lookup a key from a sequence of sources

Module Contents

jgdv.structs.dkey._util._interface.LitFalse: TypeAlias = Literal[False]

class jgdv.structs.dkey._util._interface.Expandable_p[source]

Bases: Protocol

An expandable, like a DKey, uses these hooks to customise the expansion

expand(*sources, **kwargs) → <Unknown>[source]

Return type:: jgdv.Maybe

class jgdv.structs.dkey._util._interface.Expander_p[source]

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

coerce_result(inst, opts, *, source) → <Unknown>[source]

Parameters:

inst (ExpInst_d)
opts (ExpOpts)
source (jgdv.structs.dkey._interface.Key_p)

Return type:

jgdv.Maybe[ExpInst_d]

expand(source, *sources, **kwargs) → <Unknown>[source]

Parameters:

source (T)
sources (dict)
kwargs (Any)

Return type:

jgdv.Maybe[ExpInst_d]

extra_sources(source) → <Unknown>[source]

Parameters:: source (T)
Return type:: SourceChain_d

redirect(source, *sources, **kwargs) → <Unknown>[source]

Parameters:

source (T)
sources (dict)
kwargs (Any)

Return type:

list[jgdv.Maybe[ExpInst_d]]

set_ctor(ctor) → <Unknown>[source]

Parameters:: ctor (jgdv.CtorFn[Ellipsis, T])
Return type:: None

class jgdv.structs.dkey._util._interface.ExpansionHooks_p[source]

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

exp_check_result_h(inst, opts) → <Unknown>[source]

Parameters:

inst (jgdv.Maybe[ExpInst_d])
opts (dict)

Return type:

None

exp_coerce_h(inst, factory, opts) → <Unknown>[source]

Parameters:

inst (ExpInst_d)
factory (InstructionFactory_p)
opts (dict)

Return type:

jgdv.Maybe[ExpInst_d]

exp_extra_sources_h(current) → <Unknown>[source]

Parameters:: current (SourceChain_d)
Return type:: SourceChain_d

exp_final_h( inst, root, factory, opts, ) → <Unknown>[source]

Parameters:

inst (ExpInst_d)
root (jgdv.Maybe[ExpInst_d])
factory (InstructionFactory_p)
opts (dict)

Return type:

jgdv.Maybe[ExpInst_d]

exp_flatten_h(values, factory, opts) → <Unknown>[source]

Parameters:

values (list[jgdv.Maybe[ExpInst_d]])
factory (InstructionFactory_p)
opts (dict)

Return type:

jgdv.Maybe[ExpInst_d]

exp_generate_chains_h( root, factory, opts, ) → <Unknown>[source]

Parameters:

root (ExpInst_d)
factory (InstructionFactory_p)
opts (ExpOpts)

Return type:

list[ExpInstChain_d | ExpInst_d]

exp_to_inst_h(

root,

factory,

**kwargs,

) → <Unknown>[source]

Parameters:

root (ExpInst_d)
factory (InstructionFactory_p)
kwargs (Any)

Return type:

jgdv.Maybe[ExpInst_d]

class jgdv.structs.dkey._util._interface.InstructionFactory_p[source]

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

build_chains(val, opts) → <Unknown>[source]

Parameters:

val (ExpInst_d)
opts (ExpOpts)

Return type:

list[ExpInstChain_d | ExpInst_d]

build_inst( val, root, opts, *, decrement=True, ) → <Unknown>[source]

Parameters:

val (jgdv.Maybe)
root (jgdv.Maybe[ExpInst_d])
opts (ExpOpts)
decrement (bool)

Return type:

jgdv.Maybe[ExpInst_d]

lift_inst( val, root, opts, *, decrement=False, implicit=False, ) → <Unknown>[source]

Parameters:

val (str)
root (jgdv.Maybe[ExpInst_d])
opts (ExpOpts)
decrement (bool)
implicit (bool)

Return type:

ExpInst_d

literal_inst(val) → <Unknown>[source]

Parameters:: val (Any)
Return type:: ExpInst_d

null_inst() → <Unknown>[source]

Return type:: ExpInst_d

class jgdv.structs.dkey._util._interface.ExpInstChain_d(*chain, root, merge=None)[source]

Parameters:

chain (ExpInst_d)
root (jgdv.structs.dkey._interface.Key_p)
merge (jgdv.Maybe[int])

chain: tuple[ExpInst_d, Ellipsis]

merge: jgdv.Maybe[int]

root: jgdv.structs.dkey._interface.Key_p

class jgdv.structs.dkey._util._interface.ExpInst_d(**kwargs)[source]

The lightweight holder of expansion instructions, passed through the expander mixin. Uses slots to make it as lightweight as possible

fallback : the value to use if expansion fails
convert : controls type coercion of expansion result
lift : says to lift expanded values into keys themselves (using !L in the key str)
literal : signals the value needs no more expansion
rec : the remaining recursive expansions available. -1 is unrestrained.
total_recs : tracks the number of expansions have occured

process_value() → <Unknown>[source]

Return type:: None

convert: jgdv.Maybe[str | bool]

fallback: jgdv.Maybe[str]

lift: bool | tuple[bool, bool]

literal: bool

rec: jgdv.Maybe[int]

total_recs: int

value: Any

class jgdv.structs.dkey._util._interface.SourceChain_d(*args)[source]

The core logic to lookup a key from a sequence of sources

Doesn’t perform repeated expansions.
Tries sources in order.
A Source that is a list is copied and each retrieval pops a value off it

TODO replace this with collections.ChainMap ?

Parameters:: args (jgdv.Maybe[SourceBases | SourceChain_d])

extend(*args) → <Unknown>[source]

Parameters:: args (SourceBases)
Return type:: SourceChain_d

get(key, fallback=None) → <Unknown>[source]

Get a key’s value from an ordered sequence of potential sources.

Parameters:

key (str)
fallback (jgdv.Maybe)

Return type:

jgdv.Maybe

lookup(target) → <Unknown>[source]

Look up alternatives

pass through DKeys and (DKey, ..) for recursion
lift (str(), True, fallback)
don’t lift (str(), False, fallback)

Parameters:: target (ExpInstChain_d)
Return type:: jgdv.Maybe[ExpInst_d | tuple]

sources: list[collections.abc.Mapping | list]