gedih3.validation#

gedih3 Validation Module

Parameter validation functions for H3, EGI, and other critical operations. These functions raise descriptive exceptions to help users fix configuration issues.

Usage:

from gedih3.validation import validate_h3_params, validate_egi_level

validate_h3_params(res=12, part=3) # Raises H3ValidationError if invalid

Attributes#

`H3_MIN_RESOLUTION`
`H3_MAX_RESOLUTION`
`EGI_MIN_LEVEL`
`EGI_MAX_LEVEL`
`VALID_PRODUCTS`

Functions#

`validate_h3_resolution`(→ int)	Validate H3 resolution is within valid range [0, 15].
`validate_h3_params`(→ tuple)	Validate H3 resolution and partition parameters.
`validate_h3_cell`(→ str)	Validate an H3 cell index string.
`validate_egi_level`(→ int)	Validate EGI level is within valid range [1, 12].
`validate_product`(→ str)	Validate GEDI product identifier.
`validate_product_vars`(→ Dict[str, List[str]])	Validate product variables dictionary.
`validate_file_exists`(→ str)	Validate that a file exists.
`validate_directory_exists`(→ str)	Validate that a directory exists, optionally creating it.
`validate_database_path`(→ str)	Validate H3 database path exists and appears valid.
`validate_coordinates`(→ tuple)	Validate latitude and longitude coordinates.
`validate_bbox`(→ tuple)	Validate bounding box coordinates.

Module Contents#

gedih3.validation.H3_MIN_RESOLUTION = 0#

gedih3.validation.H3_MAX_RESOLUTION = 15#

gedih3.validation.validate_h3_resolution(res: int, param_name: str = 'resolution') → int[source]#

Validate H3 resolution is within valid range [0, 15].

Parameters:

resint: H3 resolution level
param_namestr: Parameter name for error messages

Returns:

int: Validated resolution

Raises:

H3ValidationError: If resolution is out of range or not an integer

gedih3.validation.validate_h3_params(res: int, part: int) → tuple[source]#

Validate H3 resolution and partition parameters.

Parameters:

resint: H3 resolution level for indexing (0-15)
partint: H3 resolution level for partitioning (0-15, must be <= res)

Returns:

tuple: (res, part) validated values

Raises:

H3ValidationError: If parameters are invalid

Examples

>>> validate_h3_params(12, 3)  # OK
(12, 3)
>>> validate_h3_params(3, 12)  # Raises H3ValidationError

gedih3.validation.validate_h3_cell(cell: str, expected_res: int | None = None) → str[source]#

Validate an H3 cell index string.

Parameters:

cellstr: H3 cell index (hexadecimal string)
expected_resint, optional: Expected resolution level

Returns:

str: Validated cell index

Raises:

H3ValidationError: If cell is invalid

gedih3.validation.EGI_MIN_LEVEL = 1#

gedih3.validation.EGI_MAX_LEVEL = 12#

gedih3.validation.validate_egi_level(level: int, param_name: str = 'level') → int[source]#

Validate EGI level is within valid range [1, 12].

Parameters:

levelint: EGI resolution level
param_namestr: Parameter name for error messages

Returns:

int: Validated level

Raises:

EGIValidationError: If level is out of range

gedih3.validation.VALID_PRODUCTS#

gedih3.validation.validate_product(product: str) → str[source]#

Validate GEDI product identifier.

Parameters:

productstr: GEDI product code (e.g., ‘L2A’, ‘L4A’)

Returns:

str: Normalized product code (uppercase)

Raises:

GediProductError: If product is invalid

gedih3.validation.validate_product_vars(product_vars: Dict[str, Any]) → Dict[str, List[str]][source]#

Validate product variables dictionary.

Parameters:

product_varsdict: Dictionary mapping product codes to variable specifications

Returns:

dict: Validated product variables

Raises:

GediProductError: If product is invalid
GediVariableError: If variable specification is invalid

gedih3.validation.validate_file_exists(path: str, file_type: str = 'file') → str[source]#

Validate that a file exists.

Parameters:

pathstr: File path to validate
file_typestr: Description for error message (e.g., ‘HDF5 file’, ‘database’)

Returns:

str: Validated path

Raises:

GediFileError: If file does not exist

gedih3.validation.validate_directory_exists(path: str, create: bool = False) → str[source]#

Validate that a directory exists, optionally creating it.

Parameters:

pathstr: Directory path to validate
createbool: If True, create directory if it doesn’t exist

Returns:

str: Validated path

Raises:

GediFileError: If directory does not exist and create=False

gedih3.validation.validate_database_path(db_path: str) → str[source]#

Validate H3 database path exists and appears valid.

Parameters:

db_pathstr: Path to H3 database directory

Returns:

str: Validated path

Raises:

GediDatabaseNotFoundError: If database directory doesn’t exist or appears invalid

gedih3.validation.validate_coordinates(lat: float, lon: float) → tuple[source]#

Validate latitude and longitude coordinates.

Parameters:

latfloat: Latitude in degrees
lonfloat: Longitude in degrees

Returns:

tuple: (lat, lon) validated coordinates

Raises:

ValueError: If coordinates are out of range

gedih3.validation.validate_bbox(bbox: list | tuple) → tuple[source]#

Validate bounding box coordinates.

Parameters:

bboxlist or tuple: Bounding box as (west, south, east, north) or [west, south, east, north]

Returns:

tuple: Validated (west, south, east, north)

Raises:

ValueError: If bbox is invalid