roman-numerals

A library for manipulating well-formed Roman numerals.

Integers between 1 and 3,999 (inclusive) are supported. Numbers beyond this range will return an OutOfRangeError.

The classical system of roman numerals requires that the same character may not appear more than thrice consecutively, meaning that ‘MMMCMXCIX’ (3,999) is the largest well-formed Roman numeral. The smallest is ‘I’ (1), as there is no symbol for zero in Roman numerals.

Both upper- and lower-case formatting of roman numerals are supported, and likewise for parsing strings, although the entire string must be of the same case. Numerals that do not adhere to the classical form are rejected with an InvalidRomanNumeralError.

Example usage

Creating a roman numeral

from roman_numerals import RomanNumeral

num = RomanNumeral(16)
assert str(num) == 'XVI'

num = RomanNumeral.from_string("XVI")
assert int(num) == 16

Convert a roman numeral to a string

from roman_numerals import RomanNumeral

num = RomanNumeral(16)
assert str(num) == 'XVI'
assert num.to_uppercase() == 'XVI'
assert num.to_lowercase() == 'xvi'
assert repr(num) == 'RomanNumeral(16)'

Extract the decimal value of a roman numeral

from roman_numerals import RomanNumeral

num = RomanNumeral(42)
assert int(num) == 42

Invalid input

from roman_numerals import RomanNumeral, InvalidRomanNumeralError

num = RomanNumeral.from_string("Spam!")  # raises InvalidRomanNumeralError
num = RomanNumeral.from_string("CLL")  # raises InvalidRomanNumeralError
num = RomanNumeral(0)  # raises OutOfRangeError
num = RomanNumeral(4_000)  # raises OutOfRangeError

Licence

This project is licenced under the terms of either the Zero-Clause BSD licence or the CC0 1.0 Universal licence. See LICENCE.rst for the full text of both licences.

Metadata

Release files for roman-numerals 4.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for roman-numerals 4.1.0
File	Size	Uploaded
roman_numerals-4.1.0.tar.gz	9.1 kB	Dec 17, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for roman-numerals 4.1.0
File	Interpreter	ABI	Platform	Reset
roman_numerals-4.1.0-py3-none-any.whl 7.7 kB Dec 17, 2025	Python 3	none	any	Details

Total release size: 16.8 kB

Release files / roman_numerals-4.1.0.tar.gz

Download URL	roman_numerals-4.1.0.tar.gz
Size	9.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2`
BLAKE2b-256 checksum How to use checksums	`aef941dc953bbeb056c17d5f7a519f50fdf010bd0553be2d630bc69d1e022703`
Upload date	Dec 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AA-Turner/roman-numerals
Publishing commit: github.com/AA-Turner/roman-numerals/tree/53c9c4eac63b91728fba3c26329163ee57654d21

Workflow

Publishing configuration: github.com/AA-Turner/roman-numerals/blob/53c9c4eac63b91728fba3c26329163ee57654d21/.github/workflows/create-release.yml
Publishing logs: github.com/AA-Turner/roman-numerals/actions/runs/20313117993/attempts/1

Artifact

Subject: roman_numerals-4.1.0.tar.gz
SHA-256 checksum: 1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2 Verifying attestations

Release files / roman_numerals-4.1.0-py3-none-any.whl

Download URL	roman_numerals-4.1.0-py3-none-any.whl
Size	7.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7`
BLAKE2b-256 checksum How to use checksums	`04546f679c435d28e0a568d8e8a7c0a93a09010818634c3c3907fc98d8983770`
Upload date	Dec 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AA-Turner/roman-numerals
Publishing commit: github.com/AA-Turner/roman-numerals/tree/53c9c4eac63b91728fba3c26329163ee57654d21

Workflow

Publishing configuration: github.com/AA-Turner/roman-numerals/blob/53c9c4eac63b91728fba3c26329163ee57654d21/.github/workflows/create-release.yml
Publishing logs: github.com/AA-Turner/roman-numerals/actions/runs/20313117993/attempts/1

Artifact

Subject: roman_numerals-4.1.0-py3-none-any.whl
SHA-256 checksum: 647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7 Verifying attestations