Global-Ready Django Framework

GEOGRAPHIC CANON.

/// LOCALE_CANONICAL_LAYER Jurisdictions, ISO codes, currencies, addresses, phones, flags, timezones, languages, holidays, and locale formatting for Django.

EXPLORE ARCHITECTURE PYPI PACKAGE INSTALLATION

CANONICAL DATA FOR

JURISDICTIONS DIAL CODES FLAGS TIMEZONES HOLIDAYS LANGUAGES

The Localisation Problem

Stop rebuilding locale infrastructure for every project. One canonical source of truth for geographic data.

Scattered Data

Country lists hardcoded in templates. Timezone logic scattered across views. Dial codes copy-pasted from Stack Overflow. Every project reinvents the wheel.

# ❌ Ad-hoc locale handling
COUNTRY_CHOICES = [ ('US', 'United States'), ('UK', 'United Kingdom'), # ... copy-paste 190 more? # ⚠️ Which ISO standard? # ⚠️ Are they translatable? # ⚠️ What about dial codes? ]

GeoCanon

One import. Canonical, typed, translatable data for 190+ jurisdictions. Forms, middleware, and settings included.

# ✅ Canonical locale data
from geo_canon import ( get_jurisdiction_choices, get_dial_code, get_flag_css_class, get_current_local_time, ) # 190+ jurisdictions, typed & translatable # Dial codes, flags, timezones — all linked

SEVEN MODULES.

Everything a Django application needs to serve a global user base, in one coherent package.

Jurisdictions

190+ countries with translatable names, form fields, and context-switching middleware.

  • JurisdictionChoiceField for forms
  • Session-based middleware
  • Validation helpers

Dial Codes

International dial codes for 150+ countries with phone number validation patterns.

  • Country-to-code mapping
  • Regex phone validation
  • Django form choices

Flags

Country-to-ISO-3166 CSS class mapping compatible with the flag-icons library.

  • 190+ flag CSS classes
  • QuerySet annotation helper
  • Reverse ISO lookup

Timezones

200+ jurisdiction-to-IANA timezone mappings with aware datetime utilities.

  • zoneinfo + pytz fallback
  • Settings-level overrides
  • get_current_local_time()

Public Holidays

Holiday detection for 140+ countries powered by the open-source holidays library.

  • is_public_holiday() check
  • Full year holiday listing
  • Optional dependency

Languages

75+ language choices with jurisdiction-to-default-language mapping.

  • Django LANGUAGE_CODE compatible
  • Jurisdiction auto-detection
  • Sorted form choices

Canonical codes

ISO, currency, and address APIs

Resolve alpha-2, alpha-3, and numeric country codes, map jurisdiction currencies, validate postal patterns, localize field labels, and format addresses.

Bundled mappings are versioned defaults with documented provenance and limitations.

Optional extras

Phones and locale formatting

geocanon[phones] adds libphonenumber parsing and E.164/display formats. geocanon[locale] adds Babel-backed number, currency, date, time, and list formatting.

Core imports remain usable without either extra.

Agent interface

Public MCP contract

The packaged geocanon-mcp command exposes a review-first contract for API discovery, optional extras, locale workflows, and public documentation.

It does not require customer personal data or production access.

Designed for Global Scale

Stop copy-pasting country lists. GeoCanon provides versioned, typed, translatable geographic defaults with Django-native integration.

Rich Exceptions

Every error includes a hint and a documentation link. No more cryptic stack traces.

Pydantic Settings

Type-safe configuration with validation. Works with or without Pydantic installed.

PEP 561 Typed

Full py.typed support for MyPy and VS Code autocompletion out of the box.

views.py
from geo_canon import (
    get_current_local_time,
    get_flag_css_class,
    is_public_holiday,
)

def dashboard(request):
    jurisdiction = request.jurisdiction
    now = get_current_local_time(jurisdiction)
    flag = get_flag_css_class(jurisdiction)
    holiday = is_public_holiday(jurisdiction)
    # All data — one canonical source

INTEGRATION

1 Install the package

$ pip install geocanon[all]

2 Configure in settings.py 

# settings.py

GEOCANON = {
    "default_jurisdiction": "United Kingdom",
    "default_language": "en",
    "enable_form_widgets": True,
}

MIDDLEWARE = [
    # ...
    "geo_canon.jurisdictions.middleware.JurisdictionMiddleware",
]

3 Use anywhere in your app 

from geo_canon.jurisdictions.forms import JurisdictionContextSwitchForm
from geo_canon.timezones import get_current_local_time
from geo_canon.holidays import is_public_holiday
from geo_canon.flags import get_flag_css_class

# request.jurisdiction is set automatically by the middleware
local_time = get_current_local_time(request.jurisdiction)
flag_class = get_flag_css_class(request.jurisdiction)

Global operations playbook

Design once, localize everywhere

GeoCanon helps product, legal, and engineering teams move at the same speed by centralizing jurisdiction data into one versioned source. Teams avoid drift between forms, billing, reporting, and support tooling.

Product teams

Ship locale-aware UX defaults for language, region formatting, and holidays without hardcoding market-specific branches.

Operations teams

Coordinate support windows and cutoff times from local timezone truth instead of manually maintained spreadsheets.

Compliance teams

Track jurisdiction-level policy requirements with consistent naming and stable IDs for downstream audits.

GeoCanon supplies identifiers and defaults, not legal or policy decisions.

Common implementation outcomes

  • • One canonical jurisdiction object shared across apps and services.
  • • Fewer production regressions from stale localization constants.
  • • Faster expansion to new countries with predictable onboarding checklists.
  • • Cleaner analytics slices by geography with validated identifiers.