siege-utilities 3.4.1

A comprehensive Python utilities package with enhanced auto-discovery

🚀 Siege Utilities

A comprehensive Python utilities package providing 260+ functions across 12 categories for data engineering, analytics, and distributed computing workflows.

🎯 What Makes This Special?

Complete Library Restoration: Fully restored from catastrophic AI-induced failures to professional excellence.

100% Reliability: Every function either works perfectly or provides clear installation guidance - no more broken functions!

Dynamic Function Discovery: Real-time, honest reporting of available functionality - no more hardcoded lies about what works.

Graceful Dependency Handling: Missing dependencies provide helpful installation guidance instead of crashes.

Comprehensive Coverage: 260+ functions across 12 categories, from core utilities to advanced analytics.

Professional Architecture: Proper error handling, logging, and modern Python patterns throughout.

🎆 Major Library Restoration Complete

🚀 NEW: GeoDjango Integration for Census Boundaries 🗺️

NEW: Full GeoDjango integration for Census boundary data storage and spatial queries.

from django.contrib.gis.geos import Point
from siege_utilities.geo.django.models import Tract, County, State

# Find tract containing a point
point = Point(-122.4194, 37.7749, srid=4326)
tract = Tract.objects.containing_point(point).for_year(2020).first()

# Populate boundaries from TIGER/Line
# python manage.py populate_boundaries --year 2020 --type county --state CA

# Query with demographics
from siege_utilities.geo.django.models import DemographicSnapshot
demographics = DemographicSnapshot.objects.filter(
    content_type__model='tract',
    variables__contains={'B19013_001': True}  # Median income
)

Key Features:

• ✅ 8 Boundary Models: State, County, Tract, BlockGroup, Block, Place, ZCTA, CongressionalDistrict
• ✅ Spatial Queries: containing_point(), intersecting(), for_state(), for_year()
• ✅ Demographic Storage: JSON-based variable storage with time series support
• ✅ Boundary Crosswalks: 2010→2020 boundary change tracking
• ✅ Management Commands: CLI for populating boundaries, demographics, and crosswalks
• ✅ DRF GeoJSON Serializers: Ready for REST API integration

🚀 NEW: Google Analytics Reporting with Geographic Integration 📊

NEW: Professional PDF reports from Google Analytics data with geographic visualization.

from siege_utilities.reporting.examples.google_analytics_report_example import (
    generate_sample_ga_data,
    generate_ga_report_pdf
)

# Generate sample data for testing
ga_data = generate_sample_ga_data(start_date, end_date)

# Generate professional PDF report
generate_ga_report_pdf(
    ga_data=ga_data,
    output_path="ga_report.pdf",
    client_name="Demo Company",
    report_title="Website Analytics Report"
)

# Geographic analysis with Census integration
from siege_utilities.reporting.examples.ga_geographic_analysis import (
    geocode_ga_cities,
    aggregate_by_state,
    create_state_choropleth
)

state_df = aggregate_by_state(geocode_ga_cities(ga_city_data))
create_state_choropleth(state_df, 'sessions')

Key Features:

• ✅ KPI Dashboard Cards: Custom ReportLab flowables with period-over-period comparison
• ✅ Sparkline Charts: Compact inline trend visualization
• ✅ Traffic Analysis: Time series, sources breakdown, performance tables
• ✅ Geographic Maps: State choropleths, city heatmaps
• ✅ Census Integration: Demographic joins with traffic data
• ✅ Automated Insights: Algorithm-generated performance analysis

🚀 Hydra + Pydantic Configuration System 🔧

Advanced configuration management with Hydra composition, Pydantic validation, and client-specific overrides.

from siege_utilities.config import HydraConfigManager

# Load configurations with validation and client-specific overrides
with HydraConfigManager() as manager:
    # Load user profile with validation
    user_profile = manager.load_user_profile()
    print(f"User: {user_profile.full_name}")
    
    # Load client-specific branding (inherits defaults + overrides)
    branding = manager.load_branding_config("client_a")
    print(f"Brand color: {branding.primary_color}")
    
    # Load database connections
    db_connections = manager.load_database_connections("client_a")
    
    # Load social media accounts
    social_accounts = manager.load_social_media_accounts("client_a")

# Create validated configurations
from siege_utilities.config import UserProfile, ClientProfile, BrandingConfig

# User profile with comprehensive validation
user = UserProfile(
    username="john_doe",
    email="[e-mail]",
    full_name="John Doe",
    default_output_format="pptx",
    default_dpi=300
)

# Client profile with nested configurations
client = ClientProfile(
    client_id="acme_corp",
    client_name="Acme Corporation", 
    client_code="ACME",
    industry="Technology",
    branding_config=BrandingConfig(
        primary_color="#1f77b4",
        secondary_color="#ff7f0e",
        primary_font="Arial"
    )
)

# Migration from legacy system
from siege_utilities.config import migrate_configurations

# Migrate existing configurations with backup
results = migrate_configurations(dry_run=False)
print(f"Migrated {results['total_migrated']} profiles")

Key Benefits:

• ✅ Type Safety: Full Pydantic validation with detailed error messages
• ✅ Configuration Composition: Hydra's powerful composition and override system
• ✅ Client Customization: Easy client-specific branding and preferences
• ✅ Seamless Migration: Automated migration from legacy systems with backup
• ✅ Production Ready: 100% test coverage with comprehensive validation
• ✅ Hierarchical Resolution: Smart fallback from client-specific to defaults

From Catastrophic Failure to Professional Excellence

This library was completely broken after automated AI modifications. Here's what was restored:

🔥 The Disaster (Before Restoration)

• 87 functions claimed, 24 were broken (None)
• 72.7% reliability - functions failed or didn't exist
• Hardcoded lies about function availability
• Import crashes due to dependency issues
• 415 functions hidden - 83% of codebase inaccessible

✨ The Restoration (Current State)

• 260 functions available (156% increase)
• 100% reliability - every function works or gives guidance
• Dynamic discovery - honest, real-time function reporting
• Graceful dependencies - helpful errors, not crashes
• Professional architecture - proper error handling throughout

Quick Validation:

import siege_utilities as su

# Discover all functionality
info = su.get_package_info()
print(f"Available: {info['total_functions']} functions")
# Result: 260 functions across 12 categories

# Core functions work immediately
su.log_info("Library restored successfully!")
result = su.remove_wrapping_quotes_and_trim('"clean text"')

# Advanced functions provide helpful guidance
try:
    su.create_bivariate_choropleth({}, 'location', 'var1', 'var2')
except ImportError as e:
    print(f"Helpful guidance: {e}")
    # Shows exactly what to install: pip install matplotlib geopandas

📊 Function Categories & Availability

260+ Functions Across 12 Categories

Category	Count	Description	Dependencies	Status
Core	16	Logging, strings, basic utils	None	✅ Always available
Config	54	Database, project, client setup	None	✅ Always available
Files	21	File ops, paths, remote downloads	None	✅ Always available
Distributed	37	Spark utilities, HDFS operations	PySpark	📆 Helpful guidance
Geo	65+	Census data, boundaries, spatial, GeoDjango	pandas, geopandas	📆 Helpful guidance
Analytics	28	Google Analytics, Snowflake APIs	pandas, connectors	📆 Helpful guidance
Reporting	30+	Charts, maps, GA reports, PDF generation	matplotlib, reportlab	📆 Helpful guidance
Testing	15	Environment setup, test runners	None	✅ Always available
Git	9	Branch ops, commit management	None	✅ Always available
Development	9	Architecture analysis, code hygiene	None	✅ Always available
Hygiene	5	Docstring generation, analysis	None	✅ Always available
Data	3	Sample data utilities	pandas	📆 Helpful guidance

Legend:

• ✅ Always available: Works without any external dependencies
• 📆 Helpful guidance: Provides clear installation instructions when dependencies missing

Example Function Discovery:

# See all available functions by category
for category, functions in info['categories'].items():
    print(f"{category}: {len(functions)} functions")
    print(f"  Examples: {functions[:3]}")

🧪 Testing Status

Current Test Results: ✅ All tests passing
Test Coverage: Comprehensive coverage across all major modules including new Census Data Intelligence system
Code Quality: Modern Python patterns with full type safety

Test Categories

• Core Logging: ✅ All tests passing
• File Operations: ✅ All tests passing
• Remote File: ✅ All tests passing
• Paths: ✅ All tests passing
• Distributed Computing: ✅ All tests passing
• Analytics Integration: ✅ All tests passing
• Configuration Management: ✅ All tests passing
• Geospatial Functions: ✅ All tests passing
• Multi-Engine Processing: ✅ All tests passing
• SVG Marker System: ✅ All tests passing
• Database Connections: ✅ All tests passing
• Census Data Intelligence: ✅ All tests passing
• Census API Client: ✅ 102 tests passing
• GEOID Utilities: ✅ 45 tests passing
• GeoDjango Integration: ✅ All tests passing

Running Tests

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_core_logging.py -v

# Run by marker (v3.2.0+)
python -m pytest tests/ -m core          # Core-only tests
python -m pytest tests/ -m geo           # Geo tests
python -m pytest tests/ -m "not requires_gdal"  # Skip GDAL-dependent tests

# Run with coverage
python -m pytest tests/ --cov=siege_utilities --cov-report=html

# Quick smoke test
python -m pytest tests/ --tb=short -q

✨ Key Features

• ⚡ Lazy Imports (v3.2.0): import siege_utilities loads in ~0.02s via PEP 562 __getattr__ — no heavy packages loaded until first use
• 📦 Optional Dependencies (v3.2.0): Core install is 4 packages. Add [geo], [reporting], [analytics], [distributed], or [all] as needed
• 🌐 Mutual Availability: All 260+ functions accessible via from siege_utilities import X — lazy loaded on first access
• 🛡️ Graceful Dependencies: Missing optional packages give clear ImportError messages with install instructions
• 📝 Universal Logging: Comprehensive logging system available everywhere
• 📊 Built-in Diagnostics: Monitor package health and function availability
• 👥 Client Management: Comprehensive client profile management with contact info and design artifacts
• 🔌 Connection Persistence: Notebook, Spark, and database connection management and testing
• 🎨 Modern Python: Full type hints, modern patterns, and comprehensive testing
• 🗺️ Advanced Mapping: 7+ map types with professional reporting capabilities
• 🧠 Census Intelligence: Intelligent Census data selection and relationship mapping
• 📊 Sample Datasets: Built-in synthetic data for testing and development

🚀 Census Data Intelligence System

The new Census Data Intelligence system makes complex Census data human-comprehensible:

Automatic Dataset Selection

• Intelligent Recommendations: Automatically suggests the best Census datasets for your analysis needs
• Analysis Type Recognition: Recognizes demographics, housing, business, transportation, education, health, and poverty analysis
• Geography Level Support: Works with nation, state, county, tract, block group, and more
• Time Sensitivity: Considers how current your data needs to be

Dataset Relationship Mapping

• Survey Type Understanding: Maps relationships between Decennial, ACS, Economic Census, and Population Estimates
• Quality Guidance: Provides reliability levels (High, Medium, Low, Estimated) with explanations
• Pitfall Prevention: Helps avoid common mistakes like comparing incompatible datasets
• Best Practices: Built-in guidance for correct tabulation and visualization

Quick Start

from siege_utilities.geo import quick_census_selection

# Quick selection for business analysis
result = quick_census_selection("business", "county")
print(f"Use {result['recommendations']['primary_recommendation']['dataset']}")

# Get comprehensive analysis approach
from siege_utilities.geo import get_analysis_approach
approach = get_analysis_approach("demographics", "tract", "comprehensive")
print(f"Recommended Approach: {approach['recommended_approach']}")

🚀 Quick Start

# Install with the extras you need
pip install siege-utilities[data,geo]

import siege_utilities  # ~0.02s (lazy loaded, no heavy imports)

# Core functions are always available
siege_utilities.log_info("Package loaded successfully!")

# String utilities (core — no extra deps needed)
clean_text = siege_utilities.remove_wrapping_quotes_and_trim('  "hello"  ')

# Geo functions load on first access (requires [geo] extra)
from siege_utilities.geo import select_census_datasets
recommendations = select_census_datasets("demographics", "tract")
print(f"Use {recommendations['primary_recommendation']['dataset']}")

# Missing extras give helpful errors instead of crashes
try:
    from siege_utilities import ReportGenerator  # requires [reporting]
except ImportError as e:
    print(e)  # "ReportGenerator requires matplotlib. Install with: pip install siege-utilities[reporting]"

# Package diagnostics
info = siege_utilities.get_package_info()
print(f"Available functions: {info['total_functions']}")

📚 Documentation & Resources

📖 Official Documentation

• Sphinx Docs: GitHub Pages
• API Reference: Complete API documentation for all modules
• Installation Guide: Setup and configuration instructions

📝 Wiki Documentation

• Comprehensive Recipes: End-to-end workflows and examples
• Census Data Intelligence Guide: Complete guide to using the new system
• Architecture Documentation: System design and implementation details
• Code Decision Documentation: OOP vs functional choices, design patterns
• Interrelationship Diagrams: Visual representations of system components

🚀 Recipe Collections

• wiki_fresh/: Latest recipes with comprehensive examples
• wiki_recipes/: Curated recipe collections organized by use case
• wiki_debug/: Troubleshooting guides and debugging recipes

🔧 Installation Options

v3.2.0+: Core install is lightweight (4 packages). Add extras for the features you need.

# Core only (pyyaml, requests, tqdm, pydantic) — fast, minimal
pip install siege-utilities

# With geospatial support (geopandas, shapely, pyproj, tobler, etc.)
pip install siege-utilities[geo]

# With data manipulation (pandas, numpy, openpyxl, faker)
pip install siege-utilities[data]

# With reporting/visualization (matplotlib, seaborn, folium, plotly, reportlab)
pip install siege-utilities[reporting]

# With analytics connectors (GA4, Facebook, Snowflake, scipy, scikit-learn)
pip install siege-utilities[analytics]

# With distributed computing (PySpark, Apache Sedona)
pip install siege-utilities[distributed]

# With GeoDjango (Django, DRF, PostGIS)
pip install siege-utilities[geodjango]

# With Hydra configuration framework
pip install siege-utilities[config-extras]

# With web scraping (BeautifulSoup, lxml)
pip install siege-utilities[web]

# With database connectivity (SQLAlchemy, psycopg2)
pip install siege-utilities[database]

# Full installation — everything (identical to pre-3.2.0 behavior)
pip install siege-utilities[all]

# Combine extras as needed
pip install siege-utilities[data,geo,reporting]

# Development installation
git clone https://github.com/siege-analytics/siege_utilities.git
cd siege_utilities
pip install -e ".[all,dev]"

🚀 Modern Package Management with UV

Siege Utilities now supports modern Python package management with UV for faster, more reliable dependency management:

UV Installation (Recommended)

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new UV project
uv init my-siege-project
cd my-siege-project

# Add siege_utilities with all dependencies
uv add --editable ../siege_utilities

# Or install with specific extras
uv add --extra geo ../siege_utilities
uv add --extra distributed ../siege_utilities
uv add --extra all ../siege_utilities

Package Format Generation

The library includes powerful functions for generating modern package configuration files:

from siege_utilities.development.architecture import (
    generate_requirements_txt,
    generate_pyproject_toml,
    generate_poetry_toml,
    generate_uv_toml
)

# Generate requirements.txt from setup.py
generate_requirements_txt("setup.py", "requirements.txt")

# Generate UV/Setuptools compatible pyproject.toml
generate_pyproject_toml("setup.py", "pyproject.toml")

# Generate Poetry compatible pyproject.toml
generate_poetry_toml("setup.py", "pyproject_poetry.toml")

# Generate UV compatible pyproject.toml (same as standard)
generate_uv_toml("setup.py", "pyproject.toml")

Dependency Extras (v3.2.0)

Core install pulls only 4 packages. Add extras for the functionality you need:

Extra	Packages	Use Case
[data]	pandas, numpy, openpyxl, faker	Data manipulation
[geo]	geopandas, shapely, pyproj, fiona, tobler, pysal	Geospatial analysis
[reporting]	matplotlib, seaborn, folium, plotly, reportlab	Visualization & reports
[analytics]	google-analytics-data, scipy, scikit-learn, facebook-business	Analytics connectors
[distributed]	pyspark, apache-sedona	Big data processing
[geodjango]	django, djangorestframework-gis, psycopg2	GeoDjango ORM
[config-extras]	hydra-core, hydra-zen, omegaconf	Configuration framework
[web]	beautifulsoup4, lxml	Web scraping
[database]	sqlalchemy, psycopg2	Database connectivity
[export]	openpyxl, xlsxwriter, psutil, memory-profiler	Data export & profiling
[performance]	duckdb	DuckDB backend
[streamlit]	streamlit, altair, bokeh, pydeck, jupyter	Interactive apps
[dev]	pytest, black, flake8	Development tools
[all]	Everything above	Full install

🏗️ Library Architecture

The library is organized into major functional areas:

🔧 Core Utilities

• Logging System: Modern, thread-safe, configurable logging
• String Utilities: Advanced string manipulation and cleaning

📁 File Operations

• File Hashing: Cryptographic hashing and integrity verification
• File Operations: Modern file manipulation with clean API
• Path Management: Enhanced directory creation and file extraction
• Remote Operations: Advanced URL-based file operations

🚀 Distributed Computing

• Spark Utilities: 503+ functions for big data processing
• HDFS Configuration: Cluster configuration and management
• HDFS Operations: File system operations and data movement

🌍 Geospatial (Enhanced)

• Geocoding: Address processing and coordinate generation
• Spatial Data: Census, Government, and OpenStreetMap data sources
• Spatial Transformations: Format conversion, CRS transformation
• Census Data Intelligence: Intelligent dataset selection and relationship mapping
• Census API Client: Direct ACS/Decennial data fetching with caching
• GEOID Utilities: Construction, parsing, normalization, validation
• GeoDjango Integration: Full Django models for Census boundaries with spatial queries

⚙️ Configuration Management

• Client Management: Client profile creation and project association
• Connection Management: Database, notebook, and Spark connection persistence
• Project Management: Project configuration and directory management

📊 Sample Data & Testing

• Built-in Datasets: Census-based samples with synthetic population data
• Synthetic Generation: Customizable demographics, businesses, and housing
• Development Tools: Realistic data for testing without external dependencies

📊 Analytics Integration

• Google Analytics: GA4/UA data retrieval and client association
• Data Export: Pandas and Spark DataFrame export capabilities
• Batch Processing: Multi-account data retrieval and processing

🛠️ Development & Package Management

• Package Format Generation: Convert setup.py to modern package formats
• Requirements Management: Generate requirements.txt from setup.py
• UV Integration: Full support for UV package manager
• Poetry Support: Generate Poetry-compatible pyproject.toml
• Architecture Analysis: Package structure analysis and documentation
• Function Discovery: Dynamic function discovery and reporting

🗺️ Reporting & Visualization

• Chart Generation: 7+ map types including choropleth, marker, 3D, heatmap, cluster, and flow maps
• Report Generation: Professional PDF reports with TOC, sections, and appendices
• PowerPoint Integration: Automated presentation creation with various slide types
• Google Analytics Reports: Professional PDF reports with KPI cards, sparklines, and geographic analysis
• Geographic Visualization: State choropleths, city heatmaps, Census demographic integration

🧪 Testing & Quality Assurance

This package includes a comprehensive test suite designed to ensure code quality and maintain reliability.

Quick Test Run

# Basic functionality check
python -m pytest tests/ --tb=short -q

# Or with verbose output
python -m pytest tests/ -v

Test Installation

# Install test dependencies
pip install -r test_requirements.txt

# Or install with development extras
pip install -e ".[dev]"

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Add your functions to existing modules or create new ones
4. Run tests: python -m pytest tests/ --tb=short -q
5. Test with: python3 scripts/check_imports.py
6. Commit changes: git commit -am 'Add new feature'
7. Push: git push origin feature-name
8. Submit a Pull Request

The auto-discovery system will automatically find and integrate your new functions!

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built by Siege Analytics
• Inspired by the need for truly seamless Python utilities
• Special thanks to the auto-discovery pattern that makes this possible

---

Siege Utilities: Spatial Intelligence, In Python! 🚀

NEW: Census Data Intelligence System - Making complex Census data human-comprehensible! 🧠