Internal Development Interface

Module mimeogram.__.application

Information about application.

class mimeogram.__.application.Information(*, name: Annotated[str, Doc('For derivation of platform directories.')] = 'mimeogram', publisher: Annotated[str | None, Doc('For derivation of platform directories.'), Suppress] | None = None, version: Annotated[str | None, Doc('For derivation of platform directories.'), Suppress] | None = None)

Bases: object

Information about an application.

produce_platform_directories() → Unix

Produces platform directories object for application.

name: Annotated[str, Doc('For derivation of platform directories.')]

publisher: Annotated[str | None, Doc('For derivation of platform directories.'), Suppress]

version: Annotated[str | None, Doc('For derivation of platform directories.'), Suppress]

Module mimeogram.__.asyncf

Helper functions for async execution.

async mimeogram.__.asyncf.gather_async(*operands: Any, return_exceptions: Annotated[bool, Doc(' Raw or wrapped results. Wrapped, if true. ')] = False, error_message: str = 'Failure of async operations.', ignore_nonawaitables: Annotated[bool, Doc(' Ignore or error on non-awaitables. Ignore, if true. ')] = False) → tuple[Any, ...]

Gathers results from invocables concurrently and asynchronously.

async mimeogram.__.asyncf.intercept_error_async(awaitable: Awaitable[Any]) → Result[object, Exception]

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() → bool

Does enum indicate a retain state?

Disable = 'disable'

Enable = 'enable'

Retain = 'retain'

async mimeogram.__.configuration.acquire(application_name: str, directories: Unix, distribution: Information, edits: Iterable[Edit] = (), file: Path | AbsentSingleton = absence.absent) → Dictionary[str, Any]

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: MutableMapping[str, Any]) → Any

Dereferences value at address in configuration.

inject(configuration: MutableMapping[str, Any], value: Any) → None

Injects value at address in configuration.

address: Sequence[str]

mimeogram.__.dictedits.Edits

alias of Iterable[Edit]

class mimeogram.__.dictedits.ElementsEntryEdit(*, address: Sequence[str], editee: tuple[str, Any], identifier: tuple[str, Any] | None = None)

Bases: Edit

Applies entry edit to every matching dictionary in array.

dereference(configuration: MutableMapping[str, Any]) → Any

Dereferences value at address in configuration.

inject(configuration: MutableMapping[str, Any], value: Any) → None

Injects value at address in configuration.

address: Sequence[str]

editee: tuple[str, Any]

identifier: tuple[str, Any] | None

class mimeogram.__.dictedits.SimpleEdit(*, address: Sequence[str], value: Any)

Bases: Edit

Applies edit to single entity.

dereference(configuration: MutableMapping[str, Any]) → Any

Dereferences value at address in configuration.

inject(configuration: MutableMapping[str, Any], value: Any) → None

Injects value at address in configuration.

address: Sequence[str]

value: Any

Module mimeogram.__.distribution

Information about package distribution.

class mimeogram.__.distribution.Information(*, name: str, location: Path, editable: bool)

Bases: object

Information about a package distribution.

async classmethod prepare(package: str, exits: AsyncExitStack, project_anchor: Path | AbsentSingleton = absence.absent) → Self

Acquires information about our package distribution.

provide_data_location(*appendages: str) → Path

Provides location of distribution data.

editable: bool

location: Path

name: str

Module mimeogram.__.environment

Persistent and active process environment values.

async mimeogram.__.environment.update(auxdata: Globals)

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.

• Omniexception: Base for all internal exceptions

• Omnierror: Base for all internals errors

exception mimeogram.__.exceptions.AddressLocateFailure(subject: str, address: Sequence[str], part: str)

Bases: Omnierror, LookupError

Failure to locate address.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.__.exceptions.AsyncAssertionFailure(entity: Any)

Bases: Omnierror, AssertionError, TypeError

Assertion of awaitability of entity failed.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

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

Bases: Omnierror, AssertionError, KeyError

Assertion of entry in dictionary failed.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.__.exceptions.Omnierror

Bases: Omniexception, Exception

Base for error exceptions raised internally.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception mimeogram.__.exceptions.Omniexception

Bases: BaseException

Base for all exceptions raised internally.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

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

Bases: Omnierror, RuntimeError

Invalid operation.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

mimeogram.__.exceptions.report_exceptions(scribe: ~logging.Logger, message: str, eclass: type[BaseException] = <class 'SystemExit'>, eposargs: ~collections.abc.Sequence[~typing_extensions.Any] = (1, )) → Generator[None, None, None]

Intercepts and reports exceptions.

By default, raises SystemExit( 1 ).

Module mimeogram.__.generics

Generic types.

class mimeogram.__.generics.Error(error: E)

Bases: Result[T, E]

Result of failed computation.

extract() → Never

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

Similar to Result.unwrap in Rust.

is_error() → bool

Returns True if error result. Else False.

is_value() → bool

Returns True if value result. Else False.

transform(function: Callable[[T], U]) → Self

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

error: E

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

Bases: Object, Generic[T, E]

Either a value or an error.

abstract extract() → T

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

Similar to Result.unwrap in Rust.

is_error() → bool

Returns True if error result. Else False.

is_value() → bool

Returns True if value result. Else False.

abstract transform(function: Callable[[T], U]) → Self | Result[U, E]

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

class mimeogram.__.generics.Value(value: T)

Bases: Result[T, E]

Result of successful computation.

extract() → T

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

Similar to Result.unwrap in Rust.

is_error() → bool

Returns True if error result. Else False.

is_value() → bool

Returns True if value result. Else False.

transform(function: Callable[[T], U]) → Result[U, E]

Transforms value in value result. Ignores error result.

Similar to Result.map in Rust.

value: T

Module mimeogram.__.imports

Common imports and type aliases used throughout the package.

mimeogram.__.imports.AccretiveDictionary

alias of Dictionary

mimeogram.__.imports.ExitsAsync

alias of AsyncExitStack

mimeogram.__.imports.ImmutableClass

alias of Class

mimeogram.__.imports.ImmutableDictionary

alias of Dictionary

mimeogram.__.imports.ImmutableNominativeDictionary

alias of Mapping[str, Any]

mimeogram.__.imports.ImmutableObject

alias of Object

mimeogram.__.imports.ImmutableProtocolClass

alias of ProtocolClass

class mimeogram.__.imports.ImmutableStandardDataclass(name: str, bases: tuple[type, ...], namespace: dict[str, Any], *, decorators: Iterable[Callable[[type], type]] = (), docstring: str | None | AbsentSingleton = absence.absent, mutables: Collection[str] = (), **args: Any)

Bases: Class

Metaclass for immutable standard dataclasses. (Typechecker hack.)

mro()

Return a type’s method resolution order.

class mimeogram.__.imports.ImmutableStandardProtocolDataclass(name: str, bases: tuple[type, ...], namespace: dict[str, Any], *, decorators: Iterable[Callable[[type], type]] = (), docstring: str | None | AbsentSingleton = absence.absent, mutables: Collection[str] = (), **args: Any)

Bases: ProtocolClass

Metaclass for immutable standard dataclasses. (Typechecker hack.)

mro()

Return a type’s method resolution order.

register(subclass)

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

mimeogram.__.imports.NominativeDictionary

alias of MutableMapping[str, Any]

class mimeogram.__.imports.Path(*args, **kwargs)

Bases: PurePath

PurePath subclass that can make system calls.

Path represents a filesystem path but unlike PurePath, also offers methods to do system calls on path objects. Depending on your system, instantiating a Path will return either a PosixPath or a WindowsPath object. You can also instantiate a PosixPath or WindowsPath directly, but cannot instantiate a WindowsPath on a POSIX system or vice versa.

absolute()

Return an absolute version of this path. This function works even if the path doesn’t point to anything.

No normalization is done, i.e. all ‘.’ and ‘..’ will be kept along. Use resolve() to get the canonical path to a file.

as_posix()

Return the string representation of the path with forward (/) slashes.

as_uri()

Return the path as a ‘file’ URI.

chmod(mode, *, follow_symlinks=True)

Change the permissions of the path, like os.chmod().

classmethod cwd()

Return a new path pointing to the current working directory (as returned by os.getcwd()).

exists()

Whether this path exists.

expanduser()

Return a new path with expanded ~ and ~user constructs (as returned by os.path.expanduser)

glob(pattern)

Iterate over this subtree and yield all existing files (of any kind, including directories) matching the given relative pattern.

group()

Return the group name of the file gid.

hardlink_to(target)

Make this path a hard link pointing to the same file as target.

Note the order of arguments (self, target) is the reverse of os.link’s.

classmethod home()

Return a new path pointing to the user’s home directory (as returned by os.path.expanduser(‘~’)).

is_absolute()

True if the path is absolute (has both a root and, if applicable, a drive).

is_block_device()

Whether this path is a block device.

is_char_device()

Whether this path is a character device.

is_dir()

Whether this path is a directory.

is_fifo()

Whether this path is a FIFO.

is_file()

Whether this path is a regular file (also True for symlinks pointing to regular files).

is_mount()

Check if this path is a POSIX mount point

is_relative_to(*other)

Return True if the path is relative to another path or False.

is_reserved()

Return True if the path contains one of the special names reserved by the system, if any.

is_socket()

Whether this path is a socket.

is_symlink()

Whether this path is a symbolic link.

iterdir()

Iterate over the files in this directory. Does not yield any result for the special paths ‘.’ and ‘..’.

joinpath(*args)

Combine this path with one or several arguments, and return a new path representing either a subpath (if all arguments are relative paths) or a totally different path (if one of the arguments is anchored).

lchmod(mode)

Like chmod(), except if the path points to a symlink, the symlink’s permissions are changed, rather than its target’s.

link_to(target)

Make the target path a hard link pointing to this path.

Note this function does not make this path a hard link to target, despite the implication of the function and argument names. The order of arguments (target, link) is the reverse of Path.symlink_to, but matches that of os.link.

Deprecated since Python 3.10 and scheduled for removal in Python 3.12. Use hardlink_to() instead.

lstat()

Like stat(), except if the path points to a symlink, the symlink’s status information is returned, rather than its target’s.

match(path_pattern)

Return True if this path matches the given pattern.

mkdir(mode=511, parents=False, exist_ok=False)

Create a new directory at this given path.

open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

Open the file pointed by this path and return a file object, as the built-in open() function does.

owner()

Return the login name of the file owner.

read_bytes()

Open the file in bytes mode, read it, and close the file.

read_text(encoding=None, errors=None)

Open the file in text mode, read it, and close the file.

readlink()

Return the path to which the symbolic link points.

relative_to(*other)

Return the relative path to another path identified by the passed arguments. If the operation is not possible (because this is not a subpath of the other path), raise ValueError.

rename(target)

Rename this path to the target path.

The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.

Returns the new Path instance pointing to the target path.

replace(target)

Rename this path to the target path, overwriting if that path exists.

The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.

Returns the new Path instance pointing to the target path.

resolve(strict=False)

Make the path absolute, resolving all symlinks on the way and also normalizing it (for example turning slashes into backslashes under Windows).

rglob(pattern)

Recursively yield all existing files (of any kind, including directories) matching the given relative pattern, anywhere in this subtree.

rmdir()

Remove this directory. The directory must be empty.

samefile(other_path)

Return whether other_path is the same or not as this file (as returned by os.path.samefile()).

stat(*, follow_symlinks=True)

Return the result of the stat() system call on this path, like os.stat() does.

symlink_to(target, target_is_directory=False)

Make this path a symlink pointing to the target path. Note the order of arguments (link, target) is the reverse of os.symlink.

touch(mode=438, exist_ok=True)

Create this file with the given access mode, if it doesn’t exist.

unlink(missing_ok=False)

Remove this file or link. If the path is a directory, use rmdir() instead.

with_name(name)

Return a new path with the file name changed.

with_stem(stem)

Return a new path with the stem changed.

with_suffix(suffix)

Return a new path with the file suffix changed. If the path has no suffix, add given suffix. If the given suffix is an empty string, remove the suffix from the path.

write_bytes(data)

Open the file in bytes mode, write to it, and close the file.

write_text(data, encoding=None, errors=None, newline=None)

Open the file in text mode, write to it, and close the file.

property anchor

The concatenation of the drive and root, or ‘’.

property drive

The drive prefix (letter or UNC path), if any.

property name

The final path component, if any.

property parent

The logical parent of the path.

property parents

A sequence of this path’s logical parents.

property parts

An object providing sequence-like access to the components in the filesystem path.

property root

The root of the path, if any.

property stem

The final path component, minus its last suffix.

property suffix

The final component’s last suffix, if any.

This includes the leading period. For example: ‘.txt’

property suffixes

A list of the final component’s suffixes, if any.

These include the leading periods. For example: [‘.tar’, ‘.gz’]

mimeogram.__.imports.PlatformDirs

alias of Unix

mimeogram.__.imports.dataclass(cls=None, /, *, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False)

Returns the same class as was passed in, with dunder methods added based on the fields defined in the class.

Examines PEP 526 __annotations__ to determine fields.

If init is true, an __init__() method is added to the class. If repr is true, a __repr__() method is added. If order is true, rich comparison dunder methods are added. If unsafe_hash is true, a __hash__() method function is added. If frozen is true, fields may not be assigned to after instance creation. If match_args is true, the __match_args__ tuple is added. If kw_only is true, then by default all fields are keyword-only. If slots is true, an __slots__ attribute is added.

mimeogram.__.imports.dataclass_declare(*, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=<dataclasses._MISSING_TYPE object>)

Return an object to identify dataclass fields.

default is the default value of the field. default_factory is a 0-argument function called to initialize a field’s value. If init is true, the field will be a parameter to the class’s __init__() function. If repr is true, the field will be included in the object’s repr(). If hash is true, the field will be included in the object’s hash(). If compare is true, the field will be used in comparison functions. metadata, if specified, must be a mapping which is stored but not otherwise examined by dataclass. If kw_only is true, the field will become a keyword-only parameter to __init__().

It is an error to specify both default and default_factory.

mimeogram.__.imports.is_absent(value: object) → TypeIs[AbsentSingleton]

Checks if value is the global absence sentinel.

mimeogram.__.imports.produce_scribe(name=None)

Return a logger with the specified name, creating it if necessary.

If no name is specified, return the root logger.

mimeogram.__.imports.reclassify_modules_as_immutable(attributes: Annotated[Mapping[str, Any] | ModuleType | str, Doc('Module, module name, or dictionary of object attributes.')], recursive: Annotated[bool, Doc('Recursively reclassify package modules?')] = False) → None

Reclassifies modules to be immutable.

This function converts existing modules to immutable modules, enforcing attribute immutability after conversion. It can operate on individual modules or entire package hierarchies.

Notes

• Only converts modules within the same package to prevent unintended modifications to external modules

• When used with a dictionary, converts any module objects found as values if they belong to the same package

• Module conversion is permanent for the runtime session

• Has no effect on already-immutable modules

mimeogram.__.imports.simple_tyro_class(callable: CallableType) → CallableType

mimeogram.__.imports.standard_dataclass(cls)

mimeogram.__.imports.standard_tyro_class(callable: CallableType) → CallableType

mimeogram.__.imports.uuid4()

Generate a random UUID.

Module mimeogram.__.inscription

Scribes for debugging and logging.

class mimeogram.__.inscription.Control(*, mode: Modes = Modes.Null, level: Literal['debug', 'info', 'warn', 'error', 'critical'] | None = None)

Bases: object

Logging and debug printing behavior.

level: Literal['debug', 'info', 'warn', 'error', 'critical'] | None

mode: Modes

class mimeogram.__.inscription.Modes(value)

Bases: Enum

Possible modes for logging output.

Null = 'null'

Pass = 'pass'

Rich = 'rich'

mimeogram.__.inscription.prepare(control: Control) → None

Prepares various scribes in a sensible manner.

mimeogram.__.inscription.prepare_scribe_icecream(control: Control) → None

Prepares Icecream debug printing.

mimeogram.__.inscription.prepare_scribe_logging(control: Control) → None

Prepares standard Python logging.

Module mimeogram.__.io

Common I/O primitives.

async mimeogram.__.io.acquire_text_file_async(file: str | Path, charset: str = 'utf-8', deserializer: Callable[[str], Any] | AbsentSingleton = absence.absent) → Any

Reads file asynchronously.

async mimeogram.__.io.acquire_text_files_async(*files: str | Path, charset: str = 'utf-8', deserializer: Callable[[str], Any] | AbsentSingleton = absence.absent, return_exceptions: bool = False) → Sequence[Any]

Reads files in parallel asynchronously.

Module mimeogram.__.preparation

Preparation of the library core.

async mimeogram.__.preparation.prepare(exits: AsyncExitStack, application: Information = Information(name='mimeogram', publisher=None, version=None), configedits: Iterable[Edit] = (), configfile: Path | AbsentSingleton = absence.absent, environment: bool = False, inscription: Control | AbsentSingleton = absence.absent) → Globals

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.

Cache = 'cache'

Data = 'data'

State = 'state'

class mimeogram.__.state.Globals(*, application: Information, configuration: Dictionary[str, Any], directories: Unix, distribution: Information, exits: AsyncExitStack)

Bases: object

Immutable global data. Required by some library functions.

as_dictionary() → Mapping[str, Any]

Returns shallow copy of state.

provide_cache_location(*appendages: str) → Path

Provides cache location from configuration.

provide_data_location(*appendages: str) → Path

Provides data location from configuration.

provide_location(species: DirectorySpecies, *appendages: str) → Path

Provides particular species of location from configuration.

provide_state_location(*appendages: str) → Path

Provides state location from configuration.

application: Information

configuration: Dictionary[str, Any]

directories: Unix

distribution: Information

exits: AsyncExitStack