form

Version: 0.1.16

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
• Tests
• Architecture
• Integration in the Suite
• Dependencies
• Versioning & Compatibility Policy
• License
• About us
• Known Limitations & Roadmap
• Status & Compatibility
• Useful Links
• 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:

pytest tests/

With coverage:

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:

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 for the complete package ecosystem.

Dependencies

• attrs: >=23.1.0
• cattrs: >=23.1.0
• wexample-helpers: >=19.1.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 file for details.

Free to use in both personal and commercial projects.

About us

Wexample 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 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
• Issue Tracker: https://github.com/wexample/python-form/issues
• Discussions: https://github.com/wexample/python-form/discussions
• PyPI: 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.