English

Module converting Arabic numerals to Greek and Roman numbers

Version: 1.2.0
Supported Python: 3.11-3.14 stable; 3.15.0rc2 provisionally tested
Repository: GitHub - GreekRomanNumerical
License: Apache 2.0

Description

The library converts Arabic numbers, such as 1234, to Roman equivalents, such as MCCXXXIV, or Greek — Α_ΣΛΔ.

This module can also output Greek numbers in different formats. For example, the number 20005003001 can be represented as Κ___Ε__Γ_Α or Κ~Ε~Γ~Α. In addition, it is possible to output the text name of the digits, for example, Kappa macron Epsilon macron Gamma macron Alpha, or output them in lowercase.

Finite float fractions are encoded digit by digit, with numeral tokens separated by colons. For example, 1.25 becomes I.(II:V) or α.(β:ε). A zero digit is written as _ for Roman numerals and classic Greek, or ~ for positional Greek; thus 1.05 becomes I.(_:V), α.(_:ε), or α.(~:ε).

Installation

Install the package using pip:

pip install GreekRomanUtils

Detailed usage

For step-by-step examples of the converters, number formats, arithmetic, and backend selection, see the detailed usage guide.

Hybrid backend (Python + Rust)

Starting from this migration stage, the public API stays unchanged while internal conversion logic can run on a Rust backend.

• Default behavior: try Rust backend first, fallback to Python automatically.
• Force Python backend:

GREEKROMAN_FORCE_PYTHON=1

The Rust bridge preserves Python's arbitrary-precision integers. The core library applies configured input, output, and Greek-group limits to bound resource use.

Development environment and quality checks

Requirements: Python 3.11 or newer, uv, and rustup. Windows builds also require the MSVC C++ Build Tools.

The Rust core is included as the greekromannumerical-core Git submodule. Clone this repository with submodules, or initialize them in an existing checkout:

git clone --recurse-submodules git@github.com:PavelKotDRM/GreekRomanNumerical.git
# Existing checkout:
git submodule update --init --recursive

The core repository is accessed over SSH. GitHub Actions also needs a CORE_SUBMODULE_TOKEN repository secret: a read-only token with Contents: read access to both this repository and the core repository.

Create the environment and install the project with its Rust extension:

rustup toolchain install stable
uv python install 3.11
uv sync --locked --group dev --python 3.11

Install the optional notebook tools only when needed:

uv sync --locked --group dev --group notebook --python 3.11

Run the full test suite with the Python backend:

GREEKROMAN_FORCE_PYTHON=1 uv run pytest -v

On Windows PowerShell:

$env:GREEKROMAN_FORCE_PYTHON = "1"
uv run pytest -v
Remove-Item Env:GREEKROMAN_FORCE_PYTHON

Rebuild the Rust extension after Rust changes and test the hybrid backend:

uv run maturin develop --manifest-path rust/Cargo.toml
uv run pytest -v

Run Python lint and type checks:

uv run ruff check --exclude tests/
uv run ty check --exclude tests/

Check Rust formatting, compile the Rust crate, and build the package:

cargo fmt --manifest-path rust/Cargo.toml --check
cargo test --locked --manifest-path rust/Cargo.toml
uv build

Rust behavior is covered by native unit tests and Python backend-equivalence tests.

Run the opt-in performance benchmarks (the Rust extension must be built):

uv sync --locked --group dev --group performance --python 3.11
uv run maturin develop --manifest-path rust/Cargo.toml
uv run --group performance pytest benchmarks/test_backend_performance.py --benchmark-only --benchmark-sort=mean

The benchmark checks result equivalence before timing Roman, classic Greek, and positional Greek conversions in both backends. It reports measurements without enforcing a speed threshold because timings depend on the machine.

The structure of the project

There are two main classes: GreekConvert and RomanConvert. They implement the logic of converting to the corresponding numbers. There are also classes GreekAlphabet and RomanNumberAlphabet, which are used to store lists and dictionaries.
There are proprietary data types GreekNumber and RomanNumber for working with Greek and Roman numbers, which will allow you to perform basic mathematical operations with them.

Main functions

For "GreekConvert":

• change_capital — A flag that controls the conversion of characters to upper or lower case.
• change_positional — Change the positional mode for conversion.
• convert — The function of converting an Arabic number to a Greek one, returns GreekNumber object. For example, the number 20005003001 is converted to Κ___Ε__Γ_Α (non-positional mode) or to Κ~Ε~Γ~Α (positional mode).
• convert_to_arabic — A function for converting a Greek number to an Arabic one.
• unicode_to_name — The function converts a Unicode character into its name.
• name_to_unicode — The reverse operation for unicode_to_name.

The "GreekNumber" class:

• set_number — Set a new value.
• set_positional — Set the positional mode flag (affects display format: underscore _ for non-positional, tilde ~ for positional).
• set_capital — Set the upper case flag.
• get_number — Get the current number.
• get_positional — Get the positional flag value.
• get_capital — Get the capital flag value.
• get_str — Get the textual representation of the number (e.g., "alpha beta gamma").
• And basic mathematical operations (+, -, *, /, //, %, **, ==, !=, <, <=, >, >=).

For "RomanConvert":

• convert — The method converts an Arabic number to a Roman number, returns RomanNumber object.
• convert_to_arabic — The reverse method for convert.

For "RomanNumber":

• set_number — Set a new value.
• get_number — Get the current number.
• get_value — Get the string representation of the Roman numeral.
• And basic mathematical operations (+, -, *, /, //, %, **, ==, !=, <, <=, >, >=).

---

Ru

Модуль преобразование арабских цифр в греческие и римские числа

Версия: 1.2.0
Поддерживаемые версии Python: 3.11-3.14 stable; 3.15.0rc2 проверяется предварительно
Репозиторий: GitHub - GreekRomanNumerical
Лицензия: Apache 2.0

Описание

Библиотека преобразует арабские числа, такие как 1234, в римские эквиваленты, например, MCCXXXIV, или греческие — Α_ΣΛΔ.

Также этот модуль может выводить греческие цифры в разных форматах. Например, число 20005003001 можно представить как Κ___Ε__Γ_Α или Κ~Ε~Γ~Α. Кроме того, есть возможность выводить текстовое название цифр, например, Kappa macron Epsilon macron Gamma macron Alpha, или выводить их в нижнем регистре.

Дробная часть конечного float кодируется по цифрам, разделённым двоеточиями. Например, 1.25 преобразуется в I.(II:V) или α.(β:ε). Нулевой разряд записывается как _ для римского и классического греческого форматов, или ~ для позиционного греческого; поэтому 1.05 выглядит как I.(_:V), α.(_:ε) или α.(~:ε).

Установка

Установите пакет с помощью pip:

pip install GreekRomanUtils

Подробная документация

Подробные примеры конвертации, форматов чисел, арифметики и настройки backend собраны в руководстве на русском языке. См. также английскую версию.

Гибридный backend (Python + Rust)

На этапе миграции публичный API не меняется, но внутренняя логика конвертации может выполняться через Rust backend.

• Поведение по умолчанию: сначала попытка Rust backend, при недоступности автоматический fallback на Python.
• Принудительное отключение Rust backend:

GREEKROMAN_FORCE_PYTHON=1

Rust-мост сохраняет произвольную точность целых Python. Core-библиотека ограничивает размер входа и результата, а также число греческих разрядов, чтобы контролировать расход ресурсов.

Настройка среды и проверки качества

Требования: Python 3.11 или новее, uv и rustup. Для сборки в Windows также нужны MSVC C++ Build Tools.

Rust core подключён как Git submodule greekromannumerical-core. Клонируйте репозиторий вместе с submodule или инициализируйте его в уже существующей копии:

git clone --recurse-submodules git@github.com:PavelKotDRM/GreekRomanNumerical.git
# Для уже клонированного репозитория:
git submodule update --init --recursive

Core-репозиторий доступен по SSH. Для GitHub Actions также задайте секрет репозитория CORE_SUBMODULE_TOKEN: токен только для чтения с правом Contents: read для обоих репозиториев.

Создание окружения и установка проекта вместе с Rust-расширением:

rustup toolchain install stable
uv python install 3.11
uv sync --locked --group dev --python 3.11

Дополнительные инструменты для ноутбуков устанавливаются отдельно:

uv sync --locked --group dev --group notebook --python 3.11

Полный набор тестов с Python backend:

$env:GREEKROMAN_FORCE_PYTHON = "1"
uv run pytest -v
Remove-Item Env:GREEKROMAN_FORCE_PYTHON

После изменений Rust пересоберите расширение и запустите тесты в hybrid-режиме:

uv run maturin develop --manifest-path rust/Cargo.toml
uv run pytest -v

Проверки Python-кода:

uv run ruff check --exclude tests/
uv run ty check --exclude tests/

Проверки Rust и сборка пакета:

cargo fmt --manifest-path rust/Cargo.toml --check
cargo test --locked --manifest-path rust/Cargo.toml
uv build

Поведение Rust backend покрывается собственными unit-тестами и Python-тестами эквивалентности backend-ов.

Запуск opt-in тестов производительности (Rust-расширение должно быть собрано):

uv sync --locked --group dev --group performance --python 3.11
uv run maturin develop --manifest-path rust/Cargo.toml
uv run --group performance pytest benchmarks/test_backend_performance.py --benchmark-only --benchmark-sort=mean

Перед замером тесты проверяют равенство результатов и затем измеряют Roman, classic Greek и positional Greek конвертации в обоих backend’ах. Порог скорости не задан: время зависит от машины и окружения.

Структура пректа

Есть два основных класса: GreekConvert и RomanConvert. Они реализуют логику преобразования в соответствующие числа. Также есть классы GreekAlphabet и RomanNumberAlphabet, которые используются для хранения списков и словарей.
Есть собственные типы данных GreekNumber и RomanNumber для работы с греческими и римскими числами, что позволит выполнять с ними базовые математические операции.

Основные функции

Для «GreekConvert»:

• change_capital — Флаг, управляющий преобразованием символов в верхний или нижний регистр.
• change_positional — Изменить режим позиционного преобразования.
• convert — Функция преобразования арабского числа в греческое, возвращает объект GreekNumber. Например, число 20005003001 преобразуется в Κ___Ε__Γ_Α (непозиционный режим) или в Κ~Ε~Γ~Α (позиционный режим).
• convert_to_arabic — Функция преобразования греческого числа в арабское.
• unicode_to_name — Функция преобразует символ Unicode в его название.
• name_to_unicode — Обратная операция для unicode_to_name.

Класс «GreekNumber»:

• set_number — Установить новое значение.
• set_positional — Установить флаг позиционного режима (влияет на формат отображения: подчеркивание _ для непозиционного, тильда ~ для позиционного).
• set_capital — Установить флаг верхнего регистра.
• get_number — Получить текущее число.
• get_positional — Получить значение флага позиционности.
• get_capital — Получить значение флага регистра.
• get_str — Получить текстовое представление числа (например, "alpha beta gamma").
• И базовые математические операции (+, -, *, /, //, %, **, ==, !=, <, <=, >, >=).

Для «RomanConvert»:

• convert — Метод преобразует арабское число в римское, возвращает объект RomanNumber.
• convert_to_arabic — Обратный метод для convert.

Для «RomanNumber»:

• set_number — Установить новое значение.
• get_number — Получить текущее число.
• get_value — Получить строковое представление римского числа.
• И базовые математические операции (+, -, *, /, //, %, **, ==, !=, <, <=, >, >=).

Схема пректа

License

Apache License 2.0