tessl/pypi-erddapy

Python interface for ERDDAP data servers that simplifies accessing scientific datasets

—

Pending

Overview

Eval results

Files

Server Management

Name: tessl/pypi-erddapy
Author: tessl

Built-in catalog of ERDDAP servers with shortcuts and utilities for managing server connections. erddapy maintains a curated list of public ERDDAP servers that can be accessed using shortcut names instead of full URLs.

Capabilities

Server Dictionary

Access the built-in catalog of ERDDAP servers using shortcut names.

servers: dict[str, Server]  # Dictionary mapping server names to Server objects

Usage Examples:

from erddapy import servers

# List all available servers
print(list(servers.keys()))
# ['mda', 'mii', 'cscgom', 'cswc', 'cencos', 'neracoos', 'ngdac', ...]

# Get server information
secoora = servers['secoora']
print(secoora.description)  # "Southeast Coastal Ocean Observing Regional Association"
print(secoora.url)          # "http://erddap.secoora.org/erddap"

# Use in ERDDAP constructor
from erddapy import ERDDAP
e = ERDDAP(server="secoora")  # Automatically resolves to full URL

Server Class

Container for server metadata including description and URL.

from typing import NamedTuple

class Server(NamedTuple):
    """
    Container for server short description and URL.
    
    Attributes:
    - description: Human-readable server description
    - url: Full ERDDAP server URL
    """
    description: str
    url: str

Usage Examples:

from erddapy.servers.servers import Server

# Create custom server
custom_server = Server(
    description="My Institution ERDDAP",
    url="https://data.myinstitution.edu/erddap"
)

print(custom_server.description)
print(custom_server.url)

Server List Function

Download and cache the latest list of public ERDDAP servers from the awesome-erddap repository.

def servers_list() -> dict[str, Server]:
    """
    Download updated server list from awesome-erddap repository.
    
    First attempts to load the latest list from GitHub. If that fails,
    falls back to the default server list shipped with the package.
    Uses LRU cache to avoid repeated downloads.
    
    Returns:
    - Dictionary mapping server shortcut names to Server objects
    """

Usage Examples:

from erddapy.servers.servers import servers_list

# Get fresh server list (cached)
current_servers = servers_list()

# Check if new servers are available
print(f"Total servers: {len(current_servers)}")

# Access specific server
if 'noaa_coastwatch' in current_servers:
    server = current_servers['noaa_coastwatch']
    print(f"URL: {server.url}")
    print(f"Description: {server.description}")

Built-in Server Shortcuts

The following server shortcuts are commonly available (updated from awesome-erddap):

Major Oceanographic Data Centers:

'cswc' - NOAA CoastWatch West Coast
'ncei' - NOAA National Centers for Environmental Information
'osmc' - NOAA Observing System Monitoring Center
'ngdac' - IOOS National Glider Data Assembly Center

Regional Associations:

'secoora' - Southeast Coastal Ocean Observing Regional Association
'neracoos' - Northeastern Regional Association of Coastal Ocean Observing Systems
'pacioos' - Pacific Islands Ocean Observing System
'cencos' - Central and Northern California Ocean Observing System

International:

'mda' - European Marine Data Archive (JRC)
'mii' - Marine Institute Ireland
'ifremer' - French Research Institute for Exploitation of the Sea

Research Institutions:

'uaf' - University of Alaska Fairbanks
'onc' - Ocean Networks Canada
'ubc' - University of British Columbia

Usage with Server Shortcuts:

from erddapy import ERDDAP

# Use any server shortcut
e = ERDDAP(server="secoora", protocol="tabledap")
print(e.server)  # "http://erddap.secoora.org/erddap"

e = ERDDAP(server="ngdac", protocol="tabledap") 
print(e.server)  # "https://gliders.ioos.us/erddap"

e = ERDDAP(server="pacioos", protocol="griddap")
print(e.server)  # "http://oos.soest.hawaii.edu/erddap"

Custom Server Configuration

For servers not in the built-in catalog, use the full URL:

from erddapy import ERDDAP

# Use custom server URL
e = ERDDAP(
    server="https://my-institution.edu/erddap",
    protocol="tabledap"
)

# Or with authentication
e = ERDDAP(server="https://private-server.org/erddap")
e.auth = ('username', 'password')

Server Discovery

Find servers with specific characteristics:

from erddapy import servers

# Find servers by description keywords
coastal_servers = {
    name: server for name, server in servers.items() 
    if 'coastal' in server.description.lower()
}

# Find NOAA servers
noaa_servers = {
    name: server for name, server in servers.items()
    if 'noaa' in server.description.lower()
}

print("Coastal servers:", list(coastal_servers.keys()))
print("NOAA servers:", list(noaa_servers.keys()))

Error Handling

The server management system handles various failure modes:

from erddapy import ERDDAP

# Invalid server shortcut - raises KeyError during initialization
try:
    e = ERDDAP(server="nonexistent_server")
except Exception as ex:
    print(f"Server not found: {ex}")

# If servers_list() fails to download from GitHub, 
# it automatically falls back to the bundled server list
from erddapy.servers.servers import servers_list
servers = servers_list()  # Always returns a valid server dictionary

Install with Tessl CLI