Metadata-Version: 2.4
Name: RomanPy
Version: 1.3.2
Summary: Effortlessly convert decimal numbers to Roman numerals in Python.
Author-email: "M.P. van de Weerd" <michael@parcifal.dev>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://gitlab.com/parcifal/roman-py
Project-URL: Bug Tracker, https://gitlab.com/parcifal/roman-py/-/issues
Keywords: unicode,decimal numbers,roman numbers,conversion,numeral system
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli
Provides-Extra: dev
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pylint-gitlab; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Dynamic: license-file

# RomanPy

[![pipeline status](https://gitlab.com/parcifal/roman-py/badges/master/pipeline.svg)](https://gitlab.com/parcifal/roman-py/-/pipelines)
[![coverage report](https://gitlab.com/parcifal/roman-py/badges/master/coverage.svg)](https://gitlab.com/parcifal/roman-py/-/commits/master)
[![PyPI version](https://img.shields.io/pypi/v/RomanPy)][pypi]

RomanPy is a Python library and CLI for converting decimal numbers to Roman 
numerals. It provides:

 - ASCII or Unicode output (with full support for Unicode numeral symbols)
 - Upper- and lowercase variants
 - Configurable numeral variants (subtractive, extended, apostrophus, medieval,
   zero, or custom mappings)
 - Arithmetic operations (+, -, *, //) between Roman numerals and integers
 - Equality and comparison with ints and strings

> Licensed under the [AGPLv3.0](LICENSE).

## Installation

RomanPy is available on PyPI and can be installed using `pip`:

```bash
pip install RomanPy
```

Alternatively, you can pull the repository and install it straight from the 
source:

```bash
git clone git@gitlab.com:parcifal/roman-py.git
cd roman-py
pip install .
```

## Usage (API)

### Basic Conversion

```python
from roman import roman

print(roman(207))  # CCVII
```

### Encoding and Case Variants

```bash
n = roman(1776)

print(n.encode("ascii").upper())   # MDCCLXXVI
print(n.encode("ascii").lower())   # mdcclxxvi
print(n.encode("unicode").upper()) # ⅯⅮⅭⅭⅬⅩⅩⅥ
print(n.encode("unicode").lower()) # ⅿⅾⅽⅽⅼⅹⅹⅵ
```

### Arithmetic with Roman Numerals

Roman numerals can be added, subtracted, multiplied, or divided with  
other Roman numerals or integers:

```python
print(roman(100) + roman(60))   # CLX
print(roman(45) - roman(7))     # XXXVIII
print(roman(533) * 2)                   # MLXVI
print(roman(2460) // 10)                # CCXLVI

# mix with ints
print(100 + roman(60))                  # CLX
print(roman(1954) == "MCMLIV")          # True
```

### Custom Variants

You can extend or override numeral variants:

```bash
from roman.roman import VARIANT_ZERO

n = roman(0).extend_variant(VARIANT_ZERO)
print(n)  # N
```

Built-in variants include:

 - `VARIANT_BASE` (I, V, X, …)
 - `VARIANT_SUBTRACTIVE` (IV, IX, XL, …)
 - `VARIANT_SUBTRACTIVE_EXTENDED` (IIX, IC, …)
 - `VARIANT_ZERO` (N)
 - `VARIANT_APOSTROPHUS` (large numbers with I) and ((I)))
 - `VARIANT_MEDIEVAL` (A, Z, O, …)

By default, `VARIANT_SUBTRACTIVE` is used.

## Usage (CLI)

Installing RomanPy also provides a roman command-line tool:

```bash
roman 42
# = XLII
```

### Options

```bash
usage: roman [-h] [-a | -A | -u | -U] [-b | -s | -e] [-z] [-p] [-m] [-c DECIMAL NUMERAL] [-v] [-V] value

Convert a decimal number to roman numeral.

positional arguments:
  value                 a decimal number to convert to a roman numeral

optional arguments:
  -h, --help            show this help message and exit
  -a, --ascii           output encoding of roman numerals in lowercase ascii
  -A, --ASCII           output encoding of roman numerals in uppercase ascii (default)
  -u, --unicode         output encoding of roman numerals in lowercase unicode
  -U, --UNICODE         output encoding of roman numerals in uppercase unicode
  -b, --no-base         do not use the base variant
  -s, --subtractive     use the subtractive variant (includes base) (default)
  -e, --subtractive-extended
                        use the extended subtractive variant(includes subtractive)
  -z, --zero            use the zero variant N
  -p, --apostrophus     use the apostrophus method for large numbers
  -m, --medieval        use the medieval variant
  -c DECIMAL NUMERAL, --custom DECIMAL NUMERAL
                        map a decimal number to a roman numeral
  -v, --verbose         increase verbosity
  -V, --version         show program's version number and exit
```

## Contributing

Found a bug? Have a suggestion? Open an issue or submit a merge request at 
[the GitLab repository](https://gitlab.com/parcifal/roman-py). All 
contributions are welcome.

[pypi]: https://pypi.org/project/RomanPy/
