Skip to main content

Python

The Oceanum python package provides full access to the Oceanum.io platform, including the Datamesh and Storage services.

Installation​

Install from PyPI:

pip install oceanum

Or using conda:

conda install -c conda-forge oceanum

Authentication​

Set your Datamesh token as an environment variable:

export DATAMESH_TOKEN="your-token-here"

Or pass it directly when creating a connector:

from oceanum.datamesh import Connector

connector = Connector(token="your-token-here")

Quick Start​

Connect to the Datamesh​

from oceanum.datamesh import Connector

# Initialize connector (uses DATAMESH_TOKEN env var)
connector = Connector()

# Browse the catalog
catalog = connector.get_catalog()
print(catalog)

# Search for datasets
results = connector.get_catalog(search="wave")

Load Data​

# Load a datasource as xarray Dataset
ds = connector.load_datasource("datasource-id")
print(ds)

# Query with filters
from oceanum.datamesh import Query

query = Query(
    datasource="datasource-id",
    geofilter={"type": "bbox", "geom": [170, -40, 180, -35]},
    timefilter={"times": ["2024-01-01", "2024-12-31"]}
)
result = connector.query(query)

Work with Storage​

from oceanum import storage

# List files
files = storage.ls("/my-folder")

# Upload/download
storage.put("local_file.nc", "/remote/file.nc")
storage.get("/remote/file.nc", "local_file.nc")

Features​

  • Catalog browsing - Search and discover datasets
  • Data loading - Load datasources as xarray Datasets
  • OceanQL queries - Filter by space, time, and variables
  • Lazy loading - Efficient handling of large datasets with Dask
  • Storage access - Full read/write access to Oceanum Storage
  • fsspec integration - Use oceanum:// protocol with xarray, Dask, and more

Documentation​

Full documentation: oceanum-python.readthedocs.io

Source Code​

GitHub: github.com/oceanum-io/oceanum-python