bharatutils 0.1.0__py3-none-any.whl

bharatutils/__init__.py

@@ -0,0 +1,9 @@
+"""bharatutils — Python utilities for Indian developers."""
+
+   __version__ = "0.1.0"
+
+   from .number_format import to_lakh, to_crore, format_inr
+   from .gst import validate_gstin, validate_gstin_strict, parse_gstin
+   from .pan import validate_pan, parse_pan
+   from .address import parse_address, extract_pincode, pincode_to_state
+   from .festivals import get_festivals, next_festival, days_until, is_festival

bharatutils/address.py

@@ -0,0 +1,78 @@
+
+import re
+
+PINCODE_PATTERN = re.compile(r"\b[1-9][0-9]{5}\b")
+
+PINCODE_PREFIX_TO_STATE = {
+    "11": "Delhi",
+    "12": "Haryana", "13": "Haryana",
+    "14": "Punjab", "15": "Punjab",
+    "16": "Chandigarh",
+    "17": "Himachal Pradesh",
+    "18": "Jammu & Kashmir", "19": "Jammu & Kashmir",
+    "20": "Uttar Pradesh", "21": "Uttar Pradesh", "22": "Uttar Pradesh",
+    "23": "Uttar Pradesh", "24": "Uttar Pradesh", "25": "Uttar Pradesh",
+    "26": "Uttar Pradesh", "27": "Uttar Pradesh", "28": "Uttar Pradesh",
+    "30": "Rajasthan", "31": "Rajasthan", "32": "Rajasthan", "33": "Rajasthan", "34": "Rajasthan",
+    "36": "Gujarat", "37": "Gujarat", "38": "Gujarat", "39": "Gujarat",
+    "40": "Maharashtra", "41": "Maharashtra", "42": "Maharashtra",
+    "43": "Maharashtra", "44": "Maharashtra",
+    "45": "Madhya Pradesh", "46": "Madhya Pradesh", "47": "Madhya Pradesh", "48": "Madhya Pradesh",
+    "49": "Chhattisgarh",
+    "50": "Telangana",
+    "51": "Andhra Pradesh", "52": "Andhra Pradesh", "53": "Andhra Pradesh",
+    "56": "Karnataka", "57": "Karnataka", "58": "Karnataka", "59": "Karnataka",
+    "60": "Tamil Nadu", "61": "Tamil Nadu", "62": "Tamil Nadu", "63": "Tamil Nadu", "64": "Tamil Nadu",
+    "67": "Kerala", "68": "Kerala", "69": "Kerala",
+    "70": "West Bengal", "71": "West Bengal", "72": "West Bengal", "73": "West Bengal", "74": "West Bengal",
+    "75": "Odisha", "76": "Odisha", "77": "Odisha",
+    "78": "Assam",
+    "79": "North East",
+    "80": "Bihar", "81": "Bihar", "82": "Bihar", "83": "Bihar", "84": "Bihar", "85": "Bihar",
+    "90": "Army Postal Service", "91": "Army Postal Service", "92": "Army Postal Service",
+    "99": "Army Postal Service",
+}
+
+KNOWN_CITIES = [
+    "Mumbai", "Delhi", "Bangalore", "Bengaluru", "Hyderabad", "Chennai",
+    "Kolkata", "Pune", "Ahmedabad", "Jaipur", "Surat", "Lucknow",
+    "Kanpur", "Nagpur", "Indore", "Bhopal", "Patna", "Vadodara",
+    "Ludhiana", "Agra", "Nashik", "Varanasi", "Amritsar", "Noida",
+    "Gurgaon", "Gurugram", "Chandigarh", "Coimbatore", "Kochi", "Goa",
+    "Visakhapatnam", "Thane", "Guwahati", "Bhubaneswar", "Mysore", "Mysuru",
+]
+
+
+def extract_pincode(address):
+    """Find the pincode in a messy address string. None if not found."""
+    if address is None or not isinstance(address, str):
+        return None
+    cleaned = re.sub(r"(\b[1-9][0-9]{2})\s+([0-9]{3}\b)", r"\1\2", address)
+    match = PINCODE_PATTERN.search(cleaned)
+    return match.group() if match else None
+
+
+def pincode_to_state(pincode):
+    """Get the state from a pincode. None if unknown."""
+    if pincode is None:
+        return None
+    pincode = str(pincode).strip()
+    if not re.match(r"^[1-9][0-9]{5}$", pincode):
+        return None
+    return PINCODE_PREFIX_TO_STATE.get(pincode[:2])
+
+
+def parse_address(address):
+    """Parse a messy Indian address. Always returns a dict."""
+    result = {"raw": address, "pincode": None, "state": None, "city": None}
+    if address is None or not isinstance(address, str):
+        return result
+    result["pincode"] = extract_pincode(address)
+    if result["pincode"]:
+        result["state"] = pincode_to_state(result["pincode"])
+    address_lower = address.lower()
+    for city in KNOWN_CITIES:
+        if re.search(r"\b" + city.lower() + r"\b", address_lower):
+            result["city"] = city
+            break
+    return result

bharatutils/festivals.py

@@ -0,0 +1,74 @@
+
+from datetime import date
+
+FIXED_FESTIVALS = {
+    "New Year":          (1, 1),
+    "Republic Day":      (1, 26),
+    "Independence Day":  (8, 15),
+    "Gandhi Jayanti":    (10, 2),
+    "Christmas":         (12, 25),
+}
+
+# Verified against official Government of India holiday lists
+MOVABLE_FESTIVALS = {
+    2026: {
+        "Makar Sankranti":    (1, 14),
+        "Holi":               (3, 4),
+        "Eid ul-Fitr":        (3, 21),
+        "Ram Navami":         (3, 26),
+        "Mahavir Jayanti":    (3, 31),
+        "Good Friday":        (4, 3),
+        "Eid ul-Adha":        (5, 27),
+        "Muharram":           (6, 26),
+        "Milad-un-Nabi":      (8, 26),
+        "Janmashtami":        (9, 4),
+        "Ganesh Chaturthi":   (9, 14),
+        "Dussehra":           (10, 20),
+        "Diwali":             (11, 8),
+        "Guru Nanak Jayanti": (11, 24),
+    },
+}
+
+
+def get_festivals(year):
+    """All festivals for a year, sorted by date."""
+    festivals = []
+    for name, (m, d) in FIXED_FESTIVALS.items():
+        festivals.append({"name": name, "date": date(year, m, d), "type": "fixed"})
+    if year in MOVABLE_FESTIVALS:
+        for name, (m, d) in MOVABLE_FESTIVALS[year].items():
+            festivals.append({"name": name, "date": date(year, m, d), "type": "movable"})
+    festivals.sort(key=lambda f: f["date"])
+    return festivals
+
+
+def next_festival(from_date=None):
+    """The next upcoming festival from a given date (default: today)."""
+    if from_date is None:
+        from_date = date.today()
+    for year in [from_date.year, from_date.year + 1]:
+        for f in get_festivals(year):
+            if f["date"] >= from_date:
+                return f
+    return None
+
+
+def days_until(festival_name, from_date=None):
+    """Days remaining until a festival. None if not found."""
+    if from_date is None:
+        from_date = date.today()
+    for year in [from_date.year, from_date.year + 1]:
+        for f in get_festivals(year):
+            if f["name"].lower() == festival_name.lower() and f["date"] >= from_date:
+                return (f["date"] - from_date).days
+    return None
+
+
+def is_festival(check_date=None):
+    """Is this date a festival? Returns the festival name or None."""
+    if check_date is None:
+        check_date = date.today()
+    for f in get_festivals(check_date.year):
+        if f["date"] == check_date:
+            return f["name"]
+    return None

bharatutils/gst.py

@@ -0,0 +1,71 @@
+
+import re
+
+STATE_CODES = {
+    "01": "Jammu & Kashmir",  "02": "Himachal Pradesh",
+    "03": "Punjab",           "04": "Chandigarh",
+    "05": "Uttarakhand",      "06": "Haryana",
+    "07": "Delhi",            "08": "Rajasthan",
+    "09": "Uttar Pradesh",    "10": "Bihar",
+    "11": "Sikkim",           "12": "Arunachal Pradesh",
+    "13": "Nagaland",         "14": "Manipur",
+    "15": "Mizoram",          "16": "Tripura",
+    "17": "Meghalaya",        "18": "Assam",
+    "19": "West Bengal",      "20": "Jharkhand",
+    "21": "Odisha",           "22": "Chhattisgarh",
+    "23": "Madhya Pradesh",   "24": "Gujarat",
+    "25": "Daman & Diu",      "26": "Dadra & Nagar Haveli",
+    "27": "Maharashtra",      "28": "Andhra Pradesh",
+    "29": "Karnataka",        "30": "Goa",
+    "31": "Lakshadweep",      "32": "Kerala",
+    "33": "Tamil Nadu",       "34": "Puducherry",
+    "35": "Andaman & Nicobar","36": "Telangana",
+    "37": "Andhra Pradesh (New)",
+}
+
+GSTIN_PATTERN = re.compile(r"^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$")
+
+
+def validate_gstin(gstin):
+    """Check if a GSTIN has valid format and a real state code."""
+    if gstin is None or not isinstance(gstin, str):
+        return False
+    gstin = gstin.strip().upper()
+    if len(gstin) != 15 or not GSTIN_PATTERN.match(gstin):
+        return False
+    return gstin[:2] in STATE_CODES
+
+
+def parse_gstin(gstin):
+    """Break a GSTIN into state, PAN, entity number. None if invalid."""
+    if not validate_gstin(gstin):
+        return None
+    gstin = gstin.strip().upper()
+    return {
+        "gstin": gstin,
+        "state_code": gstin[:2],
+        "state": STATE_CODES[gstin[:2]],
+        "pan": gstin[2:12],
+        "entity_number": gstin[12],
+        "check_digit": gstin[14],
+    }
+
+
+def gstin_check_digit(gstin_first_14):
+    """Official mod-36 checksum for GSTIN."""
+    chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    total = 0
+    for i, char in enumerate(gstin_first_14):
+        value = chars.index(char)
+        factor = 2 if i % 2 != 0 else 1
+        product = value * factor
+        total += product // 36 + product % 36
+    return chars[(36 - total % 36) % 36]
+
+
+def validate_gstin_strict(gstin):
+    """Full validation: format + state + checksum."""
+    if not validate_gstin(gstin):
+        return False
+    gstin = gstin.strip().upper()
+    return gstin_check_digit(gstin[:14]) == gstin[14]

bharatutils/number_format.py

@@ -0,0 +1,38 @@
+
+def to_lakh(number):
+    """Convert a number to lakhs. Handles strings, negatives, None, NaN."""
+    if number is None or (isinstance(number, float) and number != number):
+        return None
+    if isinstance(number, str):
+        number = float(number.replace(",", "").replace("₹", "").strip())
+    return round(number / 100_000, 2)
+
+
+def to_crore(number):
+    """Convert a number to crores. Handles strings, negatives, None, NaN."""
+    if number is None or (isinstance(number, float) and number != number):
+        return None
+    if isinstance(number, str):
+        number = float(number.replace(",", "").replace("₹", "").strip())
+    return round(number / 10_000_000, 2)
+
+
+def format_inr(number, symbol=True):
+    """
+    Format a number in Indian style (lakh/crore).
+    symbol=False gives you 15.0 L without the rupee sign.
+    """
+    if number is None or (isinstance(number, float) and number != number):
+        return "N/A"
+    if isinstance(number, str):
+        number = float(number.replace(",", "").replace("₹", "").strip())
+    prefix = "₹" if symbol else ""
+    negative = number < 0
+    number = abs(number)
+    if number >= 10_000_000:
+        result = f"{prefix}{to_crore(number)} Cr"
+    elif number >= 100_000:
+        result = f"{prefix}{to_lakh(number)} L"
+    else:
+        result = f"{prefix}{number:,.0f}"
+    return f"-{result}" if negative else result

bharatutils/pan.py

@@ -0,0 +1,40 @@
+
+import re
+
+PAN_PATTERN = re.compile(r"^[A-Z]{5}[0-9]{4}[A-Z]{1}$")
+
+HOLDER_TYPES = {
+    "P": "Individual",
+    "C": "Company",
+    "H": "Hindu Undivided Family",
+    "F": "Firm / Partnership",
+    "T": "Trust",
+    "G": "Government",
+    "A": "Association of Persons",
+    "B": "Body of Individuals",
+    "L": "Local Authority",
+    "J": "Artificial Juridical Person",
+}
+
+
+def validate_pan(pan):
+    """Check if a PAN is valid. Returns True or False."""
+    if pan is None or not isinstance(pan, str):
+        return False
+    pan = pan.strip().upper()
+    if len(pan) != 10 or not PAN_PATTERN.match(pan):
+        return False
+    return pan[3] in HOLDER_TYPES
+
+
+def parse_pan(pan):
+    """Extract holder type and name initial from a PAN."""
+    if not validate_pan(pan):
+        return None
+    pan = pan.strip().upper()
+    return {
+        "pan": pan,
+        "holder_type": HOLDER_TYPES[pan[3]],
+        "name_initial": pan[4],
+        "is_individual": pan[3] == "P",
+    }

bharatutils-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: bharatutils
+Version: 0.1.0
+Summary: Python utilities for Indian developers — lakh/crore formatting, GST & PAN validation, address parsing, festival calendar
+Author: Ansuman Jaiswal
+License: MIT
+Project-URL: Homepage, https://github.com/iam-ansuman/bharatutils
+Project-URL: Issues, https://github.com/iam-ansuman/bharatutils/issues
+Keywords: india,gst,pan,lakh,crore,inr,pincode,address,festivals,indian
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bharatutils 🇮🇳
+
+Python utilities for Indian developers — because `1,500,000` should display as `₹15 L`.
+
+Lakh/crore formatting · GST & PAN validation · Address parsing · Festival calendar
+
+## Why?
+
+Every Indian developer has written these same utility functions a hundred times:
+
+```python
+# Without bharatutils 😩
+df["salary_display"] = df["salary"].apply(
+    lambda x: f"₹{round(x/100000, 2)} L" if x >= 100000 else f"₹{x:,}"
+)  # ...and it crashes on NaN
+
+# With bharatutils 😎
+from bharatutils import format_inr
+df["salary_display"] = df["salary"].apply(format_inr)   # handles NaN, strings, negatives
+```
+
+## Install
+
+```bash
+pip install bharatutils
+```
+
+## Features
+
+### 💰 Indian number formatting
+```python
+from bharatutils import format_inr, to_lakh, to_crore
+
+format_inr(1500000)     # '₹15.0 L'
+format_inr(50000000)    # '₹5.0 Cr'
+format_inr("15,00,000") # '₹15.0 L'  — handles messy strings
+to_lakh(1500000)        # 15.0
+```
+
+### 🧾 GST validation — with real checksum
+```python
+from bharatutils import validate_gstin_strict, parse_gstin
+
+validate_gstin_strict("27AAAPZ2318J1ZI")  # True — verifies the check digit
+parse_gstin("27AAAPZ2318J1ZI")
+# {'state': 'Maharashtra', 'pan': 'AAAPZ2318J', 'entity_number': '1', ...}
+```
+Catches single-character typos that format-only validators miss.
+
+### 🪪 PAN validation + holder type
+```python
+from bharatutils import parse_pan
+
+parse_pan("AAAPZ2318J")
+# {'holder_type': 'Individual', 'is_individual': True, ...}
+# P=Person, C=Company, T=Trust, G=Government...
+```
+
+### 📍 Indian address parsing
+```python
+from bharatutils import parse_address
+
+parse_address("Flat 302, Nr. SBI ATM, MG Road, Pune - 411001")
+# {'pincode': '411001', 'state': 'Maharashtra', 'city': 'Pune'}
+```
+Handles space-broken pincodes ("700 016"), ignores phone numbers, never crashes.
+
+### 🪔 Festival calendar
+```python
+from bharatutils import next_festival, days_until
+
+next_festival()        # {'name': 'Muharram', 'date': datetime.date(2026, 6, 26)}
+days_until("Diwali")   # 150
+```
+Covers Hindu, Muslim, Christian, Sikh & Jain festivals plus national holidays — verified against official Government of India lists.
+
+## Status
+
+`v0.1.0` — early but tested. Pincode→state mapping is prefix-based (~95% accurate); exact-lookup coming in v0.2.
+
+Found a bug? [Open an issue](../../issues) — responses are fast.
+
+## License
+
+MIT

bharatutils-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bharatutils/__init__.py,sha256=mueOFE44C_eYSamdm9auXuIhPP7JieSwAVBDsMxkCyA,417
+bharatutils/address.py,sha256=uhqo-kGQQT3HW-39YufUy5jvqxfMrBt0AXMACk-ToRk,3343
+bharatutils/festivals.py,sha256=uZXOo2VmoMaSL3MPTv85DBqGX1om19Qt2_jjpLVxNIY,2402
+bharatutils/gst.py,sha256=HS0IvX8YG3nuG1w_8EfyH0tDfEiAMXNG5NoXTcEqKHg,2393
+bharatutils/number_format.py,sha256=o18vAJbLdbTuwbOyALrXtGSYIbSlq1f52Rbb8xRgfM0,1391
+bharatutils/pan.py,sha256=6EJVXAqwOhlGrrf3QWtG9Zl2fmT7hsdQNZ57YauwKoI,980
+bharatutils-0.1.0.dist-info/licenses/LICENSE,sha256=0FgLW7i4VQLgVuuM9SILS92HZCJzTqS6hQG79eHqIzM,1072
+bharatutils-0.1.0.dist-info/METADATA,sha256=Bp9OX64XeFRpuDy_DSTLMo6ODMqXxCtrP8bpahRnEVI,3463
+bharatutils-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bharatutils-0.1.0.dist-info/top_level.txt,sha256=B-7-oVIICxabiTjrEfjn8aQyzBUkzHkTQhW1nQMv2LY,12
+bharatutils-0.1.0.dist-info/RECORD,,

bharatutils-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
+

bharatutils-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ansuman Jaiswal
+
+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.

bharatutils-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bharatutils