Metadata-Version: 2.5
Name: wuti-py-util
Version: 0.7.4
Summary: Small Python toolkit: structured files, validation, filesystem, and optional tabular readers.
Project-URL: Homepage, https://github.com/wuti-labs/wuti-py-util
Project-URL: Repository, https://github.com/wuti-labs/wuti-py-util
Author-email: Alex Qin <qinqinghai@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: csv,excel,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: jsonschema>=4.25
Requires-Dist: pyyaml>=6.0.1
Provides-Extra: all
Requires-Dist: openpyxl>=3.1.5; extra == 'all'
Requires-Dist: pandas>=2.3; extra == 'all'
Requires-Dist: tabulate>=0.10.0; extra == 'all'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.5; extra == 'excel'
Requires-Dist: pandas>=2.3; extra == 'excel'
Requires-Dist: tabulate>=0.10.0; extra == 'excel'
Provides-Extra: pandas
Requires-Dist: pandas>=2.3; extra == 'pandas'
Requires-Dist: tabulate>=0.10.0; extra == 'pandas'
Description-Content-Type: text/markdown

# wuti-py-util

[![codecov](https://codecov.io/github/wuti-labs/wuti-py-util/graph/badge.svg?token=DTNQBHFGM5)](https://codecov.io/github/wuti-labs/wuti-py-util)

A small Python toolkit for internal tools: read and write structured files,
validate inputs, touch the filesystem safely, and optionally read CSV/Excel.

Requirements: Python >= 3.12. [uv](https://docs.astral.sh/uv/) is recommended
for local development.

## Install

```sh
pip install wuti-py-util
```

The core package only depends on `jsonschema` and `PyYAML`. DataFrame and Excel
features are opt-in:

| Extra    | Enables                                | Install                              |
| -------- | -------------------------------------- | ------------------------------------ |
| `pandas` | `conversion_stats`, `csv` (CsvReader)  | `pip install "wuti-py-util[pandas]"` |
| `excel`  | `excel` (ExcelReader), includes pandas | `pip install "wuti-py-util[excel]"`  |
| `all`    | Everything above                       | `pip install "wuti-py-util[all]"`    |

## What this library is

Core modules: `serialization`, `validation`, `filesystem`, `log`, `csv` /
`excel` (extras), `check`, plus small helpers (`filelist`, `filehash`,
`datetime`, `string`, `environment`, `process`).

Frozen (kept for compatibility, no new features): `database`, `web`,
`dataclass_utils`.

## Development

Development dependencies (pytest, coverage, ruff, mypy, hatchling, etc.) live in
`[dependency-groups].dev` in `pyproject.toml` — not as a published PyPI extra.
Use [uv](https://docs.astral.sh/uv/) from the repository root:

```sh
uv sync --group dev
```

Run checks through that environment:

```sh
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
```

If you intentionally use an already-active shared venv, use `--inexact` so uv
does not remove packages installed manually with `uv pip install`:

```sh
uv sync --active --inexact --group dev
uv run --active pytest
uv run --active ruff check .
uv run --active ruff format --check .
uv run --active mypy
```

## Build and publish

Version comes from `__version__` in `src/wuti/util/__init__.py`. The GitHub
Release workflow requires the git tag (`vX.Y.Z`) to match that version. PyPI
rejects duplicate versions.

```sh
uv build
uv pip install dist/wuti_py_util-<version>.tar.gz
```

Publish to PyPI (`https://upload.pypi.org/legacy/`) with a [PyPI API
token](https://pypi.org/manage/account/token/) via `UV_PUBLISH_TOKEN` or
`--token`:

```sh
uv publish
```
