Roman Numeral Converter

5.2 · active · verified Sat Apr 11

The `roman` library is a small, active Python utility that facilitates the conversion of Arabic (decimal) integers to Roman numerals and vice versa. Currently at version 5.2, it supports Python 3.10 and newer, with a history of regular updates often tied to Python version compatibility.

Warnings

breaking The `roman` library frequently drops support for older Python versions. For example, version 5.2 dropped support for Python 3.9, and version 5.0 removed support for Python 3.7 and 3.8. Always check the `requires_python` metadata or changelog before upgrading to ensure compatibility with your environment.
Fix: Consult the `roman` library's PyPI page or GitHub changelog for `requires_python` information. Upgrade your Python interpreter if necessary, or pin to an older `roman` version.
gotcha Providing malformed or non-Roman numeral strings to `roman.fromRoman()` will raise an `InvalidRomanNumeralError`. This is intended behavior, but users should be aware of this specific exception for robust error handling.
Fix: Implement `try-except roman.InvalidRomanNumeralError` blocks when parsing user input or external data that might contain invalid Roman numerals.
deprecated The behavior related to the 'N' representation for zero has changed. As of version 5.1, 'undocumented special behavior for N' was hidden behind a method parameter. This implies that direct or implicit handling of 'N' might require explicit parameter usage or could behave differently in future versions.
Fix: If relying on the 'N' representation for zero, consult the official GitHub repository's source code or documentation (if available) to understand the current explicit method parameter required for its use.
gotcha While the `roman` library handles zero, standard Roman numeral systems typically represent integers between 1 and 3999 (or higher with specific conventions). Attempting to convert numbers significantly outside this range, especially very large numbers or negative numbers (other than 0, which is 'N'), might not produce conventionally recognized Roman numerals or could lead to unexpected behavior if not explicitly handled by the library. The library's `toRoman` function will raise `roman.InvalidRomanNumeralError` for negative numbers or numbers above 3999.
Fix: Validate input integers to `roman.toRoman()` to be within the conventionally supported range (typically 0-3999) if strict classical Roman numeral representation is desired, or handle `roman.InvalidRomanNumeralError` for out-of-range inputs.

Install

pip install roman Install latest version

Imports

roman
```
import roman
```
toRoman
```
import roman
roman.toRoman(...)
```
fromRoman
```
import roman
roman.fromRoman(...)
```
InvalidRomanNumeralError
```
from roman import InvalidRomanNumeralError
```
Exceptions are typically imported directly from the module or accessed as attributes of the imported module.

Quickstart

This quickstart demonstrates how to convert between integers and Roman numerals using `roman.toRoman()` and `roman.fromRoman()`. It also shows how the library handles the special case for zero ('N') and catches errors for invalid Roman numeral input.

import roman

# Convert integer to Roman numeral
numeral = roman.toRoman(1994)
print(f"1994 in Roman numerals: {numeral}")

# Convert Roman numeral to integer
integer = roman.fromRoman('MCMXCIV')
print(f"MCMXCIV as an integer: {integer}")

# Example with zero (N)
zero_numeral = roman.toRoman(0)
print(f"0 in Roman numerals: {zero_numeral}")

# Handling invalid input
try:
    invalid_int = roman.fromRoman('ABC')
    print(invalid_int)
except roman.InvalidRomanNumeralError as e:
    print(f"Error converting 'ABC': {e}")

view raw JSON →