Roman Numerals

4.1.0 · active · verified Thu Apr 09

The `roman-numerals` library provides utilities to manipulate well-formed Roman numerals, including converting between integers and Roman numeral strings. The current version is 4.1.0, and it generally sees major releases annually with minor updates as needed.

Warnings

breaking The `Roman` class constructor arguments changed from positional to keyword-only. Previously, `Roman('IV')` or `Roman(4)` was valid. Post-3.0.0, you must use keyword arguments like `Roman(string='IV')` or `Roman(integer=4)`.
Fix: Update `Roman` class instantiations to use `string=` or `integer=` keyword arguments.
breaking The `Roman` class constructor logic was refined. If both `integer` and `string` keyword arguments are provided, `integer` now takes precedence. Additionally, an empty string (`''`) for the `string` argument will now result in a `Roman` object representing `None`.
Fix: Review code where both `integer` and `string` might be passed to the `Roman` constructor, ensuring the desired precedence. Be aware of `Roman(string='')` behavior.
gotcha The library primarily supports Roman numerals representing integers from 1 to 3999 (inclusive). Inputs outside this range for integers, or malformed Roman numeral strings, will raise `ValueError`.
Fix: Validate input integers are within the 1-3999 range before conversion. Handle `ValueError` for invalid Roman numeral strings.
breaking The `Roman` class was introduced, and the `to_roman` and `from_roman` functions were moved to be directly importable from the top-level `roman_numerals` package. Earlier versions might have required different import paths or not had the `Roman` class.
Fix: Ensure imports for `to_roman` and `from_roman` are directly from `from roman_numerals import ...`. Utilize the `Roman` class for object-oriented manipulation.

Install

pip install roman-numerals Install stable version

Imports

Roman
```
from roman_numerals import Roman
```
to_roman
```
from roman_numerals import to_roman
```
from_roman
```
from roman_numerals import from_roman
```

Quickstart

Demonstrates converting integers to Roman numerals and vice-versa using both the `Roman` class and the utility functions `to_roman` and `from_roman`.

from roman_numerals import Roman, to_roman, from_roman

# Using the Roman class
roman_four = Roman(integer=4)
print(f"Roman(integer=4): {roman_four} (integer: {roman_four.integer})")

roman_ninety = Roman(string='XC')
print(f"Roman(string='XC'): {roman_ninety} (integer: {roman_ninety.integer})")

# Using direct functions
converted_to_roman = to_roman(1994)
print(f"to_roman(1994): {converted_to_roman}")

converted_from_roman = from_roman('MCMXCIV')
print(f"from_roman('MCMXCIV'): {converted_from_roman}")

view raw JSON →