ucrs 0.1.0__tar.gz

ucrs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Panos Mavrogiorgos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ucrs-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.3
+Name: ucrs
+Version: 0.1.0
+Summary: 
+Author: Panos Mavrogiorgos
+Author-email: pmav99@gmail.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: cartopy
+Provides-Extra: dev
+Provides-Extra: full
+Provides-Extra: gdal
+Provides-Extra: test
+Requires-Dist: cartopy ; extra == "cartopy"
+Requires-Dist: cartopy ; extra == "full"
+Requires-Dist: gdal ; extra == "full"
+Requires-Dist: gdal ; extra == "gdal"
+Requires-Dist: pyproj
+Requires-Dist: pyright (>=1.1.0) ; extra == "dev"
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: pytest (>=8.0.0) ; extra == "test"
+Requires-Dist: pytest-cov (>=4.1.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=4.1.0) ; extra == "test"
+Requires-Dist: pytest-xdist (>=3.5.0) ; extra == "dev"
+Requires-Dist: pytest-xdist (>=3.5.0) ; extra == "test"
+Description-Content-Type: text/markdown
+
+# UCRS - Unified CRS
+
+Working with geospatial data in Python often means juggling multiple libraries, each with its own CRS representation:
+- **pyproj** uses `pyproj.CRS`
+- **cartopy** uses `cartopy.crs.CRS` and `cartopy.crs.Projection`
+- **GDAL/osgeo** uses `osgeo.osr.SpatialReference`
+
+Converting between these formats is well
+[documented](https://pyproj4.github.io/pyproj/stable/crs_compatibility.html),
+but a bit tedious.
+
+UCRS solves this by providing a single wrapper class that accepts any CRS input
+and lazily converts to an instance of any library you need.
+
+## Usage
+
+```python
+from ucrs import UCRS
+
+# Create UCRS from any CRS representation
+ucrs = UCRS(4326)                         # EPSG code
+ucrs = UCRS("EPSG:4326")                  # EPSG string
+ucrs = UCRS(pyproj.CRS.from_epsg(4326))   # pyproj.CRS
+ucrs = UCRS(cartopy.crs.PlateCarree())    # cartopy CRS
+ucrs = UCRS(srs)                          # osgeo.osr.SpatialReference
+
+# Access different representations
+ucrs.proj        # Always available
+ucrs.cartopy     # Requires cartopy
+ucrs.osgeo       # Requires GDAL
+```
+
+## How It Works
+
+UCRS uses `pyproj.CRS` as its internal canonical representation. All conversions follow this pattern:
+
+1. **Input** → `pyproj.CRS` (during initialization)
+2. `pyproj.CRS` → **Output format** (via cached properties)
+
+Conversions are lazy and cached, so accessing `.proj`, `.cartopy`, or `.osgeo` multiple times returns the same object without re-conversion.
+
+## Requirements
+
+- Python 3.10+
+- pyproj (required)
+- cartopy (optional)
+- GDAL (optional)
+
+## Installation
+
+```bash
+# Minimal installation (pyproj only)
+pip install ucrs
+
+# With cartopy support
+pip install ucrs[cartopy]
+
+# With GDAL support
+pip install ucrs[gdal]
+
+# With all optional dependencies
+pip install ucrs[full]
+```
+
+
+## License
+
+MIT License - see LICENSE file for details.
+

ucrs-0.1.0/README.md

@@ -0,0 +1,68 @@
+# UCRS - Unified CRS
+
+Working with geospatial data in Python often means juggling multiple libraries, each with its own CRS representation:
+- **pyproj** uses `pyproj.CRS`
+- **cartopy** uses `cartopy.crs.CRS` and `cartopy.crs.Projection`
+- **GDAL/osgeo** uses `osgeo.osr.SpatialReference`
+
+Converting between these formats is well
+[documented](https://pyproj4.github.io/pyproj/stable/crs_compatibility.html),
+but a bit tedious.
+
+UCRS solves this by providing a single wrapper class that accepts any CRS input
+and lazily converts to an instance of any library you need.
+
+## Usage
+
+```python
+from ucrs import UCRS
+
+# Create UCRS from any CRS representation
+ucrs = UCRS(4326)                         # EPSG code
+ucrs = UCRS("EPSG:4326")                  # EPSG string
+ucrs = UCRS(pyproj.CRS.from_epsg(4326))   # pyproj.CRS
+ucrs = UCRS(cartopy.crs.PlateCarree())    # cartopy CRS
+ucrs = UCRS(srs)                          # osgeo.osr.SpatialReference
+
+# Access different representations
+ucrs.proj        # Always available
+ucrs.cartopy     # Requires cartopy
+ucrs.osgeo       # Requires GDAL
+```
+
+## How It Works
+
+UCRS uses `pyproj.CRS` as its internal canonical representation. All conversions follow this pattern:
+
+1. **Input** → `pyproj.CRS` (during initialization)
+2. `pyproj.CRS` → **Output format** (via cached properties)
+
+Conversions are lazy and cached, so accessing `.proj`, `.cartopy`, or `.osgeo` multiple times returns the same object without re-conversion.
+
+## Requirements
+
+- Python 3.10+
+- pyproj (required)
+- cartopy (optional)
+- GDAL (optional)
+
+## Installation
+
+```bash
+# Minimal installation (pyproj only)
+pip install ucrs
+
+# With cartopy support
+pip install ucrs[cartopy]
+
+# With GDAL support
+pip install ucrs[gdal]
+
+# With all optional dependencies
+pip install ucrs[full]
+```
+
+
+## License
+
+MIT License - see LICENSE file for details.

ucrs-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "ucrs"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Panos Mavrogiorgos",email = "pmav99@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pyproj"
+]
+
+[project.optional-dependencies]
+cartopy = ["cartopy"]
+gdal = ["gdal"]
+full = ["cartopy", "gdal"]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.5.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.5.0",
+    "pyright>=1.1.0",
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+pytest-cov = "*"
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+]
+testpaths = ["tests"]
+pythonpath = ["."]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "requires_cartopy: marks tests that require cartopy to be installed",
+    "requires_osgeo: marks tests that require osgeo/GDAL to be installed",
+]
+
+[tool.coverage.run]
+source = ["ucrs"]
+branch = true
+parallel = true
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]
+
+[tool.coverage.paths]
+source = ["ucrs.py"]
+

ucrs-0.1.0/ucrs.py

@@ -0,0 +1,162 @@
+
+"""Unified CRS (UCRS) class for seamless conversion between pyproj, cartopy, and osgeo."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import cast
+from typing import TypeAlias
+from typing import TYPE_CHECKING
+
+import pyproj
+
+try:
+    import cartopy.crs as ccrs
+    CARTOPY_AVAILABLE = True
+except ImportError:
+    CARTOPY_AVAILABLE = False  # pyright: ignore[reportConstantRedefinition]
+
+try:
+    import osgeo
+    from osgeo.osr import SpatialReference
+    OSGEO_AVAILABLE = True
+except ImportError:
+    OSGEO_AVAILABLE = False  # pyright: ignore[reportConstantRedefinition]
+
+# Type alias for accepted input types
+if TYPE_CHECKING:
+    import cartopy.crs as ccrs
+    from osgeo.osr import SpatialReference
+
+    CRSInput: TypeAlias = (
+        pyproj.CRS
+        | ccrs.CRS
+        | ccrs.Projection
+        | SpatialReference
+        | str
+        | int
+        | dict[str, str]
+    )
+
+
+class UCRS:
+    """Unified CRS for seamless conversion between pyproj, cartopy, and osgeo.
+
+    Parameters
+    ----------
+    obj : CRSInput
+        Can be anything that pyproj.crs.CRS.from_user_input() accepts, or
+        instances of cartopy.crs.CRS, cartopy.crs.Projection, pyproj.CRS,
+        or osgeo.osr.SpatialReference.
+
+    Examples
+    --------
+    >>> ucrs = UCRS(4326)
+    >>> ucrs = UCRS("EPSG:4326")
+    >>> ucrs = UCRS(pyproj.CRS.from_epsg(4326))
+
+    Access different CRS representations:
+    >>> proj_crs = ucrs.proj
+    >>> cart_crs = ucrs.cartopy  # if cartopy available
+    >>> osgeo_crs = ucrs.osgeo   # if osgeo available
+    """
+
+    def __init__(self, obj: CRSInput) -> None:
+        """Initialize UCRS from various CRS representations."""
+        self._original: CRSInput = obj
+
+        # Convert input to pyproj.CRS
+        match obj:
+            case pyproj.CRS():
+                self._pyproj_crs: pyproj.CRS = obj
+
+            case _ if OSGEO_AVAILABLE and isinstance(obj, SpatialReference):
+                # Convert from osgeo to pyproj
+                wkt: str
+                if osgeo.version_info.major < 3:
+                    wkt = cast(str, obj.ExportToWkt())
+                else:
+                    wkt = cast(str, obj.ExportToWkt(["FORMAT=WKT2_2018"]))
+                self._pyproj_crs = pyproj.CRS.from_wkt(wkt)
+
+            case _ if CARTOPY_AVAILABLE and isinstance(obj, (ccrs.CRS, ccrs.Projection)):
+                # cartopy.crs.CRS inherits from pyproj.CRS, so use from_user_input
+                self._pyproj_crs = pyproj.CRS.from_user_input(obj)
+
+            case _:
+                # Handle all other inputs via from_user_input (str, int, dict, etc.)
+                self._pyproj_crs = pyproj.CRS.from_user_input(obj)
+
+    @cached_property
+    def proj(self) -> pyproj.CRS:
+        """Return pyproj.CRS representation."""
+        return self._pyproj_crs
+
+    @cached_property
+    def cartopy(self) -> ccrs.CRS | ccrs.Projection:
+        """Return cartopy.crs.CRS or cartopy.crs.Projection representation.
+
+        Returns
+        -------
+        ccrs.CRS or ccrs.Projection
+            Geographic CRS returns ccrs.CRS, projected CRS returns ccrs.Projection.
+
+        Raises
+        ------
+        ImportError
+            If cartopy is not installed.
+        RuntimeError
+            If the CRS cannot be converted (e.g., WKT2 not available).
+        """
+        if not CARTOPY_AVAILABLE:
+            raise ImportError(
+                "cartopy is not installed. Install it with: pip install cartopy"
+            )
+
+        proj_crs = self.proj
+
+        # Check if geographic or projected
+        if proj_crs.is_geographic:
+            return ccrs.CRS(proj_crs)
+        else:
+            return ccrs.Projection(proj_crs)
+
+    @cached_property
+    def osgeo(self) -> SpatialReference:
+        """Return osgeo.osr.SpatialReference representation.
+
+        Returns
+        -------
+        SpatialReference
+            GDAL/OGR Spatial Reference object.
+
+        Raises
+        ------
+        ImportError
+            If osgeo is not installed.
+        """
+        if not OSGEO_AVAILABLE:
+            raise ImportError(
+                "osgeo (GDAL) is not installed. Install it with: pip install gdal"
+            )
+
+        from pyproj.enums import WktVersion
+
+        proj_crs = self.proj
+        osr_crs = SpatialReference()
+
+        # Convert from pyproj to osgeo
+        if osgeo.version_info.major < 3:
+            osr_crs.ImportFromWkt(proj_crs.to_wkt(WktVersion.WKT1_GDAL))
+        else:
+            osr_crs.ImportFromWkt(proj_crs.to_wkt())
+
+        return osr_crs
+
+    def __repr__(self) -> str:  # pyright: ignore[reportImplicitOverride]
+        """Return string representation."""
+        return f"UCRS({self.proj.name})"
+
+    def __str__(self) -> str:  # pyright: ignore[reportImplicitOverride]
+        """Return string representation."""
+        return str(self.proj)