swopy 0.1.5

A collection of numeral system converters.

Swopy

A Python library for converting between different numeral systems.

Overview

Swopy provides a simple and extensible interface to convert numbers between various numeral systems. Swopy supports bidirectional conversion — you can convert from any supported system to any other.

Supported Numeral Systems

• Roman, in the forms:
  • Early, supporting integers between 1 and 899
  • Standard, supporting integers between 1 and 3,999
  • Apostrophus, supporting integers between 1 and 100,000
• Egyptian, supporting integers between 1 and 1,000,000/many
• Arabic, supporting integers between -int(sys.float_info.max) and int(sys.float_info.max)

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'>,
# '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