rastr 0.2.0__tar.gz → 0.3.0__tar.gz

{rastr-0.2.0 → rastr-0.3.0}/.github/copilot-instructions.md

@@ -2,8 +2,7 @@
 
 ## General Guidelines
 
-- We are using Windows for development and Linux for deployment/CI. When running commands in terminal, use Windows commands for local development (like ";" instead of "&&" to separate commands) and Linux commands when running in CI environments.
-- Every time I ask you to fix linter errors and provide the error messages, update the Linter section in `.github/copilot-instructions.md` accordingly. Use concise, oneliner instruction. Ensure your future responses avoid repeating the same errors.
+- Every time you need to fix linter errors and provide the error messages, update the Linter section in `.github/copilot-instructions.md` accordingly. Use concise, oneliner instruction. Ensure your future responses avoid repeating the same errors.
 - Never create notebooks (ipynb files) unless asked explicitly.
 
 ## Testing  
@@ -11,29 +10,32 @@
 - Write unit tests using `pytest` inside `tests/`, structured based on `src/`.  
   - Example: `src/x/y/z` → `tests/x/y/test_z.py`  
 - Use test fixtures and group tests into classes when appropriate.  
+- When testing methods on classes, create nested test classes within the test class associated with the overall tested class (e.g., `TestContour` nested within `TestRasterModel` when testing the `contour` method of `RasterModel`).
 - After modifying a function, run its unit tests using pytest.
 - Run tests in virtual environment: `.\.venv\Scripts\activate; python -m pytest tests/path/to/test_file.py -v`
 
 ## Python
 
 - We use Python 3.12, so ensure that the code is compatible and up to date with this version.
-- When adding a new package that requires installation, list it under dependencies in `pyproject.toml`, then run `tasks\dev_sync.ps1`.
+- When adding a new package that requires installation, add it using `uv add <pkg>` so it gets properly declared.
+- When running a CLI such as `pytest`, always run it using `uv run`, e.g. `uv run pytest`.
+- Always run `uv run pre-commit run --all-files` to determine whether your code is compliant with the pre-commit hooks, including linters.
+- When importing internal modules, do not include the "src" folder in the import path as it is already defined in pyproject.toml
 - Limit line length to 100 characters.
-- We are using uv to install packages.
-- Never create functions that return more than one output value.
-- Never return tuples; use dictionaries for multiple return values.
+- Never create functions that return more than one output value (i.e. Never return tuples). Use dedicated return classes.
 - Do not add exceptions to functions unless explicitly requested.
 - Prefer to type hint strictly with the likes of `Literal["a", "b"]` instead of hinting broader types like `str`. This means the constraints on the input arguments to a function can reside in the type annotation rather than the docstring. Consider @validate_call (from pydantic import validate_call) to avoid boilerplate case-checking in such cases.
+- Prefer `isinstance` rather than `hasattr` for runtime type inference.
 - Refrain from backslash unescaping in raw strings (e.g., `r"\\path"` should be `r"\path"`).
 - When writing scripts, always use "Scripting Style" (Top-Level Code) unless stated otherwise. Write code directly at the module level instead of wrapping in functions or `if __name__ == "__main__":` blocks.
 - For scripts that need to access package files (e.g., templates, data files):
 
   ```python
   from importlib.resources import files
-  
+
   # Define package path as a module-level constant
   PACKAGE_PATH = files('package.subpackage.module')
-  
+
   # Use joinpath for accessing files
   file_path = Path(str(PACKAGE_PATH.joinpath('filename')))
   ```
@@ -45,23 +47,12 @@
 - Remove dtype specifications from all `Args:` sections (e.g., `text (str):` → `text:`)
 - Use "Args:" instead of "Parameters:" for consistency
 
-## Code Structure & Data Handling
-
-- Use value objects stored in `src/<package_name>/domain/value_object.py`, implemented using Pandera > v0.2 and Pydantic. Prefer passing DataFrame when possible.  
-- Use Pandera > v0.2 syntax, such as `DataFrameModel` when possible.
-- When importing internal modules, do not include the "src" folder in the import path as it is already defined in pyproject.toml
-
 ## Linter
 
-- For file-level linter suppressions, use `# ruff: noqa: RULE1, RULE2` format (not `# ruff noqa:`)
-- For line-level suppressions, use `# noqa: RULE1, RULE2` format
+- For file-level linter suppressions, use `# ruff: noqa: RULE1, RULE2` format (not `# ruff noqa:`). Avoid these where possible.
 - Use `pathlib.Path` for all filesystem operations instead of `os.path`. Path objects provide a more readable and maintainable object-oriented interface (e.g., `Path('dir') / 'file.txt'` instead of `os.path.join()`, `path.exists()` instead of `os.path.exists()`, etc.)
-- Exception messages must not use string literals directly, assign to variables first
-- Try-except patterns: Use bare `raise` in except blocks to preserve the original traceback, put return statements in the `else` block when using try-except (e.g., `try: result = process() except Exception: raise else: return result`)
 - Remove trailing whitespace from blank lines (W293)
 - Move statements after try blocks into else blocks when the statements depend on the try block's success (TRY300)
-- Use logging.exception instead of logging.error in except blocks (TRY400)
-- Do not include the exception object in logging.exception calls (TRY401)
 - Use keyword arguments for boolean parameters (FBT003) instead of positional arguments
 - Make boolean default arguments keyword-only using `*` to prevent positional passing (FBT002)
 - Avoid variable names that shadow Python builtins (A001)
@@ -70,15 +61,13 @@
 - Break long docstring lines at logical points to stay under the 88 character limit (E501)
 - Include a blank line between docstring summary and description (D205)
 - Add type annotations to function signatures (ANN201, ANN204)
-- Add `# noqa: N806` comment for scikit-learn convention of uppercase X in tests
 - Use `dict` instead of `Dict` for type annotation (UP006)
 - Avoid importing deprecated types like `typing.Dict` (UP035)
-- Remove unused code instead of commenting it out (ERA001)
-- Never use `from __future__ import annotations` in any file; Python 3.11+ does not require it.
+- Use `NDArray` without specific dtype parameter (e.g., `NDArray` instead of `NDArray[np.number]`) for generic array parameters
 
 ## Testing
 
-- Use `pytest` for testing, and ensure all tests are passing before committing changes.
+- Use `uv run pytest` for testing, and ensure all tests are passing before committing changes.
 - Do not perform equality checks with floating point values; instead, use `pytest.approx`.
 - Use only one assert statement per test function to ensure clarity and simplicity.
 

{rastr-0.2.0 → rastr-0.3.0}/.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
         with:
-          version: "0.8.3" # Sync with pyproject.toml
+          version: "0.7.13" # Sync with pyproject.toml
           enable-cache: true
 
       - name: Set up Python
@@ -51,10 +51,15 @@ jobs:
           uv pip install --system -r ci-requirements.txt
 
       - name: Run pre-commit
-        if: matrix.pre-commit
+        if: matrix.checks
         run: |
           uv run --frozen pre-commit run --all-files
 
+      - name: Run pyright
+        if: matrix.checks
+        run: |
+          uv run pyright
+
       - name: Run pytest
         uses: pavelzw/pytest-action@510c5e90c360a185039bea56ce8b3e7e51a16507 # v2.2.0
         if: matrix.pytest
@@ -77,13 +82,13 @@ jobs:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
         resolution: ["highest"]
-        pre-commit: [true]
+        checks: [true]
         pytest: [true]
         include:
           - os: "ubuntu-latest"
             python-version: "3.10"
             resolution: "lowest-direct"
-            pre-commit: false
+            checks: false
             pytest: true
 
   code-analysis:

{rastr-0.2.0 → rastr-0.3.0}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
         - name: Set up uv
           uses: astral-sh/setup-uv@3b9817b1bf26186f03ab8277bab9b827ea5cc254 # v3.2.0
           with:
-            version: "0.8.3" # Sync with pyproject.toml
+            version: "0.7.13" # Sync with pyproject.toml
 
         - name: "Set up Python"
           uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0

{rastr-0.2.0 → rastr-0.3.0}/.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
         entry: uv lock --offline
         files: ^(uv\.lock|pyproject\.toml|uv\.toml)$
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         always_run: true
         pass_filenames: false
@@ -40,7 +40,7 @@ repos:
         entry: uv sync --no-active --offline
         args: [--locked]
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         always_run: true
         pass_filenames: false
@@ -52,7 +52,7 @@ repos:
         entry: uv export --frozen --offline --quiet --no-default-groups 
             -o="requirements.txt"
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         pass_filenames: false
         require_serial: true
@@ -76,7 +76,7 @@ repos:
         entry: uv run --frozen --offline ruff format --force-exclude
         types_or: [python, pyi, jupyter]
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         pass_filenames: false
       - id: ruff-check
@@ -86,7 +86,7 @@ repos:
             --ignore "FIX"
         types_or: [python, pyi, jupyter]
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         pass_filenames: false
 
@@ -106,7 +106,7 @@ repos:
         name: nbstripout
         entry: uv run --frozen --offline nbstripout
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         files: .*\.(ipynb)$
         exclude: .*\.(example|template|keepoutput|)\.ipynb$
@@ -117,7 +117,7 @@ repos:
         name: deptry
         entry: uv run --frozen --offline deptry src
         additional_dependencies:
-          - uv==0.8.3
+          - uv==0.7.13
         language: python
         always_run: true
         pass_filenames: false

rastr-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+Thank you for your interest in contributing to Rastr!
+
+Since `rastr` is at early stages of development, please [ensure a GitHub Issue is opened](https://github.com/tonkintaylor/rastr/issues) before starting work on a new feature or bug fix. This helps to ensure that the feature is aligned with the project's goals and that there is no duplication of effort. Sometimes these Issues don't have enough guidance in them, so consider asking for some more guidance from the ticket creator before getting started.
+
+## Setup
+
+Most of the setup described below is automated. Try invoking the `tasks/dev_setup` command.
+
+### Development Environment
+
+[uv](https://github.com/astral-sh/uv) is required to install the development environment. You can install it using the instructions here:
+
+<https://docs.astral.sh/uv/getting-started/installation/>
+
+Then with the current working directory set to the project root, run:
+
+```shell
+uv sync
+```
+
+### Pre-commit Hooks
+
+This project uses the `pre-commit` framework to manage Git hooks. To install the hooks,
+run:
+
+```shell
+uv run pre-commit install
+```
+
+## Testing
+
+### Running the Test Suite
+
+To run the tests, simply run:
+
+```shell
+uv run pytest
+```
+
+### Writing Tests
+
+Tests are written using the `pytest` framework. The test suite is located in the `tests` directory. The tests are organized into subdirectories with a directory structure that mirrors the structure of the code being tested. This makes it easy to find the tests for a specific module or function.
+
+PRs should ideally include tests for any new features or bug fixes.
+
+### Fuzzing Test Leakage (a.k.a. Test Pollution)
+
+To diagnose test leakage, run this command:
+
+```shell
+uv run detect-test-pollution --fuzz --tests ./tests
+```
+
+and follow the prompts to bisect the tests.
+
+### Profiling Test collection speed
+
+To profile the speed of test collection (which is mostly related to import times), use `pyinstrument`:
+
+```shell
+uv run pyinstrument -m pytest --collect-only
+```
+
+## Version Control
+
+Git is used for version control, using
+[Trunk-based development](https://trunkbaseddevelopment.com/).
+
+It is recommended that you use signed commits, although this is not a requirement. Please see this guide from the VS Code project for instructions on how to do this: <https://github.com/microsoft/vscode/wiki/Commit-Signing>
+
+## Architecture
+
+This project uses [Import Linter](https://import-linter.readthedocs.io/en/stable/) to
+enforce a software architecture. Refer to the `[[tool.importlinter.contracts]]` sections
+in `pyproject.toml` to understand the structure of the project.

rastr-0.3.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: rastr
+Version: 0.3.0
+Summary: Geospatial Raster datatype library for Python.
+Project-URL: Source Code, https://github.com/tonkintaylor/rastr
+Project-URL: Bug Tracker, https://github.com/tonkintaylor/rastr/issues
+Project-URL: Releases, https://github.com/tonkintaylor/rastr/releases
+Project-URL: Source Archive, https://github.com/tonkintaylor/rastr/archive/46f802e7abd275eff61c73c5edc147d92966c886.zip
+Author-email: Tonkin & Taylor Limited <Sub-DisciplineData+AnalyticsStaff@tonkintaylor.co.nz>, Nathan McDougall <nmcdougall@tonkintaylor.co.nz>, Ben Karl <bkarl@tonkintaylor.co.nz>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: affine>=2.4.0
+Requires-Dist: branca>=0.8.1
+Requires-Dist: folium>=0.20.0
+Requires-Dist: geopandas>=1.1.1
+Requires-Dist: matplotlib>=3.10.5
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyproj>=3.7.1
+Requires-Dist: rasterio>=1.4.3
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: shapely>=2.1.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typing-extensions>=4.14.1
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/tonkintaylor/rastr/refs/heads/develop/docs/logo.svg"><br>
+</h1>
+
+# rastr
+
+[![PyPI Version](https://img.shields.io/pypi/v/rastr.svg)](<https://pypi.python.org/pypi/rastr>)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![usethis](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/usethis-python/usethis-python/main/assets/badge/v1.json)](https://github.com/usethis-python/usethis-python)
+
+A lightweight geospatial raster datatype library for Python focused on simplicity.
+
+## Overview
+
+`rastr` provides an intuitive interface for creating, reading, manipulating, and exporting geospatial raster data in Python.
+
+### Features
+
+- 🧮 **Complete raster arithmetic**: Full support for mathematical operations (`+`, `-`, `*`, `/`) between rasters and scalars.
+- 📊 **Flexible visualization**: Built-in plotting with matplotlib and interactive mapping with folium.
+- 🗺️ **Geospatial analysis tools**: Contour generation, Gaussian blurring, and spatial sampling.
+- 🛠️ **Data manipulation**: Fill NaN values, extrapolate missing data, and resample to different resolutions.
+- 🔗 **Seamless integration**: Works with GeoPandas, rasterio, and the broader Python geospatial ecosystem.
+- ↔️ **Vector-to-raster workflows**: Convert GeoDataFrame polygons, points, and lines to raster format.
+
+## Installation
+
+```bash
+# With uv
+uv add rastr
+
+# With pip
+pip install rastr
+```
+
+## Quick Start
+
+```python
+from pyproj.crs.crs import CRS
+from rasterio.transform import from_origin
+from rastr.create import full_raster
+from rastr.meta import RasterMeta
+from rastr.raster import RasterModel
+
+# Create an example raster
+raster = RasterModel.example()
+
+# Basic arithmetic operations
+doubled = raster * 2
+summed = raster + 10
+combined = raster + doubled
+
+# Create full rasters with specified values
+cell_size = 1.0
+empty_raster = full_raster(
+    RasterMeta(
+        cell_size=cell_size,
+        crs=CRS.from_epsg(2193),
+        transform=from_origin(0, 100, cell_size, cell_size),
+    ),
+    bounds=(0, 0, 100, 100),
+    fill_value=0.0,
+)
+
+# Visualize the data
+ax = raster.plot(cbar_label="Values")
+
+# Interactive web mapping (requires folium)
+m = raster.explore(opacity=0.8, colormap="plasma")
+
+# Sample values at specific coordinates
+xy_points = [(100.0, 200.0), (150.0, 250.0)]
+values = raster.sample(xy_points)
+
+# Generate contour lines
+contours = raster.contour(levels=[0.1, 0.5, 0.9], smoothing=True)
+
+# Apply spatial operations
+blurred = raster.blur(sigma=2.0)  # Gaussian blur
+filled = raster.extrapolate(method="nearest")  # Fill NaN values via nearest-neighbours
+resampled = raster.resample(new_cell_size=0.5)  # Change resolution
+
+# Export to file
+raster.to_file("output.tif")
+
+# Convert to GeoDataFrame for vector analysis
+gdf = raster.as_geodataframe(name="elevation")
+```
+
+## Limitations
+
+Current version limitations:
+
+- Only Single-band rasters are supported.
+- In-memory processing only (streaming support planned).
+- Square cells only (rectangular cell support planned).
+- Only float dtypes (integer support planned).
+
+### Contributing
+
+See the
+[CONTRIBUTING.md](https://github.com/usethis-python/usethis-python/blob/main/CONTRIBUTING.md)
+file.

rastr-0.3.0/README.md

@@ -0,0 +1,104 @@
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/tonkintaylor/rastr/refs/heads/develop/docs/logo.svg"><br>
+</h1>
+
+# rastr
+
+[![PyPI Version](https://img.shields.io/pypi/v/rastr.svg)](<https://pypi.python.org/pypi/rastr>)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![usethis](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/usethis-python/usethis-python/main/assets/badge/v1.json)](https://github.com/usethis-python/usethis-python)
+
+A lightweight geospatial raster datatype library for Python focused on simplicity.
+
+## Overview
+
+`rastr` provides an intuitive interface for creating, reading, manipulating, and exporting geospatial raster data in Python.
+
+### Features
+
+- 🧮 **Complete raster arithmetic**: Full support for mathematical operations (`+`, `-`, `*`, `/`) between rasters and scalars.
+- 📊 **Flexible visualization**: Built-in plotting with matplotlib and interactive mapping with folium.
+- 🗺️ **Geospatial analysis tools**: Contour generation, Gaussian blurring, and spatial sampling.
+- 🛠️ **Data manipulation**: Fill NaN values, extrapolate missing data, and resample to different resolutions.
+- 🔗 **Seamless integration**: Works with GeoPandas, rasterio, and the broader Python geospatial ecosystem.
+- ↔️ **Vector-to-raster workflows**: Convert GeoDataFrame polygons, points, and lines to raster format.
+
+## Installation
+
+```bash
+# With uv
+uv add rastr
+
+# With pip
+pip install rastr
+```
+
+## Quick Start
+
+```python
+from pyproj.crs.crs import CRS
+from rasterio.transform import from_origin
+from rastr.create import full_raster
+from rastr.meta import RasterMeta
+from rastr.raster import RasterModel
+
+# Create an example raster
+raster = RasterModel.example()
+
+# Basic arithmetic operations
+doubled = raster * 2
+summed = raster + 10
+combined = raster + doubled
+
+# Create full rasters with specified values
+cell_size = 1.0
+empty_raster = full_raster(
+    RasterMeta(
+        cell_size=cell_size,
+        crs=CRS.from_epsg(2193),
+        transform=from_origin(0, 100, cell_size, cell_size),
+    ),
+    bounds=(0, 0, 100, 100),
+    fill_value=0.0,
+)
+
+# Visualize the data
+ax = raster.plot(cbar_label="Values")
+
+# Interactive web mapping (requires folium)
+m = raster.explore(opacity=0.8, colormap="plasma")
+
+# Sample values at specific coordinates
+xy_points = [(100.0, 200.0), (150.0, 250.0)]
+values = raster.sample(xy_points)
+
+# Generate contour lines
+contours = raster.contour(levels=[0.1, 0.5, 0.9], smoothing=True)
+
+# Apply spatial operations
+blurred = raster.blur(sigma=2.0)  # Gaussian blur
+filled = raster.extrapolate(method="nearest")  # Fill NaN values via nearest-neighbours
+resampled = raster.resample(new_cell_size=0.5)  # Change resolution
+
+# Export to file
+raster.to_file("output.tif")
+
+# Convert to GeoDataFrame for vector analysis
+gdf = raster.as_geodataframe(name="elevation")
+```
+
+## Limitations
+
+Current version limitations:
+
+- Only Single-band rasters are supported.
+- In-memory processing only (streaming support planned).
+- Square cells only (rectangular cell support planned).
+- Only float dtypes (integer support planned).
+
+### Contributing
+
+See the
+[CONTRIBUTING.md](https://github.com/usethis-python/usethis-python/blob/main/CONTRIBUTING.md)
+file.

rastr-0.3.0/docs/index.md

@@ -0,0 +1,3 @@
+# rastr
+
+Welcome to the documentation for rastr.