Metadata-Version: 2.1
Name: wexample-form
Version: 0.1.17
Summary: Declares CLI forms as composable models with validators and renderers, built on top of wexample-prompt
Author-Email: weeger <contact@wexample.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Project-URL: homepage, https://github.com/wexample/python-form
Requires-Python: >=3.10
Requires-Dist: attrs>=23.1.0
Requires-Dist: cattrs>=23.1.0
Requires-Dist: wexample-helpers>=20.0.0
Requires-Dist: wexample-prompt>=15.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-benchmark>=5.2.3; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Description-Content-Type: text/markdown

# form

Version: 0.1.17

`wexample-form` is a Python library for declaring CLI forms as composable models with validators and renderers, built on top of `wexample-prompt`. It targets Python ≥ 3.10 developers in the Wexample suite who need structured, reusable input handling for command-line interfaces. The model layer relies on `attrs` and `cattrs`, keeping field definitions, validation, and rendering as distinct, separately testable concerns.

## Table of Contents

- [Quickstart](#quickstart)
- [Tests](#tests)
- [Architecture](#architecture)
- [Integration in the Suite](#integration-in-the-suite)
- [Dependencies](#dependencies)
- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
- [License](#license)
- [About us](#about-us)
- [Known Limitations & Roadmap](#known-limitations--roadmap)
- [Status & Compatibility](#status--compatibility)
- [Useful Links](#useful-links)
- [Migration Notes](#migration-notes)

## Quickstart

`wexample-form` is not yet implemented. The package ships only the `py.typed` marker and an empty `__init__.py`; no public API exists to import or call. This page will be written once the model, validator, and renderer layers described in the architecture document are in place.

## Tests

Run the test suite:

```bash
pytest tests/
```

With coverage:

```bash
pytest --cov=form tests/
```

## Architecture

`wexample-form` is a Python library for declaring CLI forms as composable models. The design keeps three concerns separate: **models** declare form fields using `attrs`, **validators** check field values independently of presentation, and **renderers** drive the terminal interaction through `wexample-prompt`. None of these three layers is expected to reach into the other two.

### Repository layout

The project uses PDM with a `src` layout. The distributable package lives under `src/wexample_form/`; build metadata is declared in pyproject.toml.

```
src/
  wexample_form/   ← installed package (wexample-form on PyPI)
tests/             ← pytest suite (testpaths = ["tests"])
examples/          ← runnable usage examples
```

`pytest` is configured with `pythonpath = ["src"]`, so the package resolves from source without installation during development.

### Dependency stack

Each dependency occupies a distinct layer:

| Package | Minimum | Role |
|---|---|---|
| `attrs` | 23.1.0 | Class generation and field definitions for form models |
| `cattrs` | 23.1.0 | Structuring and unstructuring of model data |
| `wexample-helpers` | 19.0.0 | Shared utilities from the Wexample suite |
| `wexample-prompt` | 14.1.0 | All terminal output — renderers delegate here entirely |

`attrs` + `cattrs` handle the model layer; `wexample-prompt` handles everything the user sees. `wexample-helpers` provides cross-cutting utilities shared across the suite.

### Three-concern design

The library is built around three independently testable concerns:

1. **Model** — an `attrs`-based class that declares the fields of a form, their types, and defaults.
2. **Validator** — logic that inspects field values and raises or returns errors without knowing how the form renders.
3. **Renderer** — receives a model instance and drives the CLI interaction through `wexample-prompt`, keeping all terminal code out of the model.

A form is defined as a model, validated independently, then handed to a renderer that uses `wexample-prompt` to present prompts and collect input. The split means a validator can be unit-tested against plain Python values, and a renderer can be swapped without touching model or validation code.

## Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

### Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.

## Dependencies

- attrs: >=23.1.0
- cattrs: >=23.1.0
- wexample-helpers: >=20.0.0
- wexample-prompt: >=15.0.0

## Versioning & Compatibility Policy

Wexample packages follow **Semantic Versioning** (SemVer):

- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Free to use in both personal and commercial projects.

## About us

[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

## Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the [project roadmap](https://github.com/wexample/python-form/issues) for upcoming features and improvements.

## Status & Compatibility

**Maturity**: Production-ready

**Python Support**: >=3.10

**OS Support**: Linux, macOS, Windows

**Status**: Actively maintained

## Useful Links

- **Homepage**: https://github.com/wexample/python-form
- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
- **Issue Tracker**: https://github.com/wexample/python-form/issues
- **Discussions**: https://github.com/wexample/python-form/discussions
- **PyPI**: [pypi.org/project/wexample-form](https://pypi.org/project/wexample-form/)

## Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.
