bdkit 0.1.0__py3-none-any.whl

bdkit/__init__.py

@@ -0,0 +1,27 @@
+"""Everyday Bangladesh utilities: taka in words, mobile numbers, Bangla digits.
+
+>>> from bdkit import taka_in_words, normalize_mobile
+>>> taka_in_words(1500)
+'One Thousand Five Hundred Taka Only'
+>>> normalize_mobile("01712-345678")
+'+8801712345678'
+"""
+from .digits import format_lakh, to_bangla_digits, to_english_digits
+from .phone import OPERATORS, MobileNumber, is_valid_mobile, mobile_operator, normalize_mobile, parse_mobile
+from .words import number_to_words, taka_in_words
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OPERATORS",
+    "MobileNumber",
+    "format_lakh",
+    "is_valid_mobile",
+    "mobile_operator",
+    "normalize_mobile",
+    "number_to_words",
+    "parse_mobile",
+    "taka_in_words",
+    "to_bangla_digits",
+    "to_english_digits",
+]

bdkit/cli.py

@@ -0,0 +1,76 @@
+"""``bdkit`` command line.
+
+    bdkit words 125050.50          # One Lakh Twenty-Five Thousand Fifty Taka and Fifty Paisa Only
+    bdkit words 12500 --bn         # বারো হাজার পাঁচ শত টাকা মাত্র
+    bdkit phone "+880 1712-345678" # +8801712345678  Grameenphone
+    bdkit lakh 12345678            # 1,23,45,678
+    bdkit bn 2026                  # ২০২৬
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .digits import format_lakh, to_bangla_digits, to_english_digits
+from .phone import parse_mobile
+from .words import taka_in_words
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bdkit", description="Everyday Bangladesh utilities.",
+                                     formatter_class=argparse.RawDescriptionHelpFormatter,
+                                     epilog=__doc__.split("\n", 2)[2])
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    words = sub.add_parser("words", help="taka amount in words")
+    words.add_argument("amount")
+    words.add_argument("--bn", action="store_true", help="in Bangla")
+    words.add_argument("--no-only", action="store_true", help='leave out "Only" / "মাত্র"')
+
+    phone = sub.add_parser("phone", help="validate a mobile number and show its operator")
+    phone.add_argument("number", nargs="+")
+
+    lakh = sub.add_parser("lakh", help="format a number with lakh/crore commas")
+    lakh.add_argument("amount")
+    lakh.add_argument("-d", "--decimals", type=int, default=0)
+    lakh.add_argument("--bn", action="store_true", help="use Bangla digits")
+
+    bn = sub.add_parser("bn", help="convert digits to Bangla")
+    bn.add_argument("text", nargs="+")
+    en = sub.add_parser("en", help="convert Bangla digits to English")
+    en.add_argument("text", nargs="+")
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "words":
+            print(taka_in_words(args.amount, lang="bn" if args.bn else "en", only=not args.no_only))
+        elif args.command == "phone":
+            status = 0
+            for raw in args.number:
+                parsed = parse_mobile(raw)
+                if parsed:
+                    print(f"{parsed.e164}  {parsed.operator}")
+                else:
+                    print(f"{raw}  invalid", file=sys.stderr)
+                    status = 1
+            return status
+        elif args.command == "lakh":
+            print(format_lakh(args.amount, decimals=args.decimals, bangla=args.bn))
+        elif args.command == "bn":
+            print(to_bangla_digits(" ".join(args.text)))
+        elif args.command == "en":
+            print(to_english_digits(" ".join(args.text)))
+    except (ValueError, ArithmeticError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bdkit/digits.py

@@ -0,0 +1,44 @@
+"""Bangla ↔ English digits and lakh-style number formatting."""
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Union
+
+_EN = "0123456789"
+_BN = "০১২৩৪৫৬৭৮৯"
+_TO_BN = str.maketrans(_EN, _BN)
+_TO_EN = str.maketrans(_BN, _EN)
+
+
+def to_bangla_digits(value: object) -> str:
+    """``'2026-11-15' -> '২০২৬-১১-১৫'``"""
+    return str(value).translate(_TO_BN)
+
+
+def to_english_digits(value: object) -> str:
+    """``'০১৭১২' -> '01712'``"""
+    return str(value).translate(_TO_EN)
+
+
+def format_lakh(amount: Union[int, float, Decimal, str], decimals: int = 0, bangla: bool = False) -> str:
+    """Group digits the South Asian way: ``12345678 -> '1,23,45,678'``.
+
+    >>> format_lakh(12345678.5, decimals=2)
+    '1,23,45,678.50'
+    >>> format_lakh(150000, bangla=True)
+    '১,৫০,০০০'
+    """
+    value = Decimal(to_english_digits(str(amount)).replace(",", ""))
+    sign = "-" if value < 0 else ""
+    text = f"{abs(value):.{decimals}f}"
+    whole, _, frac = text.partition(".")
+    if len(whole) > 3:
+        head, tail = whole[:-3], whole[-3:]
+        groups = []
+        while len(head) > 2:
+            groups.insert(0, head[-2:])
+            head = head[:-2]
+        groups.insert(0, head)
+        whole = ",".join(groups + [tail])
+    result = sign + whole + (f".{frac}" if frac else "")
+    return to_bangla_digits(result) if bangla else result

bdkit/phone.py

@@ -0,0 +1,86 @@
+"""Bangladeshi mobile numbers: validate, normalise and detect the operator."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .digits import to_english_digits
+
+OPERATORS = {
+    "013": "Grameenphone",
+    "017": "Grameenphone",
+    "014": "Banglalink",
+    "019": "Banglalink",
+    "016": "Robi",  # formerly Airtel, merged into Robi
+    "018": "Robi",
+    "015": "Teletalk",
+}
+
+_SEPARATORS = re.compile(r"[\s\-().]")
+# Optional country code (+88 / 0088 / 88), optional trunk 0, then 1 + operator digit + 8 digits.
+_PATTERN = re.compile(r"^(?:(?:\+|00)?88)?0?(1[3-9]\d{8})$")
+
+
+@dataclass(frozen=True)
+class MobileNumber:
+    """A valid Bangladeshi mobile number."""
+
+    local: str  # 01712345678
+
+    @property
+    def e164(self) -> str:
+        """International format: ``+8801712345678``."""
+        return "+88" + self.local
+
+    @property
+    def prefix(self) -> str:
+        return self.local[:3]
+
+    @property
+    def operator(self) -> str:
+        return OPERATORS[self.prefix]
+
+    def formatted(self) -> str:
+        """Readable local format: ``01712-345678``."""
+        return f"{self.local[:5]}-{self.local[5:]}"
+
+    def __str__(self) -> str:
+        return self.e164
+
+
+def parse_mobile(number: str) -> Optional[MobileNumber]:
+    """Parse a mobile number written in almost any common way.
+
+    Accepts ``01712345678``, ``+880 1712-345678``, ``8801712345678``,
+    ``008801712345678`` and Bangla digits. Returns ``None`` if invalid.
+
+    >>> parse_mobile("+880 1712-345678").operator
+    'Grameenphone'
+    >>> parse_mobile("০১৮১২৩৪৫৬৭৮").e164
+    '+8801812345678'
+    >>> parse_mobile("0123") is None
+    True
+    """
+    cleaned = _SEPARATORS.sub("", to_english_digits(str(number)))
+    match = _PATTERN.match(cleaned)
+    return MobileNumber("0" + match.group(1)) if match else None
+
+
+def is_valid_mobile(number: str) -> bool:
+    """``True`` if ``number`` is a valid Bangladeshi mobile number."""
+    return parse_mobile(number) is not None
+
+
+def normalize_mobile(number: str) -> str:
+    """Return the number as ``+8801XXXXXXXXX`` or raise ``ValueError``."""
+    parsed = parse_mobile(number)
+    if parsed is None:
+        raise ValueError(f"Not a valid Bangladeshi mobile number: {number!r}")
+    return parsed.e164
+
+
+def mobile_operator(number: str) -> Optional[str]:
+    """Operator name for a number (``'Grameenphone'``, ``'Robi'``...), or ``None`` if invalid."""
+    parsed = parse_mobile(number)
+    return parsed.operator if parsed else None

bdkit/words.py

@@ -0,0 +1,123 @@
+"""Numbers and taka amounts in words, using the lakh/crore system, in English or Bangla."""
+from __future__ import annotations
+
+from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
+from typing import List, Tuple, Union
+
+Number = Union[int, float, str, Decimal]
+
+_EN_ONES = (
+    "Zero One Two Three Four Five Six Seven Eight Nine Ten Eleven Twelve Thirteen Fourteen "
+    "Fifteen Sixteen Seventeen Eighteen Nineteen"
+).split()
+_EN_TENS = "_ _ Twenty Thirty Forty Fifty Sixty Seventy Eighty Ninety".split()
+
+# Bangla number words 0-99 are irregular, so they are listed in full.
+_BN_0_99 = (
+    "শূন্য এক দুই তিন চার পাঁচ ছয় সাত আট নয় "
+    "দশ এগারো বারো তেরো চৌদ্দ পনেরো ষোলো সতেরো আঠারো উনিশ "
+    "বিশ একুশ বাইশ তেইশ চব্বিশ পঁচিশ ছাব্বিশ সাতাশ আটাশ ঊনত্রিশ "
+    "ত্রিশ একত্রিশ বত্রিশ তেত্রিশ চৌত্রিশ পঁয়ত্রিশ ছত্রিশ সাঁইত্রিশ আটত্রিশ ঊনচল্লিশ "
+    "চল্লিশ একচল্লিশ বিয়াল্লিশ তেতাল্লিশ চুয়াল্লিশ পঁয়তাল্লিশ ছেচল্লিশ সাতচল্লিশ আটচল্লিশ ঊনপঞ্চাশ "
+    "পঞ্চাশ একান্ন বায়ান্ন তিপ্পান্ন চুয়ান্ন পঞ্চান্ন ছাপ্পান্ন সাতান্ন আটান্ন ঊনষাট "
+    "ষাট একষট্টি বাষট্টি তেষট্টি চৌষট্টি পঁয়ষট্টি ছেষট্টি সাতষট্টি আটষট্টি ঊনসত্তর "
+    "সত্তর একাত্তর বাহাত্তর তিয়াত্তর চুয়াত্তর পঁচাত্তর ছিয়াত্তর সাতাত্তর আটাত্তর ঊনআশি "
+    "আশি একাশি বিরাশি তিরাশি চুরাশি পঁচাশি ছিয়াশি সাতাশি আটাশি ঊননব্বই "
+    "নব্বই একানব্বই বিরানব্বই তিরানব্বই চুরানব্বই পঁচানব্বই ছিয়ানব্বই সাতানব্বই আটানব্বই নিরানব্বই"
+).split()
+assert len(_BN_0_99) == 100
+
+# (value, english, bangla) from largest to smallest; crore repeats for bigger numbers.
+_SCALES: Tuple[Tuple[int, str, str], ...] = (
+    (10_000_000, "Crore", "কোটি"),
+    (100_000, "Lakh", "লক্ষ"),
+    (1_000, "Thousand", "হাজার"),
+    (100, "Hundred", "শত"),
+)
+
+
+def _en_below_100(n: int) -> str:
+    if n < 20:
+        return _EN_ONES[n]
+    tens, ones = divmod(n, 10)
+    return _EN_TENS[tens] + (f"-{_EN_ONES[ones]}" if ones else "")
+
+
+def _words(n: int, lang: str) -> List[str]:
+    """Words for a non-negative integer, lakh/crore style."""
+    small = _en_below_100 if lang == "en" else (lambda k: _BN_0_99[k])
+    if n < 100:
+        return [small(n)]
+    parts: List[str] = []
+    for value, en, bn in _SCALES:
+        if n >= value:
+            count, n = divmod(n, value)
+            # Above 99 crore, the crore count itself is spelled out ("One Hundred Crore").
+            parts += _words(count, lang) if count >= 100 else [small(count)]
+            parts.append(en if lang == "en" else bn)
+    if n:
+        parts.append(small(n))
+    return parts
+
+
+def _check_lang(lang: str) -> str:
+    lang = lang.lower()
+    if lang not in ("en", "bn"):
+        raise ValueError("lang must be 'en' or 'bn'")
+    return lang
+
+
+def number_to_words(number: int, lang: str = "en") -> str:
+    """Spell out a whole number using lakh and crore.
+
+    >>> number_to_words(1_25_000)
+    'One Lakh Twenty-Five Thousand'
+    >>> number_to_words(1_25_000, lang="bn")
+    'এক লক্ষ পঁচিশ হাজার'
+    """
+    lang = _check_lang(lang)
+    if isinstance(number, bool) or int(number) != number:
+        raise ValueError("number_to_words needs a whole number; use taka_in_words for money")
+    n = int(number)
+    prefix = ("Minus " if lang == "en" else "ঋণাত্মক ") if n < 0 else ""
+    return prefix + " ".join(_words(abs(n), lang))
+
+
+def _to_decimal(amount: Number) -> Decimal:
+    try:
+        value = Decimal(str(amount).replace(",", "").replace("৳", "").strip())
+    except InvalidOperation:
+        raise ValueError(f"Not a valid amount: {amount!r}") from None
+    if not value.is_finite():
+        raise ValueError(f"Not a valid amount: {amount!r}")
+    return value.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+
+def taka_in_words(amount: Number, lang: str = "en", only: bool = True) -> str:
+    """Write a taka amount in words, as on invoices and cheques.
+
+    Paisa (two decimal places) are included when present. Pass ``only=False``
+    to drop the trailing "Only" / "মাত্র".
+
+    >>> taka_in_words(125050.50)
+    'One Lakh Twenty-Five Thousand Fifty Taka and Fifty Paisa Only'
+    >>> taka_in_words("12,500", lang="bn")
+    'বারো হাজার পাঁচ শত টাকা মাত্র'
+    """
+    lang = _check_lang(lang)
+    value = _to_decimal(amount)
+    negative = value < 0
+    taka, paisa = divmod(int(abs(value) * 100), 100)
+
+    if lang == "en":
+        text = f"{number_to_words(taka)} Taka"
+        if paisa:
+            text += f" and {number_to_words(paisa)} Paisa"
+        text += " Only" if only else ""
+        return ("Minus " + text) if negative else text
+
+    text = f"{number_to_words(taka, 'bn')} টাকা"
+    if paisa:
+        text += f" {number_to_words(paisa, 'bn')} পয়সা"
+    text += " মাত্র" if only else ""
+    return ("ঋণাত্মক " + text) if negative else text

bdkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: bdkit
+Version: 0.1.0
+Summary: Everyday Bangladesh utilities: taka in words (English/Bangla, lakh/crore), mobile number validation with operator detection, Bangla digits.
+Project-URL: Homepage, https://github.com/sarif-mia/bdkit
+Project-URL: Source, https://github.com/sarif-mia/bdkit
+Project-URL: Tracker, https://github.com/sarif-mia/bdkit/issues
+Author: Sarif Mia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: amount-in-words,bangla,bangladesh,bengali,crore,grameenphone,lakh,phone,taka
+Classifier: Natural Language :: Bengali
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# bdkit
+
+Everyday utilities for Bangladeshi apps: write taka amounts in words for invoices and cheques (English or Bangla, lakh/crore), validate mobile numbers and detect the operator, and convert between Bangla and English digits.
+
+No dependencies. Python 3.9+.
+
+```sh
+pip install bdkit
+```
+
+## Taka in words
+
+```python
+from bdkit import taka_in_words, number_to_words
+
+taka_in_words(125050.50)
+# 'One Lakh Twenty-Five Thousand Fifty Taka and Fifty Paisa Only'
+
+taka_in_words("12,500", lang="bn")
+# 'বারো হাজার পাঁচ শত টাকা মাত্র'
+
+taka_in_words(1000, only=False)
+# 'One Thousand Taka'
+
+number_to_words(52_71_036, lang="bn")
+# 'বায়ান্ন লক্ষ একাত্তর হাজার ছত্রিশ'
+```
+
+Amounts can be numbers, `Decimal`s or strings with commas or `৳`. Paisa are rounded half up to two decimal places.
+
+## Mobile numbers
+
+```python
+from bdkit import parse_mobile, normalize_mobile, mobile_operator, is_valid_mobile
+
+normalize_mobile("01712-345678")      # '+8801712345678'
+mobile_operator("+880 1912 345678")   # 'Banglalink'
+is_valid_mobile("০১৮১২৩৪৫৬৭৮")        # True (Bangla digits work)
+
+m = parse_mobile("008801512345678")
+m.local, m.e164, m.operator, m.formatted()
+# ('01512345678', '+8801512345678', 'Teletalk', '01512-345678')
+```
+
+Accepted forms are `017…`, `+880 17…`, `+88 017…`, `88017…` and `0088017…`, with or without spaces, dashes or brackets.
+
+| Prefix | Operator |
+| --- | --- |
+| 013, 017 | Grameenphone |
+| 014, 019 | Banglalink |
+| 016, 018 | Robi |
+| 015 | Teletalk |
+
+## Digits and lakh formatting
+
+```python
+from bdkit import to_bangla_digits, to_english_digits, format_lakh
+
+to_bangla_digits("2026-11-15")         # '২০২৬-১১-১৫'
+to_english_digits("৳১,২৫,০০০")         # '৳1,25,000'
+format_lakh(12345678)                  # '1,23,45,678'
+format_lakh(1234567.5, decimals=2)     # '12,34,567.50'
+format_lakh(150000, bangla=True)       # '১,৫০,০০০'
+```
+
+## Command line
+
+```console
+$ bdkit words 125050.50
+One Lakh Twenty-Five Thousand Fifty Taka and Fifty Paisa Only
+$ bdkit words 12500 --bn
+বারো হাজার পাঁচ শত টাকা মাত্র
+$ bdkit phone "+880 1712-345678" 01812345678
++8801712345678  Grameenphone
++8801812345678  Robi
+$ bdkit lakh 12345678
+1,23,45,678
+$ bdkit bn 2026
+২০২৬
+```
+
+## Related
+
+- [bd-income-tax](https://pypi.org/project/bd-income-tax/): Bangladesh income tax calculator
+- [bangladesh-mcp](https://pypi.org/project/bangladesh-mcp/): these tools for AI assistants (MCP)
+
+## License
+
+MIT

bdkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bdkit/__init__.py,sha256=J9BaTfF-14VHaCDgeXjxWMjX9O3d8RCYj0NJ5oCBiL0,760
+bdkit/cli.py,sha256=vTMODd9tb22Nonp-CREKr6iVOskK6YcCOMtdsxwSULg,3120
+bdkit/digits.py,sha256=Qz177DAClKyUd8-Iy-ZOx9NnvBbBMoUA5vDYcVrakQc,1436
+bdkit/phone.py,sha256=LpS-r_uBnbczVgupnRkvzY_diQ6--8Hy-ekEHC9-M-A,2560
+bdkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bdkit/words.py,sha256=aBy9HcrxlpmdFmm9N_ryY3yA4-pgCTPOEobGJ8a9rEU,6156
+bdkit-0.1.0.dist-info/METADATA,sha256=HhCa1m0H0RgVIobvbfuhp2I0MMLLt4ELv6DIjVHlL9Y,3568
+bdkit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+bdkit-0.1.0.dist-info/entry_points.txt,sha256=qGzJ_IC2kG6HI2RLOhgAXa819r_3Q2mf4LH44HZsbgU,41
+bdkit-0.1.0.dist-info/licenses/LICENSE,sha256=vOTqrVxUhsF2lbDM6B4om77vgEd8hlC_kIHmtMKa4R8,1066
+bdkit-0.1.0.dist-info/RECORD,,

bdkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bdkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bdkit = bdkit.cli:main

bdkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarif Mia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.