H9A — How Many 9 in 1 to 100

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.

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

More screenshots: View all screenshots

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

Table of Contents

• Overview
• Screenshot
• Key Features
• Installation
• Quick Start
• Usage Examples
• Documentation
• Interface
• Architecture
• Requirements
• Prerequisites
• Development
• Contributing
• Security
• License
• 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

python -m pip install h9a

For screenshot support, install the extra:

python -m pip install "h9a[screenshot]"

From the repository

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

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

python -m pip install -e .[screenshot]

Dependencies

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

Full instructions are in docs/installation.md.

Quick Start

python -m pip install rich pyfiglet
python -m h9a

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

h9a

Usage Examples

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


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:

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

Machine-readable output:

h9a --json

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

Documentation

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

Interface

Command line

The h9a command takes no positional arguments:

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

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 for the full library reference.

Architecture

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

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

h9a/
├── .github/
│   └── workflows/
│       ├── docs.yml            # documentation -> GitHub Pages
│       └── publish-container.yml  # container -> GHCR
├── Dockerfile
├── LICENSE                 # GNU GPL v3
├── 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

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.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and the Code of Conduct before opening a pull request.

Security

Please report security issues privately as described in SECURITY.md.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Acknowledgments

• RK Riad Khan — author and maintainer.
• Built with the rich, pyfiglet, and Pillow libraries.