jgdv.structs.strang._interface

The Interface for Strang.

Strang Enums: - StrangMarkAbstract_e

Describes the internal data structs: - Sec_d : A Single section spec - Sections_d : Collects the sec_d’s. ClassVar - Strang_d : Instance data of a strang beyond the normal str’s

Type Aliases

`FindSlice`
`FullSlice`
`ItemIndex`
`MSlice`
`MarkIndex`
`PushVal`
`SectionIndex`
`WordIndex`

Enums

StrangMarkAbstract_e

Enum where members are also (and must be) strings

Protocols

`Importable_p`	Marks a class as able to import code. Userd for CodeRef's.
`StrangFormatter_p`	A string.Formatter with some Strang-specific methods
`StrangMod_p`	Base class for protocol classes.
`StrangUUIDs_p`	Base class for protocol classes.
`Strang_p`	The Main protocol describing a Strang.

Classes

`CodeRefHeadMarks_e`	Available Group values of CodeRef strang's
`DefaultBodyMarks_e`	Markers Used in a base Strang's body
`DefaultHeadMarks_e`	Markers used in a Strang's head
`Sec_d`	Data of a named Strang section
`Sections_d`	An object to hold information about word separation and sections,
`Strang_d`	Extra Data of a Strang.

Module Contents

jgdv.structs.strang._interface.FindSlice: TypeAlias = str | StrangMarkAbstract_e | WordIndex | MarkIndex

jgdv.structs.strang._interface.FullSlice: TypeAlias = slice[None, None, None]

jgdv.structs.strang._interface.ItemIndex: TypeAlias = SectionIndex | FullSlice | MSlice | tuple[ItemIndex, ...]

jgdv.structs.strang._interface.MSlice: TypeAlias = slice[Maybe[int], Maybe[int], Maybe[int]]

jgdv.structs.strang._interface.MarkIndex: TypeAlias = tuple[SectionIndex, StrangMarkAbstract_e]

jgdv.structs.strang._interface.PushVal: TypeAlias = Maybe[str | StrangMarkAbstract_e | UUID]

jgdv.structs.strang._interface.SectionIndex: TypeAlias = str | int

jgdv.structs.strang._interface.WordIndex: TypeAlias = tuple[SectionIndex, int]

class jgdv.structs.strang._interface.StrangMarkAbstract_e[source]

Bases: enum.StrEnum

Enum where members are also (and must be) strings

classmethod default() → <Unknown>[source]

Return type:: jgdv.Maybe

classmethod idempotent() → <Unknown>[source]

Return type:: set[str]

classmethod implicit() → <Unknown>[source]

Return type:: set

classmethod skip() → <Unknown>[source]

Return type:: jgdv.Maybe[StrangMarkAbstract_e.skip.T]

class jgdv.structs.strang._interface.Importable_p[source]

Bases: Protocol

Marks a class as able to import code. Userd for CodeRef’s.

_does_imports() → <Unknown>[source]

Return type:: Literal[True]

class jgdv.structs.strang._interface.StrangFormatter_p[source]

Bases: Protocol

A string.Formatter with some Strang-specific methods

convert_field(value, conversion) → <Unknown>[source]

Parameters:

value (Any)
conversion (Any)

Return type:

str

expanded_str(data, *, stop=None) → <Unknown>[source]

Parameters:

data (Strang_p)
stop (jgdv.Maybe[int])

Return type:

str

format(

format_string,

/,

*args,

**kwargs,

) → <Unknown>[source]

Parameters:

format_string (str)
args (Any)
kwargs (Any)

Return type:

str

get_value(key, args, kwargs) → <Unknown>[source]

Parameters:

key (str)
args (Any)
kwargs (Any)

Return type:

str

class jgdv.structs.strang._interface.StrangMod_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:
        ...

pop(*, top=False) → <Unknown>[source]

Parameters:: top (bool)
Return type:: Strang_p

push(*vals) → <Unknown>[source]

Parameters:: vals (PushVal)
Return type:: Strang_p

class jgdv.structs.strang._interface.StrangUUIDs_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:
        ...

de_uniq() → <Unknown>[source]

Return type:: Self

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

Parameters:: args (str)
Return type:: Self

class jgdv.structs.strang._interface.Strang_p[source]

Bases: StrangUUIDs_p, StrangMod_p, jgdv._abstract.protocols.str.String_p, Protocol

The Main protocol describing a Strang.

args() → <Unknown>[source]

Return type:: jgdv.Maybe[tuple]

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

Parameters:: args (SectionIndex | WordIndex)
Return type:: Any

index(*sub, start=None, end=None) → <Unknown>[source]

index

Extended str.index, to handle marks and word slices

Parameters:

sub (FindSlice) – The indices to slice
start (jgdv.Maybe[int]) – The start of the slice to cover.
end (jgdv.Maybe[int]) – The end of the slice to cover.

Returns:

The index of the char

Return type:

int

rindex( *sub, start=None, end=None, ) → <Unknown>[source]

Parameters:

sub (FindSlice)
start (jgdv.Maybe[int])
end (jgdv.Maybe[int])

Return type:

int

classmethod section(arg) → <Unknown>[source]

Parameters:: arg (int | str)
Return type:: Sec_d

classmethod sections() → <Unknown>[source]

Return type:: Sections_d

uuid() → <Unknown>[source]

Return type:: jgdv.Maybe[uuid.UUID]

words(idx, *, case=False) → <Unknown>[source]

Parameters:

idx (SectionIndex)
case (bool)

Return type:

list

_formatter: ClassVar[string.Formatter]

_processor: ClassVar[jgdv._abstract.protocols.pre_processable.PreProcessor_p]

_sections: ClassVar[Sections_d]

property base: Self[source]

Return type:: Self

data: Strang_d

property shape: tuple[int, Ellipsis][source]

Return type:: tuple[int, Ellipsis]

class jgdv.structs.strang._interface.CodeRefHeadMarks_e[source]

Bases: StrangMarkAbstract_e

Available Group values of CodeRef strang’s

classmethod default() → <Unknown>[source]

Return type:: str

classmethod idempotent() → <Unknown>[source]

Return type:: set[str]

cls = 'cls'

fn = 'fn'

module = 'module'

val = 'value'

value = 'value': The value of the Enum member.

class jgdv.structs.strang._interface.DefaultBodyMarks_e[source]

Bases: StrangMarkAbstract_e

Markers Used in a base Strang’s body

classmethod default() → <Unknown>[source]

Return type:: str

classmethod idempotent() → <Unknown>[source]

Return type:: set[str]

classmethod implicit() → <Unknown>[source]

Return type:: set[str]

classmethod skip() → <Unknown>[source]

Return type:: jgdv.Maybe[DefaultBodyMarks_e]

empty = ''

extend = '+'

gen = '$gen$'

head = '$head$'

hide = '_'

class jgdv.structs.strang._interface.DefaultHeadMarks_e[source]

Bases: StrangMarkAbstract_e

Markers used in a Strang’s head

basic = '$basic$'

class jgdv.structs.strang._interface.Sec_d( name, case, end, types, marks, required=True, *, idx=-1, )[source]

Data of a named Strang section

for an example section ‘a.2.c.+::d’ - case : the word boundary. = ‘.’ - end : the rhs end str. = ‘::’ - types : allowed types. = str|int - marks : StrangMarkAbstract_e of words with a meta meaning. = ‘+’ - required : a strang errors if a required section isnt found

idx : the index of the section

TODO Maybe ‘type_re’ and ‘mark_re’

Parameters:

name (str)
case (jgdv.Maybe[str])
end (jgdv.Maybe[str])
types (type | types.UnionType)
marks (jgdv.Maybe[type[StrangMarkAbstract_e]])
required (bool)
idx (int)

case: Final[jgdv.Maybe[str]]

end: Final[jgdv.Maybe[str]]

idx: int

marks: Final[jgdv.Maybe[type[StrangMarkAbstract_e]]]

name: Final[str]

required: Final[bool]

types: Final[type | types.UnionType]

class jgdv.structs.strang._interface.Sections_d(*sections)[source]

An object to hold information about word separation and sections, a strang type is structured into these

Each Section is a Sec_d TODO add format conversion specs

Parameters:: sections (tuple | Sec_d)

named: Final[dict[str, int]]

order: Final[tuple[Sec_d, Ellipsis]]

types: type | types.UnionType

class jgdv.structs.strang._interface.Strang_d(uuid=None)[source]

Extra Data of a Strang. Sections are accessed by their index, so use cls._sections.named[name] to get the index

sections : tuple[slice, …] - Section boundaries
sec_words : tuple[tuple[int, …]] - lookup of (sec, word) -> WordIndex
words : tuple[slice, …] - Word Slices
meta : tuple[Maybe, …] - Flat word level meta data

Parameters:: uuid (jgdv.Maybe[uuid.UUID])

args: jgdv.Maybe[tuple]

args_start: jgdv.Maybe[int]

flat_idx: tuple[tuple[int, int], Ellipsis]

meta: tuple[jgdv.Maybe, Ellipsis]

sec_words: tuple[tuple[int, Ellipsis], Ellipsis]

sections: tuple[slice, Ellipsis]

uuid: jgdv.Maybe[uuid.UUID]

words: tuple[slice, Ellipsis]