Metadata-Version: 2.4
Name: cowser
Version: 1.4.0
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: Changelog, https://github.com/rkriad585/Cowser/releases
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"
Dynamic: license-file

# Cowser

![Logo](logo.svg)

A fun, cross-platform command-line tool that greets you with ASCII art
animals. Inspired by `cowsay`, written in Python.

## Features

- **35+ animals** across categories: cows, cats, dogs, birds, sea life,
  robots, mythical creatures and more
- Greet users with a random animal, or pick one by name/index/prefix
- Custom messages and piping from stdin
- **Configurable eyes** (`--eyes`) and **tongues** (`--tongue`) on token-based art
- **cowsay-style modes** (`--mode dead`, `--think`, ...)
- **Word wrapping** for long messages (`-W/--wrap`, `-n/--no-wrap`)
- **Color themes**: rainbow, bold, plus plain colored output
- **Fortune mode** (`--fortune`) and **two animals at once** (`--and`)
- **Interactive REPL** (`--interactive`)
- **Colored output** (ANSI, works on modern Windows terminals)
- **Legacy-console fallback** — output is automatically made printable for
  cp437/cmd.exe and other old codepages
- **Windows wrappers** (`cowser.cmd`, `cowser.ps1`) and **single-file
  binaries** built with PyInstaller for Linux/macOS/Windows
- **Config file** at `~/.config/neostore/cowser/config.toml`
- Usable as a **library** in your own Python code

## Installation

Requires Python 3.8+.

```bash
pip install cowser
```

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

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

From source:

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

## Usage

```bash
cowser Alice                 # greet with a random animal
cowser --cow owl Bob         # pick a specific animal
cowser --message "Hello!"    # custom message
echo "From stdin" | cowser   # pipe a 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
```

```
 _________
/ Hi Bob! \
\__________/
   _____
  / o o \
 (   V   )
  \_____/
```

### Options

| Option                    | Description                                    |
|---------------------------|------------------------------------------------|
| `-c, --cow NAME_OR_INDEX` | Choose an animal by name, prefix, or index.    |
| `-e, --eyes CHARS`        | Replace the `{eyes}` token in the art.         |
| `--mode MODE`             | Preset style: borg, dead, greedy, paranoid, stoned, drunk, wired, youthful. |
| `--tongue CHARS`          | Replace the `{tongue}` token in the art.       |
| `--think`                 | Use a thought bubble instead of a speech bubble. |
| `-W, --wrap WIDTH`        | Word-wrap the message to WIDTH columns.        |
| `-n, --no-wrap`           | Disable word wrapping.                         |
| `--rainbow`               | Colorize output line by line in rainbow order. |
| `--bold`                  | Make the output bold.                          |
| `--fortune`               | Show a random fortune instead of a message.    |
| `--and NAME_OR_INDEX`     | Render a second animal next to the first.      |
| `--interactive`           | Start an interactive REPL session.             |
| `--seed INT`              | Seed random selection for reproducible output. |
| `-m, --message TEXT`      | Show a custom message instead of a greeting.   |
| `-l, --list`              | List all available animals.                    |
| `--search TEXT`           | List animals matching name, category, or tag.  |
| `--color COLOR`           | Output color (default: `cyan`).                |
| `--no-color`              | Disable colored output.                        |
| `-V, --version`           | Show version.                                  |
| `-h, --help`              | Show help.                                     |

### Legacy commands

Backwards-compatible with the original script:

```bash
python main.py Alice
python main.py help
python main.py list
./cowset Alice
```

### Windows wrappers

On Windows, if `python` is on your PATH, use the bundled wrappers instead of
installing anything extra:

```cmd
cowser.cmd Alice
cowser.cmd --cow owl --message "Hello"
```

```powershell
.\cowser.ps1 Alice
.\cowser.ps1 --think --cow owl "Where am I?"
```

### Single-file binaries

Optional standalone binaries (no Python needed) are built with PyInstaller:

```bash
pip install -e ".[binary]"
python scripts/build_binary.py
```

The binary lands in `dist/` (`cowser.exe` on Windows). CI also builds and
attaches Linux/macOS/Windows binaries to every `v*` git tag.

### Legacy consoles

When output cannot be encoded by the current console (e.g. cp437 `cmd.exe`),
Cowser automatically replaces unsupported characters with readable ASCII —
smart quotes, dashes, accents, and emoji all get a safe fallback.

## Configuration

Defaults are read from `~/.config/neostore/cowser/config.toml`.
Command-line flags always win. See [`config.example.toml`](config.example.toml).

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

## Using Cowser as a library

`cowser` (and its stable surface, `cowser.api`) exposes a pure, side-effect
free API — no I/O — so it is safe to embed in other tools. All public
functions are fully type-hinted and documented with examples.

```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"))
```

The stable public surface is listed in `cowser.api.__all__`:
`Cow`, `COWS`, `render`, `render_pair`, `render_cow`, `build_speech_bubble`,
`resolve_cow`, `search_cows`, `register_cow`, `substitute_eyes`,
`substitute_tongue`, and `wrap_text`. These names are covered by a
backwards-compatibility guarantee.

## Adding more animals

Open `cowser/cows.py` and add a `Cow` to the `COWS` list. Art may include an
`{eyes}` token that `--eyes` replaces, and a `{tongue|default}` token that
`--tongue` (or `--mode`) replaces:

```python
Cow("my-cow", r"""   /\
  /  \
 | oo |
  ~~   ~~""", "misc", ("new",)),
```

## Development

```bash
pip install -e ".[dev]"
python -m pytest
python -m mypy cowser
```

Tests and type checks run on Linux, macOS, and Windows via GitHub Actions.

## License

[MIT](LICENSE) &copy; 2026 rkriad585
