Core API#

The core API provides the main client interface, configuration management, and exception handling for the sgu-client library.

Main Client#

The SGUClient is the primary entry point for all API interactions. It provides a hierarchical interface to access different data domains.

Usage Example:

from sgu_client import SGUClient, SGUConfig

# Basic usage
client = SGUClient()

# With custom configuration
config = SGUConfig(timeout=60, debug=True, max_retries=5)
client = SGUClient(config=config)

# Using context manager
with SGUClient() as client:
    stations = client.levels.observed.get_stations()

API Documentation:

Main SGU Client class.

class sgu_client.sgu_client.SGUClient(config=None)[source]#

Bases: object

Main client for interacting with SGU API.

This is the primary interface users will interact with.

Example

>>> client = SGUClient()
>>> stations = client.levels.observed.get_stations()
>>> measurements = client.levels.observed.get_measurements()

>>> # With custom config
>>> config = SGUConfig(timeout=60, debug=True)
>>> client = SGUClient(config=config)
Parameters:

config (SGUConfig | None)

__init__(config=None)[source]#

Initialize the SGU client.

Parameters:

config (SGUConfig | None) – Configuration object. If None, uses default config.

__enter__()[source]#

Context manager entry.

Returns:

The SGU client instance for use in with statements

__exit__(exc_type, exc_val, exc_tb)[source]#

Context manager exit - clean up resources.

Parameters:

  • exc_type – Exception type (if any)

  • exc_val – Exception value (if any)

  • exc_tb – Exception traceback (if any)

Configuration#

The SGUConfig class manages all configuration options for the SGU client, including API endpoints, timeouts, retry behavior, and logging.

Configuration Options:

  • timeout: Request timeout in seconds (default: 30)

  • max_retries: Maximum number of retry attempts (default: 3)

  • debug: Enable debug logging (default: False)

  • base_url: Override default API base URL (advanced usage)

Configuration management for SGU Client.

class sgu_client.config.SGUConfig(**data)[source]#

Bases: BaseModel

Configuration settings for SGU API client.

Parameters:

data (Any)

base_url: str#
timeout: float#
max_retries: int#
user_agent: str#
log_level: str | int | None#
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sgu_client.config.setup_logging(log_level)[source]#

Configure logging for the SGU client.

This function sets up logging with a standard format that includes timestamp, logger name, level, and message. It uses a singleton pattern to ensure logging is only configured once per process.

Parameters:

log_level (str | int | None) – Logging level to use. Can be: - String: “DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL” - Integer: logging.DEBUG, logging.INFO, etc. - None: Skip logging configuration (user manages their own logging)

Return type:

None

Example

>>> setup_logging("DEBUG")
>>> setup_logging(logging.INFO)
>>> setup_logging(None)  # Don't configure logging

Exceptions#

The library provides specific exception classes for different error scenarios, all inheriting from SGUClientError.

Exception Hierarchy:

  • SGUClientError - Base exception

  • APIError - API-related errors

  • ValidationError - Data validation errors

  • NetworkError - Network communication errors

Custom exceptions for SGU Client.

exception sgu_client.exceptions.SGUClientError[source]#

Bases: Exception

Base exception for all SGU client errors.

exception sgu_client.exceptions.SGUAPIError(message, status_code=None, response_data=None)[source]#

Bases: SGUClientError

Raised when the SGU API returns an error response.

Parameters:

  • message (str)

  • status_code (int | None)

  • response_data (dict | None)

__init__(message, status_code=None, response_data=None)[source]#
Parameters:

  • message (str)

  • status_code (int | None)

  • response_data (dict | None)

exception sgu_client.exceptions.SGUConnectionError[source]#

Bases: SGUClientError

Raised when connection to SGU API fails.

exception sgu_client.exceptions.SGUTimeoutError[source]#

Bases: SGUClientError

Raised when a request to SGU API times out.

exception sgu_client.exceptions.SGUValidationError[source]#

Bases: SGUClientError

Raised when data validation fails.

Base Client#

The BaseClient provides low-level HTTP communication with retry logic and error handling. Most users won’t interact with this directly.

Base HTTP client for SGU API.

class sgu_client.client.base.BaseClient(config=None)[source]#

Bases: object

Base HTTP client with common functionality for SGU API.

Parameters:

config (SGUConfig | None)

__init__(config=None)[source]#

Initialize the base client.

Parameters:

config (SGUConfig | None) – Configuration object. If None, uses default config.

get(endpoint, params=None, base_url=None, **kwargs)[source]#

Make a GET request.

Parameters:

  • endpoint (str) – API endpoint path

  • params (dict[str, Any] | None) – Query parameters

  • base_url (str | None) – Optional override for base URL

  • **kwargs – Additional arguments passed to requests

Return type:

dict[str, Any]

Returns:

JSON response data

Raises:
post(endpoint, data=None, **kwargs)[source]#

Make a POST request.

Parameters:

  • endpoint (str) – API endpoint path

  • data (dict[str, Any] | None) – Request body data

  • **kwargs – Additional arguments passed to requests

Return type:

dict[str, Any]

Returns:

JSON response data

Raises:
__enter__()[source]#

Context manager entry.

Returns:

The client instance for use in with statements

__exit__(exc_type, exc_val, exc_tb)[source]#

Context manager exit - clean up resources.

Parameters:

  • exc_type – Exception type (if any)

  • exc_val – Exception value (if any)

  • exc_tb – Exception traceback (if any)

See Also#