DaFab Client

The Python client for DaFab metadata queries, asset downloads and publication.

Install

pip install dafab-client

Python 3.10 or newer is required.

Generated-publication audits, static reports, and collages are maintained in dafab-audit.

Connection profile

The default account is user_dafab. Set DAFAB_PROFILE before importing the client to select another account. DAFAB_PROFILE_PATH selects an explicit JSON profile. Otherwise, it checks <profile-directory>/<account>/config before the packaged profile. The directory is DAFAB_PROFILE_DIR, then $XDG_CONFIG_HOME/dafab/credentials/profiles when set, or ~/.config/dafab/credentials/profiles.

The profile's ca_cert selects the TLS trust bundle. $profile_path resolves to the directory containing that profile. Keep private credentials outside this repository. Publisher deployment and mounted trust configuration follow the platform runbook.

Quick Start

import dafab_client as dc

print(dc.ping())
print(dc.whoami())
print(dc.list_storages())

All public helpers are available as dc.<method>.

For examples, you can also copy the packaged simple-user notebook into the current directory:

python -c "import dafab_client as dc; print(dc.get_example('user'))"

This overwrites local files if they already exist.

Simple User API Reference

The reference below lists required arguments. Module docstrings describe optional arguments and return values. The enhanced-filter guide covers compound queries.

Session And Discovery

• ping() : Health check of the connected Rucio/STAC service.
• whoami() : Return authenticated identity/session details.
• list_stac_scopes() : Print visible scopes for the active account.
• list_catalogs_and_collections() : Print catalog/collection container ids in the active scope.
• get_catalogs_and_collections() : Return structured catalog/collection rows.
• get_items() : Return item DID rows.

Filter And Relationship Queries

• get_items_by_enhanced_filter(filter_payload) : Execute an enhanced STAC filter query.
• get_item_ids_by_collection_field(collection_id) : Resolve item ids by collection metadata value.
• get_item_ids_by_top_facet_catalog(top_facet_catalog_id) : Resolve item ids indexed under a top facet catalog.
• get_item_ids_by_facet_value_catalog(facet_value_catalog_id) : Resolve item ids linked from one facet value catalog.
• get_item_facet_placements(item_id, collection_id=...) : Return the exact facet-value placement under each collection facet.
• get_related_item_ids_from_original_item(original_item_id) : Resolve derived item ids linked via rel=related.
• get_source_original_item_ids_from_derived_item(derived_item_id) : Resolve original item ids linked via rel=derived_from.
• get_sibling_derived_item_ids(original_item_id) : Resolve sibling derived items for one original item.

An enhanced filter group with type set to inherited follows Rucio parent attachments recursively to the roots. Every ancestor's metadata stays separate. One ancestor must satisfy the complete group, and the starting item's own metadata is excluded. A STAC derived_from link alone does not establish this attachment relationship. Raw JSON submission supports the node when the server supports it. InheritedFilter builds the same node through the Python filter DSL.

Spatial And Temporal Queries

• get_items_by_timerange(start_date, end_date) : Filter items by temporal interval.
• get_items_by_bbox(min_long, min_lat, max_long, max_lat) : Filter items by spatial bounding box.
• get_items_by_bbox_and_timerange(bbox, timerange) : Filter items by combined bbox and time window.

Metadata Access

• extract_metadata_value(value_path) : Read one metadata value path (requires metadata or pname via optional args).
• get_bulk_metadata(pname) : Retrieve full or partial metadata document values.
• as_json(data) : Pretty-print payloads for notebook/debug display.

Storage And Asset Operations

• list_storages() : Print configured storage endpoints (RSEs).
• check_storage(rse_name) : Fetch one storage endpoint metadata record.
• list_item_asset_entries(item_id) : Inspect an item's assets entries.
• build_stable_asset_href(item_id, asset_key) : Build canonical stable asset URL used by DaFab STAC metadata.
• download_asset_from_stable_href(stable_href) : Download content by stable asset URL.
• download_item_asset(item_id, asset_key) : Download one metadata asset by key (URL or attached file resolution).
• download_all_derived_item_assets(item_id) : Download all assets for one derived item.

Visualization

• get_map(metadata_batch) : Render bbox overlays from metadata to an interactive HTML map.

Local Files And Outputs

Demo-data directory

For writable helper outputs, default base directory is:

• DAFAB_DEMO_DATA_DIR (if set), else
• <current working directory>/demo-data

get_map(...) default output path:

• <demo-data-dir>/filters/bbox_map.html

Bundled schemas

Packaged schema files (used as fallback in validators):

• Schema_Copernicus_with_dafab.json
• Schema_DaFab_Facet_Value_Catalog.json
• dafab-smart_agriculture-item.schema.json
• dafab-water_analysis-item.schema.json

Logging Defaults

Current defaults in dafab_client._rucio.global_utils:

• debug_mode = False
• minimal_logging = True

So runtime output is intentionally minimal unless logging flags are changed.

Releasing

Maintainers should follow docs/releasing.md. Publishing credentials remain in the local private configuration and must never be added to this repository.