fcollections.sad

Auxiliary data lookup an fetch module.

This modules aims at handling the auxiliary data that is needed by a software, but is not shipped with the binary. It references useful datasets, looks up for the files and eventually download missing files.

Software may call the class matching their use case and simply get the file they need. The fetching part will be automatically done by this module, allowing the caller to only know the dataset purpose and not its distribution point.

Functions

main()

Entry point for the auxiliary data handling.

Classes

GSHHG([preferred_target_folder])	Data from GSHHG data base.
IAuxiliaryDataFetcher([preferred_target_folder])	Interface for an auxiliary data source definition.
KarinFootprints([preferred_target_folder])	Karin geometries footprints.

class fcollections.sad.GSHHG(preferred_target_folder: Path | None = None)

Bases: IAuxiliaryDataFetcher

Data from GSHHG data base.

A Global Self-consistent, Hierarchical, High-resolution Geography Database.

It contains the following geometries’ types: GSHHS (aka. coastlines), river and border. It also comes in 5 resolutions: f, h, i, l, c (high resolution to crude resolution). The key for getting an asset is a composition of the geometry type and the resolution, for example: ‘GSHHS_c’, ‘border_i’, ‘river_l’

Parameters:

preferred_target_folder – The folder where data will be downloaded if it is missing. Default to the user home (~/.config/sad)

FILE = 'gshhg/gshhg-gmt-2.3.7.tar.gz'

FTP_URL = 'ftp.soest.hawaii.edu'

property keys: set[str]

Keys identifying single downloadable elements.

This key is used to build the file names to retrieve from the remote source.

class fcollections.sad.IAuxiliaryDataFetcher(preferred_target_folder: Path | None = None)

Bases: ABC

Interface for an auxiliary data source definition.

Parameters:

preferred_target_folder – The folder where data will be downloaded if it is missing. Default to the user home (~/.config/sad)

PATTERN = re.compile('(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])')

file(key: str) → Path

Look for a file in local.

The file is identified by its key and if it not found on the local file system, a fallback path is returned that points to the user space.

Parameters:

key – Identifier for the file to download

Returns:

The file path on the local file system. The existence is not guaranteed and must be handled by this method caller.

abstract property keys: set[str]

Keys identifying single downloadable elements.

This key is used to build the file names to retrieve from the remote source.

lookup_folders() → list[Path]

Lists the folders that may contain the files we seek.

In order to provide flexibility for the system setup, we scan multiple folders centered around the SAD_DATA environment variable. For an auxiliary data class named AtomicTime, the order of priority is given as followed ${SAD_DATA_ATOMIC_TIME} > ${SAD_DATA}/atomic_time > ${SAD_DATA} > ${HOME}/.config/sad

Returns:

A list of folders to scan. Candidate folders that do not exists are omitted from the list, with the exception of the user folder which serves as a fallback

property name: str

Name of the auxiliary data.

It is set as the class name. However, because the name can be used as a key, it is converted to snake_case for improved ergonomy.

class fcollections.sad.KarinFootprints(preferred_target_folder: Path | None = None)

Bases: IAuxiliaryDataFetcher

Karin geometries footprints.

Each mission phase has its own orbit thus its own footprint. Available keys are the lower case mission phases: ‘calval’ and ‘science’

Parameters:

preferred_target_folder – The folder where data will be downloaded if it is missing. Default to the user home (~/.config/sad)

HTTP_URL = 'https://data.aviso.altimetry.fr/aviso-gateway/data/.geometries_karin'

property keys: set[str]

Keys identifying single downloadable elements.

This key is used to build the file names to retrieve from the remote source.

fcollections.sad.main()

Entry point for the auxiliary data handling.