numly 0.1.0__py3-none-any.whl

numly/__init__.py

@@ -0,0 +1,64 @@
+"""
+numly
+~~~~~
+A Python library for working with numbers across numeral systems.
+
+Supported systems
+-----------------
+  decimal      : Standard base-10
+  roman        : Roman numerals          (I V X L C D M)
+  arabic_indic : Eastern Arabic digits   (٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩)
+  chinese      : Traditional Chinese     (零 一 二 三 四 … 万)
+  greek        : Greek alphabetic        (Α Β Γ … Ω  +  ͵ for thousands)
+  egyptian     : Egyptian hieroglyphs    (𓏺 𓎆 𓍢 𓆼 𓂭 𓆐 𓁨)
+
+Quick start
+-----------
+    import numly
+
+    numly.to_roman(2024)                       # 'MMXXIV'
+    numly.to_chinese(42)                       # '四十二'
+    numly.convert("MMXXIV", "roman", "greek")  # '͵ΒΚΔʹ'
+    numly.to_all(42)                           # dict of every system
+
+Individual modules
+------------------
+    from numly.roman        import to_roman, from_roman
+    from numly.arabic_indic import to_arabic_indic, from_arabic_indic
+    from numly.chinese      import to_chinese, from_chinese
+    from numly.greek        import to_greek, from_greek
+    from numly.egyptian     import to_egyptian, from_egyptian, symbol_breakdown
+    from numly.convert      import convert, to_all, SYSTEMS
+"""
+
+__version__ = "0.1.0"
+__author__  = "numly contributors"
+__license__ = "MIT"
+
+# ── individual converters ──────────────────────────────────────────────────
+from numly.roman        import to_roman,        from_roman,        is_valid as is_valid_roman
+from numly.arabic_indic import to_arabic_indic,  from_arabic_indic, is_valid as is_valid_arabic_indic
+from numly.chinese      import to_chinese,       from_chinese,      is_valid as is_valid_chinese
+from numly.greek        import to_greek,         from_greek,        is_valid as is_valid_greek
+from numly.egyptian     import to_egyptian,      from_egyptian,     is_valid as is_valid_egyptian
+from numly.egyptian     import symbol_breakdown
+
+# ── universal converter ────────────────────────────────────────────────────
+from numly.convert import convert, to_all, SYSTEMS, supported_systems
+
+__all__ = [
+    # roman
+    "to_roman", "from_roman", "is_valid_roman",
+    # arabic-indic
+    "to_arabic_indic", "from_arabic_indic", "is_valid_arabic_indic",
+    # chinese
+    "to_chinese", "from_chinese", "is_valid_chinese",
+    # greek
+    "to_greek", "from_greek", "is_valid_greek",
+    # egyptian
+    "to_egyptian", "from_egyptian", "is_valid_egyptian", "symbol_breakdown",
+    # universal
+    "convert", "to_all", "SYSTEMS", "supported_systems",
+    # meta
+    "__version__",
+]

numly/arabic_indic.py

@@ -0,0 +1,113 @@
+"""
+numly.arabic_indic
+~~~~~~~~~~~~~~~~~~
+Convert integers to Eastern Arabic numerals (٠١٢٣٤٥٦٧٨٩) and back.
+
+These are the digits used in Arabic, Persian, and Urdu scripts.
+Unlike Roman or Chinese, this is a pure digit-substitution system —
+the positional value works exactly like decimal.
+
+Range: 0 – unlimited
+
+Examples:
+    >>> from numly.arabic_indic import to_arabic_indic, from_arabic_indic
+    >>> to_arabic_indic(2024)
+    '٢٠٢٤'
+    >>> from_arabic_indic('٤٢')
+    42
+"""
+
+#  Western:      0  1  2  3  4  5  6  7  8  9
+#  Eastern: ٠  ١  ٢  ٣  ٤  ٥  ٦  ٧  ٨  ٩
+_DIGITS    = "٠١٢٣٤٥٦٧٨٩"
+_TO_ASCII  = {ch: str(i) for i, ch in enumerate(_DIGITS)}
+
+SYSTEM = "arabic_indic"
+MIN    = 0
+MAX    = None   # unlimited
+
+
+def to_arabic_indic(num: int) -> str:
+    """
+    Convert an integer to an Eastern Arabic numeral string.
+
+    Args:
+        num: Non-negative integer (no upper limit).
+
+    Returns:
+        Eastern Arabic numeral string, e.g. '٤٢'.
+
+    Raises:
+        TypeError:  If num is not an int.
+        ValueError: If num is negative.
+
+    Examples:
+        >>> to_arabic_indic(0)
+        '٠'
+        >>> to_arabic_indic(42)
+        '٤٢'
+        >>> to_arabic_indic(2024)
+        '٢٠٢٤'
+    """
+    if not isinstance(num, int):
+        raise TypeError(f"Expected int, got {type(num).__name__!r}")
+    if num < 0:
+        raise ValueError("Only non-negative integers are supported")
+    return "".join(_DIGITS[int(d)] for d in str(num))
+
+
+def from_arabic_indic(s: str) -> int:
+    """
+    Convert an Eastern Arabic numeral string to an integer.
+
+    Args:
+        s: Eastern Arabic numeral string, e.g. '٤٢'.
+           Also accepts plain ASCII digits or a mix of both.
+
+    Returns:
+        Integer value.
+
+    Raises:
+        TypeError:  If s is not a str.
+        ValueError: If s contains non-numeric characters.
+
+    Examples:
+        >>> from_arabic_indic('٤٢')
+        42
+        >>> from_arabic_indic('٢٠٢٤')
+        2024
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    s = s.strip()
+    if not s:
+        raise ValueError("Empty string")
+
+    ascii_s = "".join(_TO_ASCII.get(ch, ch) for ch in s)
+    try:
+        return int(ascii_s)
+    except ValueError:
+        raise ValueError(f"Invalid Arabic-Indic numeral: {s!r}")
+
+
+def is_valid(s: str) -> bool:
+    """
+    Check whether a string is a valid Eastern Arabic numeral.
+
+    Examples:
+        >>> is_valid('٤٢')
+        True
+        >>> is_valid('abc')
+        False
+    """
+    try:
+        from_arabic_indic(s)
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+if __name__ == "__main__":
+    for n in [0, 1, 42, 100, 2024, 999_999]:
+        r = to_arabic_indic(n)
+        print(f"{n:<10} → {r:<12} → {from_arabic_indic(r)}")

numly/chinese.py

@@ -0,0 +1,187 @@
+"""
+numly.chinese
+~~~~~~~~~~~~~
+Convert integers to Traditional Chinese numerals and back.
+
+Uses the standard literary/financial positional system:
+    零一二三四五六七八九  (digits)
+    十 百 千 万          (place units)
+
+Range: 0 – 99,999,999
+
+Examples:
+    >>> from numly.chinese import to_chinese, from_chinese
+    >>> to_chinese(42)
+    '四十二'
+    >>> from_chinese('一万零一')
+    10001
+"""
+
+_DIGITS   = "零一二三四五六七八九"
+_UNIT_MAP = {"十": 10, "百": 100, "千": 1000, "万": 10_000}
+
+SYSTEM   = "chinese"
+MIN, MAX = 0, 99_999_999
+
+
+# ── internal helper ────────────────────────────────────────────────────────
+
+def _encode_section(n: int) -> str:
+    """
+    Encode an integer 1–9999 to Chinese without any outer 万 context.
+    Handles internal zeros (e.g. 101 → 一百零一).
+    """
+    units        = [(1000, "千"), (100, "百"), (10, "十"), (1, "")]
+    result       = ""
+    zero_pending = False
+
+    for val, unit in units:
+        d  = n // val
+        n %= val
+        if d:
+            if zero_pending:
+                result       += "零"
+                zero_pending  = False
+            result += _DIGITS[d] + unit
+        elif result:                   # non-leading zero in the middle
+            zero_pending = True
+
+    return result
+
+
+def _decode_section(s: str) -> int:
+    """
+    Decode a Chinese string that contains no 万 character (up to 9999).
+    Handles leading 零 and bare 十 (e.g. '十二' → 12).
+    """
+    cn_val = {ch: i for i, ch in enumerate(_DIGITS)}
+    result, digit = 0, 0
+
+    for ch in s:
+        if ch in cn_val:
+            digit = cn_val[ch]
+        elif ch in _UNIT_MAP and ch != "万":
+            unit = _UNIT_MAP[ch]
+            if digit == 0:
+                digit = 1              # bare 十 → treat as 一十
+            result += digit * unit
+            digit   = 0
+
+    result += digit                    # final ones digit (may be 0 for 零)
+    return result
+
+
+# ── public API ─────────────────────────────────────────────────────────────
+
+def to_chinese(num: int) -> str:
+    """
+    Convert an integer to a Traditional Chinese numeral string.
+
+    Args:
+        num: Integer between 0 and 99,999,999.
+
+    Returns:
+        Chinese numeral string, e.g. '四十二'.
+
+    Raises:
+        TypeError:  If num is not an int.
+        ValueError: If num is outside 0–99,999,999.
+
+    Examples:
+        >>> to_chinese(0)
+        '零'
+        >>> to_chinese(42)
+        '四十二'
+        >>> to_chinese(10001)
+        '一万零一'
+        >>> to_chinese(20240)
+        '二万零二百四十'
+        >>> to_chinese(99999999)
+        '九千九百九十九万九千九百九十九'
+    """
+    if not isinstance(num, int):
+        raise TypeError(f"Expected int, got {type(num).__name__!r}")
+    if num == 0:
+        return "零"
+    if not MIN <= num <= MAX:
+        raise ValueError(f"Chinese numerals support {MIN}–{MAX:,}, got {num}")
+
+    wan  = num // 10_000
+    rest = num %  10_000
+
+    if wan == 0:
+        return _encode_section(rest)
+
+    result = _encode_section(wan) + "万"
+
+    if rest == 0:
+        return result
+    # bridge 零 when rest has a missing thousands digit
+    if rest < 1_000 or rest // 100 == 0:
+        return result + "零" + _encode_section(rest)
+    return result + _encode_section(rest)
+
+
+def from_chinese(s: str) -> int:
+    """
+    Convert a Traditional Chinese numeral string to an integer.
+
+    Args:
+        s: Chinese numeral string, e.g. '四十二'.
+
+    Returns:
+        Integer value.
+
+    Raises:
+        TypeError:  If s is not a str.
+        ValueError: If s is empty or malformed.
+
+    Examples:
+        >>> from_chinese('零')
+        0
+        >>> from_chinese('四十二')
+        42
+        >>> from_chinese('一万零一')
+        10001
+        >>> from_chinese('九千九百九十九万九千九百九十九')
+        99999999
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    s = s.strip()
+    if not s:
+        raise ValueError("Empty string")
+    if s == "零":
+        return 0
+
+    if "万" in s:
+        idx  = s.index("万")
+        left  = s[:idx]
+        right = s[idx + 1:]            # may start with bridge 零
+        return _decode_section(left) * 10_000 + _decode_section(right)
+
+    return _decode_section(s)
+
+
+def is_valid(s: str) -> bool:
+    """
+    Check whether a string is a valid Chinese numeral.
+
+    Examples:
+        >>> is_valid('四十二')
+        True
+        >>> is_valid('hello')
+        False
+    """
+    try:
+        val = from_chinese(s)
+        return to_chinese(val) == s
+    except (TypeError, ValueError):
+        return False
+
+
+if __name__ == "__main__":
+    tests = [0, 1, 10, 42, 100, 101, 1001, 10001, 20240, 99_999_999]
+    for n in tests:
+        r = to_chinese(n)
+        print(f"{n:<12} → {r:<28} → {from_chinese(r)}")

numly/convert.py

@@ -0,0 +1,187 @@
+"""
+numly.convert
+~~~~~~~~~~~~~
+Universal converter — convert any number between all supported systems.
+
+Supported systems
+-----------------
+  'decimal'      Standard base-10        range: 0 – unlimited
+  'roman'        Roman numerals          range: 1 – 3,999
+  'arabic_indic' Eastern Arabic digits   range: 0 – unlimited
+  'chinese'      Chinese numerals        range: 0 – 99,999,999
+  'greek'        Greek alphabetic        range: 1 – 9,999
+  'egyptian'     Egyptian hieroglyphs    range: 1 – 9,999,999
+
+Examples:
+    >>> from numly.convert import convert, to_all
+    >>> convert(42, "decimal", "roman")
+    'XLII'
+    >>> convert("MMXXIV", "roman", "chinese")
+    '二千零二十四'
+    >>> convert("四十二", "chinese", "greek")
+    'ΜΒʹ'
+    >>> convert("𓎆𓎆𓎆𓎆𓏺𓏺", "egyptian", "roman")
+    'XLII'
+    >>> to_all(42)
+    {'decimal': 42, 'roman': 'XLII', 'arabic_indic': '٤٢', ...}
+"""
+
+from numly.roman        import to_roman,        from_roman
+from numly.arabic_indic import to_arabic_indic,  from_arabic_indic
+from numly.chinese      import to_chinese,       from_chinese
+from numly.greek        import to_greek,         from_greek
+from numly.egyptian     import to_egyptian,      from_egyptian
+
+# ── registry ───────────────────────────────────────────────────────────────
+
+_ENCODERS: dict = {
+    "roman":        to_roman,
+    "arabic_indic": to_arabic_indic,
+    "chinese":      to_chinese,
+    "greek":        to_greek,
+    "egyptian":     to_egyptian,
+}
+
+_DECODERS: dict = {
+    "decimal":      int,
+    "roman":        from_roman,
+    "arabic_indic": from_arabic_indic,
+    "chinese":      from_chinese,
+    "greek":        from_greek,
+    "egyptian":     from_egyptian,
+}
+
+#: Frozenset of all supported system names (including 'decimal').
+SYSTEMS: frozenset = frozenset(_DECODERS.keys())
+
+
+# ── public API ─────────────────────────────────────────────────────────────
+
+def convert(value, from_system: str, to_system: str):
+    """
+    Convert a number from one numeral system to another.
+
+    Args:
+        value:       The number to convert.
+                     Pass an ``int`` when from_system is 'decimal',
+                     otherwise pass a ``str``.
+        from_system: Source system name (see ``SYSTEMS``).
+        to_system:   Target system name (see ``SYSTEMS``).
+                     Pass ``'all'`` to receive a dict of every system.
+
+    Returns:
+        str  — converted numeral string.
+        int  — when to_system is 'decimal'.
+        dict — when to_system is 'all'.
+
+    Raises:
+        ValueError: If from_system or to_system is unrecognised.
+        TypeError / ValueError: Propagated from the individual modules
+                                if the value is malformed or out of range.
+
+    Examples:
+        >>> convert(42, "decimal", "roman")
+        'XLII'
+        >>> convert("XLII", "roman", "decimal")
+        42
+        >>> convert("XLII", "roman", "chinese")
+        '四十二'
+        >>> convert("四十二", "chinese", "egyptian")
+        '𓎆𓎆𓎆𓎆𓏺𓏺'
+        >>> convert("𓎆𓎆𓎆𓎆𓏺𓏺", "egyptian", "greek")
+        'ΜΒʹ'
+        >>> convert(42, "decimal", "all")
+        {'decimal': 42, 'roman': 'XLII', ...}
+    """
+    from_system = from_system.lower().strip()
+    if to_system != "all":
+        to_system = to_system.lower().strip()
+
+    if from_system not in _DECODERS:
+        raise ValueError(
+            f"Unknown source system {from_system!r}. "
+            f"Choose from: {sorted(SYSTEMS)}"
+        )
+
+    # Step 1 — decode to a plain Python int
+    n = _DECODERS[from_system](value)
+
+    # Step 2 — encode to target
+    if to_system == "all":
+        return to_all(n)
+    if to_system == "decimal":
+        return n
+    if to_system not in _ENCODERS:
+        raise ValueError(
+            f"Unknown target system {to_system!r}. "
+            f"Choose from: {sorted(SYSTEMS)}"
+        )
+    return _ENCODERS[to_system](n)
+
+
+def to_all(value, from_system: str = "decimal") -> dict:
+    """
+    Convert a number to every supported numeral system at once.
+
+    Systems whose range does not include the value are returned as ``None``.
+
+    Args:
+        value:       The number to convert.
+        from_system: Source system (default ``'decimal'``).
+
+    Returns:
+        dict with keys: 'decimal', 'roman', 'arabic_indic',
+                        'chinese', 'greek', 'egyptian'.
+
+    Examples:
+        >>> to_all(42)
+        {'decimal': 42, 'roman': 'XLII', 'arabic_indic': '٤٢',
+         'chinese': '四十二', 'greek': 'ΜΒʹ', 'egyptian': '𓎆𓎆𓎆𓎆𓏺𓏺'}
+
+        >>> to_all(5000)['greek']   # out of range → None
+        None
+    """
+    from_system = from_system.lower().strip()
+    n = _DECODERS[from_system](value)
+
+    out: dict = {"decimal": n}
+    for name, encoder in _ENCODERS.items():
+        try:
+            out[name] = encoder(n)
+        except (TypeError, ValueError):
+            out[name] = None           # value out of range for that system
+    return out
+
+
+def supported_systems() -> list[str]:
+    """Return a sorted list of all supported system names."""
+    return sorted(SYSTEMS)
+
+
+if __name__ == "__main__":
+    samples = [1, 42, 100, 2024, 3999]
+
+    print(f"{'n':<8} {'roman':<12} {'arabic_indic':<14} {'chinese':<22} {'greek':<10} {'egyptian'}")
+    print("─" * 90)
+    for n in samples:
+        r = to_all(n)
+        print(
+            f"{r['decimal']:<8}"
+            f"{str(r['roman']):<12}"
+            f"{str(r['arabic_indic']):<14}"
+            f"{str(r['chinese']):<22}"
+            f"{str(r['greek']):<10}"
+            f"{r['egyptian']}"
+        )
+
+    print()
+    cross = [
+        ("MMXXIV",               "roman",    "chinese"),
+        ("四十二",                "chinese",  "egyptian"),
+        ("ΜΒʹ",                  "greek",    "roman"),
+        ("𓎆𓎆𓎆𓎆𓏺𓏺",           "egyptian", "arabic_indic"),
+        ("٤٢",                   "arabic_indic", "greek"),
+    ]
+    print("Cross-system conversions:")
+    for val, frm, to in cross:
+        print(f"  {val!r:<28} ({frm:<13}) → {to:<13} : {convert(val, frm, to)}")

numly/egyptian.py

@@ -0,0 +1,163 @@
+"""
+numly.egyptian
+~~~~~~~~~~~~~~
+Convert integers to Egyptian hieroglyphic numerals and back.
+
+Pure additive system — no subtraction (unlike Roman).
+Symbols are written largest to smallest, left to right.
+
+    𓁨 = 1,000,000   (Heh — god with arms raised)
+    𓆐 =   100,000   (tadpole / frog)
+    𓂭 =    10,000   (bent finger)
+    𓆼 =     1,000   (lotus flower)
+    𓍢 =       100   (coil of rope)
+    𓎆 =        10   (heel bone / hobble)
+    𓏺 =         1   (vertical stroke / tally)
+
+Range: 1 – 9,999,999
+
+Note: Rendering requires a Unicode font that supports the
+      Egyptian Hieroglyphs block (U+13000–U+1342F), such as
+      Noto Sans Egyptian Hieroglyphs.
+
+Examples:
+    >>> from numly.egyptian import to_egyptian, from_egyptian
+    >>> to_egyptian(42)
+    '𓎆𓎆𓎆𓎆𓏺𓏺'
+    >>> from_egyptian('𓎆𓎆𓎆𓎆𓏺𓏺')
+    42
+"""
+
+_ENC: list[tuple[int, str]] = [
+    (1_000_000, "𓁨"),   # Heh
+    (100_000,   "𓆐"),   # tadpole
+    (10_000,    "𓂭"),   # bent finger
+    (1_000,     "𓆼"),   # lotus
+    (100,       "𓍢"),   # rope coil
+    (10,        "𓎆"),   # heel bone
+    (1,         "𓏺"),   # tally stroke
+]
+
+_DEC: dict[str, int] = {sym: val for val, sym in _ENC}
+
+SYSTEM   = "egyptian"
+MIN, MAX = 1, 9_999_999
+
+
+def to_egyptian(num: int) -> str:
+    """
+    Convert an integer to an Egyptian hieroglyphic numeral string.
+
+    Args:
+        num: Positive integer between 1 and 9,999,999.
+
+    Returns:
+        Hieroglyphic numeral string, e.g. '𓎆𓎆𓎆𓎆𓏺𓏺'.
+
+    Raises:
+        TypeError:  If num is not an int.
+        ValueError: If num is outside 1–9,999,999.
+
+    Examples:
+        >>> to_egyptian(1)
+        '𓏺'
+        >>> to_egyptian(42)
+        '𓎆𓎆𓎆𓎆𓏺𓏺'
+        >>> to_egyptian(1234)
+        '𓆼𓍢𓍢𓎆𓎆𓎆𓏺𓏺𓏺𓏺'
+        >>> to_egyptian(1000000)
+        '𓁨'
+    """
+    if not isinstance(num, int):
+        raise TypeError(f"Expected int, got {type(num).__name__!r}")
+    if not MIN <= num <= MAX:
+        raise ValueError(f"Egyptian numerals support {MIN}–{MAX:,}, got {num}")
+
+    result = ""
+    for val, sym in _ENC:
+        count, num = divmod(num, val)
+        result    += sym * count
+    return result
+
+
+def from_egyptian(s: str) -> int:
+    """
+    Convert an Egyptian hieroglyphic numeral string to an integer.
+
+    Args:
+        s: Hieroglyphic string, e.g. '𓎆𓎆𓎆𓎆𓏺𓏺'.
+
+    Returns:
+        Integer value.
+
+    Raises:
+        TypeError:  If s is not a str.
+        ValueError: If s contains unknown hieroglyphs or is empty.
+
+    Examples:
+        >>> from_egyptian('𓏺')
+        1
+        >>> from_egyptian('𓎆𓎆𓎆𓎆𓏺𓏺')
+        42
+        >>> from_egyptian('𓆼𓍢𓍢𓎆𓎆𓎆𓏺𓏺𓏺𓏺')
+        1234
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    s = s.strip()
+    if not s:
+        raise ValueError("Empty string")
+
+    result = 0
+    for ch in s:
+        if ch not in _DEC:
+            raise ValueError(f"Unknown Egyptian hieroglyph: {ch!r}")
+        result += _DEC[ch]
+    return result
+
+
+def symbol_breakdown(num: int) -> dict[str, int]:
+    """
+    Return a breakdown of how many of each symbol are used.
+
+    Args:
+        num: Positive integer between 1 and 9,999,999.
+
+    Returns:
+        Dict mapping symbol → count (only non-zero entries).
+
+    Examples:
+        >>> symbol_breakdown(1234)
+        {'𓆼': 1, '𓍢': 2, '𓎆': 3, '𓏺': 4}
+    """
+    result = {}
+    for val, sym in _ENC:
+        count, num = divmod(num, val)
+        if count:
+            result[sym] = count
+    return result
+
+
+def is_valid(s: str) -> bool:
+    """
+    Check whether a string is a valid Egyptian hieroglyphic numeral.
+
+    Examples:
+        >>> is_valid('𓎆𓎆𓏺𓏺')
+        True
+        >>> is_valid('hello')
+        False
+    """
+    try:
+        from_egyptian(s)
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+if __name__ == "__main__":
+    tests = [1, 7, 10, 42, 100, 1234, 9999, 1_000_000]
+    for n in tests:
+        r = to_egyptian(n)
+        bd = symbol_breakdown(n)
+        print(f"{n:<10} → {r}  breakdown: {bd}")

numly/greek.py

@@ -0,0 +1,152 @@
+"""
+numly.greek
+~~~~~~~~~~~
+Convert integers to Greek alphabetic (Milesian) numerals and back.
+
+The Milesian system assigns numeric values to Greek letters:
+
+    Units  (1–9) : Α Β Γ Δ Ε Ϛ Ζ Η Θ
+    Tens  (10–90): Ι Κ Λ Μ Ν Ξ Ο Π Ϙ
+    Hundreds(100–900): Ρ Σ Τ Υ Φ Χ Ψ Ω Ϡ
+    Thousands (1000–9000): ͵Α ͵Β ͵Γ ͵Δ ͵Ε ͵Ϛ ͵Ζ ͵Η ͵Θ
+
+A keraia (ʹ) follows the numeral to distinguish it from words.
+The lower numeral sign ͵ (U+0375) precedes the letter for thousands.
+
+Range: 1 – 9,999
+
+Examples:
+    >>> from numly.greek import to_greek, from_greek
+    >>> to_greek(42)
+    'ΜΒʹ'
+    >>> from_greek('͵ΒΚΔʹ')
+    2024
+"""
+
+# ── lookup tables ──────────────────────────────────────────────────────────
+
+_UNITS = ["", "Α", "Β", "Γ", "Δ", "Ε", "Ϛ", "Ζ", "Η", "Θ"]
+_TENS  = ["", "Ι", "Κ", "Λ", "Μ", "Ν", "Ξ", "Ο", "Π", "Ϙ"]
+_HUNDS = ["", "Ρ", "Σ", "Τ", "Υ", "Φ", "Χ", "Ψ", "Ω", "Ϡ"]
+_THOU  = ["", "͵Α", "͵Β", "͵Γ", "͵Δ", "͵Ε", "͵Ϛ", "͵Ζ", "͵Η", "͵Θ"]
+
+_KERAIA       = "ʹ"          # U+02B9  MODIFIER LETTER PRIME
+_NUMERAL_SIGN = "͵"          # U+0375  GREEK LOWER NUMERAL SIGN
+
+# Reverse map: Greek letter → integer value
+_VALUE: dict[str, int] = {}
+for _i, _ch in enumerate(_UNITS[1:], 1): _VALUE[_ch] = _i
+for _i, _ch in enumerate(_TENS[1:],  1): _VALUE[_ch] = _i * 10
+for _i, _ch in enumerate(_HUNDS[1:], 1): _VALUE[_ch] = _i * 100
+
+SYSTEM   = "greek"
+MIN, MAX = 1, 9_999
+
+
+# ── public API ─────────────────────────────────────────────────────────────
+
+def to_greek(num: int) -> str:
+    """
+    Convert an integer to a Greek alphabetic numeral string.
+
+    Args:
+        num: Positive integer between 1 and 9,999.
+
+    Returns:
+        Greek numeral string with trailing keraia, e.g. 'ΜΒʹ'.
+
+    Raises:
+        TypeError:  If num is not an int.
+        ValueError: If num is outside 1–9999.
+
+    Examples:
+        >>> to_greek(1)
+        'Αʹ'
+        >>> to_greek(42)
+        'ΜΒʹ'
+        >>> to_greek(999)
+        'ϠϘΘʹ'
+        >>> to_greek(2024)
+        '͵ΒΚΔʹ'
+        >>> to_greek(9999)
+        '͵ΘϠϘΘʹ'
+    """
+    if not isinstance(num, int):
+        raise TypeError(f"Expected int, got {type(num).__name__!r}")
+    if not MIN <= num <= MAX:
+        raise ValueError(f"Greek numerals support {MIN}–{MAX}, got {num}")
+
+    t = num // 1000
+    h = (num % 1000) // 100
+    d = (num % 100)  // 10
+    u = num % 10
+
+    return _THOU[t] + _HUNDS[h] + _TENS[d] + _UNITS[u] + _KERAIA
+
+
+def from_greek(s: str) -> int:
+    """
+    Convert a Greek alphabetic numeral string to an integer.
+
+    Args:
+        s: Greek numeral string, with or without keraia, e.g. 'ΜΒʹ'.
+
+    Returns:
+        Integer value.
+
+    Raises:
+        TypeError:  If s is not a str.
+        ValueError: If s contains unknown characters or is malformed.
+
+    Examples:
+        >>> from_greek('ΜΒʹ')
+        42
+        >>> from_greek('͵ΒΚΔʹ')
+        2024
+        >>> from_greek('Αʹ')
+        1
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    s = s.rstrip(_KERAIA).strip()
+    if not s:
+        raise ValueError("Empty string")
+
+    result, i = 0, 0
+    while i < len(s):
+        ch = s[i]
+        if ch == _NUMERAL_SIGN:                   # thousands prefix ͵
+            i += 1
+            if i >= len(s) or s[i] not in _VALUE:
+                raise ValueError(f"Invalid Greek numeral: missing letter after ͵")
+            result += _VALUE[s[i]] * 1000
+        elif ch in _VALUE:
+            result += _VALUE[ch]
+        else:
+            raise ValueError(f"Unknown Greek numeral character: {ch!r}")
+        i += 1
+
+    return result
+
+
+def is_valid(s: str) -> bool:
+    """
+    Check whether a string is a valid Greek alphabetic numeral.
+
+    Examples:
+        >>> is_valid('ΜΒʹ')
+        True
+        >>> is_valid('hello')
+        False
+    """
+    try:
+        return to_greek(from_greek(s)) == s.strip()
+    except (TypeError, ValueError):
+        return False
+
+
+if __name__ == "__main__":
+    tests = [1, 6, 9, 10, 42, 90, 100, 399, 999, 1000, 2024, 9999]
+    for n in tests:
+        r = to_greek(n)
+        print(f"{n:<8} → {r:<12} → {from_greek(r)}")

numly/roman.py

@@ -0,0 +1,118 @@
+"""
+numly.roman
+~~~~~~~~~~~
+Convert integers to Roman numerals and back.
+
+Range: 1 – 3,999
+
+Examples:
+    >>> from numly.roman import to_roman, from_roman
+    >>> to_roman(2024)
+    'MMXXIV'
+    >>> from_roman('XLII')
+    42
+"""
+
+_ENC = [
+    (1000, "M"), (900, "CM"), (500, "D"), (400, "CD"),
+    (100,  "C"), (90,  "XC"), (50,  "L"), (40,  "XL"),
+    (10,   "X"), (9,   "IX"), (5,   "V"), (4,   "IV"), (1, "I"),
+]
+_DEC = {"I": 1, "V": 5, "X": 10, "L": 50, "C": 100, "D": 500, "M": 1000}
+
+SYSTEM   = "roman"
+MIN, MAX = 1, 3_999
+
+
+def to_roman(num: int) -> str:
+    """
+    Convert an integer to a Roman numeral string.
+
+    Args:
+        num: Positive integer between 1 and 3,999.
+
+    Returns:
+        Roman numeral string, e.g. 'XLII'.
+
+    Raises:
+        TypeError:  If num is not an int.
+        ValueError: If num is outside 1–3999.
+
+    Examples:
+        >>> to_roman(42)
+        'XLII'
+        >>> to_roman(2024)
+        'MMXXIV'
+        >>> to_roman(3999)
+        'MMMCMXCIX'
+    """
+    if not isinstance(num, int):
+        raise TypeError(f"Expected int, got {type(num).__name__!r}")
+    if not MIN <= num <= MAX:
+        raise ValueError(f"Roman numerals support {MIN}–{MAX}, got {num}")
+
+    result = ""
+    for val, sym in _ENC:
+        while num >= val:
+            result += sym
+            num   -= val
+    return result
+
+
+def from_roman(s: str) -> int:
+    """
+    Convert a Roman numeral string to an integer.
+
+    Args:
+        s: Roman numeral string (case-insensitive), e.g. 'xlii'.
+
+    Returns:
+        Integer value.
+
+    Raises:
+        TypeError:  If s is not a str.
+        ValueError: If s contains invalid characters or is empty.
+
+    Examples:
+        >>> from_roman('XLII')
+        42
+        >>> from_roman('mmxxiv')
+        2024
+    """
+    if not isinstance(s, str):
+        raise TypeError(f"Expected str, got {type(s).__name__!r}")
+    s = s.upper().strip()
+    if not s:
+        raise ValueError("Empty string")
+    for ch in s:
+        if ch not in _DEC:
+            raise ValueError(f"Invalid Roman numeral character: {ch!r}")
+
+    result, prev = 0, 0
+    for ch in reversed(s):
+        v      = _DEC[ch]
+        result = result - v if v < prev else result + v
+        prev   = v
+    return result
+
+
+def is_valid(s: str) -> bool:
+    """
+    Check whether a string is a valid Roman numeral.
+
+    Examples:
+        >>> is_valid('XIV')
+        True
+        >>> is_valid('ABC')
+        False
+    """
+    try:
+        return to_roman(from_roman(s)).upper() == s.upper().strip()
+    except (TypeError, ValueError):
+        return False
+
+
+if __name__ == "__main__":
+    for n in [1, 4, 9, 42, 399, 2024, 3999]:
+        r = to_roman(n)
+        print(f"{n:<8} → {r:<14} → {from_roman(r)}")

numly-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: numly
+Version: 0.1.0
+Summary: Convert numbers across numeral systems — Roman, Chinese, Greek, Egyptian, Arabic-Indic and more.
+Home-page: https://github.com/TheMadrasTechie/numly
+Author: TheMadrasTechie
+Author-email: you@example.com
+Keywords: numerals,roman,chinese,greek,egyptian,arabic-indic,number,converter
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-python
+Dynamic: summary
+
+<p align="center">
+  <img src="numly_rounded_square.svg" alt="numly logo" width="120" height="120"/>
+</p>
+
+<h1 align="center">numly</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/pypi/v/numly" alt="PyPI version"/>
+  <img src="https://img.shields.io/pypi/pyversions/numly" alt="Python versions"/>
+  <img src="https://img.shields.io/github/license/yourusername/numly" alt="License"/>
+</p>
+
+<p align="center">
+  A Python library to work with numbers across formats — decimal, roman, words, binary, hex, and more.
+</p>
+
+---
+
+## Installation
+
+```bash
+pip install numly
+```
+
+---
+
+## Quick Start
+
+```python
+import numly
+
+# Convert to Roman numerals
+numly.to_roman(2024)        # → 'MMXXIV'
+
+# Convert to words
+numly.to_words(42)          # → 'forty-two'
+
+# Convert to binary
+numly.to_binary(255)        # → '11111111'
+
+# Convert to hex
+numly.to_hex(255)           # → 'FF'
+```
+
+---
+
+## Features
+
+- 🔢 Decimal → Roman numerals
+- 🔤 Decimal → Words (English)
+- 💻 Decimal → Binary / Octal / Hex
+- 🔁 Reverse conversions (Roman → Decimal, etc.)
+- 🌍 Locale-aware number formatting *(coming soon)*
+
+---
+
+## API Reference
+
+| Function | Input | Output |
+|---|---|---|
+| `to_roman(n)` | `int` | `str` — e.g. `'XIV'` |
+| `from_roman(s)` | `str` | `int` — e.g. `14` |
+| `to_words(n)` | `int` | `str` — e.g. `'forty-two'` |
+| `to_binary(n)` | `int` | `str` — e.g. `'1110'` |
+| `to_octal(n)` | `int` | `str` — e.g. `'16'` |
+| `to_hex(n)` | `int` | `str` — e.g. `'E'` |
+
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to open an issue or submit a pull request.
+
+```bash
+git clone https://github.com/yourusername/numly.git
+cd numly
+pip install -e .
+```
+
+---
+
+## License
+
+MIT License © 2026 TheMadrasTechie

numly-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+numly/__init__.py,sha256=Em-_1edoHiwNc78ZuPiLCuSIMlol87DtxsRtWlgXUAQ,2769
+numly/arabic_indic.py,sha256=9kGWCT7bz71MuWKUhw_yxIyFwz9L19DrgEHSI4Zei8E,2855
+numly/chinese.py,sha256=0JSUhfj0ryMca4uIRYDZG8-ix9fBw0s69I4Z9_57wpI,5150
+numly/convert.py,sha256=tIrU4gfFMe2F7Nt5iWZzprCykoYA1jFlpceaR6DtIu0,6400
+numly/egyptian.py,sha256=loWwpHi-gaQIV5d7mELK8d4QiyHstGxWM67Wnr9u8fQ,4238
+numly/greek.py,sha256=pENWN19_Z_ZuahPCV1Skg7smjiyrIp9f-RB08-jhK-M,4493
+numly/roman.py,sha256=sBxrO0idsefcB4RNGtG-Z6kuYhKmBYogX1fFOT5I_yU,2733
+numly-0.1.0.dist-info/METADATA,sha256=DrW-cd69PeFHKrsC9o056yeLIjsDj3QhHycss9WuQXE,2602
+numly-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+numly-0.1.0.dist-info/top_level.txt,sha256=ob_L0EynydpPFHV5aX-Be18Kim6Y1uQ5QMyYom5K6fQ,6
+numly-0.1.0.dist-info/RECORD,,

numly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

numly-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+numly