Metadata-Version: 2.4
Name: yae
Version: 1.0.0a1
Summary: YAE - A Collection of Miscellaneous Utilities
Home-page: https://github.com/malanore-z/yae
Author: malanore
Author-email: malanore.z@gmail.com
Project-URL: Bug Tracker, https://github.com/malanore-z/yae/issues
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru
Requires-Dist: PyYAML
Requires-Dist: requests
Requires-Dist: rich
Requires-Dist: textcase
Requires-Dist: tyro
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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+.

```bash
pip install .
```

For development (includes test dependencies):

```bash
pip install -e .[dev]
```

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

## Usage

```text
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.

```bash
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.

```bash
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.

```bash
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:

```yaml
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

```python
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

```python
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

```bash
pip install -e .[dev]
pytest
```

## License

[MIT](LICENSE)

[tyro]: https://github.com/brentyi/tyro
[rich]: https://github.com/Textualize/rich
