Skip to content

TheMadrasTechie/numly

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

28 Commits
.github/workflows
.github/workflows
Β 
Β 
images
images
Β 
Β 
numly
numly
Β 
Β 
.gitignore
.gitignore
Β 
Β 
LICENSE
LICENSE
Β 
Β 
numly_rounded_square.svg
numly_rounded_square.svg
Β 
Β 
readme.md
readme.md
Β 
Β 
setup.cfg
setup.cfg
Β 
Β 
setup.py
setup.py
Β 
Β 
to do tasks
to do tasks
Β 
Β 

Repository files navigation

numly

A Python library to convert numbers across the world's numeral systems.

PyPI version Python versions License Downloads

pip install numly

What is numly?

numly lets you convert any number between 12 different numeral systems with a single function call β€” from ancient Egyptian hieroglyphs to modern binary, from Mayan glyphs to English words.

import numly

numly.convert(42, "decimal", "roman")         # β†’ 'XLII'
numly.convert("XLII", "roman", "chinese")     # β†’ 'ε››εδΊŒ'
numly.to_words(1_234_567, "indian")           # β†’ 'twelve lakh thirty four thousand...'
numly.to_binary(255)                          # β†’ '11111111'
numly.to_all(42)                              # β†’ all systems at once

Supported Systems

System Example (42) Range
decimal 42 0 – unlimited
roman XLII 1 – 3,999
arabic_indic Ω€Ω’ 0 – unlimited
chinese ε››εδΊŒ 0 – 99,999,999
greek ΞœΞ’ΚΉ 1 – 9,999
egyptian π“Ž†π“Ž†π“Ž†π“Ž†π“Ίπ“Ί 1 – 9,999,999
tamil ΰ―ͺΰ―°ΰ―¨ 0 – 9,999
babylonian π’Œ‹π’Œ‹π’Œ‹π’Œ‹π’Ήπ’Ή 1 – 216,000 (base 60)
mayan 𝋂 𝋂 0 – 7,999 (base 20)
binary 101010 0 – unlimited
octal 52 0 – unlimited
hex 2A 0 – unlimited
words forty two 0 – 999 trillion

Systems with a range limit return None in to_all() if the number is out of range.

Installation

pip install numly

Requires Python 3.8 or higher.

Quick Start

import numly

# Numeral systems
numly.to_roman(2024)              # β†’ 'MMXXIV'
numly.to_chinese(42)              # β†’ 'ε››εδΊŒ'
numly.to_arabic_indic(2024)       # β†’ 'Ω’Ω Ω’Ω€'
numly.to_greek(999)               # β†’ 'ϠϘΘʹ'
numly.to_egyptian(1234)           # β†’ 'π“†Όπ“’π“’π“Ž†π“Ž†π“Ž†π“Ίπ“Ίπ“Ίπ“Ί'
numly.to_tamil(42)                # β†’ 'ΰ―ͺΰ―°ΰ―¨'
numly.to_babylonian(61)           # β†’ '𒁹 𒁹'
numly.to_mayan(42)                # β†’ '𝋂 𝋂'
numly.to_mayan_text(42)           # β†’ 'β€’β€’ | β€’β€’'

# Base conversions
numly.to_binary(42)               # β†’ '101010'
numly.to_octal(42)                # β†’ '52'
numly.to_hex(255)                 # β†’ 'FF'
numly.to_hex(255, prefix=True)    # β†’ '0xFF'
numly.to_base(42, 36)             # β†’ '16'

# English words
numly.to_words(1_234_567)                  # β†’ 'one million two hundred thirty four thousand five hundred sixty seven'
numly.to_words(1_234_567, "indian")        # β†’ 'twelve lakh thirty four thousand five hundred sixty seven'

# Convert back to decimal
numly.from_roman('MMXXIV')        # β†’ 2024
numly.from_chinese('ε››εδΊŒ')      # β†’ 42
numly.from_tamil('ΰ―ͺΰ―°ΰ―¨')          # β†’ 42
numly.from_babylonian('𒁹 𒁹')    # β†’ 61
numly.from_mayan('𝋂 𝋂')          # β†’ 42
numly.from_binary('101010')       # β†’ 42
numly.from_hex('FF')              # β†’ 255

Universal Converter

convert(value, from_system, to_system)

Convert between any two systems directly β€” no need to go through decimal.

from numly import convert

# decimal β†’ others
convert(42, "decimal", "roman")           # β†’ 'XLII'
convert(42, "decimal", "tamil")           # β†’ 'ΰ―ͺΰ―°ΰ―¨'
convert(42, "decimal", "babylonian")      # β†’ 'π’Œ‹π’Œ‹π’Œ‹π’Œ‹π’Ήπ’Ή'
convert(42, "decimal", "mayan")           # β†’ '𝋂 𝋂'
convert(42, "decimal", "binary")          # β†’ '101010'
convert(42, "decimal", "hex")             # β†’ '2A'

# cross-system (no decimal step needed)
convert("MMXXIV",  "roman",    "chinese")      # β†’ 'δΊŒεƒι›ΆδΊŒεε››'
convert("ε››εδΊŒ",  "chinese",  "greek")         # β†’ 'ΞœΞ’ΚΉ'
convert("ΞœΞ’ΚΉ",    "greek",    "roman")          # β†’ 'XLII'
convert("Ω€Ω’",     "arabic_indic", "egyptian")   # β†’ 'π“Ž†π“Ž†π“Ž†π“Ž†π“Ίπ“Ί'
convert("101010",  "binary",   "hex")           # β†’ '2A'

# to decimal
convert("XLII", "roman", "decimal")       # β†’ 42
convert("FF",   "hex",   "decimal")       # β†’ 255

to_all(value, from_system="decimal")

Convert a number to all systems at once.

from numly import to_all

to_all(42)
# {
#   'decimal':      42,
#   'roman':        'XLII',
#   'arabic_indic': 'Ω€Ω’',
#   'chinese':      'ε››εδΊŒ',
#   'greek':        'ΞœΞ’ΚΉ',
#   'egyptian':     'π“Ž†π“Ž†π“Ž†π“Ž†π“Ίπ“Ί',
#   'tamil':        'ΰ―ͺΰ―°ΰ―¨',
#   'babylonian':   'π’Œ‹π’Œ‹π’Œ‹π’Œ‹π’Ήπ’Ή',
#   'mayan':        '𝋂 𝋂',
#   'binary':       '101010',
#   'octal':        '52',
#   'hex':          '2A'
# }

English Words

Convert numbers to English words in Western or Indian system.

from numly import to_words, to_words_western, to_words_indian

# Western system (thousand β†’ million β†’ billion β†’ trillion)
to_words_western(0)              # β†’ 'zero'
to_words_western(42)             # β†’ 'forty two'
to_words_western(1_000)          # β†’ 'one thousand'
to_words_western(1_000_000)      # β†’ 'one million'
to_words_western(1_234_567)      # β†’ 'one million two hundred thirty four thousand five hundred sixty seven'
to_words_western(1_000_000_000)  # β†’ 'one billion'

# Indian system (thousand β†’ lakh β†’ crore)
to_words_indian(0)               # β†’ 'zero'
to_words_indian(42)              # β†’ 'forty two'
to_words_indian(1_00_000)        # β†’ 'one lakh'
to_words_indian(1_234_567)       # β†’ 'twelve lakh thirty four thousand five hundred sixty seven'
to_words_indian(1_00_00_000)     # β†’ 'one crore'
to_words_indian(1_00_00_00_000)  # β†’ 'ten crore'

# or use to_words() with system parameter
to_words(1_234_567, "western")   # β†’ 'one million two hundred...'
to_words(1_234_567, "indian")    # β†’ 'twelve lakh thirty four thousand...'

Base Conversions

from numly import to_binary, to_octal, to_hex, to_base

# Binary
to_binary(42)                # β†’ '101010'
to_binary(42, prefix=True)   # β†’ '0b101010'
from_binary('101010')        # β†’ 42

# Octal
to_octal(42)                 # β†’ '52'
to_octal(42, prefix=True)    # β†’ '0o52'
from_octal('52')             # β†’ 42

# Hexadecimal
to_hex(255)                  # β†’ 'FF'
to_hex(255, prefix=True)     # β†’ '0xFF'
to_hex(255, upper=False)     # β†’ 'ff'
from_hex('FF')               # β†’ 255
from_hex('0xff')             # β†’ 255

# Any custom base (2–36)
to_base(42, 2)               # β†’ '101010'
to_base(42, 8)               # β†’ '52'
to_base(42, 16)              # β†’ '2A'
to_base(255, 36)             # β†’ '73'
from_base('2A', 16)          # β†’ 42

Ancient Numeral Systems

Tamil (0 – 9,999)

Ancient Tamil positional-additive system using Unicode Tamil block.

numly.to_tamil(0)       # β†’ 'ΰ―¦'
numly.to_tamil(10)      # β†’ 'ΰ―°'
numly.to_tamil(42)      # β†’ 'ΰ―ͺΰ―°ΰ―¨'
numly.to_tamil(1234)    # β†’ 'ΰ―§ΰ―²ΰ―¨ΰ―±ΰ―©ΰ―°ΰ―ͺ'
numly.from_tamil('ΰ―ͺΰ―°ΰ―¨') # β†’ 42

Babylonian (1 – 216,000)

Base-60 cuneiform system using 𒁹 (1) and π’Œ‹ (10). Digits separated by spaces.

numly.to_babylonian(10)    # β†’ 'π’Œ‹'
numly.to_babylonian(42)    # β†’ 'π’Œ‹π’Œ‹π’Œ‹π’Œ‹π’Ήπ’Ή'
numly.to_babylonian(60)    # β†’ '𒁹 π’‘±'   (1Γ—60 + zero)
numly.to_babylonian(61)    # β†’ '𒁹 𒁹'   (1Γ—60 + 1)
numly.to_babylonian(3661)  # β†’ '𒁹 𒁹 𒁹' (1Γ—3600 + 1Γ—60 + 1)
numly.from_babylonian('𒁹 𒁹') # β†’ 61

Mayan (0 – 7,999)

Base-20 system β€” one of the first civilisations to use zero. Available in Unicode glyph form and human-readable dot/bar form.

numly.to_mayan(0)          # β†’ '𝋠'
numly.to_mayan(19)         # β†’ '𝋳'
numly.to_mayan(20)         # β†’ '𝋑 𝋠'    (1Γ—20 + 0)
numly.to_mayan(42)         # β†’ '𝋂 𝋂'    (2Γ—20 + 2)
numly.to_mayan_text(0)     # β†’ 'β—Ž'       (shell = zero)
numly.to_mayan_text(7)     # β†’ '‒‒━'     (2 dots + 1 bar)
numly.to_mayan_text(42)    # β†’ 'β€’β€’ | β€’β€’'
numly.from_mayan('𝋂 𝋂')   # β†’ 42

Validation

Each system has an is_valid_* function:

numly.is_valid_roman("XIV")           # β†’ True
numly.is_valid_roman("ABC")           # β†’ False
numly.is_valid_chinese("ε››εδΊŒ")      # β†’ True
numly.is_valid_greek("ΞœΞ’ΚΉ")           # β†’ True
numly.is_valid_egyptian("π“Ž†π“Ž†π“Ίπ“Ί")   # β†’ True
numly.is_valid_arabic_indic("Ω€Ω’")    # β†’ True
numly.is_valid_tamil("ΰ―ͺΰ―°ΰ―¨")          # β†’ True
numly.is_valid_babylonian("𒁹 𒁹")   # β†’ True
numly.is_valid_mayan("𝋂 𝋂")          # β†’ True

Egyptian Symbol Breakdown

from numly import symbol_breakdown

symbol_breakdown(1234)
# {'𓆼': 1, '𓍒': 2, 'π“Ž†': 3, '𓏺': 4}
# 1 lotus (1000) + 2 rope coils (100) + 3 heel bones (10) + 4 tallies (1)

Error Handling

numly raises clear, descriptive errors:

numly.to_roman(5000)
# ValueError: Roman numerals support 1–3999, got 5000

numly.to_roman("hello")
# TypeError: Expected int, got 'str'

numly.from_roman("XYZ")
# ValueError: Invalid Roman numeral character: 'Y'

numly.to_binary(-1)
# ValueError: Negative numbers are not supported

numly.to_words(42, "french")
# ValueError: Unknown system 'french'. Choose 'western' or 'indian'.

Full API Reference

Numeral Systems

Function Input Output
to_roman(n) / from_roman(s) int / str str / int
to_arabic_indic(n) / from_arabic_indic(s) int / str str / int
to_chinese(n) / from_chinese(s) int / str str / int
to_greek(n) / from_greek(s) int / str str / int
to_egyptian(n) / from_egyptian(s) int / str str / int
to_tamil(n) / from_tamil(s) int / str str / int
to_babylonian(n) / from_babylonian(s) int / str str / int
to_mayan(n) / from_mayan(s) int / str str / int
to_mayan_text(n) int str (dots & bars)
symbol_breakdown(n) int dict

Base Conversions

Function Input Output
to_binary(n, prefix) / from_binary(s) int / str str / int
to_octal(n, prefix) / from_octal(s) int / str str / int
to_hex(n, prefix, upper) / from_hex(s) int / str str / int
to_base(n, base) / from_base(s, base) int / str str / int

Words

Function Input Output
to_words(n, system) int, 'western'/'indian' str
to_words_western(n) int str
to_words_indian(n) int str

Universal

Function Input Output
convert(value, from, to) any str / int
to_all(value, from) any dict
supported_systems() β€” list

What's Coming Next

  • πŸ”œ Negative number support
  • πŸ”œ Locale-aware formatting (1,000.00 vs 1.000,00)
  • πŸ”œ Words in more languages (Tamil, Hindi, Arabic…)
  • πŸ”œ Numbers beyond current range limits
  • πŸ”œ More ancient systems (Aztec, Sumerian, Greek acrophonic)

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

git clone https://github.com/TheMadrasTechie/numly.git
cd numly
pip install -e .

License

MIT License Β© 2026 TheMadrasTechie

About

This is a new pypi package for some basic number operations .

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages