Metadata-Version: 2.4
Name: h9a
Version: 0.2.1
Summary: Count how many times a digit appears in a range of numbers, with a colorized step-by-step breakdown.
Author-email: RK Riad Khan <rkriad585@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rkriad585/h9a
Project-URL: Documentation, https://rkriad585.github.io/h9a
Keywords: cli,terminal,math,counting,educational
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich
Requires-Dist: pyfiglet
Provides-Extra: screenshot
Requires-Dist: Pillow; extra == "screenshot"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/rkriad585/h9a/main/logo/logo.svg" alt="H9A logo" height="150">
</p>

<h1 align="center">H9A — How Many 9 in 1 to 100</h1>

<p align="center">
  A CLI tool and Python library that counts how many times a digit appears in a range of numbers, with a colorized step-by-step breakdown.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.8%2B-3776AB" alt="Python 3.8+">
  <img src="https://img.shields.io/badge/License-MIT-yellow" alt="License: MIT">
  <img src="https://img.shields.io/pypi/v/h9a" alt="PyPI version">
  <img src="https://img.shields.io/github/actions/workflow/status/rkriad585/h9a/docs.yml" alt="Docs build">
  <img src="https://img.shields.io/github/actions/workflow/status/rkriad585/h9a/publish-container.yml" alt="Container build">
  <img src="https://img.shields.io/badge/Made%20by-rkriad585-1F6FEB" alt="Made by rkriad585">
</p>

## Overview

H9A is an installable Python package that counts how many times a given digit appears in a range of numbers (by default: the digit 9 between 1 and 100). It provides both a `h9a` command-line tool and an importable library, and it prints each step of the calculation — the per-place counts and the combined total — as styled, colorized output. It is built with `rich` for console formatting, `pyfiglet` for an ASCII-art banner, and Pillow for optional terminal-style screenshots.

## Screenshot

<p align="center">
  <img src="https://raw.githubusercontent.com/rkriad585/h9a/main/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>

> The screenshot above is generated by the tool itself. Regenerate it at any time with `h9a --screenshot`.

## Table of Contents

- [Overview](#overview)
- [Screenshot](#screenshot)
- [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

- **Installable package** — `pip install h9a` provides the `h9a` command and the `h9a` importable library (`h9a/core.py`).
- **CLI with options** — `--digit`, `--start`, `--end`, `--json`, `--no-color`, `--screenshot`, and `--version` (`h9a/cli.py`).
- **Library API** — `count_digit()` returns a `DigitCount` with a per-place breakdown; `build_lines()`, `render_text()`, and `generate_screenshot()` are available to other programs (`h9a/__init__.py`).
- **Instant results on huge ranges** — `count_digit()` uses a closed-form, per-place formula, so ranges like 1 to 1,000,000,000 are counted instantly instead of being iterated number by number.
- **Step-by-step calculation** — prints the count for each decimal place (ones, tens, hundreds, ...) and the running total.
- **Colorized output** — uses the `rich` library for styled, readable console output.
- **ASCII-art banner** — renders "H9A" with `pyfiglet` (`h9a/render.py`).
- **Screenshot generation** — renders the output to a terminal-style PNG image with Pillow (`h9a/screenshot.py`, `Screenshots/home.png`).

## Installation

### From PyPI

```bash
python -m pip install h9a
```

For screenshot support, install the extra:

```bash
python -m pip install "h9a[screenshot]"
```

### From the repository

```bash
git clone https://github.com/rkriad585/h9a.git
cd h9a
python -m pip install .
```

For development, install in editable mode with the screenshot extra:

```bash
python -m pip install -e .[screenshot]
```

### Dependencies

- `rich`
- `pyfiglet`
- `Pillow` (optional — only needed for `--screenshot` / `generate_screenshot`)

Full instructions are in [docs/installation.md](docs/installation.md).

## Quick Start

```bash
python -m pip install rich pyfiglet
python -m h9a
```

If you installed the package, you can also use the console script directly:

```bash
h9a
```

## Usage Examples

```text
 _   _  ___    _
| | | |/ _ \  / \
| |_| | (_) |/ _ \
|  _  |\__, / ___ \
|_| |_|  /_/_/   \_\


How Many 9 In 1 to 100

Calculating step by step...
Step 2: 9 appears 10 times in the ones place.
Step 3: 9 appears 10 times in the tens place.
Step 4: Total occurrences of 9 = 20.

Explanation:
1. In the ones place: The digit 9 appears in numbers like 9, 19, 29, ..., 99.
2. In the tens place: The digit 9 appears in numbers like 90, 91, 92, ..., 99.
3. Total occurrences are calculated by adding these together.

Final Result: In the range 1 to 100, the digit '9' appears 20 times!
```

Count a different digit over a different range:

```bash
h9a --digit 5 --start 1 --end 50
```

Machine-readable output:

```bash
h9a --json
```

```json
{
  "digit": 9,
  "start": 1,
  "end": 100,
  "by_position": {
    "1": 10,
    "10": 10
  },
  "total": 20
}
```

## Documentation

| Document | Description |
| --- | --- |
| [docs/getting-started.md](docs/getting-started.md) | From a clean environment to the first run. |
| [docs/installation.md](docs/installation.md) | Installing the package, dependencies, and the Docker option. |
| [docs/usage.md](docs/usage.md) | What the output means, step by step. |
| [docs/cli.md](docs/cli.md) | The command-line interface reference. |
| [docs/api.md](docs/api.md) | Using H9A as a Python library. |
| [docs/architecture.md](docs/architecture.md) | How the package is structured and how it flows. |
| [docs/configuration.md](docs/configuration.md) | Configuration options (CLI flags; no config files). |
| [docs/development.md](docs/development.md) | Cloning, running, and modifying the source. |
| [docs/deployment.md](docs/deployment.md) | Running H9A directly, in Docker, or via the automated release pipelines. |
| [docs/faq.md](docs/faq.md) | Frequently asked questions. |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Common errors and fixes. |
| [docs/screenshots.md](docs/screenshots.md) | Screenshot gallery index. |

## Interface

### Command line

The `h9a` command takes no positional arguments:

```text
h9a [--digit DIGIT] [--start START] [--end END] [--json] [--no-color] [--screenshot [PATH]] [--version]
```

| Option | Description |
| --- | --- |
| `--digit DIGIT` | Digit (0-9) to count. Default `9`. |
| `--start START` | First number of the range, inclusive. Default `1`. |
| `--end END` | Last number of the range, inclusive. Default `100`. |
| `--json` | Print machine-readable JSON instead of styled text. |
| `--no-color` | Disable colors in the styled output. |
| `--screenshot [PATH]` | Render the output to a PNG image (default `Screenshots/home.png`). |
| `--version` | Print the version and exit. |
| `-h`, `--help` | Show the help text and exit. |

Exit codes: `0` on success, `2` on invalid arguments.

### Library

```python
from h9a import count_digit

result = count_digit(digit=9, start=1, end=100)
print(result.total)        # 20
print(result.by_position)  # {1: 10, 10: 10}
```

See [docs/api.md](docs/api.md) for the full library reference.

## Architecture

The project is an installable Python package. The `h9a` package contains four modules:

```mermaid
flowchart TD
    CLI["h9a/cli.py (argparse)"]
    API["h9a/__init__.py (public API)"]
    Core["h9a/core.py - count_digit()"]
    Render["h9a/render.py - build_lines()"]
    Shot["h9a/screenshot.py - generate_screenshot()"]
    CLI --> Core
    CLI --> Render
    CLI --> Shot
    API --> Core
    API --> Render
    API --> Shot
    Render --> Core
    Shot --> Render
```

```text
h9a/
├── .github/
│   └── workflows/
│       ├── docs.yml            # documentation -> GitHub Pages
│       └── publish-container.yml  # container -> GHCR
├── Dockerfile
├── LICENSE                 # MIT
├── README.md
├── Screenshots/
│   └── home.png            # generated by `h9a --screenshot`
├── docs/                   # project documentation
├── h9a/                    # installable package
│   ├── __init__.py         # public API
│   ├── __main__.py         # python -m h9a
│   ├── cli.py              # h9a command-line interface
│   ├── core.py             # counting logic
│   ├── render.py           # styled output lines
│   └── screenshot.py       # Pillow screenshot generator
├── logo/
│   └── logo.svg
├── pyproject.toml          # package metadata and h9a entry point
└── tests/                  # pytest suite
```

## Requirements

- Python 3.8 or later
- `rich`
- `pyfiglet`
- `Pillow` (optional — only for `--screenshot` / `generate_screenshot`)

## Prerequisites

- A working Python 3.8+ installation with `pip`
- `git` to clone the repository
- A terminal that supports ANSI colors for the best visual output (colors are optional — the text is readable without them)

## Development

```bash
git clone https://github.com/rkriad585/h9a.git
cd h9a
python -m pip install -e .[screenshot]
h9a
```

Run the checks with `pytest`, `ruff`, and `mypy` (installed via `python -m pip install -e ".[dev]"`). GitHub Actions deploys the documentation to GitHub Pages and publishes the container image to GitHub Container Registry. See [docs/development.md](docs/development.md).

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a pull request.

## Security

Please report security issues privately as described in [SECURITY.md](SECURITY.md).

## License

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

## Acknowledgments

- [RK Riad Khan](https://github.com/rkriad585) — author and maintainer.
- Built with the [`rich`](https://pypi.org/project/rich/), [`pyfiglet`](https://pypi.org/project/pyfiglet/), and [Pillow](https://pypi.org/project/pillow/) libraries.
