exeqpdal 0.1.0a1__tar.gz

exeqpdal-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: Lint, type check, tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff format
+        run: ruff format . --check
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy exeqpdal
+
+      - name: Pytest (unit)
+        run: pytest -m "not integration" tests/
+
+      - name: Build package
+        run: |
+          rm -rf dist/
+          python -m build
+          twine check dist/*

exeqpdal-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff format
+        run: ruff format . --check
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy exeqpdal
+
+      - name: Pytest (unit)
+        run: pytest -m "not integration" tests/
+
+      - name: Build distribution
+        run: |
+          rm -rf dist/
+          python -m build
+          twine check dist/*
+
+      - name: Upload distribution artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/exeqpdal/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distribution artifact
+        uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish release
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

exeqpdal-0.1.0a1/.gitignore

@@ -0,0 +1,149 @@
+# Python Artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Build & Packaging Outputs
+.Python
+*.egg
+*.egg-info/
+*.manifest
+*.spec
+*.zip
+.eggs/
+.installed.cfg
+MANIFEST
+build/
+builds/
+develop-eggs/
+dist/
+downloads/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+share/python-wheels/
+var/
+wheels/
+
+# Dependency Management
+.pdm-build/
+.pdm-python
+.pdm.toml
+Pipfile.lock
+poetry.lock
+uv.lock
+__pypackages__/
+
+# Virtual Environments
+.env
+.venv/
+ENV/
+env/
+env.bak/
+venv/
+venv.bak/
+
+# Testing & Coverage
+.coverage
+.coverage.*
+.hypothesis/
+.nox/
+.pytest_cache/
+.tox/
+.cache
+cover/
+coverage.*
+coverage.xml
+htmlcov/
+nosetests.xml
+*.cover
+*.py,cover
+
+# Type Checkers & Linters
+.dmypy.json
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+dmypy.json
+
+# Editor & IDE Settings
+.vscode/
+
+# Jupyter / IPython Artifacts
+.ipynb_checkpoints
+ipython_config.py
+profile_default/
+
+# Logs & Temporary Files
+*.log
+*~
+.*.swp
+pip-delete-this-directory.txt
+pip-log.txt
+
+# Framework & Task Queue State
+celerybeat-schedule
+celerybeat.pid
+db.sqlite3
+db.sqlite3-journal
+instance/
+local_settings.py
+.scrapy
+.webassets-cache
+
+# Documentation Outputs
+docs/_build/
+/site
+
+# Translations
+*.mo
+*.pot
+
+# Miscellaneous Python
+*.sage.py
+
+# PyPI Credentials
+.pypirc
+
+# QGIS Plugin Artifacts
+*_ui.py
+*.qgs~
+*.qgz~
+resources.py
+symbology-style.db
+
+# Operating System Artifacts
+.DS_Store
+
+# Project-Specific Artifacts
+.archive/
+*/.archive/
+**/.archive/
+.backup/
+*/.backup/
+**/.backup/
+.conf/
+.pwsh/
+.python-version
+.specify/
+AGENTS.m
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+logs/
+
+# Workflow Automation
+.claude/
+.gemini/
+.remote-workflow/
+docs/claude/
+docs/gemini/
+
+# LAZ-to-writers Test Outputs
+tests/laz_to_writers/outputs/*
+!tests/laz_to_writers/outputs/.gitkeep
+!tests/laz_to_writers/outputs/README.md

exeqpdal-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0a1] - 2025-10-16
+
+`exeqpdal 0.1.0a1` is under active development and has not yet been published to PyPI.
+
+### Added
+- Pipeline orchestration with the `Pipeline` class, including `validate`, metadata access, and point
+  count parsing.
+- Stage factories covering the most frequently used PDAL drivers (~40 readers, 80+ filters, 25
+  writers).
+- High-level wrappers for PDAL CLI applications: `info`, `translate`/`convert`, `merge`, `split`,
+  `tile`, and `tindex`.
+- PDAL discovery and configuration utilities (`set_pdal_path`, `get_pdal_version`, `validate_pdal`,
+  `set_verbose`).
+- Custom exception hierarchy (`PDALError`, `PipelineError`, `PDALExecutionError`, etc.).
+- Packaging metadata with `py.typed` for downstream type checkers.
+
+### Testing
+- Pytest suite covering pipeline assembly, stage factories, and application wrappers.
+- Integration tests gated by `@pytest.mark.integration` and the `EXEQPDAL_TEST_DATA` fixture
+  directory.
+- Strict typing enforced via `mypy --strict`.
+
+### Tooling
+- Added GitHub Actions for CI (`ci.yml`) and publishing (`publish.yml`), plus a release guide
+  (`docs/publishing.md`) and supporting development dependencies.
+
+### Known Limitations
+- `Pipeline.arrays` is not yet implemented and currently returns an empty list.
+- Stage factories do not yet expose every PDAL driver; unsupported stages can be invoked with custom
+  JSON.
+- First PyPI upload is still pending while the initial alpha stabilises.
+
+---

exeqpdal-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to exeqpdal
+
+Thank you for your interest in contributing to `exeqpdal`! All contributions are welcome, from bug reports to new features.
+
+## Development Setup
+
+1.  Fork and clone the repository:
+
+    ```bash
+    git clone https://github.com/YOUR-USERNAME/exeqpdal.git
+    cd exeqpdal
+    ```
+
+2.  Create a virtual environment and install dependencies. We recommend
+    [`uv`](https://github.com/astral-sh/uv):
+
+    ```bash
+    uv pip install -e ".[dev]"
+    ```
+
+    When `uv` is not available, fall back to standard tooling:
+
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install -e ".[dev]"
+    ```
+
+3.  Verify the toolchain by running the default formatting, linting, typing, and test commands:
+
+    ```bash
+    ruff format .
+    ruff check .
+    mypy exeqpdal
+    pytest tests/
+    ```
+
+    Integration tests require the PDAL CLI and LAZ/COPC test datasets in `tests/test_data_laz/`.
+    Tests automatically skip when PDAL or test data are unavailable. Add `-m "not integration"`
+    to skip integration tests entirely.
+
+## Development Workflow
+
+-   Create a new branch for your changes.
+-   Make your changes and add tests for them.
+-   Make sure all tests pass, including the linters and type checkers:
+
+    ```bash
+    ruff format .
+    ruff check .
+    mypy exeqpdal
+    pytest tests/
+    ```
+
+    Use `pytest -m "not integration"` to skip tests requiring PDAL and test datasets. Keep test
+    outputs (especially under `tests/laz_to_writers/outputs/`) out of commits.
+
+-   Commit your changes using the existing Conventional Commit prefixes (for example,
+    `fix: handle PDAL path lookup`) and push them to your fork.
+-   Open a pull request that explains the scenario, any data prerequisites, and how you validated the
+    change.
+
+## Release Management
+
+Maintainers preparing a PyPI upload should follow the checklist in `docs/publishing.md`. It covers
+versioning, changelog updates, local validation (`ruff`, `mypy`, `pytest`, `python -m build`), and
+the GitHub Actions workflow that publishes releases through PyPI's Trusted Publisher integration.
+
+## Code Style
+
+This project uses `ruff` for both formatting and linting with the settings defined in
+`pyproject.toml`. Four-space indentation, 100-character lines, and double-quoted strings are applied
+by `ruff format`.
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the MIT License.

exeqpdal-0.1.0a1/LICENSE

@@ -0,0 +1,34 @@
+MIT License
+
+Copyright (c) 2025 exeqpdal contributors
+
+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.
+
+---
+
+This project includes software developed by the PDAL project (https://pdal.io/).
+Copyright (c) 2025, Hobu, Inc. (howard@hobu.co)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+*   Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+*   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

exeqpdal-0.1.0a1/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: exeqpdal
+Version: 0.1.0a1
+Summary: Python API for executing PDAL CLI commands with native syntax support
+Project-URL: Homepage, https://github.com/elgorrion/exeqpdal
+Project-URL: Documentation, https://github.com/elgorrion/exeqpdal#readme
+Project-URL: Repository, https://github.com/elgorrion/exeqpdal
+Project-URL: Bug Tracker, https://github.com/elgorrion/exeqpdal/issues
+Project-URL: Changelog, https://github.com/elgorrion/exeqpdal/blob/main/CHANGELOG.md
+Project-URL: Source Code, https://github.com/elgorrion/exeqpdal
+Author-email: ElGorrion <elgorrion.eu@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: geospatial,lidar,pdal,pointcloud,qgis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.26.4
+Provides-Extra: dev
+Requires-Dist: build>=1.3.0; extra == 'dev'
+Requires-Dist: mypy>=1.18.2; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.4.2; extra == 'dev'
+Requires-Dist: ruff>=0.14.0; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# exeqpdal
+
+Alpha-stage, typed Python API for driving the PDAL command-line interface (CLI).
+
+`exeqpdal` focuses on being a reliable subprocess wrapper around the PDAL CLI so that Python
+projects – including QGIS plugins – can assemble and run PDAL pipelines without shipping
+C++ bindings. The current release series is `0.1.0a*` and is still stabilising APIs and
+coverage.
+
+## Features
+
+-   **Pythonic pipelines** – build PDAL JSON using `Reader`, `Filter`, and `Writer`
+    factories chained with the `|` operator, then execute with `Pipeline`.
+-   **CLI-first design** – no native extensions; every operation delegates to the PDAL
+    executable via `subprocess.run`.
+-   **Strict typing** – the package ships `py.typed`, is developed under `mypy --strict`,
+    and exposes typed factory helpers.
+-   **Convenience apps** – wrappers for PDAL tools such as `info`, `translate`, `merge`, `split`,
+    `tile`, and `tindex`.
+-   **Broad stage coverage** – factories currently expose ~40 readers, 80+ filters, and 25 writers.
+    Coverage is expanding; unsupported drivers can still be addressed through custom JSON.
+-   **QGIS-friendly** – automatic PDAL discovery checks PATH, `PDAL_EXECUTABLE`, and
+    common QGIS 3.4x Windows installs.
+
+## Prerequisites
+
+-   Python 3.12+
+-   PDAL CLI installed and accessible (system PATH, `PDAL_EXECUTABLE`, or detected in QGIS on
+    Windows)
+
+## Installation
+
+The first public alpha will be published to PyPI using GitHub Actions. Once the release is
+live, you can install it directly (include `--pre` while the project is in alpha):
+
+```bash
+pip install --pre exeqpdal
+```
+
+Until the package is uploaded, install from a local clone:
+
+```bash
+# From the project root
+pip install -e .
+
+# Or install with development extras
+uv pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Convert a File
+
+```python
+import exeqpdal as pdal
+
+pdal.translate("input.las", "output.laz")
+```
+
+### Filter Ground Points
+
+```python
+import exeqpdal as pdal
+
+pipeline = (
+    pdal.Reader.las("input.las")
+    | pdal.Filter.range(limits="Classification[2:2]")
+    | pdal.Writer.las("ground_only.las")
+)
+pipeline.execute()
+```
+
+### Get File Information
+
+```python
+from exeqpdal import info
+
+info_data = info("input.las", stats=True)
+print(info_data)
+```
+
+For more examples, see the [examples documentation](docs/examples.md).
+
+## Supported Components
+
+Factory helpers cover the most commonly used PDAL readers, writers, and filters. For the
+definitive driver reference, consult the
+[PDAL documentation](https://pdal.io/en/stable/stages/stages.html). If a driver is
+missing, you can still run it by injecting raw dictionaries into a `Pipeline`.
+
+## Error Handling
+
+`exeqpdal` raises custom exceptions to surface PDAL CLI failures and configuration issues.
+
+```python
+import exeqpdal as pdal
+
+try:
+    pipeline = pdal.Pipeline(
+        pdal.Reader.las("non_existent_file.las") | pdal.Writer.las("output.las")
+    )
+    pipeline.execute()
+except pdal.PipelineError as exc:
+    print(f"Pipeline execution failed: {exc}")
+```
+
+## Configuration
+
+### Custom PDAL Path
+
+If PDAL is not in your system's PATH, you can set the path to the `pdal` executable manually:
+
+```python
+import exeqpdal as pdal
+
+pdal.set_pdal_path("/path/to/your/pdal")
+```
+
+### Verbose Output
+
+Enable verbose output to see the PDAL command being executed and its output:
+
+```python
+import exeqpdal as pdal
+
+pdal.set_verbose(True)
+```
+
+## Project Status & Limitations
+
+-   `Pipeline.arrays` is not yet implemented – it currently returns an empty list even after
+    execution.
+-   Integration tests use six LAZ/COPC test datasets in `tests/test_data_laz/` covering various
+    scenarios (filtered/non-filtered data, small/mid/large sizes, LAS/COPC formats). Tests
+    automatically skip when PDAL or test data are unavailable. See `tests/test_data_laz/DATASET.md`
+    for dataset details.
+-   Stage coverage is broad but incomplete. Missing drivers can be added by extending the factory
+    modules or by building custom JSON.
+
+## License
+
+`exeqpdal` is licensed under the MIT License.
+
+This project is a wrapper around the PDAL command-line tool, which is licensed under the
+BSD license. When using `exeqpdal`, you are also using PDAL, and you should be aware of
+its license.
+
+If you are using `exeqpdal` in a QGIS plugin, you should also be aware of the QGIS license (GPLv2+).