YAE

YAE is a collection of miscellaneous command-line utilities, built on a small declarative framework (powered by tyro) that makes it easy to add new subcommands and configurable options.

Features

• Declarative subcommands — register a function as a CLI command with @subcommand.
• Layered configuration — merge YAML/JSON config files over dataclass defaults.
• Rich output — colored, human-readable output via rich.
• Built-in commands:
  • date — date/time and timestamp conversion.
  • currency — CNY exchange rates (source: China Merchants Bank).
  • config — show the effective configuration as a tree.

Installation

Requires Python 3.9+.

pip install .

For development (includes test dependencies):

pip install -e .[dev]

Installing adds a yae console script; you can also run python -m yae.

Usage

yae [-h] [-v] {config,currency,date}

Global options:

• -v / --verbose — increase log verbosity (repeatable: -v, -vv, -vvv).

date

Convert between date/time strings and timestamps. Timestamp precision (seconds / milliseconds / microseconds) is auto-detected.

yae date                                   # current time + timestamp
yae date -t 1700000000                     # timestamp -> datetime
yae date -t 1700000000000                  # milliseconds auto-detected
yae date -d "2024-01-01 12:00:00"          # datetime -> timestamp
yae date -d "2024-01-01T12:00:00+08:00" -f iso
yae date -t 1700000000 --utc               # UTC instead of local time

-f/--format accepts the presets auto, iso, date, time, or any strftime format.

currency

Query CNY exchange rates from China Merchants Bank. Rates are quoted per 100 units of foreign currency.

yae currency                 # list all rates
yae currency -c USD          # detail for a single currency
yae currency -c USD -a 100   # 100 USD -> CNY
yae currency -c USD -a 1000 --reverse   # 1000 CNY -> USD

config

Show the effective (merged) configuration as a tree.

yae config

Configuration

YAE reads config files in order and merges them; later entries override earlier ones:

1. bundled defaults: yae/resources/config.yaml
2. user config: ~/.config/yae/config.yaml
3. project config: ./.yae.yaml
4. YAE_CONFIG_PATH environment variable (highest priority)

Supported formats: YAML (.yaml / .yml) and JSON (.json).

Example:

yae:
  ext_modules: []
  server:
    host: "localhost"
    port: 9020

Values missing from the files fall back to the registered dataclass defaults. Run yae config to inspect the final, merged configuration.

Extending

Register a subcommand

from dataclasses import dataclass

import yae


@dataclass
class HelloArgs:
    name: str = "world"


@yae.subcommand("hello")
def hello(args: HelloArgs, config: yae.Config):
    print(f"Hello, {args.name}!")

Register configuration

from dataclasses import dataclass

from yae.base import register_config


@register_config("yae.server")
class ServerConfig:
    host: str = "localhost"
    port: int = 9020

External modules

yae.ext_modules lists modules imported at startup (e.g. plugins that register subcommands or config). Entries are module names or "path:module", where path is prepended to sys.path before importing.

Development

pip install -e .[dev]
pytest

License

MIT