{"id":4239,"library":"roman","title":"Roman Numeral Converter","description":"The `roman` library is a small, active Python utility that facilitates the conversion of Arabic (decimal) integers to Roman numerals and vice versa. Currently at version 5.2, it supports Python 3.10 and newer, with a history of regular updates often tied to Python version compatibility.","status":"active","version":"5.2","language":"en","source_language":"en","source_url":"https://github.com/zopefoundation/roman","tags":["roman","numerals","converter","utility","math"],"install":[{"cmd":"pip install roman","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"roman","correct":"import roman"},{"symbol":"toRoman","correct":"import roman\nroman.toRoman(...)"},{"symbol":"fromRoman","correct":"import roman\nroman.fromRoman(...)"},{"note":"Exceptions are typically imported directly from the module or accessed as attributes of the imported module.","wrong":"import roman.InvalidRomanNumeralError","symbol":"InvalidRomanNumeralError","correct":"from roman import InvalidRomanNumeralError"}],"quickstart":{"code":"import roman\n\n# Convert integer to Roman numeral\nnumeral = roman.toRoman(1994)\nprint(f\"1994 in Roman numerals: {numeral}\")\n\n# Convert Roman numeral to integer\ninteger = roman.fromRoman('MCMXCIV')\nprint(f\"MCMXCIV as an integer: {integer}\")\n\n# Example with zero (N)\nzero_numeral = roman.toRoman(0)\nprint(f\"0 in Roman numerals: {zero_numeral}\")\n\n# Handling invalid input\ntry:\n    invalid_int = roman.fromRoman('ABC')\n    print(invalid_int)\nexcept roman.InvalidRomanNumeralError as e:\n    print(f\"Error converting 'ABC': {e}\")","lang":"python","description":"This quickstart demonstrates how to convert between integers and Roman numerals using `roman.toRoman()` and `roman.fromRoman()`. It also shows how the library handles the special case for zero ('N') and catches errors for invalid Roman numeral input."},"warnings":[{"fix":"Consult the `roman` library's PyPI page or GitHub changelog for `requires_python` information. Upgrade your Python interpreter if necessary, or pin to an older `roman` version.","message":"The `roman` library frequently drops support for older Python versions. For example, version 5.2 dropped support for Python 3.9, and version 5.0 removed support for Python 3.7 and 3.8. Always check the `requires_python` metadata or changelog before upgrading to ensure compatibility with your environment.","severity":"breaking","affected_versions":"5.0, 5.2 and later major/minor releases"},{"fix":"Implement `try-except roman.InvalidRomanNumeralError` blocks when parsing user input or external data that might contain invalid Roman numerals.","message":"Providing malformed or non-Roman numeral strings to `roman.fromRoman()` will raise an `InvalidRomanNumeralError`. This is intended behavior, but users should be aware of this specific exception for robust error handling.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If relying on the 'N' representation for zero, consult the official GitHub repository's source code or documentation (if available) to understand the current explicit method parameter required for its use.","message":"The behavior related to the 'N' representation for zero has changed. As of version 5.1, 'undocumented special behavior for N' was hidden behind a method parameter. This implies that direct or implicit handling of 'N' might require explicit parameter usage or could behave differently in future versions.","severity":"deprecated","affected_versions":"5.1 and later"},{"fix":"Validate input integers to `roman.toRoman()` to be within the conventionally supported range (typically 0-3999) if strict classical Roman numeral representation is desired, or handle `roman.InvalidRomanNumeralError` for out-of-range inputs.","message":"While the `roman` library handles zero, standard Roman numeral systems typically represent integers between 1 and 3999 (or higher with specific conventions). Attempting to convert numbers significantly outside this range, especially very large numbers or negative numbers (other than 0, which is 'N'), might not produce conventionally recognized Roman numerals or could lead to unexpected behavior if not explicitly handled by the library. The library's `toRoman` function will raise `roman.InvalidRomanNumeralError` for negative numbers or numbers above 3999. ","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}