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:
- 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.
- 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
andSystemExit
must be allowed to propagate to be consistent withasyncio.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:
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:
application_name (str)
directories (platformdirs.unix.Unix)
distribution (mimeogram.__.distribution.Information)
edits (collections.abc.Iterable[ mimeogram.__.dictedits.Edit ])
file (pathlib.Path | absence.objects.AbsentSingleton)
- 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:
self
configuration (collections.abc.MutableMapping[ str, typing_extensions.Any ])
- Return type:
typing_extensions.Any
- inject(configuration, value)¶
Injects value at address in configuration.
- Parameters:
self
configuration (collections.abc.MutableMapping[ str, typing_extensions.Any ])
value (typing_extensions.Any)
- 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.
- Variables:
address (collections.abc.Sequence[ str ])
value (typing_extensions.Any)
Module mimeogram.__.distribution
¶
Information about package distribution.
- class mimeogram.__.distribution.Information(*, name, location, editable)¶
Bases:
DataclassObject
Information about a package distribution.
- Variables:
name (str)
location (pathlib.Path)
editable (bool)
- async classmethod prepare(package, exits, project_anchor=absence.absent)¶
Acquires information about our package distribution.
- Parameters:
selfclass
package (str)
exits (contextlib.AsyncExitStack)
project_anchor (pathlib.Path | absence.objects.AbsentSingleton)
- Return type:
typing_extensions.Self
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:
scribe (logging.Logger)
message (str)
eclass (type[ BaseException ])
eposargs (collections.abc.Sequence[ typing_extensions.Any ])
- 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:
self
function (collections.abc.Callable[ [ mimeogram.__.generics.T ], mimeogram.__.generics.U ])
- 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
- abstract transform(function)¶
Transforms value in value result. Ignores error result.
Similar to Result.map in Rust.
- Parameters:
self
function (collections.abc.Callable[ [ mimeogram.__.generics.T ], mimeogram.__.generics.U ])
- 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:
self
function (collections.abc.Callable[ [ mimeogram.__.generics.T ], mimeogram.__.generics.U ])
- 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:
level (Literal[ 'debug', 'info', 'warn', 'error', 'critical' ] | None)
- 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:
file (str | pathlib.Path)
charset (str)
deserializer (collections.abc.Callable[ [ str ], typing_extensions.Any ] | absence.objects.AbsentSingleton)
- 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:
files (str | pathlib.Path)
charset (str)
deserializer (collections.abc.Callable[ [ str ], typing_extensions.Any ] | absence.objects.AbsentSingleton)
return_exceptions (bool)
- Return type:
collections.abc.Sequence[ typing_extensions.Any ]
Module mimeogram.__.nomina
¶
Common names and type aliases.
- 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:
exits (contextlib.AsyncExitStack)
application (mimeogram.__.application.Information)
configedits (collections.abc.Iterable[ mimeogram.__.dictedits.Edit ])
configfile (pathlib.Path | absence.objects.AbsentSingleton)
environment (bool)
inscription (mimeogram.__.inscription.Control | absence.objects.AbsentSingleton)
- Return type:
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:
application (mimeogram.__.application.Information)
configuration (accretive.dictionaries.Dictionary[ str, typing_extensions.Any ])
directories (platformdirs.unix.Unix)
distribution (mimeogram.__.distribution.Information)
exits (contextlib.AsyncExitStack)
- 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:
- provide_data_location(*appendages)¶
Provides data location from configuration.
- Parameters:
self
appendages (str)
- Return type:
- provide_location(species, *appendages)¶
Provides particular species of location from configuration.
- Parameters:
self
species (mimeogram.__.state.DirectorySpecies)
appendages (str)
- Return type: