HFLAV FAIR Client

Overview

The HFLAV FAIR Client is a Python library designed to facilitate access to and processing of HFLAV (Heavy Flavor Averaging Group) data from Zenodo. The library provides a unified interface for querying, transforming, and using that data, adhering to FAIR (Findable, Accessible, Interoperable, Reusable) principles.

Installation

Install from PyPi

• python -m pip install hflav-fair-client

Install from source

1. git clone ssh://git@gitlab.cern.ch:7999/hflav/shared/hflav-fair-client.git
2. cd hflav-fair-client
3. python -m venv .venv
4. source .venv/bin/activate
5. pip install .

Install in editable mode (for development)

pip install -e ".[dev]"

Quick Start

Below are simple examples showing how to retrieve and work with results from an HFLAV Zenodo record. All the public classes and a ready-to-use service instance are available directly from the top-level package:

import hflav_fair_client as hflav

help(hflav)  # list all available classes and a quick-start example

Example 1: Load a specific record by ID and navigate the information

import hflav_fair_client as hflav

# Load a specific file from a known Zenodo record
data = hflav.service.load_data_file(
  record_id=19446771,
)

# Use attribute-chain navigation to list groups
for g in data.groups:
    print(g.name)

# Use attribute-chain navigation to list names and averages in the group
#   'ASLd and ASLs'
[f'{a.name} : {a.average.value.central}±{a.average.value.uncertainty}' for a in data.groups(name='ASLd and ASLs').averages]

['ASLd : -0.0021±0.0017', 'ASLs : -0.0006±0.0028']

Alternatively, use .path() to jump straight to a nested item by name in a single call. Note the / separating the group and the name of the average.

# Or use .path() to jump straight to a nested item by name in a single call
average = data.path("ASLd and ASLs/ASLd")
print(f'{average.name} : {average.average.value.central}±{average.average.value.uncertainty}')

ASLd : -0.0021±0.0017

Example 2: Get the bibtex record for citing these results

Building on the data object from the previous example

bibtex = data.reference.bibtex
print(bibtex)

@article{HeavyFlavorAveragingGroupHFLAV:2024ctg:19446771,
    author = "Banerjee, Sw. and others",
    collaboration = "Heavy Flavor Averaging Group (HFLAV)",
    title = "{Averages of b-hadron, c-hadron, and {\ensuremath{\tau}}-lepton properties as of 2023}",
    eprint = "2411.18639",
    archivePrefix = "arXiv",
    primaryClass = "hep-ex",
    doi = "10.1103/x87q-tld5",
    journal = "Phys. Rev. D",
    volume = "113",
    number = "1",
    pages = "012008",
    year = "2026",
    note = "{with specific result from \href{https://doi.org/10.5281/zenodo.19446771}{{\texttt{doi:10.5281/zenodo.19446771}}}}"
}

Example 3: Search within the loaded record

# Search within the loaded data for averages using a specific paper
import hflav_fair_client as hflav

searcher = hflav.HflavDataSearching(data)
results = searcher.get_data_object_from_key_and_value(
    object_name="groups",
    key_name="doi",
    operator=hflav.SearchOperators.EQUALS,
    value="10.1103/PhysRevD.86.072009",
)
[r.name for r in results]

['ASLd and ASLs']

Example 4: Load a local data file

Files are cached locally after you download, so usually no need for this.

import hflav_fair_client as hflav

# Load a local JSON data file
data = hflav.service.load_local_data_file_from_path(
    file_path="HFLAV.json",
)

Example 5: Print template record to understand structure

Here we show the complete set of information that may be available in the Zenodo record. Not all files will have all information. Note that this is just a template and the actual results should not be used. See example below for more details on query method.

import hflav_fair_client as hflav

# Get the latest Template
query = ( hflav.QueryBuilder().with_text(field='title', value='Template').build())
data = next(hflav.service.search_and_load_data_file(query=query))

print('Data in template. Use this to inform about structure, not the actual results.')
print(data)

Data in template. Use this to inform about structure, not the actual results.
metadata: title='HFLAV Template averages',
    description='Longer description here',
    version='1.2.0',
    date='2026-08-21',
    author='HFLAV Collaboration',
    schema='1.2.0',
groups: [name='Branching fractions',
    comment='This is a comment for the group',
    fit: chi2=177.79892806528355, ndf=156, p=0.11156555504195274,
    :
    :

Example 6: Search for HFLAV records on Zenodo and load data

This can be used to search for a given Zenodo record.

import hflav_fair_client as hflav

# Build a query to search for HFLAV records on Zenodo
query = (
    hflav.QueryBuilder()
    .with_text(field="title", value="HFLAV")
    .with_pagination(size=5, page=1)
    .order_by(field=hflav.SortOptions.MOSTRECENT)
    .build()
)

# Search Zenodo and lazily load the data file for each matching record.
# This is a generator, so each file is only downloaded once you iterate over it.
for data in hflav.service.search_and_load_data_file(query=query):
    print(data.doi)

Example 7: Combine multiple filters using merge

import hflav_fair_client as hflav
import datetime

# First query builder: filter by version number with NOT combinator
query1 = (
    hflav.QueryBuilder()
    .with_number(field="version", value=2, operator=">=")
    .apply_combinator(hflav.NotFilter)
)

# Second query builder: filter by title and date range with OR combinator
query2 = (
    hflav.QueryBuilder()
    .with_text(field="title", value="HFLAV")
    .with_date_range(
        field="created",
        start_date=datetime.datetime(2022, 1, 1),
        end_date=datetime.datetime(2025, 12, 31),
    )
    .apply_combinator(hflav.OrFilter)
)

# Create a new query builder and merge both previous queries
combined_query = (
    hflav.QueryBuilder()
    .with_pagination(size=5, page=1)
    .order_by(field=hflav.SortOptions.MOSTRECENT)
    .merge_filters(query1)
    .merge_filters(query2)
    .build()  # Uses AndFilter by default to combine the merged filters
)

# Use the combined query to search and lazily load matching data files
for data in hflav.service.search_and_load_data_file(query=combined_query):
    print(data.metadata.title)

Configuring environment variables

All the environment variables available can be seen in the EnvironmentVariables enum inside the config file.

Variable	Description	Default
HFLAV_CACHE_NAME	Name of the local HTTP cache	hflav_cache
HFLAV_CACHE_EXPIRE_AFTER	Cache expiry time in seconds	2592000 (30 days)

To use environment variables in your code, simply modify the .env file:

HFLAV_CACHE_NAME=my_cache
HFLAV_CACHE_EXPIRE_AFTER=2592000

Releasing to PyPI

Releases are published automatically from GitLab CI when you create a tag that matches vX.Y.Z.

Release requirements:

• The Git tag must be named like v1.2.3.
• The version in pyproject.toml must be 1.2.3.
• GitLab CI must have a masked CI/CD variable named PYPI_API_TOKEN.

Release flow:

1. Update the version in pyproject.toml.
2. Create and push a matching Git tag, for example v1.2.3.
3. GitLab CI builds the distribution, checks the metadata, and uploads the package to PyPI.

The release pipeline validates the tag/version pair before publishing, so mismatched versions fail early.