Getting Started

The fastest path is to verify the package import, run a small offline test group, then move to RAW conversion or retrieval examples only when the local environment is known to be healthy.

Choose the Right Environment

There are two common ways to use this repository. A user installs the published package from PyPI and imports lidarpy. A developer works from the source tree with PYTHONPATH=src so local edits are used immediately. Keeping those modes separate avoids a common class of problems where Python imports an installed wheel while you think it is importing the checkout.

Goal Recommended setup Success signal
Use the library python -m pip install atmolidarpy import lidarpy succeeds.
Develop the package uv sync --group dev plus PYTHONPATH=src Focused pytest groups pass from the checkout.
Build docs Install .[docs] and run scripts/build_docs.py site/index.html and site/api/lidarpy.html exist.

Install from PyPI

python -m pip install atmolidarpy
python -c "import lidarpy; print(lidarpy.__version__)"

The package should print a version string and exit with status 0. The distribution name is atmolidarpy because lidarpy was already taken on PyPI; the Python import name remains lidarpy.

Install for Local Development

The project targets Python 3.11. The lock file and workflows use the same major runtime so numerical dependencies, NetCDF support and tests behave consistently across Windows and Linux. 

uv sync --group dev
$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python -c "import lidarpy; print(lidarpy.__version__)"

Expected result: the command imports from the local src directory. If it fails, check that the virtual environment exists and that PYTHONPATH is set in the same PowerShell session.

First Validation

Start with tests that do not need RAW fixture conversion. This confirms that imports, synthetic signals, retrieval contracts, SCC offline contracts and docs links are healthy before spending time and disk on integration tests. 

$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python -m pytest tests\synthetic tests\retrieval tests\scc tests\docs -q

A good local result is a clean pass in seconds to a few tens of seconds. Warnings from scientific dependencies can be acceptable; import errors, missing package data, or failed docs links are not.

Run RAW-Based Tests Safely

RAW conversion tests unzip Licel fixtures and write NetCDF products. They validate the real migrated path, but they are heavier than synthetic tests. On Windows, use local temporary directories and clean known leftovers before the run. 

Remove-Item .pytest_tmp,.pytest_cache,tmp_unzipped_* -Recurse -Force -ErrorAction SilentlyContinue
Get-PSDrive -Name C
$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python -m pytest tests\nc_convert tests\preprocessing tests\plot -q

Expected result: tests create temporary NetCDF files under .pytest_tmp and remove measurement unzip directories through fixture cleanup. If disk is low, stop and free space before retrying.

Build Distribution Artifacts

Build artifacts are used both for local packaging checks and for releases. They should include package data such as YAML/TOML configs and assets, while excluding coordination files and RAW fixtures. 

$env:UV_PYTHON_INSTALL_DIR = ".uv-python"
$env:UV_CACHE_DIR = ".uv-cache"
$env:UV_PROJECT_ENVIRONMENT = ".venv"
uv build

Expected result: dist/ contains an atmolidarpy-*.tar.gz and an atmolidarpy-*.whl. The packaging tests inspect those artifacts when uv is available.

What Is Not Required Locally

This repository does not require Docker for normal operation. It also does not require SCC credentials for the default test suite. SCC end-to-end submission and download depends on an external server and should be tested deliberately in a controlled environment, not as a default local check.