Swopy

A library for biredirectional conversion between numeral systems. Supports 46 different systems across all numeral systems available in Unicode.

Supported Numeral Systems

• Aramaic:
  • Hatran, supporting integers between 1 and 999
  • ImperialAramaic, supporting integers between 1 and 99,999
  • Palmyrene, supporting integers between 1 and 99
• Brahmi:
  • Brahmi, supporting integers between 1 and 9,999
• Brahmi-Dravidian:
  • Grantha, supporting integers between 0 and infinity (base-7 positional)
  • Saurashtra, supporting integers between 0 and infinity
  • Tamil, supporting integers between 1 and 9,999
• Brahmi-Gupta:
  • Bhaiksuki, supporting integers between 1 and 999
  • SinhalaArchaic, supporting integers between 1 and 9,999
• Brahmi-Tai:
  • Ahom, supporting integers between 0 and infinity
• Cuneiform:
  • Cuneiform, supporting integers between 1 and 999
• Egyptian:
  • Egyptian, supporting integers between 1 and 1,000,000/many
  • CopticEpact, supporting integers between 1 and 9,999
• Ethiopic:
  • Ethiopic, supporting integers between 1 and 99,999,999
• Greek:
  • Aegean, supporting integers between 1 and 99,999
  • Alphabetic, supporting integers between 1 and 9,999
  • Attic, supporting integers and base-4 fractions between 1/4 and 99,999
  • Etruscan, supporting integers between 1 and 399
  • Milesian, supporting integers between 1 and 9,999
• Hebrew:
  • Hebrew, supporting integers between 1 and 9,999
• Hindu-Arabic:
  • Arabic, supporting integers, floats and fractions between -math.inf and math.inf. Also available in arabic.Arabic
  • Bakhshali, supporting integers between 1 and 9,999
• Kaktovik:
  • Kaktovik, supporting integers between -infinity and +infinity
• Kharosthi:
  • Kharosthi, supporting integers between 1 and 9,999
• Mayan:
  • Mayan, supporting integers between 0 and infinity
• Medefaidrin:
  • Medefaidrin, supporting integers between 0 and infinity (base-20 positional)
• Nabataean:
  • Nabataean, supporting integers between 1 and 999
• Numeric Systems:
  • CountingRod, supporting integers between 1 and 99
• Pahlavi:
  • InscriptionalParthian, supporting integers between 1 and 9,999
  • InscriptionalPahlavi, supporting integers between 1 and 9,999
  • PsalterPahlavi, supporting integers between 1 and 999
• Phoenician:
  • Phoenician, supporting integers between 1 and 999
• Roman, in the forms:
  • Early, supporting integers between 1 and 899
  • Standard, supporting integers and base-12 fractions between 1/12 and 3,999
  • Apostrophus, supporting integers between 1 and 100,000
• Sino-Tibetan:
  • Chinese, supporting integers between 1 and 99,999,999
  • Khitan, supporting integers between 1 and 99,999,999
  • Suzhou, supporting integers between 0 and infinity
  • Tangut, supporting integers between 1 and 99,999,999
• Siyaq:
  • IndicSiyaq, supporting integers between 1 and 99,999
  • OttomanSiyaq, supporting integers between 1 and 99,999
• Sogdian:
  • Manichaean, supporting integers between 1 and 999
  • OldSogdian, supporting integers between 1 and 999
  • Sogdian, supporting integers between 1 and 999
• South Arabian:
  • AncientNorthArabian, supporting integers between 1 and 99
  • AncientSouthArabian, supporting integers between 1 and 99,999

Installation

Install the package:

pip install swopy # or
uv add swopy

Usage

Basic Conversion

import swopy
from swopy import systems

# Convert integer Roman numeral to Egyptian hieroglyphic
swopy.swop('IX', systems.roman.Standard, systems.egyptian.Egyptian)
# '𓏺𓏺𓏺𓏺𓏺𓏺𓏺𓏺𓏺'

# Convert Apostrophus to an Arabic integer
swopy.swop('IↃI', systems.roman.Apostrophus, systems.arabic.Arabic)
# 501

Available Systems

import swopy
import pprint
systems = swopy.get_all_systems()
pprint.pprint(systems)

#{'arabic.Arabic': <class 'swopy.systems.arabic.Arabic'>,
# 'egyptian.Egyptian': <class 'swopy.systems.egyptian.Egyptian'>,
# 'etruscan.Etruscan': <class 'swopy.systems.etruscan.Etruscan'>,
# 'greek.Milesian': <class 'swopy.systems.greek.Milesian'>,
# 'roman.Apostrophus': <class 'swopy.systems.roman.Apostrophus'>,
# 'roman.Early': <class 'swopy.systems.roman.Early'>,
# 'roman.Standard': <class 'swopy.systems.roman.Standard'>
# ...}

swopy.swop(42, systems['arabic.Arabic'], systems['roman.Early'])
# 'XLII'

Error Handling

Swopy will raise a ValueError if there is a number is not representable in a numeral system

import swopy
from swopy import systems

swopy.swop(4000, systems.arabic.Arabic, systems.roman.Standard)
# ValueError: Number must be less than or equal to 3999.

systems.roman.Early.to_numeral(900)
# ValueError: Number must be less than or equal to 899.

or if a numeral is invalid

import swopy
from swopy import systems

swopy.swop('IIIII', systems.egyptian.Egyptian, systems.roman.Early)
# ValueError: Invalid Egyptian hieroglyph: I

systems.roman.Apostrophus.from_numeral('P')
# ValueError: Invalid Apostrophus characters at position 0

and will raise a TypeError if a numeral is not representable in a system.

import swopy
from swopy import systems

swopy.swop(1.2, systems.arabic.Arabic, systems.roman.Early)
# TypeError: 1.2 of type float cannot be represented in Early.

swopy.swop('I', systems.arabic.Arabic, systems.roman.Early)
# TypeError: I of type str cannot be represented in Arabic.

systems.egyptian.Egyptian.to_numeral(10.1)
# TypeError: 10.1 of type float cannot be represented in Egyptian.

Requirements

Swopy only relies on the standard library and needs Python 3.13 or higher. Swopy is currently tested on the latest versions of Windows, MacOS and Ubuntu for Python versions 3.13, 3.14.0, 3.14.3, and 3.15.

Development

Dependencies

Development dependencies are managed through pyproject.toml:

# Install development dependencies
sh scripts/startup.sh

Dev tools include:

• pytest / pytest-cov: Testing framework
• ruff: Fast Python linter and formatter
• pyright: Static type checker
• deptry: Dependency validation
• hypothesis: Property-based testing
• pre-commit: Git hooks framework
• tox, with tox-uv: Test runner
• uv