API

Package appcore

Common application configuration management.

Module appcore.application

Information about application.

class appcore.application.Information(*, name, 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 appcore.distribution

Information about package distribution.

class appcore.distribution.Information(*, name, location, editable)

Bases: DataclassObject

Information about a package distribution.

Variables:

• name (str)

• location (pathlib.Path)

• editable (bool)

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

Acquires information about package distribution.

Parameters:

• selfclass

• exits (contextlib.AsyncExitStack)

• anchor (pathlib.Path | absence.objects.AbsentSingleton)

• package (str | absence.objects.AbsentSingleton)

Return type:

typing_extensions.Self

provide_data_location(*appendages)

Provides location of distribution data.

Parameters:

• self

• appendages (str)

Return type:

pathlib.Path

Module appcore.configuration

Fundamental configuration.

class appcore.configuration.AcquirerAbc

Bases: DataclassProtocol, Protocol

Abstract base class for configuration acquirers.

class appcore.configuration.EnablementTristate(value)

Bases: Enum

Disable, enable, or retain the natural state?

Variables:

• Disable (appcore.configuration.EnablementTristate)

• Retain (appcore.configuration.EnablementTristate)

• Enable (appcore.configuration.EnablementTristate)

is_retain()

Does enum indicate a retain state?

class appcore.configuration.TomlAcquirer(*, main_filename='general.toml', includes_name='includes')

Bases: AcquirerAbc

Acquires configuration data from TOML data files.

Variables:

• main_filename (str)

• includes_name (str)

Module appcore.state

Immutable global state.

class appcore.state.DirectorySpecies(value)

Bases: Enum

Possible species for locations.

Variables:

• Cache (appcore.state.DirectorySpecies)

• Data (appcore.state.DirectorySpecies)

• State (appcore.state.DirectorySpecies)

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

Bases: DataclassObject

Immutable global data. Required by some library functions.

Variables:

• application (appcore.application.Information)

• configuration (accretive.dictionaries.Dictionary[ str, typing_extensions.Any ])

• directories (platformdirs.unix.Unix)

• distribution (appcore.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:

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:

• self

• species (appcore.state.DirectorySpecies)

• appendages (str)

Return type:

pathlib.Path

provide_state_location(*appendages)

Provides state location from configuration.

Parameters:

• self

• appendages (str)

Return type:

pathlib.Path

Module appcore.inscription

Application inscription management.

Logging and, potentially, debug printing.

type appcore.inscription.Target = _io.TextIOWrapper | TextIO | appcore.inscription.TargetDescriptor

class appcore.inscription.Control(*, mode=Presentations.Plain, level='info', target=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

Bases: DataclassObject

Application inscription configuration.

Variables:

• mode (appcore.inscription.Presentations)

• level (Literal[ 'debug', 'info', 'warn', 'error', 'critical' ])

• target (_io.TextIOWrapper | TextIO | appcore.inscription.TargetDescriptor)

appcore.inscription.Modes

alias of Presentations

class appcore.inscription.Presentations(value)

Bases: Enum

Scribe presentation modes.

Variables:

• Null (appcore.inscription.Presentations)

• Plain (appcore.inscription.Presentations)

• Rich (appcore.inscription.Presentations)

class appcore.inscription.TargetDescriptor(*, location, mode=TargetModes.Truncate, codec='utf-8')

Bases: DataclassObject

Descriptor for file-based inscription targets.

Variables:

• location (bytes | str | os.PathLike[ bytes ] | os.PathLike[ str ])

• mode (appcore.inscription.TargetModes)

• codec (str)

class appcore.inscription.TargetModes(value)

Bases: Enum

Target file mode control.

Variables:

• Append (appcore.inscription.TargetModes)

• Truncate (appcore.inscription.TargetModes)

appcore.inscription.prepare(auxdata, /, control)

Prepares various scribes in a sensible manner.

Parameters:

• auxdata (appcore.state.Globals)

• control (appcore.inscription.Control)

Module appcore.preparation

Preparation of the application core.

async appcore.preparation.prepare(exits, acquirer=TomlAcquirer(main_filename='general.toml', includes_name='includes'), application=absence.absent, configedits=(), configfile=absence.absent, directories=absence.absent, distribution=absence.absent, environment=False, inscription=absence.absent)

Prepares globals DTO to pass through application.

Also: * Optionally, configures logging for 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)

• acquirer (appcore.configuration.AcquirerAbc)

• application (appcore.application.Information | absence.objects.AbsentSingleton)

• configedits (collections.abc.Iterable[ appcore.dictedits.Edit ])

• configfile (pathlib.Path | io.TextIOBase | absence.objects.AbsentSingleton)

• directories (platformdirs.unix.Unix | absence.objects.AbsentSingleton)

• distribution (appcore.distribution.Information | absence.objects.AbsentSingleton)

• environment (bool | collections.abc.Mapping[ str, typing_extensions.Any ])

• inscription (appcore.inscription.Control | absence.objects.AbsentSingleton)

Return type:

appcore.state.Globals

Module appcore.exceptions

Family of exceptions for package API.

exception appcore.exceptions.AddressLocateFailure(subject, address, part)

Bases: Omnierror, LookupError

Failure to locate address.

exception appcore.exceptions.AsyncAssertionFailure(entity)

Bases: Omnierror, AssertionError, TypeError

Assertion of awaitability of entity failed.

exception appcore.exceptions.EntryAssertionFailure(subject, name)

Bases: Omnierror, AssertionError, KeyError

Assertion of entry in dictionary failed.

exception appcore.exceptions.FileLocateFailure(subject, name)

Bases: Omnierror, FileNotFoundError

Failure to locate file.

exception appcore.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception appcore.exceptions.Omniexception(*posargs, **nomargs)

Bases: Object, BaseException

Base for all exceptions raised by package API.

exception appcore.exceptions.OperationInvalidity(subject, name)

Bases: Omnierror, RuntimeError

Invalid operation.

Module appcore.generics

Generic types.

type appcore.generics.GenericResult = appcore.generics.Result[typing_extensions.Any, Exception]

class appcore.generics.Error(error)

Bases: Result[T, E]

Result of failed computation.

Variables:

error (appcore.generics.E)

extract()

Parameters:

self

Return type:

typing_extensions.Never

transform(function)

Parameters:

• self

• function (collections.abc.Callable[ [ appcore.generics.T ], appcore.generics.U ])

Return type:

typing_extensions.Self

class appcore.generics.Result(*posargs, **nomargs)

Bases: Protocol, 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:

appcore.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:

• self

• function (collections.abc.Callable[ [ appcore.generics.T ], appcore.generics.U ])

Return type:

typing_extensions.Self | Result[ U, E ]

class appcore.generics.Value(value)

Bases: Result[T, E]

Result of successful computation.

Variables:

value (appcore.generics.T)

extract()

Parameters:

self

Return type:

appcore.generics.T

transform(function)

Parameters:

• self

• function (collections.abc.Callable[ [ appcore.generics.T ], appcore.generics.U ])

Return type:

Result[ U, E ]

appcore.generics.is_error(result)

Type guard: Returns True if result is an error.

Parameters:

result (appcore.generics.Result[ appcore.generics.T, appcore.generics.E ])

Return type:

typing_extensions.TypeIs[ appcore.generics.Error[ appcore.generics.T, appcore.generics.E ] ]

appcore.generics.is_value(result)

Type guard: Returns True if result is a value.

Parameters:

result (appcore.generics.Result[ appcore.generics.T, appcore.generics.E ])

Return type:

typing_extensions.TypeIs[ appcore.generics.Value[ appcore.generics.T, appcore.generics.E ] ]

Module appcore.io

Common I/O primitives.

async appcore.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 appcore.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 appcore.asyncf

Helper functions for async execution.

async appcore.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 appcore.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:

appcore.generics.Result[ object, Exception ]