# Sayer
<p align="center">
<a href="https://sayer.dymmond.com"><img src="https://res.cloudinary.com/tarsild/image/upload/v1747661493/packages/Sayer/Logo/w8bq4nqcphyd99kns0wl.svg" alt='Sayer logo'></a>
</p>
<p align="center">
<em>Fast. Scalable. Elegant. Command the CLI like a boss. 🧙♂️</em>
</p>
<p align="center">
<a href="https://github.com/dymmond/sayer/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" target="_blank">
<img src="https://github.com/dymmond/sayer/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" alt="Test Suite">
</a>
<a href="https://pypi.org/project/sayer" target="_blank">
<img src="https://img.shields.io/pypi/v/sayer?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/sayer" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/sayer.svg?color=%2334D058" alt="Supported Python versions">
</a>
</p>
---
**Documentation**: [https://sayer.dymmond.com](https://sayer.dymmond.com) 📚
**Source Code**: [https://github.com/dymmond/sayer](https://github.com/dymmond/sayer)
**The official supported version is always the latest released**.
---
## 🤔 What is Sayer?
Sayer is a modern, async-native Python CLI framework built for developers who want more:
- More structure.
- More power.
- More expressiveness.
Less boilerplate. Less headache. Less "why doesn't this just work?".
Designed to scale from weekend scripts to enterprise-grade CLI suites — with a touch of magic.
---
## 📦 Installation
**Using [pip](https://pip.pypa.io/):**
```bash
pip install sayer
```
**Or with [uv](https://github.com/astral-sh/uv) (blazing fast):**
```bash
uv pip install sayer
```
---
## 🧩 Features
* ✅ Fully async support out-of-the-box
* ✅ Param metadata via `Option(...)`, `Argument(...)`, `Env(...)` — inspired by the best
* ✅ Declarative CLI building with decorators
* ✅ Built-in middleware system (yes, for CLI!)
* ✅ Shared app state and lifecycle management
* ✅ Terminal-rich output via `rich`
* ✅ Easy testing with `SayerTestClient`
* ✅ Flexible help and docs rendering
* ✅ Clean project scaffolding, sensible defaults
* ✅ 100% type annotated.
---
## 🔥 Why Sayer?
| Feature | Sayer | Notes |
| --------------------- | ------------ | --------------------------------- |
| Async Support | ✅ Yes | Truly async from top to bottom |
| Param Metadata | ✅ Yes | With rich options, env vars, etc. |
| Middleware Support | ✅ Yes | Per-command, app-wide, scoped |
| Lifecycle Hooks | ✅ Yes | `on_startup`, `on_shutdown` |
| State Management | ✅ Yes | Like a Flask `g` but better |
| Testability | ✅ Yes | CLI client for unit tests |
| Output Styling | ✅ Yes | Built-in `rich` integration |
| Based on Modern Tools | ✅ Hatch + UV | Modern dev setup from day 1 |
| Full Typing | ✅ Yes | Mypy + Ruff compliant |
| Fun to Use? | 🕺 Extremely | Let the code dance with you |
---
## 🚀 Getting Started
Create your first CLI app:
```python
from sayer import Sayer, Option
app = Sayer()
@app.command()
def hello(name: str = Option(..., help="Your name")):
"""Say hello to someone"""
print(f"Hello, {name}!")
if __name__ == "__main__":
app()
```
Run it:
```bash
$ python app.py hello --name Ada
Hello, Ada!
```
---
## 🧪 Testing
```bash
hatch run test:test
```
Or with pytest:
```bash
pytest -v
```
---
## 📚 Documentation
Full docs available at: [https://sayer.dymmond.com](https://sayer.dymmond.com)
You’ll find:
* Full API reference
* Command examples
* Parameter deep dives
* Middleware patterns
* Configuration strategies
* ... and some fun easter eggs 🐣
Raw data
{
"_id": null,
"home_page": null,
"name": "sayer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "attrs, cli, click, command-line, dataclass, json, msgspec, pydantic, rich, sayer, serialization",
"author": null,
"author_email": "Tiago Silva <tiago@tarsild.io>",
"download_url": "https://files.pythonhosted.org/packages/c4/9d/2709ffae7dd874f8756cafb57ef6ff6f0400985b301d5022cabb752b1f67/sayer-0.4.0.tar.gz",
"platform": null,
"description": "# Sayer\n\n<p align=\"center\">\n <a href=\"https://sayer.dymmond.com\"><img src=\"https://res.cloudinary.com/tarsild/image/upload/v1747661493/packages/Sayer/Logo/w8bq4nqcphyd99kns0wl.svg\" alt='Sayer logo'></a>\n</p>\n\n<p align=\"center\">\n <em>Fast. Scalable. Elegant. Command the CLI like a boss. \ud83e\uddd9\u200d\u2642\ufe0f</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/dymmond/sayer/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main\" target=\"_blank\">\n <img src=\"https://github.com/dymmond/sayer/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main\" alt=\"Test Suite\">\n</a>\n\n<a href=\"https://pypi.org/project/sayer\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/sayer?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n\n<a href=\"https://pypi.org/project/sayer\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/sayer.svg?color=%2334D058\" alt=\"Supported Python versions\">\n</a>\n</p>\n\n---\n\n**Documentation**: [https://sayer.dymmond.com](https://sayer.dymmond.com) \ud83d\udcda\n\n**Source Code**: [https://github.com/dymmond/sayer](https://github.com/dymmond/sayer)\n\n**The official supported version is always the latest released**.\n\n---\n\n## \ud83e\udd14 What is Sayer?\n\nSayer is a modern, async-native Python CLI framework built for developers who want more:\n\n- More structure.\n- More power.\n- More expressiveness.\n\nLess boilerplate. Less headache. Less \"why doesn't this just work?\".\n\nDesigned to scale from weekend scripts to enterprise-grade CLI suites \u2014 with a touch of magic.\n\n---\n\n## \ud83d\udce6 Installation\n\n**Using [pip](https://pip.pypa.io/):**\n\n```bash\npip install sayer\n```\n\n**Or with [uv](https://github.com/astral-sh/uv) (blazing fast):**\n\n```bash\nuv pip install sayer\n```\n\n---\n\n## \ud83e\udde9 Features\n\n* \u2705 Fully async support out-of-the-box\n* \u2705 Param metadata via `Option(...)`, `Argument(...)`, `Env(...)` \u2014 inspired by the best\n* \u2705 Declarative CLI building with decorators\n* \u2705 Built-in middleware system (yes, for CLI!)\n* \u2705 Shared app state and lifecycle management\n* \u2705 Terminal-rich output via `rich`\n* \u2705 Easy testing with `SayerTestClient`\n* \u2705 Flexible help and docs rendering\n* \u2705 Clean project scaffolding, sensible defaults\n* \u2705 100% type annotated.\n\n---\n\n## \ud83d\udd25 Why Sayer?\n\n| Feature | Sayer | Notes |\n| --------------------- | ------------ | --------------------------------- |\n| Async Support | \u2705 Yes | Truly async from top to bottom |\n| Param Metadata | \u2705 Yes | With rich options, env vars, etc. |\n| Middleware Support | \u2705 Yes | Per-command, app-wide, scoped |\n| Lifecycle Hooks | \u2705 Yes | `on_startup`, `on_shutdown` |\n| State Management | \u2705 Yes | Like a Flask `g` but better |\n| Testability | \u2705 Yes | CLI client for unit tests |\n| Output Styling | \u2705 Yes | Built-in `rich` integration |\n| Based on Modern Tools | \u2705 Hatch + UV | Modern dev setup from day 1 |\n| Full Typing | \u2705 Yes | Mypy + Ruff compliant |\n| Fun to Use? | \ud83d\udd7a Extremely | Let the code dance with you |\n\n---\n\n## \ud83d\ude80 Getting Started\n\nCreate your first CLI app:\n\n```python\nfrom sayer import Sayer, Option\n\napp = Sayer()\n\n@app.command()\ndef hello(name: str = Option(..., help=\"Your name\")):\n \"\"\"Say hello to someone\"\"\"\n print(f\"Hello, {name}!\")\n\nif __name__ == \"__main__\":\n app()\n```\n\nRun it:\n\n```bash\n$ python app.py hello --name Ada\nHello, Ada!\n```\n\n---\n\n## \ud83e\uddea Testing\n\n```bash\nhatch run test:test\n```\n\nOr with pytest:\n\n```bash\npytest -v\n```\n\n---\n\n## \ud83d\udcda Documentation\n\nFull docs available at: [https://sayer.dymmond.com](https://sayer.dymmond.com)\n\nYou\u2019ll find:\n\n* Full API reference\n* Command examples\n* Parameter deep dives\n* Middleware patterns\n* Configuration strategies\n* ... and some fun easter eggs \ud83d\udc23\n",
"bugtrack_url": null,
"license": null,
"summary": "The click running on steroids",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://sayer.dymmond.com/release-notes/",
"Documentation": "https://sayer.dymmond.com",
"Funding": "https://github.com/sponsors/tarsil",
"Homepage": "https://github.com/dymmond/sayer",
"Source": "https://github.com/dymmond/sayer"
},
"split_keywords": [
"attrs",
" cli",
" click",
" command-line",
" dataclass",
" json",
" msgspec",
" pydantic",
" rich",
" sayer",
" serialization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c040155ce21ac36cf92fe0c1855b639a36a7724241186d6ce0341e6132795e29",
"md5": "6a5795a86c86b6a76839fa6a09b2d4dd",
"sha256": "e0adfacd33a2d54ddf5305be9d27e632a27fdcfa06ddff5769b0dd30913e1d40"
},
"downloads": -1,
"filename": "sayer-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a5795a86c86b6a76839fa6a09b2d4dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 63756,
"upload_time": "2025-07-21T19:27:43",
"upload_time_iso_8601": "2025-07-21T19:27:43.963327Z",
"url": "https://files.pythonhosted.org/packages/c0/40/155ce21ac36cf92fe0c1855b639a36a7724241186d6ce0341e6132795e29/sayer-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c49d2709ffae7dd874f8756cafb57ef6ff6f0400985b301d5022cabb752b1f67",
"md5": "6bdb4389f707426a70626b7622a1b86f",
"sha256": "d69c8a5ef1fd729fd74fb0857a13b881d9232cccd2ad48d08addc3d6781210bf"
},
"downloads": -1,
"filename": "sayer-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "6bdb4389f707426a70626b7622a1b86f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 51952,
"upload_time": "2025-07-21T19:27:45",
"upload_time_iso_8601": "2025-07-21T19:27:45.142372Z",
"url": "https://files.pythonhosted.org/packages/c4/9d/2709ffae7dd874f8756cafb57ef6ff6f0400985b301d5022cabb752b1f67/sayer-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 19:27:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "tarsil",
"github_not_found": true,
"lcname": "sayer"
}
JSON
