{"id":13826529,"url":"https://github.com/persian-tools/py-persian-tools","last_synced_at":"2025-05-16T02:09:32.413Z","repository":{"id":41850822,"uuid":"338065732","full_name":"persian-tools/py-persian-tools","owner":"persian-tools","description":"An anthology of a variety of tools for the Persian language in Python","archived":false,"fork":false,"pushed_at":"2024-11-14T18:07:59.000Z","size":84,"stargazers_count":177,"open_issues_count":9,"forks_count":17,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-08T14:02:42.774Z","etag":null,"topics":["bank","card-number","digits","national-code","national-id","number","ordinal-suffix","persian","persian-language","python","random-generator","sheba","validation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/persian-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-11T15:18:06.000Z","updated_at":"2025-04-02T14:40:17.000Z","dependencies_parsed_at":"2022-08-11T19:20:58.697Z","dependency_job_id":"1572d07c-bd92-46e6-90ae-8d9a4790a789","html_url":"https://github.com/persian-tools/py-persian-tools","commit_stats":{"total_commits":50,"total_committers":4,"mean_commits":12.5,"dds":"0.21999999999999997","last_synced_commit":"bba5f1b788eb2356d626a91719da08d9b594be7e"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persian-tools%2Fpy-persian-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persian-tools%2Fpy-persian-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persian-tools%2Fpy-persian-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/persian-tools%2Fpy-persian-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/persian-tools","download_url":"https://codeload.github.com/persian-tools/py-persian-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254453667,"owners_count":22073618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bank","card-number","digits","national-code","national-id","number","ordinal-suffix","persian","persian-language","python","random-generator","sheba","validation"],"created_at":"2024-08-04T09:01:39.772Z","updated_at":"2025-05-16T02:09:32.394Z","avatar_url":"https://github.com/persian-tools.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Persian Tools\n\nAn anthology of a variety of tools for the Persian language in Python\n\n[![codecov](https://codecov.io/gh/persian-tools/py-persian-tools/branch/master/graph/badge.svg?token=0M7JehkAWU)](https://codecov.io/gh/persian-tools/py-persian-tools)\n![Tests](https://github.com/persian-tools/py-persian-tools/workflows/Test/badge.svg)\n\n## Installation\n\n`pip install persian-tools`\n\n## Modules\n\n1. [digits](#digits)\n2. [separator](#separator)\n3. [ordinal suffix](#ordinal-suffix)\n4. [bank](#bank)\n    1. [card number](#card-number)\n    2. [sheba](#sheba)\n5. [national id](#national-id)\n6. [legal id](#legal-id)\n7. [phone number](#phone-number)\n8. [bill](#bill)\n9. [plate](#plate)\n\n## Usage\nLet's take a look at what an example test case would look like using `persian-tools`.\n\n### digits\nThis module will help you to normalize digits from Persian, Arabic and English to only one of them.\n\n```python\nfrom persian_tools import digits\n\ndigits.convert_to_fa(123)          # '۱۲۳'\ndigits.convert_to_fa('123')        # '۱۲۳'\ndigits.convert_to_fa('123٤٥٦')     # '۱۲۳۴۵۶'\ndigits.convert_to_fa('sth 123٤٥٦') # 'sth ۱۲۳۴۵۶'\n\ndigits.convert_to_en('۱۲۳')        # '123'\ndigits.convert_to_en('۱۲۳٤٥٦')     # '123456'\ndigits.convert_to_en('sth ۱۲۳٤٥٦') # 'sth 123456'\n\ndigits.convert_to_ar(123)          # '۱۲۳'\ndigits.convert_to_ar('123')        # '۱۲۳'\ndigits.convert_to_ar('sth 123۴۵۶') # 'sth ۱۲۳٤٥٦'\n```\n\n`persian-tools` also, has another function to convert numbers to words; you can convert result to ordinal mode with `ordinal=True` in inputs.\n```python\nfrom persian_tools import digits\n\ndigits.convert_to_word(500443)                  # پانصد هزار و چهارصد و چهل و سه\ndigits.convert_to_word(-500443)                 # منفی پانصد هزار و چهارصد و چهل و سه\ndigits.convert_to_word(500443, ordinal=True)    # پانصد هزار و چهارصد و چهل و سوم\ndigits.convert_to_word(30000000000)             # سی میلیارد\n```\n\nto convert words to number, you can use this function with different args:\n```python\nfrom persian_tools import digits\n\ndigits.convert_from_word('منفی سه هزارمین')                        # -3000\ndigits.convert_from_word('منفی سه هزارم', digits='fa')             # -۳۰۰۰\ndigits.convert_from_word('منفی سه هزار')                           # -3000\ndigits.convert_from_word('سه هزار دویست و دوازده')                 # 3212\ndigits.convert_from_word('دوازده هزار بیست دو', separator=True)    # '12,022'\ndigits.convert_from_word('حقوق شیش صد و ۲۷ میلیون تومان سالانه')    # 627000000\n```\n\nNote: as you can see in examples, this function will remove ordinal suffix by default.\n\n### separator\nAdding or removing thousands separators will handle; default separator is ',' but can change with second input.\n\n```python\nfrom persian_tools import separator\n\nseparator.add(300)                 # '300'\nseparator.add(3000000)             # '3,000,000'\nseparator.add(3000000.0003)        # '3,000,000.0003'\nseparator.add(3000000, '/')        # '3/000/000'\nseparator.add('۳۰۰۰۰')             # '۳۰,۰۰۰'\n\nseparator.remove('300')            # '300'\nseparator.remove('3,000,000')      # '3000000'\nseparator.remove('3/000/000', '/') # '3000000'\nseparator.remove('۳۰,۰۰۰')         # '۳۰۰۰۰'\n```\n\n### ordinal suffix\nAdding or removing ordinal suffix for persian numbers in word will handle.\n\n```python\nfrom persian_tools import ordinal_suffix\n\nordinal_suffix.add('بیست')          # 'بیستم'\nordinal_suffix.add('سی و سه')       # 'سی و سوم'\nordinal_suffix.add('سی')            # 'سی اُم'\n\nordinal_suffix.remove('دومین')      # 'دو'\nordinal_suffix.remove('سی و سوم')   # 'سی و سه'\nordinal_suffix.remove('بیستم')      # 'بیست'\nordinal_suffix.remove('سی اُم')      # 'سی'\n```\n\n### bank\n#### card number\nThis module has useful functions related to bank cards number, like:\n* validating them\n* find bank data of a card number\n* extract card numbers from a text\n\n```python\nfrom persian_tools.bank import card_number\n\ncard_number.validate('6037701689095443')    # True\ncard_number.validate('6219861034529007')    # True\ncard_number.validate('6219861034529008')    # False\n\ncard_number.bank_data('6219861034529007')\n# {'nickname': 'saman', 'name': 'Saman Bank', 'persian_name': 'بانک سامان', 'card_prefix': ['621986'], 'sheba_code': ['056']}\ncard_number.bank_data('6037701689095443')\n# {'nickname': 'keshavarzi', 'name': 'Keshavarzi', 'persian_name': 'بانک کشاورزی', 'card_prefix': ['603770', '639217'], 'sheba_code': ['016']}\n\n\n\ncard_number.extract_card_numbers('''شماره کارتم رو برات نوشتم:\n                                     6219-8610-3452-9007\n                                     اینم یه شماره کارت دیگه ای که دارم\n                                    ۵۰۲۲-۲۹۱۰-۷۰۸۷-۳۴۶۶                                     \n                                    5022291070873466''',                # first argument is a text\n                                    check_validation=True,              # a boolean that define you need only valid card numbers in result, default: True\n                                    detect_bank_name=True,              # this will add bank name in result, default: False\n                                    filter_valid_card_numbers=True)     # just valid card numbers will be in result; be careful to `check_validation` be also True, default: True\n# result\n# [\n#    {'pure': '6219861034529007', 'base': '6219-8610-3452-9007', 'index': 1, 'is_valid': True,\n#     'bank_data': {\n#         'nickname': 'saman',\n#         'name': 'Saman Bank',\n#         'persian_name': 'بانک سامان',\n#         'card_prefix': ['621986'],\n#         'sheba_code': ['056'],\n#     }},\n#    {'pure': '5022291070873466', 'base': '5022291070873466', 'index': 3, 'is_valid': True,\n#     'bank_data': {\n#         'nickname': 'pasargad',\n#         'name': 'Pasargad Bank',\n#         'persian_name': 'بانک پاسارگاد',\n#         'card_prefix': ['502229', '639347'],\n#         'sheba_code': ['057'],\n#     }},\n# ]\n```\n\n#### sheba\n`sheba` module contain 2 functions:\n* validating them\n* find bank data of a sheba number\n\n```python\n\nfrom persian_tools.bank import sheba\n\nsheba.validate('IR820540102680020817909002')    # True\nsheba.validate('IR01234567890123456789')        # False\n\nsheba.bank_data('IR820540102680020817909002')\n# {\n#     'nickname': 'parsian',\n#     'name': 'Parsian Bank',\n#     'persian_name': 'بانک پارسیان',\n#     'card_prefix': ['622106', '627884'],\n#     'sheba_code': ['054'],\n#     'account_number': '020817909002',\n#     'formatted_account_number': '002-00817909-002'\n# }\n```\n\n### national id\nThis module has useful functions related to iranian national id (code-e melli), like:\n* validating them\n* generate a random one\n* find place of national id by the prefix of id\n\n```python\nfrom persian_tools import national_id\n\nnational_id.validate('0499370899')      # True\nnational_id.validate('0684159415')      # False\n\nnational_id.generate_random()           # '0458096784'\nnational_id.generate_random()           # '1156537101'\n\nnational_id.find_place('0906582709')    # {'code': ['089', '090'], 'city': 'کاشمر', 'province': 'خراسان رضوی'}\nnational_id.find_place('0643005846')    # {'code': ['064', '065'], 'city': 'بیرجند', 'province': 'خراسان جنوبی'}\n```\n\n### legal id\nThis module contains two functions to generate random iranian legal id (shenas-e melli) and validate any given id.\n\n```python\nfrom persian_tools import legal_id\n\nlegal_id.validate('10380284790')      # True\nlegal_id.validate('11053639140')      # False\n\nlegal_id.generate_random()            # '10100387143'\nlegal_id.generate_random()            # '77111986110'\n```\n\n### phone number\nThis module can validate, normalize and give you some data from a phone number.\n\n```python\nfrom persian_tools import phone_number\n\nphone_number.validate('09123456789')        # True\nphone_number.validate('+989123456789')      # True\nphone_number.validate('989123456789')       # True\nphone_number.validate('98912345678')        # False\n\nphone_number.normalize('00989022002580')    # 09022002580\nphone_number.normalize('+989022002580')     # 09022002580\nphone_number.normalize('9022002580')        # 09022002580\nphone_number.normalize('9022002580', '0')   # 09022002580\nphone_number.normalize('9022002580', '+98') # +989022002580\n\nphone_number.operator_data('09123456789')\n# {'province': ['البرز', 'زنجان', 'سمنان', 'قزوین', 'قم', 'برخی از شهرستان های استان مرکزی'], 'base': 'تهران', 'type': ['permanent'], 'operator': 'همراه اول'}\nphone_number.operator_data('09303456789')\n# {'province': [], 'base': 'کشوری', 'type': ['permanent', 'credit'], 'operator': 'ایرانسل'}\n```\n\n### bill\nWith `bill_id` and `payment_id` (or just `barcode`), you can get detail of a `bill`.\n\n```python\nfrom persian_tools import bill\n\nbill.get_detail(bill_id=7748317800142, payment_id=1770160)\n# result\n# {'amount': 1700,\n#  'barcode': '77483178001420001770160',\n#  'bill_id': 7748317800142,\n#  'is_valid': True,\n#  'is_valid_bill_id': True,\n#  'is_valid_payment_id': True,\n#  'payment_id': 1770160,\n#  'type': 'تلفن ثابت'}\n\nbill.get_detail(barcode='77483178001420001770160')\n# same result\n\n# default currency is set to Toman, but can change like as below\nbill.get_detail(barcode='77483178001420001770160', currency=bill.CURRENCY_RIAL)\n# result\n# {'amount': 17000,\n#  ...\n```\n\n### plate\nGet information(province, category, type) about vehicles plate.\n\n```python\nfrom persian_tools import plate\n\nplate.get_info('12D45147')\n# result\n# {'category': 'دیپلمات',\n#   'province': 'مرکزی',\n#   'template': '12D451ایران47',\n#   'type': 'Car'}\n\nplate.get_info('12345678')\n# result\n# {'category': None,\n#  'province': 'مرکز تهران',\n#  'template': '123-45678',\n#  'type': 'Motorcycle'}\n\nplate.is_valid('12D45147') # True\nplate.is_valid('12345678') # True\nplate.is_valid('1234567') # False\nplate.is_valid('1204567') # False\n```\n\nNote: Plates that have farsi digits in them(like: الف، ب، ص) will be returned in this template:\n\n`{first_two_digits}{plate_character}{next_three_digits}ایران{province_code}`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersian-tools%2Fpy-persian-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpersian-tools%2Fpy-persian-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpersian-tools%2Fpy-persian-tools/lists"}