Merge remote-tracking branch 'upstream/main' into feature/analytics-dashboard

Author: adisingh396

README.md

@@ -1,48 +1,122 @@
-# Postal Regex
 
-A community-maintained repository of postal/ZIP code regex patterns for 50+ countries. 
-This package is ideal for **form validation, data cleaning, and big data applications**.
+# Postal Regex 📨
+
+[![PyPI version](https://img.shields.io/pypi/v/postal-regex.svg)](https://pypi.org/project/postal-regex/)
+[![License](https://img.shields.io/pypi/l/postal-regex)](LICENSE)
+[![Build Status](https://github.com/ankitgadling/postal-regex/actions/workflows/ci.yml/badge.svg)](https://github.com/ankitgadling/postal-regex/actions)
+
+---
+
+A community-maintained repository of postal/ZIP code regex patterns for 50+ countries.  
+Ideal for **form validation, data cleaning, and big data applications**.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Big Data Support](#big-data-support)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
 ## Features
 
 - ✅ 50+ countries included, with postal code regex patterns  
-- ✅ Supports lookup by **country code** or **country name**  
-- ✅ Precompiled regex for fast validation in Python  
-- ✅ JSON schema ensures consistent data structure  
-- ✅ Ready for **big data frameworks** like Spark, Dask, or Pandas  
+- ✅ Validate postal codes by **country code** or **country name**
+```python
+from postal_regex.core import validate
+
+validate("IN", "110001")      # True
+validate("India", "110001")   # True
+validate("US", "12345-6789")  # True
+````
+
+* ✅ Normalize country identifiers
+
+```python
+from postal_regex.core import normalize
+
+normalize("United States")  # "US"
+normalize("India")          # "IN"
+```
+
+* ✅ Works with **Pandas and Spark DataFrames**
+
+```python
+import pandas as pd
+from postal_regex.bulk import validate_dataframe
+
+df = pd.DataFrame({"country": ["US", "FR"], "postal_code": ["90210", "75001"]})
+df_validated = validate_dataframe(df, country_col="country", postal_col="postal_code")
+print(df_validated)
+```
+
+* ✅ JSON schema ensures consistent data structure
+* ✅ Precompiled regex for fast Python validation
 
 ---
+
 ## Installation
 
 ```bash
 pip install postal-regex
 ```
 
-## Usage
+For development:
 
 ```bash
-from postal_regex.core import validate, normalize, get_supported_countries
+git clone https://github.com/ankitgadling/postal-regex.git
+cd postal-regex
+pip install -e .
+```
 
-# Validate postal codes
-validate("IN", "110001")          # True
-validate("India", "110001")       # True
-validate("US", "12345-6789")      # True
+---
+
+## Big Data Support
 
-# Normalize country identifiers
-normalize("India")                # "IN"
-normalize("US")                   # "US"
+Validate postal codes in **large datasets** with Spark or Pandas.
 
-# List all supported countries
-get_supported_countries()
-# [{'code': 'IN', 'name': 'India'}, {'code': 'US', 'name': 'United States'}, ...]
+### Spark Example
 
+```python
+from pyspark.sql import SparkSession
+from postal_regex.bulk import validate_spark_dataframe
+
+spark = SparkSession.builder.getOrCreate()
+df = spark.createDataFrame([
+    {"country": "FR", "postal_code": "75001"},
+    {"country": "DE", "postal_code": "10115"}
+])
+df_validated = validate_spark_dataframe(df, country_col="country", postal_col="postal_code")
+df_validated.show()
 ```
+
+### Pandas Example
+
+```python
+import pandas as pd
+from postal_regex.bulk import validate_dataframe
+
+df = pd.DataFrame({
+    "country": ["FR", "DE"],
+    "postal_code": ["75001", "10115"]
+})
+df_validated = validate_dataframe(df, country_col="country", postal_col="postal_code")
+print(df_validated)
+```
+
 ---
 
-## Contributors
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
 
-[![Contributors](https://contrib.rocks/image?repo=ankitgadling/postal-regex)](https://github.com/ankitgadling/postal-regex/graphs/contributors)
+## License
 
----
+MIT License. See [LICENSE](LICENSE) for details.

src/postal_regex/__init__.py

@@ -48,4 +48,5 @@
     "record_validation",
     "show_stats",
     "reset_stats",
+    "get_stats"
 ]

src/postal_regex/analytics.py

@@ -47,50 +47,51 @@ def reset_stats():
     else:
         print("No statistics file found to reset.")
 
+def get_stats() -> dict:
+    """
+    Loads and returns the validation statistics from the stats file.
+    This function only retrieves data and does not print anything.
+    
+    Returns:
+        dict: A dictionary containing the validation stats, or an empty dict if none exist.
+    """
+    if not STATS_FILE.exists():
+        return {}
+    try:
+        with open(STATS_FILE, "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, FileNotFoundError):
+        return {}
+
 def show_stats():
-    """Display the validation statistics dashboard in the console."""
-    stats = _load_stats()
+    """
+    Loads and prints a formatted dashboard of the validation statistics.
+    This function handles all presentation logic.
+    """
+    stats = get_stats()
     if not stats:
-        print("No validation statistics recorded yet.")
+        print("No validation analytics recorded yet.")
         return
 
-    # Prepare data for the table
-    table_data = []
-    for country, counts in stats.items():
-        valid = counts.get("valid", 0)
-        invalid = counts.get("invalid", 0)
+    print("--- Postal Regex Validation Stats ---")
+    
+    sorted_countries = sorted(stats.keys())
+    
+    print(f"{'Country':<10} | {'Valid':<10} | {'Invalid':<10} | {'Total':<10}")
+    print("-" * 50)
+    
+    total_valid = 0
+    total_invalid = 0
+    
+    for country in sorted_countries:
+        valid = stats[country].get("valid", 0)
+        invalid = stats[country].get("invalid", 0)
         total = valid + invalid
-        table_data.append([country, valid, invalid, total])
-
-    # Sort by total validations
-    table_data.sort(key=lambda row: row[3], reverse=True)
-
-    # --- Print Table ---
-    print("\nPostal Code Validation Stats (Local Project)")
-    # A simple formatted table without external dependencies
-    header = ["Country", "Valid", "Invalid", "Total"]
-    col_widths = [len(h) for h in header]
-    for row in table_data:
-        for i, cell in enumerate(row):
-            col_widths[i] = max(col_widths[i], len(str(cell)))
-
-    header_line = " | ".join(h.ljust(w) for h, w in zip(header, col_widths))
-    separator = "-+-".join("-" * w for w in col_widths)
-    print(header_line)
-    print(separator)
-
-    for row in table_data:
-        row_line = " | ".join(str(cell).ljust(w) for cell, w in zip(row, col_widths))
-        print(row_line)
-
-    # --- Print Bar Chart ---
-    print("\nValidation Success Rate")
-    for country, valid, invalid, total in table_data:
-        if total == 0:
-            success_rate = 0
-        else:
-            success_rate = (valid / total) * 100
-        bar_length = 40
-        filled_length = int(bar_length * success_rate / 100)
-        bar = "█" * filled_length + " " * (bar_length - filled_length)
-        print(f"{country.ljust(5)} |{bar}| {success_rate:.0f}% valid")
+        total_valid += valid
+        total_invalid += invalid
+        print(f"{country:<10} | {valid:<10} | {invalid:<10} | {total:<10}")
+        
+    print("-" * 50)
+    grand_total = total_valid + total_invalid
+    print(f"{'TOTAL':<10} | {total_valid:<10} | {total_invalid:<10} | {grand_total:<10}")
+    print("-" * 50)

src/postal_regex/core.py

@@ -73,12 +73,6 @@ def validate(country_identifier: str, postal_code: str, timeout: float = 0.1) ->
         is_valid = bool(entry.regex.fullmatch(postal_code, timeout=timeout))
     except (regex.TimeoutError, ValueError):
         is_valid = False
-    # --- Record the validation attempt ---
-    try:
-        country_code = normalize(country_identifier)
-        analytics.record_validation(country_code, is_valid)
-    except ValueError:
-        pass
 
     return is_valid
 

tests/test_analytics.py

@@ -46,6 +46,25 @@ def test_record_validation_and_load_stats(monkeypatch):
 
     temp_stats_file.unlink()
 
+def test_get_stats(monkeypatch):
+    """
+    Test that get_stats correctly reads and returns data.
+    """
+    temp_stats_file = Path.home() / ".postalregex_stats_temp.json"
+    monkeypatch.setattr(analytics, 'STATS_FILE', temp_stats_file)
+
+    # 1. Test when file doesn't exist
+    if temp_stats_file.exists():
+        temp_stats_file.unlink()
+    assert analytics.get_stats() == {}
+
+    dummy_data = {"US": {"valid": 5, "invalid": 1}}
+    with open(temp_stats_file, "w") as f:
+        json.dump(dummy_data, f)
+    
+    assert analytics.get_stats() == dummy_data
+    
+    temp_stats_file.unlink()
 
 def test_reset_stats(monkeypatch):
     """