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:
async classmethod prepare(exits, anchor=absence.absent, package=absence.absent)

Acquires information about 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 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:
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.cli

CLI foundation classes and interfaces.

This module provides the core infrastructure for building command-line interfaces. It offers a comprehensive framework for creating CLI applications with rich presentation options, flexible output routing, and integrated logging capabilities.

Key Components

Command Framework

  • Command - Abstract base class for CLI command implementations

  • Application dataclass for command-line application configuration

  • Rich integration with tyro for automatic argument parsing and help generation

Display and Output Control

  • DisplayOptions - Configuration for output presentation and routing

  • InscriptionControl - Configuration for logging and diagnostic output

  • Stream routing (stdout/stderr) and file output capabilities

  • Rich terminal detection with colorization control

Example Usage

Basic CLI application with custom display options and subcommands:

from appcore import cli, state

class MyDisplayOptions( cli.DisplayOptions ):
    format: str = 'table'

class MyGlobals( state.Globals ):
    display: MyDisplayOptions

class StatusCommand( cli.Command ):
    async def execute( self, auxdata: state.Globals ) -> None:
        if isinstance( auxdata, MyGlobals ):
            format_val = auxdata.display.format
            print( f"Status: Running (format: {format_val})" )

class InfoCommand( cli.Command ):
    async def execute( self, auxdata: state.Globals ) -> None:
        print( f"App: {auxdata.application.name}" )

class MyApplication( cli.Application ):
    display: MyDisplayOptions = __.dcls.field(
        default_factory = MyDisplayOptions )
    command: __.typx.Union[
        __.typx.Annotated[
            StatusCommand,
            _tyro.conf.subcommand( 'status', prefix_name = False ),
        ],
        __.typx.Annotated[
            InfoCommand,
            _tyro.conf.subcommand( 'info', prefix_name = False ),
        ],
    ] = __.dcls.field( default_factory = StatusCommand )

    async def execute( self, auxdata: state.Globals ) -> None:
        await self.command( auxdata )

    async def prepare( self, exits ) -> state.Globals:
        auxdata_base = await super( ).prepare( exits )
        return MyGlobals(
            display = self.display, **auxdata_base.__dict__ )
class appcore.cli.Application(*, configfile=None, environment=True, inscription=<factory>)

Bases: DataclassProtocol, Protocol

Common infrastructure and standard interface for applications.

Example:

class MyApplication( Application ):
    display: DisplayOptions = __.dcls.field(
        default_factory = DisplayOptions )

    async def execute( self, auxdata: state.Globals ) -> None:
        print( f"Application: {auxdata.application.name}" )
Variables:
abstract async execute(auxdata)

Executes command.

Parameters:
async prepare(exits)

Prepares session context.

Parameters:
Return type:

appcore.state.Globals

class appcore.cli.Command

Bases: DataclassProtocol, Protocol

Standard interface for command implementations.

Example:

class StatusCommand( Command ):
    async def execute( self, auxdata: state.Globals ) -> None:
        print( f"Application: {auxdata.application.name}" )
abstract async execute(auxdata)

Executes command.

Parameters:
async prepare(auxdata)

Prepares session context.

Parameters:
Return type:

appcore.state.Globals

class appcore.cli.DisplayOptions(*, colorize=True, target_file=None, target_stream=TargetStreams.Stdout, assume_rich_terminal=False)

Bases: DataclassObject

Standardized display configuration for CLI applications.

Example:

class MyDisplayOptions( DisplayOptions ):
    format: str = 'table'
    compact: bool = False
Variables:
determine_colorization(stream)

Determines whether to use colorized output.

Parameters:
Return type:

bool

async provide_stream(exits)

Provides target stream from options.

Parameters:
Return type:

TextIO

class appcore.cli.InscriptionControl(*, level='info', presentation=Presentations.Plain, target_file=None, target_stream=TargetStreams.Stderr)

Bases: DataclassObject

Inscription (logging, debug prints) control.

Variables:
as_control(exits)

Produces compatible inscription control for appcore.

Parameters:
Return type:

appcore.inscription.Control

class appcore.cli.TargetStreams(value)

Bases: Enum

Target stream selection.

Module appcore.introspection

Application for configuration introspection.

This module provides a complete CLI application for introspecting configuration, environment variables, and platform directories. It serves as both a practical utility and a comprehensive example of building CLI applications with the appcore.cli framework.

Command-Line Interface

The appcore command provides three main introspection capabilities:

Configuration Inspection

Display finalized application configuration from TOML files:

appcore configuration                    # Default rich format
appcore --display.presentation json configuration
appcore --display.presentation toml configuration
Environment Variables

Show application-specific environment variables:

appcore environment                      # All APPCORE_* variables
appcore --display.presentation plain environment
Platform Directories

Display platform-specific directories for the application:

appcore directories                      # Show all directory paths
appcore --display.target-file dirs.txt directories

Presentation Formats

Multiple output formats are supported through the presentation option:

  • rich (default) - Rich formatted output with syntax highlighting

  • json - JSON format for programmatic consumption

  • toml - TOML format matching input configuration files

  • plain - Plain text format for simple displays

Output Routing

Flexible output destinations:

Stream Routing

  • --display.target-stream stdout (default) - Main output to stdout

  • --display.target-stream stderr - Main output to stderr

  • --inscription.target-stream stderr (default) - Logging to stderr

  • --inscription.target-stream stdout - Logging to stdout

File Output

  • --display.target-file path - Save main output to file

  • --inscription.target-file path - Save logging to file

Terminal Control

Rich terminal behavior can be controlled:

  • --display.colorize / --display.no-colorize - Control colorization

  • --display.assume-rich-terminal - Force Rich capabilities (testing)

Implementation Architecture

Command Structure

Usage as Implementation Example

This module demonstrates comprehensive CLI application patterns:

  • Command inheritance from appcore.cli.Command

  • Async execution with proper error handling

  • Integration with appcore preparation and configuration systems

  • File and stream output routing capabilities

  • Rich terminal integration with automatic capability detection

The source code serves as a reference implementation for building similar CLI applications with the appcore framework.

class appcore.introspection.Application(*, configfile=None, environment=True, inscription=<factory>, display=<factory>, command=<factory>)

Bases: Application

Application for introspection of configuration.

Variables:
async execute(auxdata)
Parameters:
async prepare(exits)
Parameters:
Return type:

appcore.state.Globals

class appcore.introspection.ApplicationGlobals(*, application, configuration, directories, distribution, exits, display=<factory>)

Bases: Globals

Includes display options.

Variables:
class appcore.introspection.DisplayOptions(*, colorize=True, target_file=None, target_stream=TargetStreams.Stdout, assume_rich_terminal=False, presentation=Presentations.Rich)

Bases: DisplayOptions

Display options, including presentation mode.

Variables:
async render(data)

Renders data according to display options.

Parameters:

  • self

  • data (typing_extensions.Any)

class appcore.introspection.IntrospectConfigurationCommand

Bases: Command

Shows finalized application configuration.

async execute(auxdata)
Parameters:
class appcore.introspection.IntrospectDirectoriesCommand

Bases: Command

Shows application and package directories.

async execute(auxdata)
Parameters:
class appcore.introspection.IntrospectEnvironmentCommand

Bases: Command

Shows application-specific environment variables.

async execute(auxdata)
Parameters:
class appcore.introspection.Presentations(value)

Bases: Enum

Presentation mode (format) for CLI output.

appcore.introspection.execute_cli()

Synchronous entrypoint.

Module appcore.state

Immutable global state.

class appcore.state.DirectorySpecies(value)

Bases: Enum

Possible species for locations.

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

Module appcore.inscription

Application inscription management.

Logging and, potentially, debug printing.

type appcore.inscription.Levels = Literal['debug', 'info', 'warn', 'error', 'critical']
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:
appcore.inscription.Modes

alias of Presentations

class appcore.inscription.Presentations(value)

Bases: Enum

Scribe presentation modes.

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

Bases: DataclassObject

Descriptor for file-based inscription targets.

Variables:
class appcore.inscription.TargetModes(value)

Bases: Enum

Target file mode control.

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

Prepares various scribes in a sensible manner.

Parameters:

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:
Return type:

appcore.state.Globals

Module appcore.exceptions

Family of exceptions for package API.

This module defines a comprehensive exception hierarchy for the appcore library, providing specific exception types for different failure modes while maintaining a consistent interface for error handling and debugging.

Exception Hierarchy

The exception hierarchy follows a two-tier design:

  • Omniexception - Base for all package exceptions

  • Omnierror - Base for error exceptions, inherits from both Omniexception and Exception

Usage

Catch all package errors with Omnierror or with built-in exception types. See class inheritance for details.

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.ContextInvalidity(auxdata)

Bases: Omnierror, TypeError, ValueError

exception appcore.exceptions.DependencyAbsence(dependency, feature)

Bases: Omnierror, ImportError

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