Siege Utilities

A thesaurus of space-time composition tools. Every piece exists to serve one question: what happened, where, when, and what does proximity imply?

The library ties events to coordinates in space-time, then extrapolates significances and meanings from placement. Domain packages produce events. Geo locates them. Engines scale them. Reporting presents them.

The canonical composition chain:

address → geocoder → GEOID → boundary provider → demographic overlay → choropleth or report

Getting Started

• Getting Started
  • Installation
  • Quick Start: The Composition Chain
  • Engine-Agnostic DataFrames
  • Credential Management
  • Lazy Loading
  • Package Overview
• Installation Troubleshooting
  • Geospatial Extras and GDAL
  • Choosing the Right Extras
  • Common Errors
• Library Architecture
  • Strategic Intent
  • Composition Chain
  • Layer Model
  • Package Structure
  • Architectural Decisions
  • Design Tensions (Resolved)

Geospatial (the gravitational center)

• Geo
  • geo_capabilities()
  • get_default_crs()
  • set_default_crs()
  • reproject_if_needed()
  • detect_crs()
  • distance_to_decimal_degrees()
  • reproject_geom()
  • BoundaryFetchResult
  • BoundaryRetrievalError
  • BoundaryInputError
  • BoundaryDiscoveryError
  • BoundaryConfigurationError
  • BoundaryUrlValidationError
  • BoundaryDownloadError
  • BoundaryParseError
  • BoundaryProvider
  • CensusTIGERProvider
  • GADMProvider
  • RDHProvider
  • BoundaryFetchError
  • resolve_boundary_provider()
  • CensusDirectoryDiscovery
  • CensusDataSource
  • SpatialDataSource
  • GovernmentDataSource
  • OpenStreetMapDataSource
  • get_census_boundaries()
  • download_data()
  • normalize_state_identifier()
  • get_state_by_abbreviation()
  • get_state_by_name()
  • discover_boundary_types()
  • get_census_data()
  • download_osm_data()
  • get_available_years()
  • get_year_directory_contents()
  • construct_download_url()
  • validate_download_url()
  • get_optimal_year()
  • get_geographic_boundaries()
  • fetch_geographic_boundaries()
  • get_available_boundary_types()
  • refresh_discovery_cache()
  • get_available_state_fips()
  • get_state_abbreviations()
  • get_comprehensive_state_info()
  • validate_state_fips()
  • get_state_name()
  • get_state_abbreviation()
  • download_dataset()
  • get_unified_fips_data()
  • normalize_state_identifier_standalone()
  • normalize_state_input()
  • normalize_state_name()
  • normalize_state_abbreviation()
  • normalize_fips_code()
  • CensusDatasetMapper
  • SurveyType
  • GeographyLevel
  • DataReliability
  • CensusDataset
  • DatasetRelationship
  • get_census_dataset_mapper()
  • get_best_dataset_for_analysis()
  • compare_census_datasets()
  • get_dataset_info()
  • list_datasets_by_type()
  • list_datasets_by_geography()
  • get_best_dataset_for_use_case()
  • get_dataset_relationships()
  • compare_datasets()
  • get_data_selection_guide()
  • export_dataset_catalog()
  • CensusDataSelector
  • get_census_data_selector()
  • select_census_datasets()
  • select_datasets_for_analysis()
  • get_dataset_compatibility_matrix()
  • get_analysis_approach()
  • suggest_analysis_approach()
  • SpatialDataTransformer
  • SWMapsArchive
  • open_swmaps()
  • read_features()
  • find_vector_dataset_file_in_directory()
  • concatenate_addresses()
  • use_nominatim_geocoder()
  • NominatimGeoClassifier
  • get_country_name()
  • get_country_code()
  • list_countries()
  • get_coordinates()
  • geocode_with_nominatim_public()
  • geocode_addresses_with_nominatim()
  • GeocodingError
  • validate_geocode_data_pandas()
  • mark_valid_geocode_data_pandas()
  • IsochroneError
  • IsochroneNetworkError
  • IsochroneProviderError
  • IsochroneRequest
  • IsochroneProvider
  • OpenRouteServiceProvider
  • ValhallaProvider
  • build_isochrone_request()
  • get_isochrone()
  • isochrone_to_geodataframe()
  • get_provider()
  • CensusGeocodeError
  • CensusVintage
  • CensusGeocodeResult
  • select_vintage_for_cycle()
  • geocode_single()
  • geocode_batch()
  • geocode_batch_chunked()
  • geocode_results_to_dataframe()
  • is_valid_state_fips()
  • is_valid_county_fips()
  • is_valid_tract_geoid()
  • is_valid_block_group_geoid()
  • resolve_geographic_level()
  • LocaleCode
  • LocaleType
  • NCESLocaleClassifier
  • locale_from_code()
  • NCESDownloader
  • NCESDownloadError
  • Gazetteer
  • GazetteerResult
  • GazetteerCandidate
  • GazetteerError
  • GazetteerNotFoundError
  • GazetteerAmbiguousError
  • GazetteerBackendError
  • resolve_gazetteer()
  • EtterError
  • EtterParseError
  • EtterLowConfidenceError
  • EtterFilter
  • EtterParser
  • default_llm()
  • RelationSemantics
  • EtterGeometryResult
  • EtterToGeometryError
  • EtterReferenceNotFoundError
  • EtterUnknownRelationError
  • etter_to_geometry()
  • SpatialLoaderPlan
  • select_spatial_loader()
  • build_census_table_name()
  • build_census_ingest_targets()
  • SpatialRuntimePlan
  • resolve_spatial_runtime_plan()
  • GeometryPayload
  • encode_geometry()
  • decode_geometry()
  • payload_to_spark_row()
  • spark_row_to_payload()
  • s2_index_points()
  • s2_index_polygon()
  • s2_region_cover()
  • s2_spatial_join()
  • s2_cell_to_boundary()
  • s2_level_for_area()
  • s2_level_for_admin_level()
  • s2_kring()
  • s2_distance()
  • s2_parent()
  • s2_children()
  • s2_cell_id_to_uint64()
  • s2_uint64_to_cell_id()
  • s2_cell_id_to_token()
  • s2_token_to_cell_id()
  • s2_bbox_to_cells()
  • s2_cells_to_ranges()
  • index_points()
  • index_polygon()
  • infer_grid()
  • PlanAuthority
  • PlanDistrict
  • RedistrictingPlan
  • PlanRegistry
  • PlanResolutionError
  • PlanOverlapError
  • get_default_plan_registry()
  • detect_format()
  • extract_attributes_ogr()
  • extract_attributes_kml()
  • extract_attributes_swmaps()
  • TemporalDataStore
  • get_temporal_store()
  • save_boundaries()
  • load_boundaries()
  • query_boundaries_at_date()
  • save_demographics()
  • load_demographics()
  • spatial_query()
  • temporal_filter()
  • point_in_boundary()
  • Core Spatial Modules
  • Boundaries and Providers
  • Census Data Intelligence
  • Crosswalks and Interpolation
  • Gazetteers and Place History
  • Overlays
  • Redistricting and Plans
  • Codification
  • Schemas
  • Temporal and Timeseries
  • Other Modules
• Geocoding
  • Module Overview
  • Functions
  • Usage Examples
  • Unit Tests
• Geo Django
  • get_model()
  • get_service()
  • Models
  • Managers
  • Services
  • Serializers
  • Management Commands
  • App Configuration

Domain Packages

• Political
  • schema_migrations_dir()
  • Submodules
• Economic
  • Submodules
• Education
  • Submodules
• Survey
  • Submodules
• Analytics
  • GoogleAnalyticsConnector
  • create_ga_account_profile()
  • save_ga_account_profile()
  • load_ga_account_profile()
  • list_ga_accounts_for_client()
  • batch_retrieve_ga_data()
  • create_ga_connector_with_service_account()
  • FacebookBusinessConnector
  • create_facebook_account_profile()
  • save_facebook_account_profile()
  • load_facebook_account_profile()
  • list_facebook_accounts_for_client()
  • batch_retrieve_facebook_data()
  • SnowflakeConnector
  • get_snowflake_connector()
  • upload_to_snowflake()
  • download_from_snowflake()
  • execute_snowflake_query()
  • DataDotWorldConnector
  • get_datadotworld_connector()
  • search_datasets()
  • list_datasets()
  • search_datadotworld_datasets()
  • load_datadotworld_dataset()
  • query_datadotworld_dataset()
  • GoogleWorkspaceClient
  • create_spreadsheet()
  • write_values()
  • append_rows()
  • read_values()
  • write_dataframe()
  • read_dataframe()
  • add_sheet()
  • get_spreadsheet_metadata()
  • copy_spreadsheet()
  • create_presentation()
  • get_presentation()
  • copy_presentation()
  • add_blank_slide()
  • create_textbox()
  • create_document()
  • get_document()
  • copy_document()
  • read_document_text()
  • insert_paragraph()
  • insert_table()
  • replace_text()
  • VistaSocialConnector
  • VistaSocialResponse
  • VistaSocialError
  • VistaSocialAuthError
  • VistaSocialRateLimitError
  • Dimension
  • ThresholdConfig
  • EntityScore
  • HealthScorer
  • SignalType
  • RiskTier
  • RiskSignal
  • RiskTierConfig
  • RiskAssessment
  • RiskAnalyzer
  • DimensionScore
  • ComparisonResult
  • FeatureMatrix
  • ComparativeAnalyzer
  • ForecastAccuracy
  • CategoryBreakdown
  • TrendPoint
  • ForecastReport
  • ForecastAnalyzer
  • PipelineItem
  • StageMetrics
  • ConversionRate
  • VelocityMetrics
  • ConcentrationAlert
  • PipelineReport
  • PipelineAnalyzer
  • MappingRule
  • Outcome
  • EffectivenessReport
  • InterventionMapper
  • Submodules

Engines & Infrastructure

• Engines
  • Engine
  • DataFrameEngine
  • PandasEngine
  • DuckDBEngine
  • SparkEngine
  • PostGISEngine
  • get_engine()
  • Submodules
• Distributed
  • sanitise_dataframe_column_names()
  • tabulate_null_vs_not_null()
  • get_row_count()
  • repartition_and_cache()
  • register_temp_table()
  • move_column_to_front_of_dataframe()
  • write_df_to_parquet()
  • read_parquet_to_df()
  • flatten_json_column_and_join_back_to_df()
  • validate_geocode_data()
  • mark_valid_geocode_data()
  • clean_and_reorder_bbox()
  • ensure_literal()
  • reproject_geom_columns()
  • prepare_dataframe_for_export()
  • prepare_summary_dataframe()
  • export_pyspark_df_to_excel()
  • pivot_summary_table_for_bools()
  • pivot_summary_with_metrics()
  • export_prepared_df_as_csv_to_path_using_delimiter()
  • print_debug_table()
  • compute_walkability()
  • validate_geometry()
  • backup_full_dataframe()
  • atomic_write_with_staging()
  • create_unique_staging_directory()
  • py_round()
  • HDFSConfig
  • create_hdfs_config()
  • create_local_config()
  • create_cluster_config()
  • create_geocoding_config()
  • create_yarn_config()
  • create_census_analysis_config()
  • AbstractHDFSOperations
  • setup_distributed_environment()
  • create_hdfs_operations()
  • Submodules
• Databricks
  • build_databricks_run_url()
  • build_foreign_table_sql()
  • build_jdbc_url()
  • build_lakebase_psql_command()
  • build_pgpass_entry()
  • build_schema_and_table_sync_sql()
  • ensure_secret_scope()
  • geopandas_to_spark()
  • get_active_spark_session()
  • get_dbutils()
  • get_runtime_secret()
  • get_workspace_client()
  • pandas_to_spark()
  • parse_conninfo()
  • put_secret()
  • runtime_secret_exists()
  • spark_to_geopandas()
  • spark_to_pandas()
  • Submodules
• Trino
  • build_trino_federation_view_sql()
  • build_trino_schema_and_view_sync_sql()
  • quote_ident()
  • Submodules
• Connectors
  • Protocol
• Config
  • get_service_timeout()
  • normalize_state_identifier()
  • get_fips_info()
  • Submodules
  • Models
• conf — Project Settings
  • contextmanager()
  • Path
  • Settings
• oss_unity_catalog — Unity Catalog Registration
  • build_external_table_payload()
  • register_external_table()

Data & Reference

• Data
  • RDHClient
  • RDHDataset
  • RDHDataFormat
  • RDHDatasetType
  • polsby_popper()
  • reock()
  • convex_hull_ratio()
  • schwartzberg()
  • compute_compactness()
  • compare_plans()
  • demographic_profile()
  • fetch_enacted_plan()
  • fetch_precinct_results()
  • fetch_cvap()
  • fetch_pl94171()
  • fetch_demographic_summary()
  • CompactnessScores
  • Engine
  • DataFrameEngine
  • PandasEngine
  • DuckDBEngine
  • SparkEngine
  • PostGISEngine
  • get_engine()
  • Submodules
  • Statistics
• Reference
  • NAICSCode
  • parse_naics()
  • naics_ancestors()
  • naics_to_sector()
  • crosswalk_naics()
  • SOCCode
  • parse_soc()
  • soc_to_major_group()
  • fuzzy_match_naics()
  • get_naics_lookup()
  • get_soc_lookup()
  • naics_title()
  • soc_title()
  • filter_by_naics()
  • filter_by_naics_sector()
  • group_by_naics_sector()
  • list_available_datasets()
  • get_dataset_info()
  • load_sample_data()
  • get_census_boundaries()
  • get_census_data()
  • join_boundaries_and_data()
  • create_sample_dataset()
  • get_census_county_sample()
  • get_metropolitan_sample()
  • generate_synthetic_population()
  • generate_synthetic_businesses()
  • generate_synthetic_housing()
  • Submodules
• Schema
  • MigrationRunner
  • MigrationFile
  • MigrationStatus
  • AppliedMigration
  • PendingMigration
  • Submodules
• Identifiers
  • attestation_uuid()
  • derive_root()
  • derive_sub_namespace()
  • normalize_name_v1()
  • uuid5_from_seed()
  • Submodules
• Hygiene
  • generate_docstrings()
  • Submodules

Output & Reporting

• Reporting
  • TitlePageTemplate
  • create_title_page()
  • TableOfContentsTemplate
  • create_table_of_contents()
  • generate_sections_from_report_structure()
  • ContentPageTemplate
  • create_content_page()
  • ChartGenerator
  • ChartTypeRegistry
  • create_bar_chart()
  • create_line_chart()
  • create_scatter_plot()
  • create_pie_chart()
  • create_heatmap()
  • create_choropleth_map()
  • create_bivariate_choropleth()
  • create_marker_map()
  • create_flow_map()
  • create_convergence_diagram()
  • create_dashboard()
  • create_dataframe_summary_charts()
  • generate_chart_from_dataframe()
  • ClientBrandingManager
  • decode_rl_image()
  • show_rl_image()
  • save_rl_image()
  • Argument
  • TableType
  • Algorithm
  • Sizing
  • hex_tile_layout()
  • hex_tile_map()
  • register_layout()
  • IDMLExporter
  • export_report_idml()
  • ThreeDMapRenderer
  • create_3d_hexbin()
  • create_3d_columns()
  • sort_table_data()
  • get_report_output_directory()
  • create_report_generator()
  • create_powerpoint_generator()
  • export_branding_config()
  • import_branding_config()
  • export_chart_type_config()
  • ReportingConfigError
  • Charts and Visualization
  • Chart Engines
  • Reports and Documents
  • Analytics Reports
  • Hex Cartograms
  • 3D Maps
  • Pages
• Profiles

Utilities

• Core
  • get_logger()
  • log_info()
  • log_warning()
  • log_error()
  • log_debug()
  • log_critical()
  • init_logger()
  • configure_shared_logging()
  • remove_wrapping_quotes_and_trim()
  • clean_string()
  • normalize_whitespace()
  • snake_case()
  • remove_non_alphanumeric()
  • validate_sql_identifier()
  • validate_sql_identifier_in()
  • escape_sql_string_literal()
  • validate_sql_fragment()
  • Submodules
• Files
  • ensure_path_exists()
  • unzip_file_to_directory()
  • get_file_extension()
  • get_file_name_without_extension()
  • is_hidden_file()
  • get_relative_path()
  • find_files_by_pattern()
  • create_backup_path()
  • normalize_path()
  • remove_tree()
  • file_exists()
  • touch_file()
  • count_lines()
  • copy_file()
  • move_file()
  • get_file_size()
  • list_directory()
  • run_command()
  • delete_existing_file_and_replace_it_with_an_empty_file()
  • ensure_directory_exists()
  • safe_file_write()
  • safe_file_read()
  • safe_json_write()
  • safe_json_read()
  • get_file_size_mb()
  • list_files_recursive()
  • download_file()
  • generate_local_path_from_url()
  • download_file_with_retry()
  • get_file_info()
  • is_downloadable()
  • get_download_directory()
  • SpatialFormat
  • TabularFormat
  • save_spatial()
  • save_tabular()
  • generate_sha256_hash_for_file()
  • get_file_hash()
  • calculate_file_hash()
  • get_quick_file_signature()
  • verify_file_integrity()
  • Submodules
• Git
  • GitError
  • analyze_branch_status()
  • generate_branch_report()
  • get_commit_history()
  • categorize_commits()
  • get_file_changes()
  • create_feature_branch()
  • switch_branch()
  • merge_branch()
  • rebase_branch()
  • stash_changes()
  • apply_stash()
  • clean_working_directory()
  • reset_to_commit()
  • cherry_pick_commit()
  • create_tag()
  • push_branch()
  • pull_branch()
  • get_repository_status()
  • get_branch_info()
  • get_remote_info()
  • get_stash_list()
  • get_tag_list()
  • get_log_summary()
  • start_feature_workflow()
  • complete_feature_workflow()
  • hotfix_workflow()
  • release_workflow()
  • validate_branch_naming()
  • enforce_commit_conventions()
  • Submodules
• Admin
  • get_default_profile_location()
  • set_profile_location()
  • get_profile_location()
  • list_profile_locations()
  • migrate_profiles()
  • create_default_profiles()
  • validate_profile_location()
  • Submodules
• Cache
  • SampleDatasetError
  • ensure_sample_dataset()
• Testing
  • setup_spark_environment()
  • get_system_info()
  • ensure_env_vars()
  • check_java_version()
  • diagnose_environment()
  • quick_environment_setup()
  • run_test_suite()
  • get_test_report()
  • run_comprehensive_test()
  • quick_smoke_test()
  • build_pytest_command()
  • Submodules
• development — Internal Development Tooling
  • generate_architecture_diagram()
  • analyze_package_structure()
• Exception Hierarchy
  • Design principles
  • Reporting
  • Geographic
  • Migration guidance
  • Further reading

Examples & Notebooks

• Jupyter Notebooks
  • Foundations
  • Engines
  • Spatial
  • Analytics
  • Reports
  • Economic
  • Git
  • Config

Development

• Contributor Governance
• Coding Style
• PR Review Rubric
• Testing Guide
  • Overview
  • Test Structure
  • Running Tests
  • Test Markers
  • Writing New Tests
  • Test Fixtures
  • Test Configuration
  • Continuous Integration
  • Debugging Tests
  • Performance Testing
  • Test Data Management
  • Best Practices
  • Common Patterns
  • Troubleshooting
  • Getting Help
• Change Classification and Release Policy
• Repository Hygiene
  • Policy goals
  • Tracked vs ignored artifacts
  • Special exception: notebooks output
  • Scripts policy
• License Model

Note

v3.22.0 (June 2026) — PyPI

Key capabilities:

• Geo is the gravitational center — boundaries, geocoding, spatial transforms, isochrones, Census data intelligence, redistricting analysis

• Engine-agnostic DataFrame — pandas, DuckDB, Spark+Sedona, PostGIS

• CRM connectors — ConnectorProtocol for Salesforce, HubSpot, Zoho, Dynamics

• Temporal political models — CongressionalTerm, Seat, Race, RedistrictingPlan

• Pluggable providers — Census TIGER, GADM, RDH boundary providers; Census, Nominatim, TAMU geocoders

• PEP 562 lazy loading — import one piece without pulling the whole library

• Tiered geo extras — [geo-lite] / [geo] / [geodjango]

• 32 Jupyter notebooks organized by domain

• Report generation — PDF, PowerPoint, branded multi-client reports, hex cartograms

Install: pip install siege-utilities

Indices and tables

• Index

• Module Index

• Search Page