Source code for shapelib.factories.geo_file_factory

from pathlib import Path
from typing import Any

from shapelib.core.geometries.base import BaseShapes
from shapelib.core.handlers.geo_file_handler import GeoFileHandler




class GeoFileFactory:
    """
    A factory class for creating file handlers for geospatial files.

    This class is responsible for registering handlers for different file formats
    and retrieving the appropriate handler based on a file's extension.

    Attributes
    ----------
    _handlers : dict
        A dictionary that maps file extensions (e.g., ".shp", ".geojson") to their
        corresponding handler classes.

    Methods
    -------
    register_handler(file_extension, handler_class)
        Registers a new handler class for a specific file extension.
    get_handler(path)
        Retrieves the appropriate file handler for the given file path based on its
        extension.
    """

    _handlers: dict[str, type[GeoFileHandler]] = {}



    @classmethod
    def register_handler(cls, file_extension: str, handler_class: type[GeoFileHandler]) -> None:
        """
        Register a handler for a specific file extension.

        This method associates a file extension (e.g., ".shp", ".geojson") with a handler
        class. When a file with the registered extension is processed, the corresponding
        handler class will be used.

        Parameters
        ----------
        file_extension : str
            The file extension that the handler class is responsible for (e.g., ".shp").
        handler_class : Type[GeoFileHandler]
            The handler class to be registered for the specified file extension.

        Returns
        -------
        None
            The method registers the handler in the `_handlers` dictionary.

        Examples
        --------
        >>> GeoFileFactory.register_handler(".shp", ShapefileHandler)
        Adding support for .shp files through ShapefileHandler
        """
        print(
            "Adding support for",
            file_extension,
            "files through",
            handler_class.__name__,
        )
        cls._handlers[file_extension] = handler_class




    @classmethod
    def get_handler(cls, path: Path, keep_z: bool = False, **kwargs: Any) -> BaseShapes:
        """
        Retrieve the appropriate file handler for the given file path based on its
        extension.

        This method determines the file extension of the provided path and retrieves
        the corresponding handler class. If a handler for the file extension is found,
        the method creates an instance of the handler and returns it.

        Parameters
        ----------
        path : Path
            The path to the geospatial file.
        keep_z : bool, optional
            Keep the Z coordinate of 3-D geometries (default False). Handed to the
            handler, never to the file reader underneath it.
        **kwargs : Any
            Additional arguments passed to the handler's reader.

        Returns
        -------
        GeoFileHandler
            An instance of the appropriate handler for the file.

        Raises
        ------
        ValueError
            If the file extension does not have a registered handler.

        Examples
        --------
        >>> handler = GeoFileFactory.get_handler(Path("/path/to/file.shp"))
        >>> handler.create_obj()  # Creates an object based on the shapefile's data.
        """
        file_extension = path.suffix
        handler_class = cls._handlers.get(file_extension)

        if handler_class is None:
            raise ValueError(f"File format '{file_extension}' is not supported.")

        handler = handler_class(path)
        handler.keep_z = keep_z
        return handler.create_obj(**kwargs)