Modules#

An overview of the packages that make up pun. The API reference below is generated automatically from the source docstrings.

Core (pun.core)#

Always-included infrastructure.

Configurations for the project.

pydantic settings pun.core.config.Settings[source]#

Bases: BaseSettings

Application settings using pydantic-settings.

Settings can be configured via environment variables or .env file. All settings are prefixed with the project name.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = ignore

  • env_prefix: str = PUN_

  • env_file: str = .env

  • env_file_encoding: str = utf-8

Fields:
field debug: bool = False#

Enable debug mode

field log_level: str = 'INFO'#

Logging level

field config_dir: Path = PosixPath('/home/runner/.pun')#

Configuration directory

pun.core.config.get_settings()[source]#

Return the cached settings singleton.

Cached so all callers share one instance; tests can reset or override it via get_settings.cache_clear() instead of patching an import-time value.

Returns:

The cached settings instance.

Return type:

Settings

Directory configurations for the project.

pun.core.dirs.HOME_IS_RESOLVABLE: bool = True#

Whether the user’s home directory could be resolved at import time.

When False the project has no user-owned directory to write to, so file logging is disabled in core/logging_setup.py rather than falling back to a predictable shared location.

pun.core.dirs.ROOT_FOLDER_NAME: str = '.pun'#

Name of the root folder.

pun.core.dirs.ROOT_FOLDER_PATH: Path = PosixPath('/home/runner/.pun')#

Path to the root folder.

pun.core.dirs.LOG_FILE_PATH: Path = PosixPath('/home/runner/.pun/main.log')#

Path to the log file.

pun.core.dirs.CONFIG_FILE_PATH: Path = PosixPath('/home/runner/.pun/config.json')#

Path to the config file.

Set up logging for the project.

This module configures logging for the project, ensuring that log handlers are only added once to prevent duplicate log entries if the module is imported multiple times.

Setup is resilient to a read-only or unavailable $HOME: if the log directory cannot be created it degrades to console-only logging instead of raising, so read-only commands (--help, version) stay usable.

pun.core.logging_setup.get_logger()[source]#

Return the cached project logger.

Returns:

The cached project logger.

Return type:

logging.Logger

pun.core.logging_setup.setup_logger()[source]#

Set up and return the main logger for the project.

Ensures that handlers are only added once to avoid duplicate log entries if this module is imported multiple times.

Returns:

Configured logger for the project.

Return type:

logging.Logger

Utilities (pun.utils)#

Shared helper functions.

Utilities package for the project.

CLI (pun.cli)#

Typer command-line interface exposing version and info commands.

CLI application for the project.

The pun command is the single Typer root. Every enabled component other than the primary (CLI > GUI > TUI > web > MCP > worker) is hung off it as a lazily-imported subcommand — pun interactive (TUI), pun web, pun mcp, … — rather than a separate pun-<name> console script (see https://hasansezertasan.github.io/copier-pyproject/context/components/#secondary-components-are-subcommands-of-one-console-root-not-separate-scripts).

pun.cli.app.info()[source]#

Display information about the pun application.

Show application information:

pun info

Example output:

Application Version: 0.1.0 Python Version: 3.12.0 (CPython) Platform: Darwin

Raises:

typer.Exit – If the package metadata cannot be found.

Return type:

None

pun.cli.app.interactive()[source]#

Start interactive mode (TUI) for pun.

Launch the terminal user interface:

pun interactive

Raises:

typer.Exit – Propagating the TUI’s exit code, or code 1 if a dependency of the TUI is missing from this environment.

Return type:

None

pun.cli.app.show_version()[source]#

Show the current version number of pun.

Show the version number:

pun version

Example output:

0.1.0

Raises:

typer.Exit – If the package metadata cannot be found.

Return type:

None

TUI (pun.tui)#

Textual terminal user interface.

TUI application for the project.

final class pun.tui.app.InfoApp(message)[source]#

Bases: App[None]

Simple TUI application displaying project info.

Initialize the application.

Parameters:

  • message – The formatted information message to display.

  • message (str)

CSS: ClassVar[str] = '\n    Screen {\n        align: center middle;\n        background: $surface;\n    }\n\n    #info-container {\n        width: 60;\n        height: auto;\n        border: solid $primary;\n        background: $panel;\n    }\n\n    Static {\n        width: 100%;\n        height: auto;\n        padding: 1;\n    }\n\n    #title {\n        dock: top;\n        height: 3;\n        border-bottom: solid $primary;\n        background: $boost;\n        text-align: center;\n        content-align: center middle;\n    }\n\n    #footer {\n        dock: bottom;\n        height: 1;\n        border-top: solid $primary;\n        text-align: center;\n        background: $boost;\n    }\n    '#

Inline CSS, useful for quick scripts. This is loaded after CSS_PATH, and therefore takes priority in the event of a specificity clash.

BINDINGS: ClassVar[list[BindingType]] = [('q', 'quit', 'Quit')]#

The default key bindings.

compose()[source]#

Compose the TUI layout.

Yields:

Widget – The widgets that make up the screen layout.

Return type:

Iterable[Widget]

on_mount()[source]#

Set focus and style on mount.

Return type:

None

exception pun.tui.app.TuiDisplayError[source]#

Bases: RuntimeError

Raised when the TUI cannot be displayed.

pun.tui.app.build_info_message()[source]#

Return a short application information message for display.

Returns:

A multi-line summary of the project name, version, and platform.

Return type:

str

pun.tui.app.main(*, show_tui=True, driver=<function _run_app>)[source]#

Entry point for the TUI script.

Parameters:

  • show_tui – When False, write the info to stdout instead of starting the TUI (useful for headless environments and tests).

  • driver – Optional driver callable for running the TUI app.

  • show_tui (bool)

  • driver (Callable[[InfoApp], None])

Returns:

0 on success, 1 if the TUI could not be displayed.

Return type:

int