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