🔥 landpyre
Discover & Download USGS LANDFIRE Data
Unofficial CLI and SDK for LANDFIRE data — discover, filter, search, and download geospatial datasets with ease.
Overview
landpyre is a modern, typed SDK and CLI for working with LANDFIRE geospatial datasets published by the USGS. It handles catalog discovery, fuzzy search, manifest-based reproducible downloads, checksum verification, and data export — all from the terminal or Python.
Built with Pydantic, Click, and Rich.
What's new in v0.2.0
- Typed SDK —
LandpyreClientwithsearch(),download(),verify(),export() - Pydantic models —
CatalogItem,CatalogFilter,DownloadResult, and more landpyre search— fuzzy full-text search ranked by relevancelandpyre manifest— save reproducible download selections tomanifest.jsonlandpyre verify— checksum and existence validation against a manifestlandpyre config— persistent defaults (default_region,default_output, etc.)landpyre doctor— environment diagnostics (Python, disk, network, SSL, cache)--dry-runon download — preview files and total size without hitting the network--openon download — open the output folder in your file explorer after completion--jsonon every command — machine-readable output for scripting- Schema versioning — stale caches are detected and prompt a helpful
refresh - Resumable downloads — partial ZIPs are continued from where they left off
- Checksum verification — MD5 verified during download when available
Installation
# Standard install
pip install landpyre
# With Parquet export support
pip install "landpyre[parquet]"
# From source (development)
git clone https://github.com/samapriya/landpyre.git
cd landpyre
pip install -e ".[dev]"
Requirements: Python ≥ 3.10, internet access for refresh (all other commands work offline).
CLI Quick Start
# 1. Fetch and cache the full LANDFIRE catalogue
landpyre refresh
# 2. Fuzzy-search the catalogue
landpyre search "hawaii fuel 2022"
# 3. Browse with filters
landpyre list --version "LF 2022" --region Hawaii
# 4. Statistics summary
landpyre stats
# 5. Save a manifest for reproducible downloads
landpyre manifest --version "LF 2022" --region Hawaii -o hawaii.json
# 6. Preview what will be downloaded (no network I/O)
landpyre download --manifest hawaii.json --dry-run
# 7. Download
landpyre download --manifest hawaii.json --output ./hawaii_data
# 8. Verify integrity
landpyre verify --manifest hawaii.json --output ./hawaii_data
# 9. Check your environment
landpyre doctor
SDK Quick Start
1. Setup & Client Exploration
from landpyre import LandpyreClient
client = LandpyreClient()
# refresh() is a no-op if a valid cache already exists.
# Pass force=True to always re-scrape.
snapshot = client.refresh()
print(f"Cache contains {snapshot.item_count} items.")
print(f"Last scraped: {snapshot.last_run}")
print(f"Schema version: {snapshot.schema_version}")
2. Filtering & Fuzzy Search
from landpyre import LandpyreClient
from landpyre.models import CatalogFilter, FilterMode
client = LandpyreClient()
client.refresh()
# Precise regex filtering
f_regex = CatalogFilter(version=r"LF 202[234]", mode=FilterMode.REGEX)
items = client.get_items(f_regex)
# Ranked fuzzy search across product, theme, region, and version
results = client.search("hawaii fuel 2022", threshold=0.6)
for r in results[:3]:
print(f"{r.score:.0%} - {r.item.filename}")
3. Manifests & Dry-runs
from landpyre import LandpyreClient
from landpyre.models import CatalogFilter
client = LandpyreClient()
client.refresh()
items = client.get_items(CatalogFilter(region="Hawaii", version="LF 2022"))
# Save state to manifest
manifest = client.save_manifest(items, path="hawaii_lf2022.json")
# Dry run to calculate total payload
summary = client.dry_run(items, output_dir="./data")
print(f"Files to download : {summary['item_count']}")
print(f"Total size : {summary['total_bytes_fmt']}")
# Load state back later
loaded = client.load_manifest("hawaii_lf2022.json")
4. Downloads & Verification
from landpyre import LandpyreClient
from landpyre.models import CatalogFilter
client = LandpyreClient()
client.refresh()
items = client.get_items(CatalogFilter(region="Hawaii", version="LF 2022"))
client.save_manifest(items, path="hawaii_lf2022.json")
# Resumable multi-threaded download
results = client.download(items, output_dir="./data", workers=4)
# Post-download integrity verification against the manifest
vr = client.verify("hawaii_lf2022.json", output_dir="./data")
print(f"All OK : {vr.all_ok}")
print(f"Files missing : {vr.files_missing}")
print(f"Files corrupt : {vr.files_corrupt}")
5. Exporting Catalog Metadata
from landpyre import LandpyreClient
from landpyre.models import CatalogFilter
client = LandpyreClient()
client.refresh()
items = client.get_items(CatalogFilter(version="LF 2022"))
# Standard exports
client.export(items, format="json", path="lf2022.json")
client.export(items, format="csv", path="lf2022.csv")
client.export(items, format="markdown", path="lf2022.md")
# Parquet (requires `pip install "landpyre[parquet]"`)
client.export(items, format="parquet", path="lf2022.parquet")
CLI Reference
landpyre refresh
Scrapes the LANDFIRE catalogue and saves it to ~/.landpyre/landfire_latest.json.
landpyre refresh # Refresh only if no valid cache exists
landpyre refresh --force # Force re-scrape
landpyre refresh --check-scraper # Health-check the scraper without saving
landpyre refresh --json # Machine-readable output
landpyre search QUERY
Fuzzy full-text search across product, theme, region, and version. Results are ranked by relevance score.
landpyre search "hawaii fuel"
landpyre search "CONUS LF 2022" --limit 10
landpyre search "fire behavior" --threshold 0.5
landpyre search "fuel model" --json
| Flag | Description |
|---|---|
--limit / -l |
Maximum results (default: 20) |
--threshold |
Minimum relevance score 0.0–1.0 (default: 0.0) |
--json |
Output as JSON |
landpyre list
Browse the catalogue with exact/substring filters.
landpyre list
landpyre list --version "LF 2022"
landpyre list --region "Hawaii" --version "LF 2022"
landpyre list --theme "Fire" --limit 20 --url
landpyre list --region "CONUS" --json
| Flag | Short | Description |
|---|---|---|
--version |
-V |
Filter by version |
--region |
-r |
Filter by region |
--theme |
-t |
Filter by theme |
--limit |
-l |
Max rows (default: 50) |
--url |
Show download URLs | |
--json |
Output as JSON |
landpyre manifest
Save a filtered selection to a portable manifest.json.
landpyre manifest --version "LF 2022" --region Hawaii
landpyre manifest --version "LF 2024" -o conus_2024.json
landpyre manifest --show manifest.json # Inspect an existing manifest
| Flag | Short | Description |
|---|---|---|
--version |
-V |
Version filter |
--region |
-r |
Region filter |
--theme |
-t |
Theme filter |
--output |
-o |
Destination path (default: manifest.json) |
--show |
-s |
Inspect an existing manifest |
--json |
Output as JSON |
landpyre download
Download files and extract TIF data. Accepts filters or a manifest.
landpyre download --version "LF 2022" --output lf2022
landpyre download --manifest manifest.json --output ./data
landpyre download --region "CONUS" --dry-run # Preview only
landpyre download --manifest hawaii.json --yes --open # Skip confirm, open folder
| Flag | Short | Default | Description |
|---|---|---|---|
--version |
-V |
Version filter | |
--region |
-r |
Region filter | |
--theme |
-t |
Theme filter | |
--manifest |
-m |
Replay a manifest.json | |
--output |
-o |
config / landfire_output |
Output directory |
--workers |
-w |
config / 4 |
Concurrent threads |
--yes |
-y |
Skip confirmation | |
--dry-run |
Preview without downloading | ||
--open |
Open output folder after download | ||
--json |
Output as JSON |
landpyre verify
Verify downloaded files against a manifest (existence, size, MD5 checksum).
landpyre verify
landpyre verify --manifest hawaii.json --output ./hawaii_data
landpyre verify --json
landpyre config
View and modify persistent configuration stored at ~/.config/landpyre/config.toml.
landpyre config show
landpyre config get default_region
landpyre config set default_region CONUS
landpyre config set default_workers 6
landpyre config set auto_confirm true
| Key | Default | Description |
|---|---|---|
default_output |
landfire_output |
Default download directory |
default_workers |
4 |
Default concurrent threads |
default_region |
— | Default region filter |
default_version |
— | Default version filter |
default_theme |
— | Default theme filter |
cache_dir |
~/.landpyre |
Override cache location |
log_level |
WARNING |
Logging level |
auto_confirm |
false |
Skip download confirmation |
no_color |
false |
Disable colour output |
landpyre doctor
Run environment diagnostics: Python version, disk space, network reachability, SSL/TLS, cache existence, directory permissions, config validity, ZIP support, and Pydantic installation.
landpyre doctor
landpyre doctor --json
SDK Reference
LandpyreClient
from landpyre import LandpyreClient
client = LandpyreClient(
cache_dir=None, # override cache location
workers=4, # default download thread count
)
| Method | Returns | Description |
|---|---|---|
refresh(force, progress_callback) |
CatalogSnapshot |
Scrape and cache |
get_snapshot() |
CatalogSnapshot |
Load current cache |
get_items(f) |
list[CatalogItem] |
Filter query |
search(query, limit, threshold, f) |
list[SearchResult] |
Fuzzy search |
save_manifest(items, path) |
Manifest |
Save manifest |
load_manifest(path) |
Manifest |
Load manifest |
items_from_manifest(manifest) |
list[CatalogItem] |
Convert for download |
download(items, output_dir, workers, dry_run) |
list[DownloadResult] |
Download |
download_manifest(path, output_dir, ...) |
list[DownloadResult] |
Load + download |
dry_run(items, output_dir) |
dict |
Preview summary |
verify(manifest, output_dir) |
ValidationResult |
Integrity check |
export(items, format, path) |
Path |
Export to file |
Key Models
from landpyre.models import (
CatalogItem, # One downloadable entry
CatalogFilter, # Filter criteria (substring/exact/regex/fuzzy)
CatalogSnapshot, # The full cached catalogue
DownloadResult, # Outcome of one download
Manifest, # Portable manifest document
ValidationResult, # Outcome of a verify run
LandpyreConfig, # User preferences
)
Filtering Logic
All filters are case-insensitive and ANDed together.
from landpyre.models import CatalogFilter, FilterMode
CatalogFilter(region="haw") # Substring (default)
CatalogFilter(region="Hawaii", mode=FilterMode.EXACT) # Exact
CatalogFilter(version=r"LF 202[234]", mode=FilterMode.REGEX) # Regex
CatalogFilter(product="fbfm", mode=FilterMode.FUZZY, fuzzy_threshold=0.5) # Fuzzy
Output Structure
landfire_output/
└── tif/
├── LF2022_FBFM40_220_HI.tif
├── LF2022_FVH_220_HI.tif
└── ...
ZIP files are downloaded to .tmp_zips/, TIFs are extracted flat into tif/, and the ZIPs are removed automatically.
Links
- Documentation: landpyre.geocarpentry.org
- GitHub: github.com/samapriya/landpyre
- PyPI: pypi.org/project/landpyre
- Issues: github.com/samapriya/landpyre/issues
Apache 2.0 License · Built by Samapriya Roy · Powered by Pydantic, Click, and Rich
Metadata
Release files for landpyre 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| landpyre-0.2.2.tar.gz | 49.5 kB | Without provenance | Details for landpyre-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| landpyre-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for landpyre-0.2.2-py3-none-any.whl |
Total release size: 109.3 kB
Release files / landpyre-0.2.2.tar.gz
| Download URL | landpyre-0.2.2.tar.gz |
|---|---|
| Size | 49.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
16bf7103eb135d420aa632716bd7ddf85472749a289d52b572aca3dee6cb4f50
|
|
BLAKE2b-256 checksum How to use checksums |
5daaa7cf855d5e9915a37d1405fd55d69be8b87eff4d6706f294148b347e9016
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.6
|
Release files / landpyre-0.2.2-py3-none-any.whl
| Download URL | landpyre-0.2.2-py3-none-any.whl |
|---|---|
| Size | 59.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
07f2457997c5ea21eb04ab35140b2909544391b53eeab876290a9d2fa1eea0ee
|
|
BLAKE2b-256 checksum How to use checksums |
d62033451329679df4365b1c95996c0884b04e0f3352a88043cafbadfaaf1c5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.6
|
Security for landpyre 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.