---

Overview

XNum is a simple and lightweight Python library that helps you convert digits between different numeral systems — like English, Persian, Hindi, Arabic-Indic, Bengali, and more. It can automatically detect mixed numeral formats in a piece of text and convert only the numbers, leaving the rest untouched. Whether you're building multilingual apps or processing localized data, XNum makes it easy to handle numbers across different languages with a clean and easy-to-use API.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

PyPI

• Check Python Packaging User Guide
• Run pip install xnum==1.6

Source code

• Download Version 1.6 or Latest Source
• Run pip install .

Usage

Converting

Convert digits between different numeral systems while preserving the surrounding text.

>>> from xnum import convert, NumeralSystem
>>> convert("۱۲۳ apples & ꘤꘥꘦ cars", target=NumeralSystem.ENGLISH)
'123 apples & 456 cars'
>>> convert("۱۲۳ and 456", source=NumeralSystem.PERSIAN, target=NumeralSystem.HINDI)
'१२३ and 456'

[!NOTE] By default, the source parameter is set to NumeralSystem.AUTO, which automatically detects the numeral system

Detecting numeral systems

Detect all unique numeral systems in the input text, preserving their first appearance order.

>>> from xnum import detect_systems
>>> detect_systems("۱۲۳ apples & 456 cars")
[<NumeralSystem.PERSIAN: 'persian'>, <NumeralSystem.ENGLISH: 'english'>]

If no supported numeral system is found, an empty list is returned:

>>> detect_systems("hello world")
[]

Available systems

Get the list of all numeral systems supported by XNum.

>>> from xnum import available_systems
>>> available_systems()
['adlam', 'ahom', 'arabic_indic', ..., 'wancho', 'warang_citi']

Supported numeral systems

• English
  • Standard
  • Fullwidth
  • Subscript
  • Superscript
  • Double-Struck
  • Bold
  • Monospace
  • Sans-Serif
  • Sans-Serif Bold
  • Circled
  • Dingbat Circled Sans-Serif
  • Dingbat Negative Circled Sans-Serif
  • Keycap
  • Emoji
  • Full Stop
  • Comma
  • Segmented
• Persian
• Hindi
• Arabic-Indic
• Bengali
• Thai
• Khmer
• Myanmar
• Tibetan
• Gujarati
• Odia
• Telugu
• Kannada
• Gurmukhi
• Lao
• Nko
• Mongolian
• Sinhala Lith ★
• Myanmar Shan
• Limbu
• Vai
• Ol Chiki
• Balinese
• New Tai Lue
• Saurashtra
• Javanese
• Cham
• Lepcha
• Sundanese
• Dives Akuru
• Modi
• Takri
• Newa
• Tirhuta
• Sharada
• Khudawadi
• Chakma
• Sora Sompeng
• Hanifi Rohingya
• Osmanya
• Meetei Mayek
• Kayah Li
• Gunjala Gondi
• Masaram Gondi
• Mro
• Wancho
• Adlam
• Tai Tham Hora
• Tai Tham Tham
• Nyiakeng Puachue Hmong
• Malayalam
• Brahmi ★
• Myanmar Tai Laing
• Ahom
• Warang Citi
• Bhaiksuki
• Tamil ★
• Pahawh Hmong
• Garay
• Medefaidrin
• Nag Mundari

★ Non-positional numeral system

[!NOTE] XNum performs digit-by-digit conversion using positional notation. While most supported systems are positional, a small subset are non-positional and follow different numeric conventions. For them, XNum converts only individual digit symbols and does not interpret or generate non-positional number forms.

Issues & bug reports

Just fill an issue and describe it. We'll check it ASAP! or send an email to xnum@openscilab.com.

• Please complete the issue template

You can also join our discord server

References

1- Unicode - Compart

2- SYMBL (◕‿◕) Symbols, Emojis, Characters, Scripts, Alphabets, Hieroglyphs and the entire Unicode

3- 📙 Emojipedia — 😃 Home of Emoji Meanings 💁👌🎍😍

Show your support

Star this repo

Give a ⭐️ if this project helped you!

Donate to our project

If you do like our project and we hope that you do, can you please support us? Our project is not and is never going to be working for profit. We need the money just so we can continue doing what we do ;-) .

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

1.6 - 2026-09-04

Added

• XNumError class
• XNumValidationError class
• Nag Mundari numeral system
• detect_systems function
• available_systems function
• _validate_convert function

Changed

• detect_system function renamed to _detect_digit_system
• translate_digit function renamed to _translate_digit
• _detect_digit_system function default value changed to None
• NUMERAL_MAPS renamed to SYSTEM_TO_DIGITS_MAP
• ALL_DIGIT_MAPS renamed to DIGIT_TO_VALUE_MAP
• DIGIT_SYSTEM_MAP renamed to DIGIT_TO_SYSTEM_MAP
• README.md updated
• convert_match function modified
• convert function modified
• Test system modified
• Dependencies structure modified

1.5 - 2026-04-10

Added

• Garay numeral system
• Medefaidrin numeral system

Changed

• README.md updated

1.4 - 2026-02-16

Added

• Ahom numeral system
• Warang Citi numeral system
• Bhaiksuki numeral system
• Tamil numeral system
• Pahawh Hmong numeral system

Changed

• README.md updated
• Test system modified

1.3 - 2026-01-28

Added

• English full stop mode
• English comma mode
• English segmented mode
• Malayalam numeral system
• Brahmi numeral system
• Myanmar Tai Laing numeral system

Changed

• Burmese numeral system renamed to Myanmar

1.2 - 2025-12-11

Added

• English keycap mode
• English emoji mode

Changed

• convert function modified
• Test system modified
• README.md updated
• Digits type changed to list

1.1 - 2025-11-10

Added

• English circled mode
• English dingbat circled sans-serif mode
• English dingbat negative circled sans-serif mode
• Tai Tham Hora numeral system
• Tai Tham Tham numeral system
• Nyiakeng Puachue Hmong numeral system

Changed

• Test system modified

1.0 - 2025-10-20

Added

• Sora Sompeng numeral system
• Hanifi Rohingya numeral system
• Osmanya numeral system
• Meetei Mayek numeral system
• Kayah Li numeral system
• Gunjala Gondi numeral system
• Masaram Gondi numeral system
• Mro numeral system
• Wancho numeral system
• Adlam numeral system

Changed

• README.md updated
• Python 3.14 added to test.yml

0.9 - 2025-10-10

Added

• Dives Akuru numeral system
• Modi numeral system
• Takri numeral system
• Newa numeral system
• Tirhuta numeral system
• Sharada numeral system
• Khudawadi numeral system
• Chakma numeral system

0.8 - 2025-09-28

Added

• Vai numeral system
• Ol Chiki numeral system
• Balinese numeral system
• New Tai Lue numeral system
• Saurashtra numeral system
• Javanese numeral system
• Cham numeral system
• Lepcha numeral system
• Sundanese numeral system

Changed

• Test system modified

0.7 - 2025-09-17

Added

• Nko numeral system
• Mongolian numeral system
• Sinhala lith numeral system
• Myanmar shan numeral system
• Limbu numeral system

Changed

• Test system modified

0.6 - 2025-09-05

Added

• English double-struck mode
• English bold mode
• English monospace mode
• English sans-serif mode
• English sans-serif bold mode

Changed

• README.md updated
• Test system modified

0.5 - 2025-09-01

Added

• Lao numeral system
• English fullwidth mode
• English subscript mode
• English superscript mode

Changed

• Test system modified
• README.md updated

0.4 - 2025-08-18

Added

• Gurmukhi numeral system
• Kannada numeral system
• Telugu numeral system

Changed

• Test system modified
• README.md updated

0.3 - 2025-08-05

Added

• Tibetan numeral system
• Gujarati numeral system
• Odia numeral system

Changed

• README.md updated

0.2 - 2025-07-28

Added

• Thai numeral system
• Khmer numeral system
• Burmese numeral system
• Logo

Changed

• Test system modified
• target parameter bug fixed
• README.md updated

0.1 - 2025-07-20

Added

• English numeral system
• Persian numeral system
• Hindi numeral system
• Arabic-Indic numeral system
• Bengali numeral system