Metadata-Version: 2.4
Name: dafab_client
Version: 3.1.2
Summary: DaFab helper client built on top of Rucio client modules.
Author: DaFab
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/DaFab-AI-eu/dafab-client
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: folium<1,>=0.20.0
Requires-Dist: jsonschema<5,>=4.26.0
Requires-Dist: packaging<27,>=26.1
Requires-Dist: requests<3,>=2.33.1
Requires-Dist: typing_extensions<5,>=4.15
Requires-Dist: urllib3<3,>=2.6.3

# DaFab Client

The Python client for [DaFab](https://www.dafab-ai.eu) metadata queries, asset downloads and publication.

## Install

```bash
pip install dafab-client
```

Python 3.10 or newer is required.

Generated-publication audits, static reports, and collages are maintained in
[`dafab-audit`](https://github.com/DaFab-AI-eu/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](https://github.com/DaFab-AI-eu/dafab-platform/blob/main/docs/operations/cluster-configuration-runbook.md).

## Quick Start

```python
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:

```bash
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](<dafab_client/helpers/filtering/D3.2 Rucio current implementation of enhanced filtering.md>) 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`](docs/releasing.md). Publishing
credentials remain in the local private configuration and must never be added
to this repository.
