Ancient

Convert between integers and Roman numerals in Python

Install

Install from PyPi

$ pip install ancient

or clone the developement version from GitHub

$ git clone https://github.com/janjoswig/Ancient.git
$ cd Ancient
$ pip install .

Usage

Import

from ancient import roman

Basic conversions

Convert integer values to Roman numerals

for i in range(10):
    print(roman.roman(i))

N
I
II
III
IV
V
VI
VII
VIII
IX

By default, the conversion follows the standard scheme using a subtractive representation for the values 4, 9, 14, etc. (e.g. IV instead of IIII). An additive representation can be selected via the mapping keyword (see also Custom Mappings).

for i in range(10):
    print(roman.roman(i, mapping="ascii-additive"))

N
I
II
III
IIII
V
VI
VII
VIII
VIIII

Composition of large numbers (>4999) can be improved using an extended mapping.

for i in [5000, 10000, 50000, 100000]:
    print(roman.roman(i, mapping="unicode-extended"))

ↁ
ↂ
ↇ
ↈ

Interpretation of Roman numerals

for i in ["I", "IV", "IIII", "XX", "XL", "C"]:
    print(roman.interpret_roman(i))

1
4
4
20
40
100

The Roman data type

The packag provides the Roman data type to handle Roman numerals

number = roman.Roman(5)

print(f"{number!r}")
print(f"{number!s}")

Roman(5, format='ascii-std')
V

The type behaves like an integer in arithmetic operations

print(number + 2)
print(number - roman.Roman(1))
print(number * 2)
print(number / 2)  # Integer division!

VII
IV
X
II

Custom Mappings

A mapping of Roman symbols to integer values used for interconversions has the form

mapping = {
    "M": 1000,
    "D": 500,
    "C": 100,
    "L": 50,
    }

For the conversion of integers to Roman numerals, such a mapping should have a decreasing order in the integer values. To ensure this, mappings can inherit from roman.Symbols. Note, that only one symbol is effectively used if the same value is mapped to more than one symbols.

custom_mapping = roman.Symbols()
custom_mapping.update({"ↆ": 50, "Ж": 100, "I": 1, "Ʌ": 5})
print(custom_mapping)

{'Ж': 100, 'ↆ': 50, 'Ʌ': 5, 'I': 1}

A cutsom mapping can be used in conversions instead of the default mappings

roman.roman(156, mapping=custom_mapping)

'ЖↆɅI'

A set of mappings is provided as instances of f roman.Symbols in roman.symbols

print(roman.symbols.keys())

dict_keys(['ascii-additive', 'ascii-std', 'ascii-variant', 'unicode-additive', 'unicode-std', 'unicode-extended', 'unicode-extended-claudian'])

Mappings stored in this place can be used by their key in conversions. Instances of type Roman have an attribute format that controls the conversion and should be a valid mapping key.

number = roman.Roman(100)
print(number)

roman.symbols["custom"] = custom_mapping
number.format = "custom"
print(number)

C
Ж

Zero and negative numbers

The package can handle negative numbers

number = roman.Roman(-10)
print(number)

-X

The symbol used to represent 0 is stored on the used mappings and can be changed.

print(roman.symbols["unicode-std"].nullum)

N