API фильтров¶

@router.get("/filter_options", response_model=FilterOptions)
async def get_filter_options_endpoint(
    lang: str = Query("en", description="Language code for response (e.g., 'en', 'es')"),
    species_names: list[str] = Depends(get_species_cache),
    region_translations: dict = Depends(get_region_cache),
    data_source_translations: dict = Depends(get_data_source_cache),
):
    """Retrieves available filter options for species, regions, and data sources.

    This endpoint provides comprehensive filtering options that can be used across
    the CulicidaeLab application to filter disease data by various criteria.

    Args:
        lang: Language code for response localization (e.g., 'en' for English,
            'es' for Spanish). Defaults to 'en'.
        species_names: List of available mosquito species names for filtering.
        region_translations: Dictionary mapping region codes to translated names.
        data_source_translations: Dictionary mapping data source codes to translated names.

    Returns:
        FilterOptions: A structured response containing:
            - species: List of available mosquito species with their display names
            - regions: List of geographical regions with translated names
            - data_sources: List of data sources with translated names

    Example:
        >>> # Get filter options in English
        >>> response = await get_filter_options_endpoint("en", [...], {...}, {...})
        >>> print(response.species)  # List of species options
        >>> print(response.regions)  # List of region options

        >>> # Get filter options in Spanish
        >>> response = await get_filter_options_endpoint("es", [...], {...}, {...})
        >>> print(response.species)  # Lista de opciones de especies
    """
    return filter_service.get_filter_options(
        lang=lang,
        species_names=species_names,
        region_translations=region_translations,
        data_source_translations=data_source_translations,
    )

def get_data_source_cache(request: Request) -> dict[str, dict[str, str]]:
    """Dependency for the data sources translation cache.

    Provides access to the cached data source translations, which maps
    data source codes to translated names in multiple languages.

    Args:
        request (Request): The FastAPI request object containing app state.

    Returns:
        dict[str, dict[str, str]]: Dictionary mapping language codes to data
            source translation dictionaries.

    Example:
        >>> @app.get("/datasources/{language}")
        >>> async def get_data_sources_by_language(
        >>>     sources: dict = Depends(get_data_source_cache),
        >>>     language: str = "en"
        >>> ):
        >>>     return sources.get(language, {})
    """
    return get_cache(request, "DATASOURCE_TRANSLATIONS")

def get_region_cache(request: Request) -> dict[str, dict[str, str]]:
    """Dependency for the regions translation cache.

    Provides access to the cached region translations data, which maps
    region codes to translated names in multiple languages.

    Args:
        request (Request): The FastAPI request object containing app state.

    Returns:
        dict[str, dict[str, str]]: Dictionary mapping language codes to region
            translation dictionaries.

    Example:
        >>> @app.get("/regions/{language}")
        >>> async def get_regions_by_language(
        >>>     regions: dict = Depends(get_region_cache),
        >>>     language: str = "en"
        >>> ):
        >>>     return regions.get(language, {})
    """
    return get_cache(request, "REGION_TRANSLATIONS")

def get_species_cache(request: Request) -> list[str]:
    """Dependency for the species names list cache.

    Provides access to the cached list of all available species names
    for validation and autocomplete functionality.

    Args:
        request (Request): The FastAPI request object containing app state.

    Returns:
        list[str]: List of all available species names in the system.

    Example:
        >>> @app.get("/species")
        >>> async def get_all_species(
        >>>     species_list: list[str] = Depends(get_species_cache)
        >>> ):
        >>>     return {"species": species_list}
    """
    return get_cache(request, "SPECIES_NAMES")