Metadata-Version: 2.4
Name: dafab_client
Version: 2.2.0
Summary: DaFab helper client built on top of Rucio client modules.
Author: DaFab
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/rucio/rucio
Requires-Python: >=3.9
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

This is the official DaFab client (see https://www.dafab-ai.eu for the project details).

## Install

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

Notes:
- Runtime requires Python `>=3.9`.
- Should work on Windows, Linux and macOS.

## 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 README focuses on the methods used in `dafab_simple_user_workflows.ipynb`.
Each method below is also documented in-code via module docstrings.
For simplicity, only mandatory parameters are listed here.

### 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_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.

### 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.
