API Reference#

This page is generated from public source docstrings.

Configuration Constants#

tuning.ISO_FORMAT = '[%Y-%m-%d %H:%M:%S]'#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

tuning.DEFAULT_MAX_BYTES = 10000000#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

tuning.DEFAULT_BACKUP_COUNT = 3#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

Configuration Functions#

tuning.getLogger(name=None)#
Overloads:

  • name (str) → TunedLogger

  • name (None) → logging.Logger

Parameters:

name (str | None)

Return type:

Logger

Return a logger using tuning’s logger class for named loggers.

Parameters:

name (str | None) – Logger name. If omitted, returns the process root logger.

Returns:

A TunedLogger for named loggers, or the stdlib root logger when name is omitted.

Raises:

ValueError – If name is empty or an existing logger with that name is not a TunedLogger.

Return type:

Logger

tuning.addLevel(num, name, symbol=None, icon=None, style=None)#

Register a runtime-only custom log level and logger method.

The level is added to stdlib logging for the current Python process and a matching method is installed on TunedLogger. For example, addLevel(7, “MY_CUSTOM_LEVEL”) creates logger.my_custom_level(…) for existing and future tuning loggers. This does not update YAML files or exported configuration.

Parameters:

  • num (int) – Numeric logging level code.

  • name (str) – Custom level name. Names are normalized to uppercase and must create a valid Python method name when lowercased.

  • symbol (str | None) – Compact console prefix used when icons are disabled.

  • icon (str | None) – Console prefix used when show_icon=True.

  • style (str | None) – Rich style applied to console level prefixes and messages.

Raises:

ValueError – If the level definition is invalid or conflicts with an existing logging level or dynamic method.

Return type:

None

tuning.basicConfig(*, filename=None, filemode='a', max_bytes=None, backup_count=None, format=None, datefmt=None, style='%', level=30, stream=None, handlers=None, force=False, encoding=None, errors=None, console=False, show_icon=False, show_level=True, show_path=False, show_time=False, boxes=False, rich_tracebacks=True, markup=True, defaults_path=None)#

Configure the process root logger with tuning defaults.

This follows stdlib logging.basicConfig() semantics: if the root logger already has handlers, the call is ignored unless force=True is passed. Without filename, a console TunedHandler is installed. With filename, a detailed file handler is installed; pass console=True to install both.

Parameters:

  • filename (str | Path | None) – File path for file logging. If omitted, console logging is configured instead.

  • filemode (str) – File open mode for file handlers.

  • max_bytes (int | str | None) – Rotation threshold in bytes or as a human-readable size string such as “10 MB”. Ignored when filename is omitted.

  • backup_count (int | None) – Number of rotated log files to keep. Ignored when filename is omitted.

  • format (str | None) – Formatter format string passed to logging.basicConfig().

  • datefmt (str | None) – Formatter date format. For console timestamps, use this with show_time=True; ISO_FORMAT is provided as a convenience.

  • style (str) – Formatter style passed to logging.basicConfig().

  • level (int | str | None) – Root logger level.

  • stream (Any | None) – Console stream target.

  • handlers (list[Handler] | None) – Explicit handlers. Cannot be combined with stream, filename, or console.

  • force (bool) – Replace existing root handlers.

  • encoding (str | None) – File encoding for file handlers.

  • errors (str | None) – File encoding error handling for file handlers.

  • console (bool) – Also create a console handler when filename is provided.

  • show_icon (bool) – Use configured level icons instead of symbols.

  • show_level (bool) – Show level prefixes or boxed level titles in console output.

  • show_path (bool) – Show source file path in console output.

  • show_time (bool) – Show timestamps in console output.

  • boxes (bool) – Render each console log record inside a Rich panel.

  • rich_tracebacks (bool) – Render Rich tracebacks in console output.

  • markup (bool) – Enable Rich markup in console messages.

  • defaults_path (str | Path | None) – Optional defaults file used instead of the packaged config. Intended for tests and advanced integrations.

Raises:

ValueError – If boolean options or rotation values are invalid, or if mutually exclusive handler options are combined.

Return type:

None

tuning.basicConfigFromYaml(config_path=None, *, defaults_path=None, force=False)#

Configure the process root logger from YAML.

The packaged tuning/conf.yml defaults are loaded first. If config_path is provided, it is deep-merged on top. The resulting config is applied to the real process root logger with stdlib logging.config.dictConfig().

Parameters:

  • config_path (str | Path | None) – Optional YAML override path. If omitted, packaged defaults are used directly.

  • defaults_path (str | Path | None) – Optional defaults file used instead of the packaged config. Intended for tests and advanced integrations.

  • force (bool) – Replace existing root handlers.

Raises:

ValueError – If the resolved YAML config is invalid.

Return type:

None

tuning.export(path=None, *, force=False)#

Export the packaged default configuration to a YAML file.

The exported file is copied from packaged tuning/conf.yml; it does not reconstruct the current runtime logging state.

Parameters:

  • path (str | Path | None) – Destination file path or existing directory. If omitted, writes tuning.yml next to the calling Python file.

  • force (bool) – Overwrite an existing target file.

Return type:

Path

Returns:

The resolved path that was written.

Raises:

  • FileExistsError – If the target file exists and force is false.

  • ValueError – If force is not a boolean.

Display Helpers#

tuning.banner(path=None, name=None, *, border_style=None, text_style=None, padding=(0, 0), border=True, box=None, background_style=None)#

Print an application banner from a banner file.

Banner files contain one or more sections marked by ### banner_name. When path is omitted, banners.txt is discovered by walking upward from the calling file’s directory. If the caller has no file, discovery starts from the current working directory.

Parameters:

  • path (str | Path | None) – Banner file path, directory containing banners.txt, or None to discover banners.txt from the caller location.

  • name (str | None) – Optional banner name. If omitted, a random banner that fits the current terminal width is selected.

  • border_style (str | None) – Rich style for the panel border. If omitted, a random bold color is used.

  • text_style (str | None) – Rich style for the banner text. If omitted, a random bold color is used.

  • padding (tuple[int] | tuple[int, int] | tuple[int, int, int, int]) – Rich-compatible padding tuple. Accepts (all,), (vertical, horizontal), or (top, right, bottom, left).

  • border (bool) – Render the banner inside a Rich panel when true. When false, only styled text and padding are rendered.

  • box (str | Box | None) – Optional Rich box style name or rich.box.Box object. String names are matched case-insensitively against rich.box constants and the custom MEGA_BOLD style.

  • background_style (str | None) – Optional Rich style for the panel background. When border=False, this style is applied to the padding area.

Return type:

str | None

Returns:

The exact banner body printed, or None when no banner fits the terminal and the fallback message is printed instead.

Raises:

  • ValueError – If no banner file can be discovered, or if the banner file is malformed.

  • FileNotFoundError – If an explicit banner file path does not exist.

  • KeyError – If name is provided but no matching banner exists.

Logger Classes#

class tuning.TunedLogger#

Logger subclass with YAML configuration and styled prompts.

TunedLogger behaves like a normal stdlib logger while adding from_yaml() for named logger configuration and prompt() for styled interactive input.

__init__(name, level=0)#

Initialize the logger with a name and an optional level.

Parameters:

  • name (str)

  • level (int)

Return type:

None

isEnabledFor(level)#

Is this logger enabled for level ‘level’?

Return type:

bool

Parameters:

level (int)

classmethod from_yaml(config_path, *, name='app', defaults_path=None, force=False)#

Configure and return one named TunedLogger from YAML.

The packaged tuning/conf.yml defaults are loaded first, then config_path is deep-merged on top. This method configures only the requested named logger. If the YAML defines only root, that section is used as the template for the named logger and does not configure the process root logger.

Parameters:

  • config_path (str | Path) – YAML override path.

  • name (str) – Logger name to configure.

  • defaults_path (str | Path | None) – Optional defaults file used instead of the packaged config. Intended for tests and advanced integrations.

  • force (bool) – Replace existing managed handlers for the same logger.

Return type:

TunedLogger

Returns:

The configured TunedLogger.

Raises:

ValueError – If the logger name is invalid, the logger already exists as a non-TunedLogger, or an existing configuration would be replaced without force=True.

prompt(message, *, password=False, markup=None)#

Prompt for interactive input using configured prompt styling.

Parameters:

  • message (str) – Prompt question to display.

  • password (bool) – Hide input while typing.

  • markup (bool | None) – Whether Rich markup in the prompt message is enabled. If omitted, the first inherited TunedHandler setting is used.

Return type:

str

Returns:

The user’s typed input.

Raises:

  • ValueError – If message is not a string.

  • EOFError – If input cannot be read from the console.

class tuning.TunedHandler#

Rich console handler that renders tuning level metadata.

TunedHandler extends Rich’s RichHandler with symbol/icon level prefixes, full-message level styling, and optional per-record boxes. It is normally created through basicConfig() or YAML configuration rather than instantiated directly.

__init__(*args, show_icon=False, boxes=False, **kwargs)#

Create a console handler.

Parameters:

  • *args (Any) – Positional arguments passed to rich.logging.RichHandler.

  • show_icon (bool) – Use configured level icons instead of symbols when an icon is available.

  • boxes (bool) – Render each console log record inside a Rich panel.

  • **kwargs (Any) – Keyword arguments passed to rich.logging.RichHandler.

Return type:

None

get_level_text(record)#

Get the level name from the record.

Parameters:

record (LogRecord) – LogRecord instance.

Returns:

A tuple of the style and level name.

Return type:

Text

render_message(record, message)#

Render message text in to Text.

Parameters:

  • record (LogRecord) – logging Record.

  • message (str) – String containing log message.

Returns:

Renderable to display log message.

Return type:

Any

render(*, record, traceback, message_renderable)#

Render log for display.

Parameters:

  • record (LogRecord) – logging Record.

  • traceback (Any) – Traceback instance or None for no Traceback.

  • message_renderable (Any) – Renderable (typically Text) containing log message contents.

Returns:

Renderable to display log.

Return type:

Any

Data Models#

class tuning.LevelSpec#

Metadata attached to a logging level.

name#

Level name, for example INFO or SUCCESS.

code#

Numeric stdlib logging level code.

symbol#

Compact text prefix used when icons are disabled.

icon#

Icon prefix used when show_icon=True.

style#

Rich style applied to console level prefixes and messages.

__init__(name, code, symbol=None, icon=None, style=None)#
Parameters:

  • name (str)

  • code (int)

  • symbol (str | None)

  • icon (str | None)

  • style (str | None)

Return type:

None

class tuning.PromptSpec#

Metadata used to render styled interactive prompts.

symbol#

Prompt prefix used when icons are disabled.

icon#

Prompt prefix used when icons are enabled.

style#

Rich style applied to the prompt prefix and question text.

__init__(symbol=None, icon=None, style=None)#
Parameters:

  • symbol (str | None)

  • icon (str | None)

  • style (str | None)

Return type:

None