{"id":1699,"library":"roman-numerals","title":"Roman Numerals","description":"The `roman-numerals` library provides utilities to manipulate well-formed Roman numerals, including converting between integers and Roman numeral strings. The current version is 4.1.0, and it generally sees major releases annually with minor updates as needed.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/AA-Turner/roman-numerals/","tags":["numerals","roman","conversion","utility","mathematics"],"install":[{"cmd":"pip install roman-numerals","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Roman","correct":"from roman_numerals import Roman"},{"symbol":"to_roman","correct":"from roman_numerals import to_roman"},{"symbol":"from_roman","correct":"from roman_numerals import from_roman"}],"quickstart":{"code":"from roman_numerals import Roman, to_roman, from_roman\n\n# Using the Roman class\nroman_four = Roman(integer=4)\nprint(f\"Roman(integer=4): {roman_four} (integer: {roman_four.integer})\")\n\nroman_ninety = Roman(string='XC')\nprint(f\"Roman(string='XC'): {roman_ninety} (integer: {roman_ninety.integer})\")\n\n# Using direct functions\nconverted_to_roman = to_roman(1994)\nprint(f\"to_roman(1994): {converted_to_roman}\")\n\nconverted_from_roman = from_roman('MCMXCIV')\nprint(f\"from_roman('MCMXCIV'): {converted_from_roman}\")","lang":"python","description":"Demonstrates converting integers to Roman numerals and vice-versa using both the `Roman` class and the utility functions `to_roman` and `from_roman`."},"warnings":[{"fix":"Update `Roman` class instantiations to use `string=` or `integer=` keyword arguments.","message":"The `Roman` class constructor arguments changed from positional to keyword-only. Previously, `Roman('IV')` or `Roman(4)` was valid. Post-3.0.0, you must use keyword arguments like `Roman(string='IV')` or `Roman(integer=4)`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review code where both `integer` and `string` might be passed to the `Roman` constructor, ensuring the desired precedence. Be aware of `Roman(string='')` behavior.","message":"The `Roman` class constructor logic was refined. If both `integer` and `string` keyword arguments are provided, `integer` now takes precedence. Additionally, an empty string (`''`) for the `string` argument will now result in a `Roman` object representing `None`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Validate input integers are within the 1-3999 range before conversion. Handle `ValueError` for invalid Roman numeral strings.","message":"The library primarily supports Roman numerals representing integers from 1 to 3999 (inclusive). Inputs outside this range for integers, or malformed Roman numeral strings, will raise `ValueError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure imports for `to_roman` and `from_roman` are directly from `from roman_numerals import ...`. Utilize the `Roman` class for object-oriented manipulation.","message":"The `Roman` class was introduced, and the `to_roman` and `from_roman` functions were moved to be directly importable from the top-level `roman_numerals` package. Earlier versions might have required different import paths or not had the `Roman` class.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}