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: object

Information about an application.

produce_platform_directories()

Produces platform directories object for application.

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.

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.

Module mimeogram.__.configuration

Fundamental configuration.

class mimeogram.__.configuration.EnablementTristate(value)

Bases: Enum

Disable, enable, or retain the natural state?

is_retain()

Does enum indicate a retain state?

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

Loads configuration as dictionary.

Module mimeogram.__.dictedits

Support for edits on nested dictionaries.

class mimeogram.__.dictedits.Edit(*args, **kwargs)

Bases: Protocol

Base representation of an edit to configuration.

dereference(configuration)

Dereferences value at address in configuration.

inject(configuration, value)

Injects value at address in configuration.

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

Bases: Edit

Applies entry edit to every matching dictionary in array.

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

Bases: Edit

Applies edit to single entity.

Module mimeogram.__.distribution

Information about package distribution.

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

Bases: object

Information about a package distribution.

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

Acquires information about our package distribution.

provide_data_location(*appendages)

Provides location of distribution data.

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.

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

Bases: Omniexception, Exception

Base for error exceptions raised internally.

exception mimeogram.__.exceptions.Omniexception

Bases: 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 ).

Module mimeogram.__.generics

Generic types.

class mimeogram.__.generics.Error(error)

Bases: Result[T, E]

Result of failed computation.

extract()

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

Similar to Result.unwrap in Rust.

transform(function)

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

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.

is_error()

Returns True if error result. Else False.

is_value()

Returns True if value result. Else False.

abstract transform(function)

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

class mimeogram.__.generics.Value(value)

Bases: Result[T, E]

Result of successful computation.

extract()

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

Similar to Result.unwrap in Rust.

transform(function)

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

Module mimeogram.__.imports

Common imports used throughout the package.

class mimeogram.__.imports.ImmutableStandardDataclass(name, bases, namespace, *, decorators=(), docstring=absence.absent, mutables=(), **args)

Bases: Class

Metaclass for immutable standard dataclasses. (Typechecker hack.)

class mimeogram.__.imports.ImmutableStandardProtocolDataclass(name, bases, namespace, *, decorators=(), docstring=absence.absent, mutables=(), **args)

Bases: ProtocolClass

Metaclass for immutable standard dataclasses. (Typechecker hack.)

Module mimeogram.__.inscription

Scribes for debugging and logging.

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

Bases: object

Logging and debug printing behavior.

class mimeogram.__.inscription.Modes(value)

Bases: Enum

Possible modes for logging output.

mimeogram.__.inscription.prepare(control)

Prepares various scribes in a sensible manner.

mimeogram.__.inscription.prepare_scribe_icecream(control)

Prepares Icecream debug printing.

mimeogram.__.inscription.prepare_scribe_logging(control)

Prepares standard Python logging.

Module mimeogram.__.io

Common I/O primitives.

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

Reads file asynchronously.

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

Reads files in parallel asynchronously.

Module mimeogram.__.nomina

Common names and type aliases.

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.

Module mimeogram.__.state

Immutable global state.

class mimeogram.__.state.DirectorySpecies(value)

Bases: Enum

Possible species for locations.

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

Bases: object

Immutable global data. Required by some library functions.

as_dictionary()

Returns shallow copy of state.

provide_cache_location(*appendages)

Provides cache location from configuration.

provide_data_location(*appendages)

Provides data location from configuration.

provide_location(species, *appendages)

Provides particular species of location from configuration.

provide_state_location(*appendages)

Provides state location from configuration.