Database Operations

def get_authorities() -> list[str]:
    """
    Get list of available CRS authorities in PROJ database.

    Returns:
        List of authority names (e.g., ['EPSG', 'ESRI', 'IAU_2015', 'IGNF', 'OGC'])

    Note:
        Authorities are organizations that maintain coordinate reference system definitions.
        EPSG is the most commonly used authority for standard CRS definitions.
    """

def get_codes(
    auth_name: str,
    pj_type: PJType | str,
    allow_deprecated: bool = False
) -> list[str]:
    """
    Get list of codes for specified authority and object type.

    Args:
        auth_name: Authority name (e.g., 'EPSG', 'ESRI')
        pj_type: Type of objects to query (CRS, ELLIPSOID, DATUM, etc.)
        allow_deprecated: Include deprecated/superseded codes

    Returns:
        List of codes as strings

    Raises:
        ValueError: If authority name or PJ type is invalid
    """

def query_crs_info(
    auth_name: str | None = None,
    pj_types: list[PJType] | None = None,
    area_of_interest: AreaOfInterest | None = None,
    contains: bool = False,
    allow_deprecated: bool = False
) -> list[CRSInfo]:
    """
    Query coordinate reference system information from PROJ database.

    Args:
        auth_name: Filter by authority name (None for all authorities)
        pj_types: Filter by CRS types (None for all types)
        area_of_interest: Geographic area constraint
        contains: If True, CRS area must contain AOI; if False, must intersect AOI
        allow_deprecated: Include deprecated CRS definitions

    Returns:
        List of CRSInfo objects matching the criteria

    Note:
        Results are sorted by relevance and accuracy for the specified area.
    """

def query_utm_crs_info(
    datum_name: str | None = None,
    area_of_interest: AreaOfInterest | None = None,
    contains: bool = False
) -> list[CRSInfo]:
    """
    Query UTM coordinate reference systems from PROJ database.

    Args:
        datum_name: Filter by datum name (e.g., 'WGS 84', 'NAD83')
        area_of_interest: Geographic area constraint for UTM zone selection
        contains: If True, UTM zone must contain AOI; if False, must intersect AOI

    Returns:
        List of CRSInfo objects for UTM zones matching criteria

    Note:
        Automatically selects appropriate UTM zones based on area of interest.
        Results include both northern and southern hemisphere zones if applicable.
    """

def get_units_map(
    auth_name: str | None = None,
    category: str | None = None,
    allow_deprecated: bool = False
) -> dict[str, Unit]:
    """
    Get dictionary of available units from PROJ database.

    Args:
        auth_name: Filter by authority name (None for all authorities)
        category: Filter by unit category ('linear', 'angular', 'scale', 'time')
        allow_deprecated: Include deprecated unit definitions

    Returns:
        Dictionary mapping unit names to Unit objects

    Note:
        Units include linear units (meters, feet), angular units (degrees, radians),
        and other measurement units used in coordinate system definitions.
    """

def get_ellps_map() -> dict[str, dict[str, float]]:
    """
    Get dictionary of ellipsoid parameters.

    Returns:
        Dictionary mapping ellipsoid names to parameter dictionaries
        containing 'a' (semi-major axis), 'b' (semi-minor axis), 
        and other ellipsoid parameters

    Note:
        Provides parameters for standard ellipsoids like WGS84, GRS80, Clarke 1866, etc.
        Values are in meters for linear dimensions.
    """

def get_prime_meridians_map() -> dict[str, str]:
    """
    Get dictionary of prime meridian definitions.

    Returns:
        Dictionary mapping prime meridian names to longitude values

    Note:
        Most common prime meridian is Greenwich (0°).
        Historical data may reference other prime meridians.
    """

def get_proj_operations_map() -> dict[str, str]:
    """
    Get dictionary of available PROJ operations.

    Returns:
        Dictionary mapping operation names to descriptions

    Note:
        Includes map projections, datum transformations, and coordinate conversions
        available in the current PROJ installation.
    """

def get_database_metadata(key: str) -> str | None:
    """
    Get metadata value from PROJ database.

    Args:
        key: Metadata key to retrieve

    Returns:
        Metadata value as string, or None if key not found

    Note:
        Common keys include version information, update timestamps,
        and database configuration details.
    """

from pyproj.database import get_authorities, get_codes, PJType

# Get all available authorities
authorities = get_authorities()
print(f"Available authorities: {authorities}")

# Get EPSG coordinate reference system codes
epsg_crs_codes = get_codes('EPSG', PJType.CRS)
print(f"Number of EPSG CRS codes: {len(epsg_crs_codes)}")
print(f"First 10 codes: {epsg_crs_codes[:10]}")

# Get ellipsoid codes from different authorities
epsg_ellipsoids = get_codes('EPSG', PJType.ELLIPSOID)
esri_ellipsoids = get_codes('ESRI', PJType.ELLIPSOID, allow_deprecated=True)

print(f"EPSG ellipsoids: {len(epsg_ellipsoids)}")
print(f"ESRI ellipsoids (including deprecated): {len(esri_ellipsoids)}")

# Get datum codes
datum_codes = get_codes('EPSG', PJType.DATUM)
print(f"EPSG datum codes: {datum_codes[:5]}")

from pyproj.database import query_crs_info, AreaOfInterest, PJType

# Search for CRS in specific geographic area (Texas)
texas_aoi = AreaOfInterest(
    west_lon_degree=-106.5,
    south_lat_degree=25.8,
    east_lon_degree=-93.5,
    north_lat_degree=36.5
)

# Find all CRS for Texas area
texas_crs = query_crs_info(area_of_interest=texas_aoi)
print(f"CRS options for Texas: {len(texas_crs)}")

# Show details for first few results
for crs_info in texas_crs[:5]:
    print(f"Code: {crs_info.auth_name}:{crs_info.code}")
    print(f"Name: {crs_info.name}")
    print(f"Type: {crs_info.type}")
    print(f"Deprecated: {crs_info.deprecated}")
    print("---")

# Search for projected CRS only
projected_crs = query_crs_info(
    area_of_interest=texas_aoi,
    pj_types=[PJType.PROJECTED_CRS],
    contains=True  # CRS area must fully contain Texas
)
print(f"Projected CRS containing Texas: {len(projected_crs)}")

from pyproj.database import query_utm_crs_info, AreaOfInterest

# Find UTM zones for New York area
ny_aoi = AreaOfInterest(
    west_lon_degree=-74.5,
    south_lat_degree=40.5,
    east_lon_degree=-73.5,
    north_lat_degree=41.0
)

utm_zones = query_utm_crs_info(
    area_of_interest=ny_aoi,
    datum_name='WGS 84'
)

print(f"UTM zones for New York area:")
for utm_info in utm_zones:
    print(f"  {utm_info.auth_name}:{utm_info.code} - {utm_info.name}")

# Find UTM zones globally for specific datum
all_utm_nad83 = query_utm_crs_info(datum_name='NAD83')
print(f"All NAD83 UTM zones: {len(all_utm_nad83)}")

from pyproj.database import get_units_map, get_ellps_map, get_prime_meridians_map

# Get linear units
linear_units = get_units_map(category='linear')
print("Common linear units:")
for name, unit in list(linear_units.items())[:10]:
    print(f"  {name}: {unit.conv_factor} meters")

# Get angular units
angular_units = get_units_map(category='angular')
print("\nAngular units:")
for name, unit in list(angular_units.items())[:5]:
    print(f"  {name}: {unit.conv_factor} radians")

# Get ellipsoid parameters
ellipsoids = get_ellps_map()
wgs84_params = ellipsoids.get('WGS84', {})
grs80_params = ellipsoids.get('GRS80', {})

print(f"\nWGS84 ellipsoid:")
print(f"  Semi-major axis: {wgs84_params.get('a', 'N/A')} m")
print(f"  Semi-minor axis: {wgs84_params.get('b', 'N/A')} m")
print(f"  Flattening: {wgs84_params.get('f', 'N/A')}")

# Get prime meridians
prime_meridians = get_prime_meridians_map()
print(f"\nPrime meridians:")
for name, longitude in list(prime_meridians.items())[:5]:
    print(f"  {name}: {longitude}")

from pyproj.database import get_database_metadata, get_proj_operations_map

# Get database metadata
try:
    db_version = get_database_metadata('DATABASE.VERSION')
    print(f"PROJ database version: {db_version}")
except:
    print("Database version not available")

# Get available operations
operations = get_proj_operations_map()
print(f"Available PROJ operations: {len(operations)}")

# Show some projection operations
projection_ops = {k: v for k, v in operations.items() 
                 if 'projection' in v.lower()}
print(f"\nProjection operations:")
for name, desc in list(projection_ops.items())[:5]:
    print(f"  {name}: {desc}")

from pyproj.database import query_crs_info, get_codes, PJType

# Compare EPSG vs ESRI CRS options
epsg_geographic = query_crs_info(
    auth_name='EPSG',
    pj_types=[PJType.GEOGRAPHIC_2D_CRS, PJType.GEOGRAPHIC_3D_CRS]
)

esri_geographic = query_crs_info(
    auth_name='ESRI', 
    pj_types=[PJType.GEOGRAPHIC_2D_CRS, PJType.GEOGRAPHIC_3D_CRS]
)

print(f"EPSG geographic CRS: {len(epsg_geographic)}")
print(f"ESRI geographic CRS: {len(esri_geographic)}")

# Find deprecated CRS that have been superseded
all_epsg_crs = query_crs_info(
    auth_name='EPSG',
    allow_deprecated=True
)

deprecated_crs = [crs for crs in all_epsg_crs if crs.deprecated]
print(f"Deprecated EPSG CRS: {len(deprecated_crs)}")

# Show some deprecated entries
print("Examples of deprecated CRS:")
for crs_info in deprecated_crs[:3]:
    print(f"  {crs_info.code}: {crs_info.name}")

from pyproj.database import query_crs_info, AreaOfInterest

# Find appropriate CRS for different regions
regions = {
    'California': AreaOfInterest(-124.5, 32.5, -114.0, 42.0),
    'France': AreaOfInterest(-5.5, 42.0, 8.5, 51.5),
    'Australia': AreaOfInterest(112.0, -44.0, 154.0, -10.0)
}

for region_name, aoi in regions.items():
    regional_crs = query_crs_info(
        area_of_interest=aoi,
        pj_types=[PJType.PROJECTED_CRS],
        contains=False  # Intersects the region
    )
    
    print(f"\n{region_name} - Top 3 projected CRS:")
    for crs_info in regional_crs[:3]:
        area = crs_info.area_of_use
        area_desc = f"({area.west:.1f}, {area.south:.1f}, {area.east:.1f}, {area.north:.1f})" if area else "No area info"
        print(f"  {crs_info.auth_name}:{crs_info.code} - {crs_info.name}")
        print(f"    Area: {area_desc}")

# Information structures
class CRSInfo:
    """Information about a coordinate reference system."""
    auth_name: str  # Authority name (e.g., 'EPSG')
    code: str       # Authority code (e.g., '4326')
    name: str       # CRS name
    type: str       # CRS type description
    deprecated: bool # Whether CRS is deprecated
    area_of_use: AreaOfUse | None  # Geographic area of use
    projection_method_name: str | None  # Projection method for projected CRS

class Unit:
    """Information about a measurement unit."""
    auth_name: str      # Authority name
    code: str           # Unit code
    name: str           # Unit name
    category: str       # Unit category ('linear', 'angular', etc.)
    conv_factor: float  # Conversion factor to base unit
    proj_short_name: str | None  # PROJ short name
    deprecated: bool    # Whether unit is deprecated

# Enumeration for PROJ object types
class PJType(Enum):
    """Types of objects in PROJ database."""
    UNKNOWN = "UNKNOWN"
    ELLIPSOID = "ELLIPSOID"
    PRIME_MERIDIAN = "PRIME_MERIDIAN"
    DATUM = "DATUM"
    CRS = "CRS"
    GEOGRAPHIC_CRS = "GEOGRAPHIC_CRS"
    GEOGRAPHIC_2D_CRS = "GEOGRAPHIC_2D_CRS"  
    GEOGRAPHIC_3D_CRS = "GEOGRAPHIC_3D_CRS"
    GEOCENTRIC_CRS = "GEOCENTRIC_CRS"
    PROJECTED_CRS = "PROJECTED_CRS"
    VERTICAL_CRS = "VERTICAL_CRS"
    COMPOUND_CRS = "COMPOUND_CRS"
    ENGINEERING_CRS = "ENGINEERING_CRS"
    BOUND_CRS = "BOUND_CRS"
    OTHER_CRS = "OTHER_CRS"
    COORDINATE_OPERATION = "COORDINATE_OPERATION"
    CONVERSION = "CONVERSION"
    TRANSFORMATION = "TRANSFORMATION"
    CONCATENATED_OPERATION = "CONCATENATED_OPERATION"
    OTHER_COORDINATE_OPERATION = "OTHER_COORDINATE_OPERATION"

# Area of interest for geographic filtering
class AreaOfInterest:
    """Geographic bounding box for CRS queries."""
    west_lon_degree: float   # Western boundary longitude
    south_lat_degree: float  # Southern boundary latitude
    east_lon_degree: float   # Eastern boundary longitude  
    north_lat_degree: float  # Northern boundary latitude