Skip to main content

Support for various integer-to-numeral conversion.

Project description

This Python library implements integer-to-numeral and numeral-to-integer conversion for a variety of numeral representations, including:

  • alphabetic representation, i.e. a, b, c, d, … for 0, 1, 2, 3, …
  • Roman numbers, i.e. I, II, III, IV, … for 1, 2, 3, 4, …
  • generic tokens set representation, i.e. !, @, !!, !@, … for 0, 1, 2, 3… (given the tokens set {!, @}).

The generic tokens set representation uses the least number of tokens for representing a given integer, and uses an exponential-like notation similar to base-n conversion, except that the first symbol is used. The alphabetic representation is a special case of a generic tokens set representation, where the latin alphabet is used as tokens set. Upper/lower case conversion should be handled through Python built-ins. All representation support negative values.

Detailed documentation is available for all functions through docstrings.

Of note, the Roman numbers support include:


The recommended way of installing the software is through PyPI:

$ pip install numeral

Alternatively, you can clone the source repository from GitHub:

$ mkdir numeral
$ cd numeral
$ git clone
$ python install

(some steps may require additional permissions depending on your configuration)

The software does not have additional dependencies beyond Python and its standard library.

It was tested with Python 2.7 and 3.5. Other version were not tested.


The following functions are defined:


Convert a number to the least amount letters (within an alphabet).

>>> int2letter(10)
>>> import string  # Common string operations
>>> int2letter(10, string.ascii_letters)  # using both lower and upper cases


Convert a group of letters (within a given alphabet) to a number.

>>> letter2int('aa')


Convert a number to the least amount tokens (within a tokens set).

>>> int2tokens(12, ('!', '@', '#', '$'))


Convert a group of tokens (within a given set) to a number.

>>> tokens2int('#!', ('!', '@', '#', '$'))


Convert an integer to its corresponding Roman number representation.

>>> int2roman(1666)  # using dedicated unicode chars
>>> int2roman(1666, only_ascii=True)  # using only ASCII


Convert a string representation of a Roman number to integer.

>>> int2roman('MDCLXVI')

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for numeral, version
Filename, size File type Python version Upload date Hashes
Filename, size numeral- (22.1 kB) File type Wheel Python version py2.py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page