Internal Development Interface

Package mimeogram.__

Common constants, imports, and utilities.

Module mimeogram.__.application

Information about application.

class mimeogram.__.application.Information(*, name='mimeogram', publisher=None, version=None)

Bases: DataclassObject

Information about an application.

Variables:

  • name (str) – For derivation of platform directories.

  • publisher (str | None) – For derivation of platform directories.

  • version (str | None) – For derivation of platform directories.

produce_platform_directories()

Produces platform directories object for application.

Parameters:

self

Return type:

platformdirs.unix.Unix

Module mimeogram.__.asyncf

Helper functions for async execution.

async mimeogram.__.asyncf.gather_async(*operands, return_exceptions=False, error_message='Failure of async operations.', ignore_nonawaitables=False)

Gathers results from invocables concurrently and asynchronously.

Parameters:

  • operands (typing_extensions.Any)

  • return_exceptions (bool) – Raw or wrapped results. Wrapped, if true.

  • error_message (str)

  • ignore_nonawaitables (bool) – Ignore or error on non-awaitables. Ignore, if true.

Return type:

tuple[ typing_extensions.Any, … ]

async mimeogram.__.asyncf.intercept_error_async(awaitable)

Converts unwinding exceptions to error results.

Exceptions, which are not instances of Exception or one of its subclasses, are allowed to propagate. In particular, KeyboardInterrupt and SystemExit must be allowed to propagate to be consistent with asyncio.TaskGroup behavior.

Helpful when working with asyncio.gather(), for example, because exceptions can be distinguished from computed values and collected together into an exception group.

In general, it is a bad idea to swallow exceptions. In this case, the intent is to add them into an exception group for continued propagation.

Parameters:

awaitable (collections.abc.Awaitable[ typing_extensions.Any ])

Return type:

mimeogram.__.generics.Result[ object, Exception ]

Module mimeogram.__.configuration

Fundamental configuration.

class mimeogram.__.configuration.EnablementTristate(value)

Bases: Enum

Disable, enable, or retain the natural state?

Variables:
is_retain()

Does enum indicate a retain state?

async mimeogram.__.configuration.acquire(application_name, directories, distribution, edits=(), file=absence.absent)

Loads configuration as dictionary.

Parameters:
Return type:

accretive.dictionaries.Dictionary[ str, typing_extensions.Any ]

Module mimeogram.__.dictedits

Support for edits on nested dictionaries.

type mimeogram.__.dictedits.Edits = collections.abc.Iterable[mimeogram.__.dictedits.Edit]
class mimeogram.__.dictedits.Edit(*, address)

Bases: DataclassProtocol, Protocol

Base representation of an edit to configuration.

Variables:

address (collections.abc.Sequence[ str ])

dereference(configuration)

Dereferences value at address in configuration.

Parameters:
Return type:

typing_extensions.Any

inject(configuration, value)

Injects value at address in configuration.

Parameters:
class mimeogram.__.dictedits.ElementsEntryEdit(*, address, editee, identifier=None)

Bases: Edit

Applies entry edit to every matching dictionary in array.

Variables:
class mimeogram.__.dictedits.SimpleEdit(*, address, value)

Bases: Edit

Applies edit to single entity.

Variables:

Module mimeogram.__.distribution

Information about package distribution.

class mimeogram.__.distribution.Information(*, name, location, editable)

Bases: DataclassObject

Information about a package distribution.

Variables:
async classmethod prepare(package, exits, project_anchor=absence.absent)

Acquires information about our package distribution.

Parameters:
Return type:

typing_extensions.Self

provide_data_location(*appendages)

Provides location of distribution data.

Parameters:

  • self

  • appendages (str)

Return type:

pathlib.Path

Module mimeogram.__.environment

Persistent and active process environment values.

async mimeogram.__.environment.update(auxdata)

Updates process environment from dot files.

For editable installations (development environments): - If project-level .env exists, use it exclusively. - Otherwise fall through to normal behavior.

For normal installations: - Merge configured and local .env files. - Local values take precedence over configured values.

Parameters:

auxdata (mimeogram.__.state.Globals)

Module mimeogram.__.exceptions

Family of exceptions for package internals.

exception mimeogram.__.exceptions.AddressLocateFailure(subject, address, part)

Bases: Omnierror, LookupError

Failure to locate address.

exception mimeogram.__.exceptions.AsyncAssertionFailure(entity)

Bases: Omnierror, AssertionError, TypeError

Assertion of awaitability of entity failed.

exception mimeogram.__.exceptions.EntryAssertionFailure(subject, name)

Bases: Omnierror, AssertionError, KeyError

Assertion of entry in dictionary failed.

exception mimeogram.__.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions raised internally.

exception mimeogram.__.exceptions.Omniexception(*posargs, **nomargs)

Bases: Object, BaseException

Base for all exceptions raised internally.

exception mimeogram.__.exceptions.OperationInvalidity(subject, name)

Bases: Omnierror, RuntimeError

Invalid operation.

mimeogram.__.exceptions.report_exceptions(scribe, message, eclass=<class 'SystemExit'>, eposargs=(1, ))

Intercepts and reports exceptions.

By default, raises SystemExit( 1 ).

Parameters:
Return type:

collections.abc.Generator[ None, None, None ]

Module mimeogram.__.generics

Generic types.

type mimeogram.__.generics.GenericResult = mimeogram.__.generics.Result[typing_extensions.Any, Exception]
class mimeogram.__.generics.Error(error)

Bases: Result[T, E]

Result of failed computation.

Variables:

error (mimeogram.__.generics.E)

extract()
Parameters:

self

Return type:

typing_extensions.Never

transform(function)
Parameters:
Return type:

typing_extensions.Self

class mimeogram.__.generics.Result(*posargs, **nomargs)

Bases: Object, Generic[T, E]

Either a value or an error.

abstract extract()

Extracts value from result. Else, raises error from result.

Similar to Result.unwrap in Rust.

Parameters:

self

Return type:

mimeogram.__.generics.T

is_error()

Returns True if error result. Else False.

Parameters:

self

Return type:

bool

is_value()

Returns True if value result. Else False.

Parameters:

self

Return type:

bool

abstract transform(function)

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

Parameters:
Return type:

typing_extensions.Self | ForwardRef

class mimeogram.__.generics.Value(value)

Bases: Result[T, E]

Result of successful computation.

Variables:

value (mimeogram.__.generics.T)

extract()
Parameters:

self

Return type:

mimeogram.__.generics.T

transform(function)
Parameters:
Return type:

mimeogram.__.generics.Result[ mimeogram.__.generics.U, mimeogram.__.generics.E ]

Module mimeogram.__.imports

Common imports used throughout the package.

Module mimeogram.__.inscription

Scribes for debugging and logging.

class mimeogram.__.inscription.Control(*, mode=Modes.Null, level=None)

Bases: DataclassObject

Logging and debug printing behavior.

Variables:
class mimeogram.__.inscription.Modes(value)

Bases: Enum

Possible modes for logging output.

Variables:
mimeogram.__.inscription.prepare(control)

Prepares various scribes in a sensible manner.

Parameters:

control (mimeogram.__.inscription.Control)

mimeogram.__.inscription.prepare_scribe_icecream(control)

Prepares Icecream debug printing.

Parameters:

control (mimeogram.__.inscription.Control)

mimeogram.__.inscription.prepare_scribe_logging(control)

Prepares standard Python logging.

Parameters:

control (mimeogram.__.inscription.Control)

Module mimeogram.__.io

Common I/O primitives.

async mimeogram.__.io.acquire_text_file_async(file, charset='utf-8', deserializer=absence.absent)

Reads file asynchronously.

Parameters:
Return type:

typing_extensions.Any

async mimeogram.__.io.acquire_text_files_async(*files, charset='utf-8', deserializer=absence.absent, return_exceptions=False)

Reads files in parallel asynchronously.

Parameters:
Return type:

collections.abc.Sequence[ typing_extensions.Any ]

Module mimeogram.__.nomina

Common names and type aliases.

type mimeogram.__.nomina.ComparisonResult = bool | builtins.NotImplementedType
type mimeogram.__.nomina.NominativeArguments = collections.abc.Mapping[str, typing_extensions.Any]
type mimeogram.__.nomina.PositionalArguments = collections.abc.Sequence[typing_extensions.Any]
type mimeogram.__.nomina.NominativeDictionary = collections.abc.MutableMapping[str, typing_extensions.Any]
type mimeogram.__.nomina.ImmutableNominativeDictionary = collections.abc.Mapping[str, typing_extensions.Any]

Module mimeogram.__.preparation

Preparation of the library core.

async mimeogram.__.preparation.prepare(exits, application=Information(name='mimeogram', publisher=None, version=None), configedits=(), configfile=absence.absent, environment=False, inscription=absence.absent)

Prepares globals DTO for use with library functions.

Also: * Configures logging for library package (not application). * Optionally, loads process environment from files.

Note that asynchronous preparation allows for applications to concurrently initialize other entities outside of the library, even though the library initialization, itself, is inherently sequential.

Parameters:
Return type:

mimeogram.__.state.Globals

Module mimeogram.__.state

Immutable global state.

class mimeogram.__.state.DirectorySpecies(value)

Bases: Enum

Possible species for locations.

Variables:
class mimeogram.__.state.Globals(*, application, configuration, directories, distribution, exits)

Bases: DataclassObject

Immutable global data. Required by some library functions.

Variables:
as_dictionary()

Returns shallow copy of state.

Parameters:

self

Return type:

collections.abc.Mapping[ str, typing_extensions.Any ]

provide_cache_location(*appendages)

Provides cache location from configuration.

Parameters:

  • self

  • appendages (str)

Return type:

pathlib.Path

provide_data_location(*appendages)

Provides data location from configuration.

Parameters:

  • self

  • appendages (str)

Return type:

pathlib.Path

provide_location(species, *appendages)

Provides particular species of location from configuration.

Parameters:
Return type:

pathlib.Path

provide_state_location(*appendages)

Provides state location from configuration.

Parameters:

  • self

  • appendages (str)

Return type:

pathlib.Path