Metadata-Version: 2.4
Name: qgis-project
Version: 0.0.3
Summary: Create QGIS projects programmatically using Python
Project-URL: Documentation, https://github.com/ColinMoldenhauer/qgis-project#readme
Project-URL: Issues, https://github.com/ColinMoldenhauer/qgis-project/issues
Project-URL: Source, https://github.com/ColinMoldenhauer/qgis-project
Author-email: Colin Moldenhauer <colin.moldenhauer@posteo.de>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: cartography,geospatial,gis,mapping,qgis
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Requires-Dist: loguru
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Provides-Extra: qgis-dev
Requires-Dist: pytest-qgis; extra == 'qgis-dev'
Description-Content-Type: text/markdown

# qgis-project

[![PyPI version](https://img.shields.io/pypi/v/qgis-project)](https://pypi.org/project/qgis-project/)
[![Python versions](https://img.shields.io/pypi/pyversions/qgis-project)](https://pypi.org/project/qgis-project/)
[![License](https://img.shields.io/github/license/ColinMoldenhauer/qgis-project)](LICENSE.txt)
[![CI](https://github.com/ColinMoldenhauer/qgis-project/actions/workflows/test.yml/badge.svg)](https://github.com/ColinMoldenhauer/qgis-project/actions/workflows/test.yml)
[![Docs](https://readthedocs.org/projects/qgis-project/badge/?version=latest)](https://qgis-project.readthedocs.io/en/latest/)

Create QGIS projects programmatically using Python.

```python
from qgis_project import Project, RasterLayer, RasterStyleBW

proj = Project()
proj.add_layer("dem.tif")                                    # raster, auto-detected
proj.add_layer("boundaries.geojson")                         # vector, auto-detected
proj.add_layer(RasterLayer("dem.tif", style=RasterStyleBW(vmin=0, vmax=3000)))
proj.save("output.qgz")
proj.open()     # launch QGIS for visual inspection
```


## Installation

Install the package:

```bash
pip install qgis-project
```

QGIS is not on PyPI and must be available separately. The recommended approach is a dedicated conda environment:

```bash
conda env create -f environment_platform_independent.yml
conda activate qgis-env-pi
pip install qgis-project
```

Or install QGIS from conda-forge into an existing environment:

```bash
conda install -c conda-forge qgis
pip install qgis-project
```

> **Note:** All QGIS imports are lazy — `import qgis_project` works without QGIS installed. Errors only surface when a QGIS-backed method is actually called.


## Usage

### Basic project

```python
from qgis_project import Project

proj = Project()
proj.add_layer("dem.tif")
proj.add_layer("roads.geojson")
proj.save("my_project.qgz")
proj.exit()
```

### Layer groups

```python
proj.add_layer(RasterLayer("dem.tif", group="terrain"))
proj.add_layer(RasterLayer("slope.tif", group=["terrain", "derived"]))
```

### Raster styling

```python
from qgis_project import RasterLayer, RasterStyleBW

layer = RasterLayer(
    file="dem.tif",
    name="Elevation",
    group="terrain",
    style=RasterStyleBW(vmin=0, vmax=3000),
)
proj.add_layer(layer)
```

### Open in QGIS

```python
proj.open("output.qgz")      # saves and launches QGIS
proj.print_layer_tree()      # inspect the layer tree in the terminal
```


## Development

Install with dev dependencies:

```bash
pip install -e ".[dev]"
```

Run unit tests (no QGIS required):

```bash
pytest -m "not qgis"
```

Run integration tests (QGIS environment required):

```bash
pytest -m qgis
```

Run the manual visual test:

```bash
python scripts/manual_test.py
```
