API

API#

class altimetry_downloader_aviso.AvisoCatalog(products)#

Bases: object

Catalog of the AVISO/ODATIS service.

Contains a list of available products parsed from the metadata catalog.

Parameters:

products (list[AvisoProduct]) – List of available products in the catalog.

products: list[AvisoProduct]#
class altimetry_downloader_aviso.AvisoProduct(id, title=None, short_name=None, keywords=None, abstract=None, processing_level=None, tds_catalog_url=None, doi=None, last_update=None, last_version=None, credit=None, organisation=None, contact=None, resolution=None, temporal_extent=(None, None), geographic_extent=(None, None, None, None))#

Bases: object

Product of the catalog.

Contains the product metadata.

Parameters:

  • id (str) – Product ID.

  • title (str | None) – Full title of the product.

  • short_name (str | None) – Short name (used as identifier).

  • keywords (str | None) – Comma-separated list of keywords.

  • abstract (str | None) – Description or summary of the product.

  • processing_level (str | None) – Processing level (e.g., L2, L3).

  • tds_catalog_url (str | None) – URL to the THREDDS catalog.

  • doi (str | None) – Digital Object Identifier of the product.

  • last_update (datetime | None) – Last update of the product.

  • last_version (str | None) – Version identifier of the product.

  • credit (str | None) – Data provider or credit information.

  • organisation (str | None) – Responsible organisation.

  • contact (str | None) – Contact email or name.

  • resolution (str | None) – Spatial resolution of the dataset.

  • temporal_extent (tuple[datetime, datetime] | None) – Start and end dates of the data coverage.

  • geographic_extent (tuple[float, float, float, float] | None) – Bounding box as (west, east, south, north).

abstract: str | None = None#
contact: str | None = None#
credit: str | None = None#
doi: str | None = None#
geographic_extent: tuple[float, float, float, float] | None = (None, None, None, None)#
id: str#
keywords: str | None = None#
last_update: datetime | None = None#
last_version: str | None = None#
organisation: str | None = None#
processing_level: str | None = None#
resolution: str | None = None#
short_name: str | None = None#
tds_catalog_url: str | None = None#
temporal_extent: tuple[datetime, datetime] | None = (None, None)#
title: str | None = None#
altimetry_downloader_aviso.details(product_short_name)#

Details a product information from AVISO’s catalog.

Parameters:

product_short_name (str) – the short name of the product

Return type:

AvisoProduct

Returns:

The description of product

altimetry_downloader_aviso.ensure_credentials(host)#

Ensure authentication credentials can be found by netCDF4-c and requests.

requests looks for a .netrc file in either the home directory or at the path given by the NETRC environment variable.

netCDF4-c loads its .ncrc configuration file. If it finds a HTTP.NETRC entry, it will load the configuration from the .netrc, containing the credentials of interest. The .ncrc path can be given through the NCRCENV_RC, but this variable must be set prior importing the netCDF4 python library.

By defaults, the credentials are setup in an isolated folder. The defaults ~/.ncrc and ~/.netrc will not be used. Instead, the ~/.altimetry/.netrc and ~/.altimetry/.ncrc will be used.

Warning

altimetry_downloader_aviso sets NCRCENV_RC as early as possible (at package import time) to configure netCDF4-c correctly, since that variable only takes effect if set before netCDF4 is first imported. This only works if altimetry_downloader_aviso itself is imported before netCDF4, xarray, or pyinterp anywhere in your code. Importing one of those beforehand will prevent authentication from being correctly configured for netCDF4-c, and a UserWarning will be raised to signal it:

# Wrong: netCDF4 loaded first, NCRCENV_RC set too late to have any effect
import netCDF4
import altimetry_downloader_aviso

# Correct
import altimetry_downloader_aviso
import netCDF4
Parameters:

host (str) – host for which credentials are needed

Raises:

AuthenticationError – In case an exception happens when reading credentials

altimetry_downloader_aviso.filter_infos(product)#

Get temporal coverage, half orbit range and versions available for a given product.

The temporal coverage and half orbit range are returned as dictionaries for each Swot phases in case. This will allow

See also

altimetry_downloader_aviso.get_product_from_short_name()

For getting a product from its short name.

Parameters:

product (AvisoProduct) – the aviso product.

Returns:

The temporal coverage, half orbit range (if the product has half orbits) and versions available (if the product has multiple versions).

Return type:

tuple[dict[str, Period], dict[str, (tuple[int, int], tuple[int, int])], set[str] | None] | tuple[Period, None, set[str] | None]

altimetry_downloader_aviso.get(product_short_name, output_dir, cycle_number=None, pass_number=None, time=None, version=None, box=None, overwrite=False, assume_yes=True, show_progress=False, console=None)#

Downloads a product from Aviso’s Thredds Data Server.

Parameters:

  • product_short_name (str) – the short name of the product

  • output_dir (str | Path) – directory to store downloaded product files

  • cycle_number (int | list[int] | None) – the cycle number for files/folders selection

  • pass_number (int | list[int] | None) – the pass number for files/folders selection

  • time (tuple[datetime64, datetime64] | tuple[str, str] | None) – the period for files/folders selection

  • version (str | None) – the version for files/folders selection

  • box (tuple[float, float, float, float] | None) – Selection box (lon_min, lat_min, lon_max, lat_max) in degrees. Longitude range can be in either [0, 360[ or [-180, 180[ convention. lon_min must be inferior to lon_max (the convention must be changed to verify this constraint). Always used to select the granules to download. pass_number narrows the candidate passes tested against box if given (otherwise every pass of the mission is tested).

  • overwrite (bool) – whether to overwrite files if they already exist

  • assume_yes (bool) – whether to skip the download confirmation prompt (default: True)

  • show_progress (bool) – whether to display a download progress bar (default: False)

  • console (Console | None) – rich Console to render the progress bar on; if None, a new one is created internally. Mainly used by the CLI to share its own Console instance.

Raises:

ValueError – If cycle_number spans more than one mission phase, or matches none.

Return type:

list[str]

Returns:

The list of local files matching the request, including both that were already present, and those created by the get operation.

altimetry_downloader_aviso.get_product_from_short_name(product_short_name)#

Search for a product in AVISO’s catalog from its short name.

Return type:

AvisoProduct

altimetry_downloader_aviso.subset(product_short_name, output_dir, cycle_number=None, pass_number=None, time=None, version=None, box=None, selected_variables=None, overwrite=False, show_progress=False, console=None)#

Subset a product from Aviso’s Thredds Data Server.

Parameters:

  • product_short_name (str) – the short name of the product

  • output_dir (str | Path) – directory to store downloaded product files

  • cycle_number (int | list[int] | None) – the cycle number for files/folders selection

  • pass_number (int | list[int] | None) – the pass number for files/folders selection

  • time (tuple[datetime64, datetime64] | tuple[str, str] | None) – the period for files/folders selection

  • version (str | None) – the version for files/folders selection

  • box (tuple[float, float, float, float] | None) – Selection box (lon_min, lat_min, lon_max, lat_max) in degrees. Longitude range can be in either [0, 360[ or [-180, 180[ convention. lon_min must be inferior to lon_max (the convention must be changed to verify this constraint). Used to select the granules to download, and to crop downloaded datasets. pass_number narrows the candidate passes tested against box if given (otherwise every pass of the mission is tested).

  • selected_variables (list[str] | None) – List of variables to select.

  • overwrite (bool) – whether to overwrite files if they already exist

  • show_progress (bool) – whether to display a per-file subsetting progress bar (default: False)

  • console (Console | None) – rich Console to render the progress bar on; if None, a new one is created internally. Mainly used by the CLI to share its own Console.

Raises:

  • NotImplementedError – In case the input product does not support subsetting: only swath datasets on a (num_lines, num_pixels) grid are supported.

  • ValueError – If cycle_number spans more than one mission phase, or matches none.

Warns:

  • UserWarning – If a granule download failed.

  • UserWarning – If a granule listed in the TDS catalog does not expose a valid OpenDAP URL.

Return type:

list[str]

Returns:

The list of local files matching the request, including both that were already present, and those created by the subset operation.

altimetry_downloader_aviso.summary()#

Summarizes CDS-AVISO and SWOT products from AVISO’s catalog.

Return type:

AvisoCatalog

Returns:

The AVISO catalog object containing all the CDS-AVISO and SWOT products