Roman numerals kata in Python

Implement conversions between Arabic numerals and Roman numerals in Python 3.11 or later with pytest. Setup is complete when the existing starter test passes.

Overview

This kata complements Clean Code: Advanced TDD, Ep. 19.

This repository contains two exercises designed to improve your skills in test-driven development.

Instructions

Roman numerals are a numeral system used in ancient Rome. Numbers in this system use seven letters from the Latin alphabet:

Symbol	Value
I	1
V	5
X	10
L	50
C	100
D	500
M	1000

Instead of writing the same letter four times, a subtraction rule is used: the letter is written once, followed by the next larger Roman numeral. For example, 4 is not written as IIII, but instead as IV, because IV is V (5) minus I (1).

In general, the values for 5, 50, and 500 are not subtracted.

Exercise 1

Implement to_roman(number: int) -> str to convert Arabic numerals into Roman numerals, such as:

• 4 → IV
• 7 → VII
• 9 → IX

The smallest supported number is 1 (I), and the largest is 3999 (MMMCMXCIX).

Exercise 2

Implement from_roman(number: str) -> int to perform the reverse conversion from Roman numerals to Arabic numerals.

Guiding principles

• If you don't know an existing algorithm, follow the principles of strict Test-Driven Development (TDD) to derive one.
• Reflect on whether the sequence in which you write tests influences the final design of your algorithm.
• Consider whether it's more beneficial to devise an algorithm before embarking on TDD, especially if you don't already know one.
• If you do know an algorithm, evaluate if it can be implemented using strict TDD principles.

Prerequisites

Required:

• Git
• uv

Optional:

• GNU Make, for shorter commands. Every required task also has a direct uv command.

You do not need to install Python or pytest separately. uv installs a compatible Python version and the locked project dependencies when needed.

Set up the kata

1. Clone the repository:

   git clone https://github.com/Coding-Cuddles/roman-numerals-python-kata.git

2. Enter the repository directory:

   cd roman-numerals-python-kata

3. Run the existing test. Use Make when it is installed:

   make test

   Otherwise, run pytest through uv directly:

   uv run pytest test_*.py

   The first run may install Python and the project dependencies. Setup is complete when pytest reports 1 passed.

   If the command fails with uv: command not found, install uv and repeat this step.

Work on the kata

1. Add the next behavior to test_roman_numerals.py, then implement it in roman_numerals.py.

2. Run the tests after each change. Use Make when it is installed:

   make test

   Otherwise, run pytest through uv directly:

   uv run pytest test_*.py

   Continue when the test run passes.

Make command reference

Make is optional. Run make or make help to list these commands in the terminal.

Command	Result
make all	Run the test suite
make help	List public Make targets
make test	Run the test suite
make format	Format tracked Python files
make format-check	Check formatting without changing files
make clean	Remove generated caches