Metadata-Version: 2.4
Name: nine-recursive-calculator
Version: 0.1.2
Summary: A recursive digit-sum calculator
Author: Py Guy Py
License: MIT
Project-URL: Homepage, https://github.com/bistudio/codeplay/tree/main/python/nine-project
Project-URL: Repository, https://github.com/bistudio/codeplay/tree/main/python/nine-project
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Nine

A Python command-line application that recursively calculates the digital root of an integer after multiplying it by nine.

Nine was created as a practical project to explore **recursion, package structure, automated testing, Python packaging, and production-style development**.

![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Tests](https://img.shields.io/badge/tests-13%20passing-brightgreen)

---

## Features

* Accepts whole numbers, including positive and negative integers
* Handles zero as a special case
* Multiplies the supplied number by 9
* Recursively calculates the digit sum
* Continues recursively until the digital root is reached
* Validates invalid user input
* Provides a command-line interface
* Includes automated tests using `pytest`
* Distributed as a standard Python package

For every positive integer `n`, the digital root of `n × 9` is 9. Zero returns 0.

For example:

```text
27 × 9 = 243
2 + 4 + 3 = 9
```

---

## Tech Stack

* **Language:** Python
* **Testing:** pytest
* **Packaging:** setuptools
* **Build:** Python Build
* **Distribution:** PyPI / TestPyPI
* **Interface:** Command-line application

---

## Getting Started

### Prerequisites

* Python 3.10 or later

### Installation

The package can be installed from PyPI using:

```bash
python -m pip install nine-recursive-calculator
```

### Run the application

After installation, run:

```bash
nine
```

You will be prompted to enter an integer.

Example:

```text
Enter a number: 27
Number entered: 27
Product: 243
Digital root: 9
```

---

## Development Installation

To work with the source code locally, clone the repository:

```bash
git clone https://github.com/bistudio/codeplay.git
cd codeplay/python/nine-project
```

Create a virtual environment:

```bash
python -m venv .venv
```

### Windows PowerShell

```powershell
.\.venv\Scripts\Activate.ps1
```

### macOS / Linux

```bash
source .venv/bin/activate
```

Install the package in editable mode:

```bash
python -m pip install -e .
```

Run the application:

```bash
nine
```

---

## Usage

Enter a whole number when prompted.

### Positive integer

```text
Enter a number: 37
Number entered: 37
Product: 333
Digital root: 9
```

### Zero

```text
Enter a number: 0
Number entered: 0
Product: 0
Digital root: 0
```

### Negative integer

Negative numbers are converted to their absolute value before calculation.

```text
Enter a number: -27
Number entered: -27
Product: -243
Digital root: 9
```

### Invalid input

Invalid or blank input is rejected:

```text
Enter a number:
Invalid input. Please enter a whole number.
```

---

## How It Works

The project uses recursion in two functions.

### `digit_sum(n)`

`digit_sum()` recursively calculates the sum of the individual digits of an integer.

For example:

```text
digit_sum(243)
```

The recursive calculation is:

```text
243 % 10 = 3
24  % 10 = 4
2   % 10 = 2
```

Therefore:

```text
2 + 4 + 3 = 9
```

### `nine(n)`

`nine()` multiplies the supplied number by 9 and recursively processes the resulting digit sum until the digital root is reached.

For example:

```text
nine(27)

27 × 9 = 243
digit_sum(243) = 9
nine(9) = 9
```

The recursion stops when the base case is reached.

---

## API Reference

### `digit_sum(n)`

**Purpose:**
Recursively calculates the sum of the digits of an integer.

**Parameter:**

```text
n: int
```

**Returns:**

```text
int
```

Returns the sum of the digits. `0` returns `0`.

**Example:**

```python
digit_sum(243)
```

Returns:

```text
9
```

---

### `nine(n)`

**Purpose:**
Multiplies an integer by 9 and recursively calculates its digital root.

**Parameter:**

```text
n: int
```

**Returns:**

```text
int
```

Returns the digital root. Positive integers return `9`; zero returns `0`.

**Example:**

```python
nine(27)
```

Calculation:

```text
27 × 9 = 243
2 + 4 + 3 = 9
```

Returns:

```text
9
```

---

## Testing

The project uses `pytest`.

Run the complete test suite with:

```bash
pytest
```

The current test suite contains **13 tests** covering:

* Positive integers
* Negative integers
* Zero
* Single-digit numbers
* The value 9
* The transition around 10
* Very large integers
* Invalid input
* Blank input
* Command-line behaviour
* Recursion behaviour

---

## What I Learned

This project began as a simple recursion exercise and developed into a practical Python package.

The project provided an opportunity to learn:

* Base cases
* Recursive calls
* Recursion unwinding
* Local state within recursive calls
* Passing state through recursion
* Recursive digit processing
* Function composition
* Input validation
* Automated testing
* Test-driven improvements
* Python package structure
* `src` layout
* `pyproject.toml`
* Building wheels and source distributions
* Package metadata
* Command-line entry points
* TestPyPI publishing
* Installing packages from a package index
* Git branching, commits and releases

One of the main lessons from the project is that there can be many ways to solve a problem. Developing a strong solution requires understanding the trade-offs between correctness, readability, maintainability and efficiency, while remaining open to improving the implementation as knowledge develops.

---

## Future Improvements

* [ ] Improve code efficiency and readability as understanding develops
* [ ] Expand automated test coverage
* [ ] Add command-line arguments
* [ ] Improve command-line error handling
* [ ] Add package documentation
* [ ] Add a web interface
* [ ] Explore alternative implementations and compare their performance

---

## Project Structure

```text
nine-project/
├── src/
│   └── nine/
│       ├── __init__.py
│       ├── calculator.py
│       └── cli.py
├── tests/
│   ├── __init__.py
│   ├── test_calculator.py
│   └── test_cli.py
├── README.md
├── pyproject.toml
└── .gitignore
```

---

## License

This project is licensed under the MIT License.

See the repository for the complete license information.
