yirgacheffe 1.7.9__py3-none-any.whl → 1.8.1__py3-none-any.whl

yirgacheffe/__init__.py

@@ -14,5 +14,7 @@ except ModuleNotFoundError:
 
 from ._core import read_raster, read_rasters, read_shape, read_shape_like, constant, read_narrow_raster
 from .constants import WGS_84_PROJECTION
+from .window import Area, MapProjection, Window
+from ._backends.enumeration import dtype as DataType
 
 gdal.UseExceptions()

yirgacheffe/_backends/enumeration.py

@@ -41,6 +41,26 @@ class operators(Enum):
     ISNAN = 36
 
 class dtype(Enum):
+    """Represents the type of data returned by a layer.
+
+    This enumeration defines the valid data types supported by Yirgacheffe, and is
+    what is returned by  calling `datatype` on a layer or expression, and can be
+    passed to `astype` to convert values between types.
+
+    Attributes:
+        Float32: 32 bit floating point value
+        Float64: 64 bit floating point value
+        Byte: Unsigned 8 bit integer value
+        Int8: Signed 8 bit integer value
+        Int16: Signed 16 bit integer value
+        Int32: Signed 32 bit integer value
+        Int64: Signed 64 bit integer value
+        UInt8: Unsigned 8 bit integer value
+        UInt16: Unsigned 16 bit integer value
+        UInt32: Unsigned 32 bit integer value
+        UInt64: Unsigned 64 bit integer value
+    """
+
     Float32 = gdal.GDT_Float32
     Float64 = gdal.GDT_Float64
     Byte = gdal.GDT_Byte

yirgacheffe/_backends/mlx.py

@@ -1,4 +1,6 @@
-from typing import Callable, Dict
+from __future__ import annotations
+
+from typing import Callable
 
 import numpy as np
 import mlx.core as mx # type: ignore
@@ -184,7 +186,7 @@ def backend_to_dtype(val):
 def astype_op(data, datatype):
     return data.astype(dtype_to_backend(datatype))
 
-operator_map : Dict[op,Callable] = {
+operator_map: dict[op, Callable] = {
     op.ADD: mx.array.__add__,
     op.SUB: mx.array.__sub__,
     op.MUL: mul_op,

yirgacheffe/_backends/numpy.py

@@ -1,4 +1,6 @@
-from typing import Callable, Dict
+from __future__ import annotations
+
+from typing import Callable
 
 import numpy as np
 import torch
@@ -122,7 +124,7 @@ def backend_to_dtype(val):
 def astype_op(data, datatype):
     return data.astype(dtype_to_backend(datatype))
 
-operator_map : Dict[op,Callable] = {
+operator_map: dict[op, Callable] = {
     op.ADD: np.ndarray.__add__,
     op.SUB: np.ndarray.__sub__,
     op.MUL: np.ndarray.__mul__,

yirgacheffe/_core.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 from pathlib import Path
-from typing import Optional, Sequence, Tuple, Union
+from typing import Sequence
 
 from .layers.area import UniformAreaLayer
 from .layers.base import YirgacheffeLayer
@@ -11,30 +13,29 @@ from .window import MapProjection
 from ._backends.enumeration import dtype as DataType
 
 def read_raster(
-    filename: Union[Path,str],
+    filename: Path | str,
     band: int = 1,
     ignore_nodata: bool = False,
 ) -> RasterLayer:
     """Open a raster file (e.g., GeoTIFF).
 
-    Parameters
-    ----------
-    filename : Path
-        Path of raster file to open.
-    band : int, default=1
-        For multi-band rasters, which band to use (defaults to first if not specified)
-    ignore_nodata : bool, default=False
-        If the GeoTIFF has a NODATA value, don't subsitute that value for NaN
-
-    Returns
-    -------
-    RasterLayer
-        Returns an layer representing the raster data.
+    Args:
+        filename: Path of raster file to open.
+        band: For multi-band rasters, which band to use (defaults to first if not specified).
+        ignore_nodata: If the GeoTIFF has a NODATA value, don't substitute that value for NaN.
+
+    Returns:
+        An layer representing the raster data.
+
+    Examples:
+        >>> import yirgacheffe as yg
+        >>> with yg.read_raster('test.tif') as layer:
+        ...     total = layer.sum()
     """
     return RasterLayer.layer_from_file(filename, band, ignore_nodata)
 
 def read_narrow_raster(
-    filename: Union[Path,str],
+    filename: Path | str,
     band: int = 1,
     ignore_nodata: bool = False,
 ) -> RasterLayer:
@@ -44,41 +45,35 @@ def read_narrow_raster(
     (e.g., a WGS84 map projection). For that case you can use this to load a raster that is 1 pixel wide and have
     it automatically expanded to act like a global raster in calculations.
 
-    Parameters
-    ----------
-    filename : Path
-        Path of raster file to open.
-    band : int, default=1
-        For multi-band rasters, which band to use (defaults to first if not specified)
-    ignore_nodata : bool, default=False
-        If the GeoTIFF has a NODATA value, don't subsitute that value for NaN
-
-    Returns
-    -------
-    RasterLayer
-        Returns an layer representing the raster data.
+    Args:
+        filename: Path of raster file to open.
+        band: For multi-band rasters, which band to use (defaults to first if not specified).
+        ignore_nodata: If the GeoTIFF has a NODATA value, don't substitute that value for NaN.
+
+    Returns:
+        An layer representing the raster data.
     """
     return UniformAreaLayer.layer_from_file(filename, band, ignore_nodata)
 
 def read_rasters(
-    filenames : Sequence[Union[Path,str]],
+    filenames : Sequence[Path | str],
     tiled: bool=False
 ) -> GroupLayer:
     """Open a set of raster files (e.g., GeoTIFFs) as a single layer.
 
-    Parameters
-    ----------
-    filenames : List[Path]
-        List of paths of raster files to open.
-    tiled : bool, default=False
-        If you know that the rasters for a regular tileset, then setting this flag allows
-        Yirgacheffe to perform certain optimisations that significantly improve performance for
-        this use case.
-
-    Returns
-    -------
-    GroupLayer
-        Returns an layer representing the raster data.
+    Args:
+        filenames: List of paths of raster files to open.
+        tiled: If you know that the rasters for a regular tileset, then setting this flag allows
+            Yirgacheffe to perform certain optimisations that significantly improve performance for
+            this use case.
+
+    Returns:
+        An layer representing the raster data.
+
+    Examples:
+        >>> import yirgacheffe as yg
+        >>> with yg.read_rasters(['tile_N10_E10.tif', 'tile_N20_E10.tif']) as all_tiles:
+        ...    ...
     """
     if not tiled:
         return GroupLayer.layer_from_files(filenames)
@@ -86,31 +81,28 @@ def read_rasters(
         return TiledGroupLayer.layer_from_files(filenames)
 
 def read_shape(
-    filename: Union[Path,str],
-    projection: Union[Optional[MapProjection],Optional[Tuple[str,Tuple[float,float]]]]=None,
-    where_filter: Optional[str] = None,
-    datatype: Optional[DataType] = None,
-    burn_value: Union[int,float,str] = 1,
+    filename: Path | str,
+    projection: MapProjection | tuple[str, tuple[float, float]] | None = None,
+    where_filter: str | None = None,
+    datatype: DataType | None = None,
+    burn_value: int | float | str = 1,
 ) -> VectorLayer:
     """Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).
 
-    Parameters
-    ----------
-    filename : Path
-        Path of raster file to open.
-    projection: MapProjection or tuple, optional
-        The map projection to use,
-    where_filter : str, optional
-        For use with files with many entries (e.g., GPKG), applies this filter to the data.
-    datatype: DataType, default=DataType.Byte
-        Specify the data type of the raster data generated.
-    burn_value: int or float or str, default=1
-        The value of each pixel in the polygon.
-
-    Returns
-    -------
-    VectorLayer
-        Returns an layer representing the vector data.
+    Args:
+        filename: Path of vector file to open.
+        projection: The map projection to use.
+        where_filter: For use with files with many entries (e.g., GPKG), applies this filter to the data.
+        datatype: Specify the data type of the raster data generated.
+        burn_value: The value of each pixel in the polygon.
+
+    Returns:
+        An layer representing the vector data.
+
+    Examples:
+        >>> import yirgacheffe as yg
+        >>> with yg.read_shape('range.gpkg') as layer:
+        ...    ...
     """
 
     if projection is not None:
@@ -127,32 +119,24 @@ def read_shape(
     )
 
 def read_shape_like(
-    filename: Union[Path,str],
+    filename: Path | str,
     like: YirgacheffeLayer,
-    where_filter: Optional[str] = None,
-    datatype: Optional[DataType] = None,
-    burn_value: Union[int,float,str] = 1,
+    where_filter: str | None = None,
+    datatype: DataType | None = None,
+    burn_value: int | float | str = 1,
 ) -> VectorLayer:
     """Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).
 
-    Parameters
-    ----------
-    filename : Path
-        Path of raster file to open.
-    like: YirgacheffeLayer
-        Another layer that has a projection and pixel scale set. This layer will
-        use the same projection and pixel scale as that one.
-    where_filter : str, optional
-        For use with files with many entries (e.g., GPKG), applies this filter to the data.
-    datatype: DataType, default=DataType.Byte
-        Specify the data type of the raster data generated.
-    burn_value: int or float or str, default=1
-        The value of each pixel in the polygon.
-
-    Returns
-    -------
-    VectorLayer
-        Returns an layer representing the vector data.
+    Args:
+        filename: Path of vector file to open.
+        like: Another layer that has a projection and pixel scale set. This layer will
+            use the same projection and pixel scale as that one.
+        where_filter: For use with files with many entries (e.g., GPKG), applies this filter to the data.
+        datatype: Specify the data type of the raster data generated.
+        burn_value: The value of each pixel in the polygon.
+
+    Returns:
+        An layer representing the vector data.
     """
     return VectorLayer.layer_from_file_like(
         filename,
@@ -162,7 +146,7 @@ def read_shape_like(
         burn_value,
     )
 
-def constant(value: Union[int,float]) -> ConstantLayer:
+def constant(value: int | float) -> ConstantLayer:
     """Generate a layer that has the same value in all pixels regardless of scale, projection, and area.
 
     Generally this should not be necessary unless you must have the constant as the first term in an
@@ -170,14 +154,10 @@ def constant(value: Union[int,float]) -> ConstantLayer:
     constant is the first term in the expression it must be wrapped by this call otherwise Python will
     not know that it should be part of the Yirgacheffe expression.
 
-    Parameters
-    ----------
-    value : int or float
-        The value to be in each pixel of the expression term.
+    Args:
+        value: The value to be in each pixel of the expression term.
 
-    Returns
-    -------
-    ConstantLayer
-        Returns a constant layer of the provided value.
+    Returns:
+        A constant layer of the provided value.
     """
     return ConstantLayer(value)

yirgacheffe/_operators.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import logging
 import math
 import multiprocessing
@@ -12,7 +14,7 @@ from enum import Enum
 from multiprocessing import Semaphore, Process
 from multiprocessing.managers import SharedMemoryManager
 from pathlib import Path
-from typing import Callable, Dict, List, Optional, Union
+from typing import Callable
 
 import deprecation
 import numpy as np
@@ -265,10 +267,10 @@ class LayerMathMixin:
 
     def to_geotiff(
         self,
-        filename: Union[Path,str],
+        filename: Path | str,
         and_sum: bool = False,
-        parallelism:Optional[Union[int,bool]]=None
-    ) -> Optional[float]:
+        parallelism: int | bool | None = None
+    ) -> float | None:
         return LayerOperation(self).to_geotiff(filename, and_sum, parallelism)
 
     def sum(self):
@@ -398,7 +400,7 @@ class LayerOperation(LayerMathMixin):
     def area(self) -> Area:
         return self._get_operation_area(self.map_projection)
 
-    def _get_operation_area(self, projection: Optional[MapProjection]) -> Area:
+    def _get_operation_area(self, projection: MapProjection | None) -> Area:
         lhs_area = self.lhs._get_operation_area(projection)
         try:
             rhs_area = self.rhs._get_operation_area(projection)
@@ -482,7 +484,7 @@ class LayerOperation(LayerMathMixin):
 
     @property
     def datatype(self) -> DataType:
-        internal_types: List[DataType] = [
+        internal_types: list[DataType] = [
             self.lhs.datatype
         ]
         if self.rhs is not None:
@@ -511,7 +513,7 @@ class LayerOperation(LayerMathMixin):
         return projection
 
     @property
-    def map_projection(self) -> Optional[MapProjection]:
+    def map_projection(self) -> MapProjection | None:
         try:
             projection = self.lhs.map_projection
         except AttributeError:
@@ -530,7 +532,7 @@ class LayerOperation(LayerMathMixin):
         projection: MapProjection,
         index: int,
         step: int,
-        target_window:Optional[Window]=None
+        target_window: Window | None = None
     ):
 
         if self.buffer_padding:
@@ -607,7 +609,7 @@ class LayerOperation(LayerMathMixin):
                 res = chunk_max
         return res
 
-    def save(self, destination_layer, and_sum=False, callback=None, band=1) -> Optional[float]:
+    def save(self, destination_layer, and_sum=False, callback=None, band=1) -> float | None:
         """
         Calling save will write the output of the operation to the provied layer.
         If you provide sum as true it will additionall compute the sum and return that.
@@ -723,7 +725,7 @@ class LayerOperation(LayerMathMixin):
         callback=None,
         parallelism=None,
         band=1
-    ) -> Optional[float]:
+    ) -> float | None:
         assert (destination_layer is not None) or and_sum
         try:
             computation_window = self.window
@@ -763,7 +765,7 @@ class LayerOperation(LayerMathMixin):
                     or (computation_window.ysize != destination_window.ysize):
                 raise ValueError("Destination raster window size does not match input raster window size.")
 
-            np_type_map : Dict[int, np.dtype] = {
+            np_type_map: dict[int, np.dtype] = {
                 gdal.GDT_Byte:    np.dtype('byte'),
                 gdal.GDT_Float32: np.dtype('float32'),
                 gdal.GDT_Float64: np.dtype('float64'),
@@ -882,7 +884,7 @@ class LayerOperation(LayerMathMixin):
         callback=None,
         parallelism=None,
         band=1
-    ) -> Optional[float]:
+    ) -> float | None:
         if destination_layer is None:
             raise ValueError("Layer is required")
         return self._parallel_save(destination_layer, and_sum, callback, parallelism, band)
@@ -892,25 +894,20 @@ class LayerOperation(LayerMathMixin):
 
     def to_geotiff(
         self,
-        filename: Union[Path,str],
+        filename: Path | str,
         and_sum: bool = False,
-        parallelism:Optional[Union[int,bool]] = None
-    ) -> Optional[float]:
+        parallelism: int | bool | None = None
+    ) -> float | None:
         """Saves a calculation to a raster file, optionally also returning the sum of pixels.
 
-        Parameters
-        ----------
-        filename : Path
-            Path of the raster to save the result to.
-        and_sum : bool, default=False
-            If true then the function will also calculate the sum of the raster as it goes and return that value.
-        parallelism : int or bool, optional, default=None
-            If passed, attempt to use multiple CPU cores up to the number provided, or if set to True, yirgacheffe
-            will pick a sensible value.
-
-        Returns
-        -------
-        float, optional
+        Args:
+            filename: Path of the raster to save the result to.
+            and_sum: If true then the function will also calculate the sum of the raster as it goes and return
+                that value.
+            parallelism: If passed, attempt to use multiple CPU cores up to the number provided, or if set to True,
+                yirgacheffe will pick a sensible value.
+
+        Returns:
             Either returns None, or the sum of the pixels in the resulting raster if `and_sum` was specified.
         """
 

yirgacheffe/layers/area.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 from math import ceil, floor
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any
 
 import numpy
 from osgeo import gdal
@@ -19,7 +21,7 @@ class UniformAreaLayer(RasterLayer):
     """
 
     @staticmethod
-    def generate_narrow_area_projection(source_filename: Union[Path,str], target_filename: Union[Path,str]) -> None:
+    def generate_narrow_area_projection(source_filename: Path | str, target_filename: Path | str) -> None:
         source = gdal.Open(source_filename, gdal.GA_ReadOnly)
         if source is None:
             raise FileNotFoundError(source_filename)
@@ -57,7 +59,7 @@ class UniformAreaLayer(RasterLayer):
                 return False
         return True
 
-    def __init__(self, dataset, name: Optional[str] = None, band: int = 1, ignore_nodata: bool = False):
+    def __init__(self, dataset, name: str | None = None, band: int = 1, ignore_nodata: bool = False):
         if dataset.RasterXSize > 1:
             raise ValueError("Expected a shrunk dataset")
         self.databand = dataset.GetRasterBand(1).ReadAsArray(0, 0, 1, dataset.RasterYSize)

yirgacheffe/layers/base.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import Any, Optional, Sequence, Tuple
+from typing import Any, Sequence
 
 import deprecation
 
@@ -17,17 +17,17 @@ class YirgacheffeLayer(LayerMathMixin):
 
     def __init__(self,
         area: Area,
-        projection: Optional[MapProjection],
-        name: Optional[str] = None
+        projection: MapProjection | None,
+        name: str | None = None
     ):
         # This is just to catch code that uses the old private API
         if projection is not None and not isinstance(projection, MapProjection):
             raise TypeError("projection value of wrong type")
 
         self._underlying_area = area
-        self._active_area: Optional[Area] = None
+        self._active_area: Area | None = None
         self._projection = projection
-        self._window: Optional[Window] = None
+        self._window: Window | None = None
         self.name = name
 
         self.reset_window()
@@ -48,7 +48,7 @@ class YirgacheffeLayer(LayerMathMixin):
         pass
 
     @property
-    def _raster_dimensions(self) -> Tuple[int,int]:
+    def _raster_dimensions(self) -> tuple[int, int]:
         raise AttributeError("Does not have raster")
 
     @property
@@ -62,7 +62,7 @@ class YirgacheffeLayer(LayerMathMixin):
         current_version=__version__,
         details="Use `map_projection` instead."
     )
-    def projection(self) -> Optional[str]:
+    def projection(self) -> str | None:
         if self._projection:
             return self._projection.name
         else:
@@ -75,14 +75,14 @@ class YirgacheffeLayer(LayerMathMixin):
         current_version=__version__,
         details="Use `map_projection` instead."
     )
-    def pixel_scale(self) -> Optional[PixelScale]:
+    def pixel_scale(self) -> PixelScale | None:
         if self._projection:
             return PixelScale(self._projection.xstep, self._projection.ystep)
         else:
             return None
 
     @property
-    def map_projection(self) -> Optional[MapProjection]:
+    def map_projection(self) -> MapProjection | None:
         return self._projection
 
     @property
@@ -92,7 +92,7 @@ class YirgacheffeLayer(LayerMathMixin):
         else:
             return self._underlying_area
 
-    def _get_operation_area(self, projection: Optional[MapProjection]=None) -> Area:
+    def _get_operation_area(self, projection: MapProjection | None = None) -> Area:
         if self._projection is not None and projection is not None and self._projection != projection:
             raise ValueError("Calculation projection does not match layer projection")
         return self.area
@@ -153,7 +153,7 @@ class YirgacheffeLayer(LayerMathMixin):
         )
 
     @property
-    def geo_transform(self) -> Tuple[float, float, float, float, float, float]:
+    def geo_transform(self) -> tuple[float, float, float, float, float, float]:
         if self._projection is None:
             raise AttributeError("No geo transform for layers without explicit pixel scale")
         return (
@@ -320,26 +320,19 @@ class YirgacheffeLayer(LayerMathMixin):
     def read_array(self, x: int, y: int, width: int, height: int) -> Any:
         """Reads data from the layer based on the current reference window.
 
-        Arguments
-        ---------
-        x : int
-            X axis offset for reading
-        y : int
-            Y axis offset for reading
-        width : int
-            Width of data to read
-        height : int
-            Height of data to read
-
-        Results
-        -------
-        Any
+        Args:
+            x: X axis offset for reading
+            y: Y axis offset for reading
+            width: Width of data to read
+            height: Height of data to read
+
+        Returns:
             An array of values from the layer.
         """
         res = self._read_array(x, y, width, height)
         return backend.demote_array(res)
 
-    def latlng_for_pixel(self, x_coord: int, y_coord: int) -> Tuple[float,float]:
+    def latlng_for_pixel(self, x_coord: int, y_coord: int) -> tuple[float, float]:
         """Get geo coords for pixel. This is relative to the set view window."""
         if self._projection is None or "WGS 84" not in self._projection.name:
             raise NotImplementedError("Not yet supported for other projections")
@@ -348,7 +341,7 @@ class YirgacheffeLayer(LayerMathMixin):
             (x_coord * self._projection.xstep) + self.area.left
         )
 
-    def pixel_for_latlng(self, lat: float, lng: float) -> Tuple[int,int]:
+    def pixel_for_latlng(self, lat: float, lng: float) -> tuple[int, int]:
         """Get pixel for geo coords. This is relative to the set view window.
         Result is rounded down to nearest pixel."""
         if self._projection is None or "WGS 84" not in self._projection.name:

yirgacheffe/layers/constant.py

@@ -1,4 +1,6 @@
-from typing import Any, Union
+from __future__ import annotations
+
+from typing import Any
 
 from ..window import Area, MapProjection, PixelScale, Window
 from .base import YirgacheffeLayer
@@ -8,7 +10,7 @@ from .._backends.enumeration import dtype as DataType
 class ConstantLayer(YirgacheffeLayer):
     """This is a layer that will return the identity value - can be used when an input layer is
     missing (e.g., area) without having the calculation full of branches."""
-    def __init__(self, value: Union[int,float]): # pylint: disable=W0231
+    def __init__(self, value: int | float): # pylint: disable=W0231
         area = Area.world()
         super().__init__(area, None)
         self.value = float(value)