API Reference

tburundigeo.api.facade

Public API facade - simplified interface for end users.

tburundigeo.api.facade.set_data_source(data_source)

Set the data source for all repositories.

Return type:

None

tburundigeo.api.facade.get_all_provinces()

Get all provinces.

Return type:

List[Province]

tburundigeo.api.facade.get_province(code)

Get a province by its code.

Return type:

Optional[Province]

tburundigeo.api.facade.get_province_capital(code)

Get the capital of a province by its code.

Return type:

Optional[str]

tburundigeo.api.facade.search_provinces(query, search_by='name')

Search provinces by name or code.

Return type:

List[Province]

tburundigeo.api.facade.count_provinces()

Count total number of provinces.

Return type:

int

tburundigeo.api.facade.get_all_communes()

Get all communes.

Return type:

List[Commune]

tburundigeo.api.facade.get_commune(code)

Get a commune by its code.

Return type:

Optional[Commune]

tburundigeo.api.facade.get_communes_by_province(province_code)

Get all communes in a province.

Return type:

List[Commune]

tburundigeo.api.facade.get_commune_capital(code)

Get the capital of a commune by its code.

Return type:

Optional[str]

tburundigeo.api.facade.search_communes(query, search_by='name')

Search communes by name, capital, or code.

Return type:

List[Commune]

tburundigeo.api.facade.count_communes()

Count total number of communes.

Return type:

int

tburundigeo.api.facade.count_communes_in_province(province_code)

Count communes in a specific province.

Return type:

int

tburundigeo.api.facade.get_all_zones()

Get all zones.

Return type:

List[Zone]

tburundigeo.api.facade.get_zone(code)

Get a zone by its code.

Return type:

Optional[Zone]

tburundigeo.api.facade.get_zones_by_commune(commune_code)

Get all zones in a commune.

Return type:

List[Zone]

tburundigeo.api.facade.get_zone_chief_town(code)

Get the chief town of a zone by its code.

Return type:

Optional[str]

tburundigeo.api.facade.search_zones(query, search_by='name')

Search zones by name, chief town, or code.

Return type:

List[Zone]

tburundigeo.api.facade.count_zones()

Count total number of zones.

Return type:

int

tburundigeo.api.facade.count_zones_in_commune(commune_code)

Count zones in a specific commune.

Return type:

int

tburundigeo.api.facade.get_all_quartiers()

Get all quartiers.

Return type:

List[Quartier]

tburundigeo.api.facade.get_quartier(code)

Get a quartier by its code.

Return type:

Optional[Quartier]

tburundigeo.api.facade.get_quartiers_by_zone(zone_code)

Get all quartiers in a zone.

Return type:

List[Quartier]

tburundigeo.api.facade.search_quartiers(query, search_by='name')

Search quartiers by name or code.

Return type:

List[Quartier]

tburundigeo.api.facade.count_quartiers()

Count total number of quartiers.

Return type:

int

tburundigeo.api.facade.count_quartiers_in_zone(zone_code)

Count quartiers in a specific zone.

Return type:

int

tburundigeo.api.facade.get_full_hierarchy()

Get the complete administrative hierarchy.

Return type:

Dict

tburundigeo.api.facade.get_parent_province(commune_code)

Get the parent province of a commune.

Return type:

Optional[Province]

tburundigeo.api.facade.get_parent_commune(zone_code)

Get the parent commune of a zone.

Return type:

Optional[Commune]

tburundigeo.api.facade.get_parent_zone(quartier_code)

Get the parent zone of a quartier.

Return type:

Optional[Zone]

tburundigeo.api.facade.get_statistics()

Get comprehensive statistics about administrative divisions.

Return type:

Dict[str, int]

tburundigeo.api.facade.get_summary()

Get a quick summary of all administrative divisions.

Return type:

Dict[str, int]

tburundigeo.api.facade.export_to_json(include_hierarchy=False, entity_types=None)

Export data to JSON format.

Return type:

str

tburundigeo.api.facade.export_to_csv(entity_type, include_headers=True)

Export data to CSV format.

Return type:

str

tburundigeo.api.facade.export_to_yaml(include_hierarchy=False, entity_types=None)

Export data to YAML format.

Return type:

str

tburundigeo.api.facade.validate_code(code, expected_level=None)

Validate if a code exists and optionally matches expected level.

Return type:

bool

tburundigeo.api.facade.check_referential_integrity()

Check referential integrity across all administrative levels.

Return type:

Dict[str, List[str]]

tburundigeo.api.facade.get_province_statistics(province_code)

Get detailed statistics for a specific province.

Return type:

Dict[str, int]

tburundigeo.api.facade.get_commune_statistics(commune_code)

Get detailed statistics for a specific commune.

Return type:

Dict[str, int]

tburundigeo.api.facade.get_zone_statistics(zone_code)

Get detailed statistics for a specific zone.

Return type:

Dict[str, int]

tburundigeo.api.facade.get_all_provinces_statistics()

Get detailed statistics for all provinces.

Return type:

List[Dict[str, int]]

tburundigeo.api.facade.get_all_communes_statistics()

Get detailed statistics for all communes.

Return type:

List[Dict[str, int]]

tburundigeo.api.facade.get_all_zones_statistics()

Get detailed statistics for all zones.

Return type:

List[Dict[str, int]]

tburundigeo.domain.entities

Core business entities for Burundi administrative divisions.

class tburundigeo.domain.entities.Province(code, name, capital)

Bases: object

Represents a province in Burundi.

code: str

name: str

capital: str

__post_init__()

Validate province data after initialization.

Return type:

None

__str__()

String representation of the province.

Return type:

str

__init__(code, name, capital)

class tburundigeo.domain.entities.Commune(code, name, capital, province_code)

Bases: object

Represents a commune in Burundi.

code: str

name: str

capital: str

province_code: str

__post_init__()

Validate commune data after initialization.

Return type:

None

__str__()

String representation of the commune.

Return type:

str

__init__(code, name, capital, province_code)

class tburundigeo.domain.entities.Zone(code, name, chief_town, commune_code)

Bases: object

Represents a zone in Burundi.

code: str

name: str

chief_town: str

commune_code: str

__post_init__()

Validate zone data after initialization.

Return type:

None

__str__()

String representation of the zone.

Return type:

str

__init__(code, name, chief_town, commune_code)

class tburundigeo.domain.entities.Quartier(code, name, zone_code)

Bases: object

Represents a quartier (neighborhood) in Burundi.

code: str

name: str

zone_code: str

__post_init__()

Validate quartier data after initialization.

Return type:

None

__str__()

String representation of the quartier.

Return type:

str

__init__(code, name, zone_code)

tburundigeo.infrastructure.repositories

Repository implementations that read data from Python files.

class tburundigeo.infrastructure.repositories.py_file.BasePyFileRepository(data_module_path)

Bases: object

Base class for Python file-based repositories.

__init__(data_module_path)

Initialize repository with path to data module.

class tburundigeo.infrastructure.repositories.py_file.PyFileProvinceRepository(data_module_path='tburundigeo.data.provinces')

Bases: BasePyFileRepository, IProvinceRepository

Repository implementation for provinces using Python files.

__init__(data_module_path='tburundigeo.data.provinces')

Initialize repository with path to data module.

get_all()

Get all provinces.

Return type:

List[Province]

get_by_code(code)

Get a province by its code.

Return type:

Optional[Province]

search_by_name(name_substring)

Search provinces by name substring.

Return type:

List[Province]

count()

Count total number of provinces.

Return type:

int

exists(code)

Check if a province with the given code exists.

Return type:

bool

class tburundigeo.infrastructure.repositories.py_file.PyFileCommuneRepository(data_module_path='tburundigeo.data.communes')

Bases: BasePyFileRepository, ICommuneRepository

Repository implementation for communes using Python files.

__init__(data_module_path='tburundigeo.data.communes')

Initialize repository with path to data module.

get_all()

Get all communes.

Return type:

List[Commune]

get_by_code(code)

Get a commune by its code.

Return type:

Optional[Commune]

search_by_name(name_substring)

Search communes by name substring.

Return type:

List[Commune]

search_by_capital(capital_substring)

Search communes by capital substring.

Return type:

List[Commune]

get_by_province(province_code)

Get all communes in a province.

Return type:

List[Commune]

count()

Count total number of communes.

Return type:

int

count_in_province(province_code)

Count communes in a specific province.

Return type:

int

exists(code)

Check if a commune with the given code exists.

Return type:

bool

class tburundigeo.infrastructure.repositories.py_file.PyFileZoneRepository(data_module_path='tburundigeo.data.zones')

Bases: BasePyFileRepository, IZoneRepository

Repository implementation for zones using Python files.

__init__(data_module_path='tburundigeo.data.zones')

Initialize repository with path to data module.

get_all()

Get all zones.

Return type:

List[Zone]

get_by_code(code)

Get a zone by its code.

Return type:

Optional[Zone]

search_by_name(name_substring)

Search zones by name substring.

Return type:

List[Zone]

get_by_commune(commune_code)

Get all zones in a commune.

Return type:

List[Zone]

count()

Count total number of zones.

Return type:

int

count_in_commune(commune_code)

Count zones in a specific commune.

Return type:

int

exists(code)

Check if a zone with the given code exists.

Return type:

bool

class tburundigeo.infrastructure.repositories.py_file.PyFileQuartierRepository(data_module_path='tburundigeo.data.quartiers')

Bases: BasePyFileRepository, IQuartierRepository

Repository implementation for quartiers using Python files.

__init__(data_module_path='tburundigeo.data.quartiers')

Initialize repository with path to data module.

get_all()

Get all quartiers.

Return type:

List[Quartier]

get_by_code(code)

Get a quartier by its code.

Return type:

Optional[Quartier]

search_by_name(name_substring)

Search quartiers by name substring.

Return type:

List[Quartier]

get_by_zone(zone_code)

Get all quartiers in a zone.

Return type:

List[Quartier]

count()

Count total number of quartiers.

Return type:

int

count_in_zone(zone_code)

Count quartiers in a specific zone.

Return type:

int

exists(code)

Check if a quartier with the given code exists.

Return type:

bool