landpyre | LANDFIRE data, beautifully delivered

What's new in v0.2.0

Typed SDK & Pydantic

Full LandpyreClient with search, download, and verify. Robust models built entirely on Pydantic.

Fuzzy Search

landpyre search provides full-text search ranked by relevance across product, theme, region, and version.

Checksum Verification

MD5 verified during download. Command validates checksums and existence against generated manifests.

Resumable & Dry-runs

Preview file sizes with --dry-run. Partial ZIPs are resumed automatically without data loss.

Manifests & JSON

Save reproducible state to manifest files. Every command supports machine-readable output for pipelines.

Diagnostics

landpyre doctor checks environment, Python version, disk, network, SSL, and cache validity.

Installation

Requires Python ≥ 3.10. Internet access needed for refresh (all other commands work offline).

# With pip
pip install landpyre

# With Parquet export support
pip install "landpyre[parquet]"

# From source (recommended during development)
git clone https://github.com/samapriya/landpyre.git
cd landpyre
pip install -e ".[dev]"

Quick Start Workflow

Fetch & cache catalogue:
landpyre refresh
Fuzzy search:
landpyre search "hawaii fuel 2022"
Browse with filters:
landpyre list --version "LF 2022" --region Hawaii
Save a manifest:
landpyre manifest -V "LF 2022" -r Hawaii -o hawaii.json
Preview & Download:
landpyre download -m hawaii.json --dry-run

bash — landpyre

$ landpyre search "hawaii fuel 2022"
🔎 Searching 842 records...

1.00 LF2022_FBFM40_220_HI.zip (1.2 GB)
Hawaii • LF 2022 • Fire Behavior
0.92 LF2022_FBFM13_220_HI.zip (850 MB)
Hawaii • LF 2022 • Fire Behavior

$ landpyre stats
📊 LANDFIRE Catalogue Statistics
Total Files: 842
Total Size: 415.2 GB

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter

client = LandpyreClient()
client.refresh() # No-op if cached

# Fuzzy search
results = client.search("hawaii fuel 2022")

# Precise filter & save manifest
items = client.get_items(
    CatalogFilter(region="Hawaii", version="LF 2022")
)
manifest = client.save_manifest(items, "hawaii.json")

# Preview, Download & Verify
summary = client.dry_run(items, output_dir="./data")
client.download(items, output_dir="./data", workers=4)
client.verify(manifest, output_dir="./data")

python — output

>>> for r in results[:2]:
... print(f"{r.score:.0%} - {r.item.filename}")
...
100% - LF2022_FBFM40_220_HI.zip
92% - LF2022_FBFM13_220_HI.zip

>>> vr = client.verify(manifest, "./data")
>>> print("All OK!" if vr.all_ok else "Errors found")
All OK!

CLI Command Reference

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 list & stats

Browse the catalogue with exact/substring filters or view aggregate statistics.

landpyre list --version "LF 2022" --region "Hawaii" --limit 20
landpyre stats --version "LF 2022"

landpyre manifest & download

Save selections to a portable manifest, then perform multi-threaded, resumable downloads.

landpyre manifest --version "LF 2022" --region Hawaii -o hawaii.json
landpyre download --manifest hawaii.json --dry-run
landpyre download --manifest hawaii.json --output ./data --workers 6

landpyre doctor

Run environment diagnostics (Python version, disk space, network, SSL/TLS, cache, zip support).

landpyre doctor
landpyre doctor --json

1. Setup & Client Exploration

Initialize the client, populate the local cache from USGS, and explore snapshot metadata.

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

Use CatalogFilter for precise lookups, or perform ranked fuzzy searches across multiple fields simultaneously.

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter, FilterMode

client = LandpyreClient()

# refresh() is a no-op if a valid cache already exists.
# Pass force=True to always re-scrape.
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

Preview total payload sizes before committing to network IO, and save desired states to portable manifests.

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter

client = LandpyreClient()
client.refresh()

# Filter items to work with
items = client.get_items(CatalogFilter(region="Hawaii", version="LF 2022"))

# 1. Save state to manifest
manifest_path = "hawaii_lf2022.json"
manifest = client.save_manifest(items, path=manifest_path)

# 2. 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']}")

# 3. Load state back later
loaded = client.load_manifest(manifest_path)

4. Downloads & Verification

Initiate multi-threaded downloads. The command automatically handles resumable partial zips and runs a post-download MD5 check.

from landpyre import LandpyreClient
from landpyre.models import CatalogFilter

client = LandpyreClient()
client.refresh()

# Setup items and manifest for download
items = client.get_items(CatalogFilter(region="Hawaii", version="LF 2022"))
manifest_path = "hawaii_lf2022.json"
client.save_manifest(items, path=manifest_path)

# Resumeable multi-threaded download
results = client.download(items, output_dir="./data", workers=4)

# Post-download integrity verification against the manifest
vr = client.verify(manifest_path, 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

Export subsets of the LANDFIRE catalog natively into machine-readable formats for external data analysis.

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")

Discover & Download,
USGS LANDFIRE Data.

What's new in v0.2.0

Typed SDK & Pydantic

Fuzzy Search

Checksum Verification

Resumable & Dry-runs

Manifests & JSON

Diagnostics

Installation

Quick Start Workflow

CLI Command Reference

Python SDK Reference

1. Setup & Client Exploration

2. Filtering & Fuzzy Search

3. Manifests & Dry-runs

4. Downloads & Verification

5. Exporting Catalog Metadata

Discover & Download, USGS LANDFIRE Data.

What's new in v0.2.0

Typed SDK & Pydantic

Fuzzy Search

Checksum Verification

Resumable & Dry-runs

Manifests & JSON

Diagnostics

Installation

Quick Start Workflow

CLI Command Reference

Python SDK Reference

1. Setup & Client Exploration

2. Filtering & Fuzzy Search

3. Manifests & Dry-runs

4. Downloads & Verification

5. Exporting Catalog Metadata

Discover & Download,
USGS LANDFIRE Data.