Metadata-Version: 2.4
Name: cowser
Version: 1.5.2
Summary: A fun CLI that greets you with ASCII art animals.
Author: rkriad585
License: MIT License
        
        Copyright (c) 2026 rkriad585
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/rkriad585/Cowser
Project-URL: Repository, https://github.com/rkriad585/Cowser
Project-URL: Documentation, https://rkriad585.github.io/Cowser/
Project-URL: Changelog, https://github.com/rkriad585/Cowser/blob/main/CHANGELOG.md
Keywords: cowsay,ascii-art,cli,cow,animals,fun
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: color
Requires-Dist: colorama>=0.4.6; extra == "color"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: binary
Requires-Dist: pyinstaller>=6.0; extra == "binary"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="logo/logo.svg" alt="Cowser logo" height="150">
</p>

<h1 align="center">Cowser</h1>

<p align="center">Greet people with ASCII art animals — a fun, cross-platform
reimagining of <code>cowsay</code>, written in Python.</p>

<p align="center">
  <a href="https://pypi.org/project/cowser/"><img src="https://img.shields.io/pypi/v/cowser.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/cowser/"><img src="https://img.shields.io/pypi/pyversions/cowser.svg" alt="Python versions"></a>
  <a href="https://github.com/rkriad585/Cowser/actions/workflows/docs.yml"><img src="https://github.com/rkriad585/Cowser/actions/workflows/docs.yml/badge.svg" alt="Docs"></a>
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
  <img src="https://img.shields.io/badge/made%20by-rkriad585-blueviolet.svg" alt="Made by rkriad585">
  <!-- TODO: fill - there is no test-CI workflow; only docs.yml deploys the site. -->
</p>

<p align="center">Cowser is a command-line tool (and Python library) that wraps a
message in a speech or thought bubble and prints it above a randomly chosen
animal. It supports 35 built-in animals, cowsay-style moods, colors, fortunes,
interactive REPL sessions, and user-supplied art packs — while staying a pure,
side-effect-free function you can also call from your own code.</p>

## Screenshot

<p align="center">
  <img src="Screenshots/home.png" alt="home screen" width="80%">
</p>

<p align="center"><em>More screenshots: <a href="docs/screenshots.md">View all screenshots</a></em></p>

## Table of Contents

- [Key Features](#key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
- [Documentation](#documentation)
- [Interface](#interface)
- [Architecture](#architecture)
- [Requirements](#requirements)
- [Prerequisites](#prerequisites)
- [Development](#development)
- [Contributing](#contributing)
- [Security](#security)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## Key Features

- **35 animals** across 12 categories — cows, cats, pets, birds, sea life,
  farm, wild, robot, hedgehog, alien, spooky, and mythical creatures
- **Greetings and messages** — greet a name, pass a custom message, or pipe
  text in from stdin
- **cowsay-style moods** — `--mode borg|dead|greedy|paranoid|stoned|drunk|wired|youthful`
  plus thought bubbles with `--think`
- **Custom eyes and tongues** — `--eyes` and `--tongue` replace `{eyes}` and
  `{tongue|default}` tokens in the art
- **Word wrapping** — `-W/--wrap WIDTH`, disabled with `-n/--no-wrap`
- **Color output** — `--rainbow`, `--bold`, and 17 ANSI colors via `--color`;
  a `colorama` extra fixes legacy Windows consoles
- **Fortune mode** — a random fortune instead of a message (`--fortune`)
- **Two animals at once** — render a pair side by side (`--and`)
- **Interactive REPL** — chat-style session (`--interactive`)
- **Reproducible output** — `--seed` fixes random animal selection
- **Legacy-console fallback** — output is sanitized for cp437/cmd.exe when the
  console cannot encode it
- **Art packs** — drop `.cow`, `.txt`, or `.art` files in a folder and Cowser
  picks them up, no code changes needed
- **Config file** — defaults live in `~/.config/neostore/cowser/config.toml`
- **Windows wrappers** — `cowser.cmd` and `cowser.ps1`, plus single-file
  binaries built with PyInstaller
- **Library use** — the stable `cowser.api` surface is pure, type-hinted, and
  covered by a backwards-compatibility guarantee

## Installation

```bash
pip install cowser
```

Requires Python 3.8+. For color support on legacy Windows consoles
(pre-Windows 10 cmd.exe):

```bash
pip install "cowser[color]"
```

From source:

```bash
git clone https://github.com/rkriad585/Cowser
cd Cowser
pip install .
```

See [docs/installation.md](docs/installation.md) for platform-specific notes
and [docs/getting-started.md](docs/getting-started.md) for a first-run tour.

## Quick Start

```bash
cowser Alice                       # greet with a random animal
cowser --cow owl Bob               # pick a specific animal
echo "From stdin" | cowser         # pipe a message
cowser --fortune                   # random fortune
```

## Usage Examples

### CLI

```bash
cowser Alice                 # greet with a random animal
cowser --cow owl Bob         # pick a specific animal
cowser --message "Hello!"    # custom message
cowser --mode dead --cow pig # mood preset (eyes + tongue)
cowser --think --cow owl "Where am I?"
cowser --rainbow --bold --message "Party time!"
cowser --fortune             # random fortune
cowser --cow dog --and cat "Best friends"
cowser --list                # show all animals
cowser --search mythical     # search by name, category, or tag
cowser --interactive         # chat REPL
cowser --cow-dir ./my-cows "hello from my pack"
```

### Library

```python
from cowser import COWS, render, render_pair, register_cow, search_cows, Cow

print(render("Hello from my app", cow="owl", eyes="0.0"))
print(render("moo", cow="pig", mode="dead", think=True))
print(render_pair("best friends", "dog", "cat", rainbow=True))

for cow in search_cows(category="mythical"):
    print(cow.name, cow.tags)

register_cow(Cow("my-dragon", "   ~\n  (o.o)", category="mythical"))
```

### Configuration

```toml
# ~/.config/neostore/cowser/config.toml
color = "green"
cow = "fish"
eyes = "o o"
mode = "dead"
wrap = 40
# seed = 42
```

Command-line flags always override config values. See
[config.example.toml](config.example.toml) and
[docs/configuration.md](docs/configuration.md).

## Documentation

| File | Contents |
|------|----------|
| [docs/index.md](docs/index.md) | Home page of the docs site |
| [docs/screenshots.md](docs/screenshots.md) | Screenshots of the CLI in action |
| [docs/getting-started.md](docs/getting-started.md) | First-run tour and next steps |
| [docs/installation.md](docs/installation.md) | Install on Windows, macOS, Linux, and from source |
| [docs/usage.md](docs/usage.md) | Every CLI option and command |
| [docs/cli.md](docs/cli.md) | Command-line reference |
| [docs/api.md](docs/api.md) | Library API reference |
| [docs/configuration.md](docs/configuration.md) | Config file and environment variables |
| [docs/architecture.md](docs/architecture.md) | Module layout and how rendering works |
| [docs/development.md](docs/development.md) | Dev setup, tests, and type checks |
| [docs/deployment.md](docs/deployment.md) | Packaging, binaries, and container images |
| [docs/faq.md](docs/faq.md) | Frequently asked questions |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Common problems and fixes |
| [docs/contributing.md](docs/contributing.md) | Contributing guide (docs site) |

## Interface

Cowser exposes two interfaces from the same code base:

- **CLI** — the `cowser` command (installed via `pip`), plus
  `python -m cowser`, `python main.py` for backwards compatibility with the
  original script, and the Windows wrappers `cowser.cmd` / `cowser.ps1`.
  Run `cowser --help` for the full option list, or
  [docs/cli.md](docs/cli.md).
- **Library** — import `cowser` or the stable surface `cowser.api`:
  `Cow`, `COWS`, `render`, `render_pair`, `render_cow`, `build_speech_bubble`,
  `resolve_cow`, `search_cows`, `register_cow`, `substitute_eyes`,
  `substitute_tongue`, `wrap_text`, and the art-pack helpers. All functions are
  pure (no I/O) and fully type-hinted. See [docs/api.md](docs/api.md).

## Architecture

`cowser` is a small, layered Python package with no hard runtime dependencies
(`tomli` is used only on Python < 3.11). The CLI calls into pure rendering
functions; the renderer substitutes tokens, builds the bubble, and applies
ANSI styling.

```text
cowser/
├── __init__.py     # re-exports the stable surface + __version__
├── __main__.py     # python -m cowser entry point
├── api.py          # cowser.api: backwards-compatible public names
├── cli.py          # argparse CLI, config defaults, REPL
├── config.py       # reads ~/.config/neostore/cowser/config.toml
├── core.py         # render(), render_pair(), bubble & wrapping logic
├── cows.py         # Cow dataclass + built-in COWS registry (35 animals)
├── modes.py        # mode -> (eyes, tongue) presets
├── ansi.py         # colors, rainbow, bold, legacy-console sanitizing
├── fortunes.py     # built-in fortunes for --fortune
├── plugins.py      # art packs (.cow/.txt/.art loaders)
└── py.typed        # PEP 561 marker
```

Data flow: `cli.py` resolves text and options → `core.render()`/`render_pair()`
→ `core._substituted_art()` applies `modes.py`/`cowser.cows` token
substitutions → `build_speech_bubble()` → `ansi.py` styling →
`cli.py` sanitizes for legacy consoles and prints. Art packs are registered by
`plugins.py` into the shared `COWS` registry before rendering.

See [docs/architecture.md](docs/architecture.md) for the full breakdown.

## Requirements

- **OS** — platform-independent (Linux, macOS, Windows; the PyPI classifier
  declares "OS Independent"). The legacy-console fallback specifically targets
  Windows cmd.exe with cp437.
- **Runtime** — Python 3.8 or newer.
- **Hardware** — no special requirements; a terminal is all you need.
- **Dependencies** — none at runtime on Python 3.11+; `tomli` on Python < 3.11
  for TOML config parsing. Optional extras: `color`, `dev`, `binary`, `docs`.

## Prerequisites

- **Python 3.8+** and **pip**.
  Install from <https://www.python.org/downloads/>, a package manager
  (`winget install Python.Python.3.12`, `brew install python`,
  `apt install python3 python3-pip`), or a version manager such as `pyenv`.
- **Git** (only needed for installing from source).

## Development

```bash
git clone https://github.com/rkriad585/Cowser
cd Cowser
pip install -e ".[dev]"
python -m pytest      # run the test suite
python -m mypy cowser # type check
```

Run the docs site locally with `mkdocs serve`. Full guidance in
[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/development.md](docs/development.md).

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
branch rules, commit style, and the pull-request workflow.

## Security

Report vulnerabilities by opening an issue or contacting the maintainer — see
[SECURITY.md](SECURITY.md) for supported versions and how to report.

## License

[MIT](LICENSE) &copy; 2026 rkriad585.

## Acknowledgments

Inspired by [cowsay](https://en.wikipedia.org/wiki/Cowsay). Cow art draws on
the classic cow face / [ASCII art](https://en.wikipedia.org/wiki/ASCII_art)
tradition.
