Open-Meteo Python Requests (DeepWiki)

https://deepwiki.com/open-meteo/python-requests
Admin
Open-Meteo Python Requests is a Python client library for the Open-Meteo Weather API that uses...
Tokens:26,816
Snippets:243
Trust Score:6.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with just install

Source: https://deepwiki.com/open-meteo/python-requests/3.1-getting-started-with-development

Recommended installation method using the Just command runner. The `just install` recipe simplifies the installation process and is defined in the Justfile (line 7).

```bash
just install
```

--------------------------------

### Install project dependencies with uv sync

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Installs project dependencies including development, linting, and testing groups. This is the implementation of `just install`.

```bash
uv sync --group dev --group lint --group test
```

--------------------------------

### Install openmeteo-requests with pip

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Installs the openmeteo-requests library via pip. Requires Python 3.9 or higher and automatically installs dependencies niquests (>=3.14.1) and openmeteo-sdk (>=1.20.1).

```bash
pip install openmeteo-requests
```

--------------------------------

### Development Configuration Mapping Diagram

Source: https://deepwiki.com/open-meteo/python-requests/3-development-guide

Mermaid diagram showing the relationships between development commands (just install, check, test, clean), configuration files (Justfile, pyproject.toml, .python-version, uv.lock, .pre-commit-config.yaml), and tool execution (uv sync, ruff, mypy, pytest, pre-commit). Use this to understand how the Justfile commands orchestrate underlying tools and how configuration files control their behavior.

```mermaid
graph TB
    subgraph "Command Interface"
        JUST_INSTALL["just install"]
        JUST_CHECK["just check"]
        JUST_TEST["just test"]
        JUST_CLEAN["just clean"]
    end
    
    subgraph "Configuration Files"
        JUSTFILE["Justfile"]
        PYPROJECT["pyproject.toml"]
        PYTHON_VERSION[".python-version"]
        UV_LOCK["uv.lock"]
        PRECOMMIT_CONFIG[".pre-commit-config.yaml"]
    end
    
    subgraph "Tool Execution"
        UV_SYNC["uv sync --group dev --group lint --group test"]
        RUFF_CHECK["ruff check openmeteo_requests/"]
        RUFF_FORMAT["ruff format openmeteo_requests/"]
        MYPY_CHECK["mypy openmeteo_requests/"]
        PYTEST_RUN["pytest tests/"]
        PRECOMMIT_RUN["pre-commit run --all-files"]
    end
    
    subgraph "Source Code"
        LIB_CODE["openmeteo_requests/"]
        TEST_CODE["tests/"]
        CLIENT_PY["openmeteo_requests/Client.py"]
        INIT_PY["openmeteo_requests/__init__.py"]
    end
    
    JUSTFILE --> JUST_INSTALL
    JUSTFILE --> JUST_CHECK
    JUSTFILE --> JUST_TEST
    
    JUST_INSTALL --> UV_SYNC
    UV_SYNC --> PYPROJECT
    UV_SYNC --> UV_LOCK
    UV_SYNC --> PYTHON_VERSION
    
    JUST_CHECK --> RUFF_CHECK
    JUST_CHECK --> RUFF_FORMAT
    JUST_CHECK --> MYPY_CHECK
    
    JUST_TEST --> PYTEST_RUN
    
    RUFF_CHECK --> LIB_CODE
    RUFF_FORMAT --> LIB_CODE
    MYPY_CHECK --> CLIENT_PY
    MYPY_CHECK --> INIT_PY
    PYTEST_RUN --> TEST_CODE
    
    PRECOMMIT_CONFIG --> PRECOMMIT_RUN
    PRECOMMIT_RUN --> RUFF_CHECK
    PRECOMMIT_RUN --> MYPY_CHECK
    
    PYPROJECT --> RUFF_CHECK
    PYPROJECT --> MYPY_CHECK
    PYPROJECT --> PYTEST_RUN
```

--------------------------------

### Dependency Management Structure Diagram

Source: https://deepwiki.com/open-meteo/python-requests/5-project-configuration

Mermaid diagram showing the dependency groups and installation commands. Runtime dependencies include niquests and openmeteo-sdk, while dev, lint, and test groups are installed via pip install openmeteo_requests[dev,lint,test].

```mermaid
graph LR
    subgraph "Core Dependencies"
        RUNTIME["Runtime Dependencies<br/>niquests, openmeteo-sdk"]
    end
    
    subgraph "Development Dependency Groups"
        DEV["dev group<br/>pre-commit"]
        LINT["lint group<br/>bandit, mypy, ruff"]
        TEST["test group<br/>pytest, pytest-asyncio, pytest-cov"]
    end
    
    subgraph "Package Installation"
        BASE["Base Install<br/>pip install openmeteo_requests"]
        DEV_INSTALL["Development Install<br/>pip install openmeteo_requests[dev,lint,test]"]
    end
    
    RUNTIME --> BASE
    DEV --> DEV_INSTALL
    LINT --> DEV_INSTALL  
    TEST --> DEV_INSTALL
```

--------------------------------

### Development Lifecycle Flowchart (Mermaid)

Source: https://deepwiki.com/open-meteo/python-requests/3-development-guide

Mermaid flowchart illustrating the complete development lifecycle from local changes to production releases. It shows the sequence of commands (git clone, just install, uv venv + uv sync, pre-commit install) and the automated quality gates (ruff check, mypy, pytest) leading to commit, push, PR, CI test matrix (Python 3.9-3.14), merge, and semantic-release automation for publishing to PyPI and creating GitHub releases.

```mermaid
flowchart TD
    DEV["Developer"] --> CLONE["git clone repository"]
    CLONE --> SETUP["just install"]
    SETUP --> VENV["uv venv + uv sync"]
    VENV --> PRECOMMIT["pre-commit install"]
    
    PRECOMMIT --> CODE["Edit source code"]
    CODE --> LOCAL_CHECK["just check"]
    LOCAL_CHECK --> RUFF["ruff check + format"]
    LOCAL_CHECK --> MYPY["mypy type checking"]
    
    RUFF --> LOCAL_TEST["just test"]
    MYPY --> LOCAL_TEST
    LOCAL_TEST --> PYTEST["pytest execution"]
    
    PYTEST --> COMMIT["git commit"]
    COMMIT --> PRECOMMIT_HOOKS["pre-commit hooks"]
    PRECOMMIT_HOOKS --> PUSH["git push"]
    
    PUSH --> PR["Create Pull Request"]
    PR --> CI_PIPELINE["GitHub Actions CI"]
    CI_PIPELINE --> MATRIX_TEST["Test Matrix Python 3.9-3.14"]
    
    MATRIX_TEST --> MERGE_CHECK{"All checks pass?"}
    MERGE_CHECK -->|No| FIX["Fix issues locally"]
    MERGE_CHECK -->|Yes| MERGE["Merge to main"]
    
    FIX --> CODE
    MERGE --> RELEASE_TRIGGER["Manual release trigger"]
    RELEASE_TRIGGER --> SEMANTIC_RELEASE["semantic-release automation"]
    
    SEMANTIC_RELEASE --> PYPI["Publish to PyPI"]
    SEMANTIC_RELEASE --> GITHUB_RELEASE["Create GitHub release"]
```

--------------------------------

### Development command workflow diagram

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Mermaid flowchart illustrating the development command workflow: install, lint, check, test, and build. Shows the sequence of commands and the decision point for passing checks.

```mermaid
flowchart TD
    DEV["Developer"] --> INSTALL["just install"]
    INSTALL --> DEPS["uv sync --group dev --group lint --group test"]
    
    DEV --> EDIT["Code Modification"]
    EDIT --> LINT["just lint"]
    LINT --> RUFF_FMT["ruff format"]
    RUFF_FMT --> RUFF_FIX["ruff check --fix"]
    
    RUFF_FIX --> CHECK["just check"]
    CHECK --> RUFF_CHK["ruff format --check"]
    RUFF_CHK --> RUFF_LINT["ruff check"]
    RUFF_LINT --> MYPY["mypy"]
    
    MYPY --> TEST["just test"]
    TEST --> PYTEST["pytest"]
    
    DEV --> BUILD["just build"]
    BUILD --> UV_BUILD["uv build"]
    
    PYTEST --> PASS{All Checks Pass?}
    PASS -->|Yes| COMMIT["Ready for Commit"]
    PASS -->|No| EDIT
```

--------------------------------

### Set up pre-commit hooks

Source: https://deepwiki.com/open-meteo/python-requests/3.1-getting-started-with-development

Configures pre-commit hooks after dependencies are installed. Hooks run automatically before each commit and execute tools from the lint dependency group. The pre-commit package is included in the dev group (lines 36-38).

```bash
pre-commit install
```

--------------------------------

### weather_api(url: str, params: ParamsType, method: str = "GET", *, verify: bool | str | None = None, **kwargs) -> list[WeatherApiResponse]

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Makes a request to the Open-Meteo API and returns parsed weather data. This method is part of the Client class.

```APIDOC
## weather_api(url: str, params: ParamsType, method: str = "GET", *, verify: bool | str | None = None, **kwargs) -> list[WeatherApiResponse]

### Description
Makes a request to the Open-Meteo API and returns parsed weather data.

### Method
`weather_api`

### Parameters
- **url** (str) - Required - API endpoint URL
- **params** (ParamsType) - Required - Request parameters dictionary
- **method** (str) - Optional - HTTP method ("GET" or "POST"). Default: "GET"
- **verify** (bool | str | None) - Optional - SSL certificate verification. Default: None
- **kwargs** (Any) - Optional - Additional arguments passed to the HTTP request

### Returns
- **list[WeatherApiResponse]** - List of parsed weather response objects

### Raises
- **OpenMeteoRequestsError** - For API errors, network issues, or invalid responses
```

--------------------------------

### Development Workflow Sequence Diagram

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Mermaid sequence diagram illustrating the daily development cycle, showing interactions between the developer, Just commands, pre-commit, Ruff, and MyPy. It depicts the flow of 'just install', 'just lint', 'just check', and the commit process with pre-commit hooks.

```mermaid
sequenceDiagram
    participant D as Developer
    participant J as Just Commands
    participant PC as Pre-commit
    participant R as Ruff
    participant M as MyPy
    
    D->>J: just install
    J->>D: Dependencies ready
    
    D->>D: Edit code
    D->>J: just lint
    J->>R: ruff format
    J->>R: ruff check --fix
    R->>J: Code formatted/fixed
    J->>D: Lint complete
    
    D->>J: just check
    J->>R: ruff format --check
    J->>R: ruff check
    J->>M: mypy
    M->>J: Type check results
    J->>D: Quality check complete
    
    D->>D: git add .
    D->>PC: git commit
    PC->>PC: Run all hooks
    PC->>D: Commit allowed/blocked
```

--------------------------------

### Verify development environment

Source: https://deepwiki.com/open-meteo/python-requests/3.1-getting-started-with-development

Verification commands to confirm the development environment is set up correctly. Expected outcomes: Python 3.9+, no import errors for openmeteo_requests, and version output for ruff, pytest, and mypy. Optionally, `just --list` shows available recipes.

```bash
python --version
```

```bash
python -c "import openmeteo_requests"
```

```bash
ruff --version
```

```bash
pytest --version
```

```bash
mypy --version
```

--------------------------------

### List available commands with just --list

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Lists all available commands defined in the Justfile. This is the default command when running `just` without arguments.

```bash
just --list
```

--------------------------------

### Client(session: niquests.Session | None = None)

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Constructor for the Client class, which provides synchronous access to the Open-Meteo Weather API with automatic FlatBuffers response processing.

```APIDOC
## Client(session: niquests.Session | None = None)

### Description
Creates a new synchronous client instance for accessing the Open-Meteo Weather API.

### Constructor
`Client(session: niquests.Session | None = None)`

### Parameters
- **session** (niquests.Session | None) - Optional - Optional HTTP session. If not provided, a new session is created.

### Attributes
- `_session`: The underlying HTTP session used for requests
- `_response_cls`: Response handler class (always `WeatherApiResponse`)
- `_closed`: Connection state tracking
```

--------------------------------

### Build distribution packages with uv build

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Builds distribution packages for the project. This command is executed by `just build`.

```bash
uv build
```

--------------------------------

### Dependabot Workflow Overview (Mermaid diagram)

Source: https://deepwiki.com/open-meteo/python-requests/4.3-dependency-automation

Mermaid flowchart showing the daily schedule, dependency scanning, PR creation with fix: prefix, auto-assignment, CI trigger, semantic check, test matrix, and merge readiness. Includes a PR limit check for pip PRs.

```mermaid
flowchart TD
    SCHEDULE[Daily Schedule 13:00 UTC] --> SCAN["Dependabot Scans Dependencies"]
    SCAN --> CHECK_PIP["Check pip Dependencies"]
    SCAN --> CHECK_ACTIONS["Check GitHub Actions"]
    
    CHECK_PIP --> PIP_OUTDATED{Dependencies Outdated?}
    CHECK_ACTIONS --> ACTIONS_OUTDATED{Actions Outdated?}
    
    PIP_OUTDATED -->|Yes| CREATE_PIP_PR["Create pip PR with fix: prefix"]
    ACTIONS_OUTDATED -->|Yes| CREATE_ACTIONS_PR["Create GitHub Actions PR with fix: prefix"]
    
    CREATE_PIP_PR --> ASSIGN_REVIEWER["Auto-assign patrick.zippenfenig"]
    CREATE_ACTIONS_PR --> ASSIGN_REVIEWER
    
    ASSIGN_REVIEWER --> TRIGGER_CI["Trigger CI Pipeline"]
    TRIGGER_CI --> SEMANTIC_CHECK["Semantic PR Check"]
    SEMANTIC_CHECK --> TEST_MATRIX["Test Matrix Execution"]
    
    TEST_MATRIX --> MERGE_READY["Ready for Review & Merge"]
    
    PIP_OUTDATED -->|No| WAIT["Wait for Next Schedule"]
    ACTIONS_OUTDATED -->|No| WAIT
    
    LIMIT_CHECK["Check PR Limit (max 10 pip PRs)"] --> CREATE_PIP_PR
```

--------------------------------

### Run all code quality checks with ruff and mypy

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Runs all code quality checks: format verification without modification, linting verification, and type checking. This is the implementation of `just check`.

```bash
ruff format --check
```

```bash
ruff check
```

```bash
mypy
```

--------------------------------

### AsyncClient.weather_api

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Asynchronously makes a request to the Open-Meteo API and returns parsed weather data. Parameters and return values are identical to the synchronous version, but the method must be awaited.

```APIDOC
## AsyncClient.weather_api

### Description
Asynchronously makes a request to the Open-Meteo API and returns parsed weather data. Parameters and return values are identical to the synchronous version, but the method must be awaited.

### Method
async

### Signature
`async weather_api(url: str, params: ParamsType, method: str = "GET", *, verify: bool | str | None = None, **kwargs) -> list[WeatherApiResponse]`

### Parameters
- **url** (str) - Required - The URL to request.
- **params** (ParamsType) - Required - Query parameters for the request.
- **method** (str) - Optional - HTTP method, defaults to "GET".
- **verify** (bool | str | None) - Optional - SSL verification setting.
- **kwargs** - Optional - Additional keyword arguments.

### Returns
- **list[WeatherApiResponse]** - Parsed weather data.

### Raises
- **OpenMeteoRequestsError** - For API errors, network issues, or invalid responses.
```

--------------------------------

### HTTP Session Customization with requests_cache and retry

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Configures a custom HTTP session with SQLite caching and retry logic, then passes it to the openmeteo_requests client. Use this to enable caching, retries, and authentication for API calls.

```python
import openmeteo_requests
import requests_cache
from retry_requests import retry
 
# Setup caching with SQLite backend
cache_session = requests_cache.CachedSession('.cache', expire_after=-1)
 
# Add retry mechanism for resilient API calls
retry_session = retry(cache_session, retries=5, backoff_factor=0.2)
 
# Initialize client with custom session
om = openmeteo_requests.Client(session=retry_session)
```

--------------------------------

### Synchronous Client Usage with openmeteo_requests.Client

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Initializes a synchronous openmeteo_requests.Client and sends a blocking request to the Open-Meteo forecast API. The params dictionary defines latitude, longitude, hourly and current variables. The response is a list of WeatherApiResponse objects; the first element is accessed as response.

```python
import openmeteo_requests
from openmeteo_sdk.Variable import Variable
 
# Initialize synchronous client
om = openmeteo_requests.Client()
 
# Define request parameters
params = {
    "latitude": 52.54,
    "longitude": 13.41,
    "hourly": ["temperature_2m", "precipitation", "wind_speed_10m"],
    "current": ["temperature_2m", "relative_humidity_2m"]
}
 
# Make API request
responses = om.weather_api("https://api.open-meteo.com/v1/forecast", params=params)
response = responses[0]
```

--------------------------------

### Release System Architecture Diagram

Source: https://deepwiki.com/open-meteo/python-requests/4.2-release-management

Mermaid diagram illustrating the release management architecture: developer workflow, PR validation, release process, semantic-release steps, and configuration. Shows how conventional commits trigger semantic-release to publish to PyPI.

```mermaid
graph TB
    subgraph "Developer Workflow"
        DEV[Developer] --> COMMIT["Conventional Commits<br/>(feat:, fix:, build:)"]
        COMMIT --> PR["Pull Request"]
    end
    
    subgraph "PR Validation"
        PR --> SEMANTIC_CHECK["semantic-pr-check.yml<br/>amannn/action-semantic-pull-request"]
        SEMANTIC_CHECK --> VALIDATION{"PR Title Valid?"}
        VALIDATION -->|No| REJECT["Block Merge"]
        VALIDATION -->|Yes| APPROVE["Allow Merge"]
    end
    
    subgraph "Release Process"
        APPROVE --> MERGE["Merge to main"]
        MERGE --> MANUAL_TRIGGER["Manual workflow_dispatch<br/>release.yml"]
        MANUAL_TRIGGER --> SEMANTIC_RELEASE["semantic-release"]
    end
    
    subgraph "semantic-release Process"
        SEMANTIC_RELEASE --> ANALYZE["@semantic-release/commit-analyzer<br/>Determine version bump"]
        ANALYZE --> NOTES["@semantic-release/release-notes-generator<br/>Generate changelog"]
        NOTES --> GIT_UPDATE["@semantic-release/git<br/>Update repository"]
        GIT_UPDATE --> GITHUB_RELEASE["@semantic-release/github<br/>Create GitHub release"]
        GITHUB_RELEASE --> PYPI_PUBLISH["semantic-release-pypi<br/>Publish to PyPI"]
    end
    
    subgraph "Configuration"
        CONFIG[".releaserc.json"] --> SEMANTIC_RELEASE
        SECRETS["GitHub Secrets<br/>GITHUB_TOKEN<br/>PYPI_PASSWORD"] --> SEMANTIC_RELEASE
    end

```

--------------------------------

### Asynchronous Client Usage with openmeteo_requests.AsyncClient

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Uses openmeteo_requests.AsyncClient for non-blocking requests. The async function fetch_weather_data awaits the weather_api call and returns the first response. asyncio.run executes the coroutine, suitable for concurrent data processing.

```python
import openmeteo_requests
import asyncio
 
async def fetch_weather_data():
    # Initialize asynchronous client
    om = openmeteo_requests.AsyncClient()
    
    # Same parameter structure as synchronous client
    params = {
        "latitude": 52.54,
        "longitude": 13.41,
        "hourly": ["temperature_2m", "precipitation", "wind_speed_10m"],
        "current": ["temperature_2m", "relative_humidity_2m"]
    }
    
    # Await API response
    responses = await om.weather_api("https://api.open-meteo.com/v1/forecast", params=params)
    return responses[0]
 
# Execute async function
response = asyncio.run(fetch_weather_data())
```

--------------------------------

### Session Lifecycle State Diagram (Mermaid)

Source: https://deepwiki.com/open-meteo/python-requests/2.2-client-architecture

Mermaid state diagram illustrating the session lifecycle for both synchronous and asynchronous clients. Shows transitions from Created to Active, including Ready, Processing, HTTPRequest states, and closure/error paths.

```mermaid
stateDiagram-v2
    [*] --> Created
    Created --> Active: __init__()
    
    state Active {
        [*] --> Ready
        Ready --> Processing: weather_api()
        Processing --> Ready: Request Complete
        
        state "Synchronous Client" as SyncState {
            Ready --> HTTPRequest: _request()
            HTTPRequest --> Ready: Response Processed
        }
        
        state "Asynchronous Client" as AsyncState {
            Ready --> AsyncContext: async with session
            AsyncContext --> HTTPRequest: await method()
            HTTPRequest --> Ready: Response Processed
        }
    }
    
    Active --> Closed: close()
    Closed --> [*]
    
    Active --> Error: Connection Error
    Error --> [*]
```

--------------------------------

### Execute test suite with pytest

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Executes the test suite. This is the implementation of `just test` and accepts optional arguments.

```bash
pytest
```

--------------------------------

### Usage workflow flowchart

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Mermaid flowchart outlining the typical usage workflow for both synchronous and asynchronous clients. It shows the sequence from client initialization through parameter definition, API call, data extraction, and conversion to NumPy or DataFrames.

```mermaid
flowchart TD
    START["Initialize Client"] --> PARAMS["Define API Parameters"]
    PARAMS --> REQUEST["Call weather_api()"]
    REQUEST --> RESPONSE["Get Response Objects"]
    RESPONSE --> EXTRACT["Extract Variable Data"]
    EXTRACT --> CONVERT["Convert to NumPy/DataFrames"]
    CONVERT --> ANALYZE["Data Analysis"]
    
    subgraph "Parameter Definition"
        PARAMS --> LOCATION["latitude, longitude"]
        PARAMS --> VARIABLES["hourly, daily, current"]
        PARAMS --> TIMERANGE["start_date, end_date"]
    end
    
    subgraph "Data Extraction Methods"
        EXTRACT --> CURRENT_VARS["Current().Variables()"]
        EXTRACT --> HOURLY_VARS["Hourly().Variables()"]
        EXTRACT --> DAILY_VARS["Daily().Variables()"]
    end
    
    subgraph "Conversion Options"
        CONVERT --> NUMPY_CONV["ValuesAsNumpy()"]
        CONVERT --> PANDAS_CONV["pd.DataFrame()"]
        CONVERT --> POLARS_CONV["pl.DataFrame()"]
    end
```

--------------------------------

### Public API class diagram

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Mermaid class diagram showing the public API structure: Client and AsyncClient both expose __init__, weather_api, and close methods, and return WeatherApiResponse or raise OpenMeteoRequestsError.

```mermaid
classDiagram
    class Client {
        +__init__(session: niquests.Session | None)
        +weather_api(url: str, params: ParamsType, method: str, **kwargs) list[WeatherApiResponse]
        +close() None
        -_session: niquests.Session
        -_response_cls: type[WeatherApiResponse]
        -_closed: bool | None
    }
    
    class AsyncClient {
        +__init__(session: niquests.AsyncSession | None)
        +weather_api(url: str, params: ParamsType, method: str, **kwargs) list[WeatherApiResponse]
        +close() None
        -_session: niquests.AsyncSession
        -_response_cls: type[WeatherApiResponse]
    }
    
    class OpenMeteoRequestsError {
        <<Exception>>
        +message: str
    }
    
    class WeatherApiResponse {
        <<external>>
        +data: bytes
    }
    
    Client --> WeatherApiResponse : returns
    AsyncClient --> WeatherApiResponse : returns
    Client --> OpenMeteoRequestsError : raises
    AsyncClient --> OpenMeteoRequestsError : raises
```

--------------------------------

### AsyncClient

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Asynchronous client class for making weather API requests. It accepts an optional niquests.AsyncSession, provides a weather_api method that returns a coroutine resolving to a list of WeatherApiResponse, and a close method.

```APIDOC
## AsyncClient

### Description
Asynchronous client for the openmeteo-requests library. Provides a weather_api method to fetch weather data and a close method to clean up resources.

### Constructor
- **session** (niquests.AsyncSession | None) - Optional existing async session to use.

### Methods
#### weather_api
- **Parameters:**
  - **url** (str) - API endpoint URL.
  - **params** (ParamsType) - Query parameters for the request.
  - **method** (str) - HTTP method to use.
  - **kwargs** - Additional keyword arguments.
- **Returns:** list[WeatherApiResponse]

#### close
- **Parameters:** none
- **Returns:** None

```

--------------------------------

### Quality Gates and Integration Flowchart

Source: https://deepwiki.com/open-meteo/python-requests/4.1-continuous-integration-pipeline

Mermaid flowchart illustrating the CI quality gates (format, lint, type, test) and their integration with pre-commit hooks, PR status checks, branch protection, and development tools.

```mermaid
flowchart LR
    subgraph gates["Quality Gates"]
        format_gate["Format Check<br/>ruff format --check"]
        lint_gate["Linting<br/>ruff check"]
        type_gate["Type Checking<br/>mypy"]
        test_gate["Unit Tests<br/>pytest"]
    end
    
    subgraph integration["Integration Points"]
        precommit["Pre-commit Hooks<br/>Local Validation"]
        pr_check["PR Status Checks<br/>GitHub Integration"]
        merge_protection["Branch Protection<br/>Merge Requirements"]
    end
    
    subgraph tools["Development Tools"]
        justfile["Justfile Commands"]
        uv_sync["UV Dependency Management"]
        ruff_config["Ruff Configuration"]
        mypy_config["MyPy Configuration"]
    end
    
    format_gate --> pr_check
    lint_gate --> pr_check
    type_gate --> pr_check
    test_gate --> pr_check
    
    pr_check --> merge_protection
    precommit -.-> format_gate
    precommit -.-> lint_gate
    
    justfile --> format_gate
    justfile --> lint_gate
    justfile --> type_gate
    justfile --> test_gate
    
    uv_sync --> test_gate
    ruff_config --> format_gate
    ruff_config --> lint_gate
    mypy_config --> type_gate
```

--------------------------------

### Client

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Synchronous client class for making weather API requests. It accepts an optional niquests.Session, provides a weather_api method to fetch weather data, and a close method to release resources.

```APIDOC
## Client

### Description
Synchronous client for the openmeteo-requests library. Provides a weather_api method to fetch weather data and a close method to clean up resources.

### Constructor
- **session** (niquests.Session | None) - Optional existing session to use.

### Methods
#### weather_api
- **Parameters:**
  - **url** (str) - API endpoint URL.
  - **params** (ParamsType) - Query parameters for the request.
  - **method** (str) - HTTP method to use.
  - **kwargs** - Additional keyword arguments.
- **Returns:** list[WeatherApiResponse]

#### close
- **Parameters:** none
- **Returns:** None

```

--------------------------------

### Connection State Tracking in weather_api (Python)

Source: https://deepwiki.com/open-meteo/python-requests/2.2-client-architecture

Python code snippet showing connection state tracking in the synchronous Client's weather_api method. Raises ConnectionError with message 'Unavailable connection' if the client is closed.

```python
def weather_api(self, ...):
    if self._closed:
        msg = "Unavailable connection"
        raise ConnectionError(msg)
```

--------------------------------

### Format and fix code issues with ruff

Source: https://deepwiki.com/open-meteo/python-requests/3.2-development-tools-and-workflow

Formats code and automatically fixes resolvable linting issues. This is the implementation of `just lint`.

```bash
ruff format
```

```bash
ruff check --fix
```

--------------------------------

### Code Quality Pipeline Diagram

Source: https://deepwiki.com/open-meteo/python-requests/5.1-build-configuration-and-dependencies

Mermaid diagram illustrating the code quality pipeline and quality gates for the project. Shows how source code flows through bandit, mypy, ruff, and pytest, with coverage enforcing an 80% minimum threshold.

```mermaid
graph TB
    subgraph "Code Quality Pipeline"
        SOURCE["Source Code"]
        BANDIT["bandit - Security Scanner"]
        MYPY["mypy - Type Checker"]
        RUFF["ruff - Linter & Formatter"]
        PYTEST["pytest - Test Runner"]
        COVERAGE["coverage - Test Coverage"]
    end
    
    subgraph "Quality Gates"
        SECURITY_CHECK["Security Vulnerabilities"]
        TYPE_SAFETY["Type Safety"]
        CODE_STYLE["Code Style & Quality"]
        TEST_RESULTS["Test Results"]
        COVERAGE_THRESHOLD["80% Coverage Minimum"]
    end
    
    SOURCE --> BANDIT
    SOURCE --> MYPY
    SOURCE --> RUFF
    SOURCE --> PYTEST
    PYTEST --> COVERAGE
    
    BANDIT --> SECURITY_CHECK
    MYPY --> TYPE_SAFETY
    RUFF --> CODE_STYLE
    PYTEST --> TEST_RESULTS
    COVERAGE --> COVERAGE_THRESHOLD
```

--------------------------------

### Dependency Update Lifecycle Sequence Diagram

Source: https://deepwiki.com/open-meteo/python-requests/4.3-dependency-automation

Sequence diagram illustrating the automated dependency update lifecycle: Dependabot scans pip and GitHub Actions dependencies daily, creates PRs with a 'fix:' prefix, and auto-assigns patrick.zippenfenig. The CI pipeline validates conventional commits, runs a test matrix (Python 3.9-3.14), and executes quality checks (ruff, mypy). After review and merge, Semantic Release analyzes 'fix:' commits, increments the patch version, and publishes to PyPI.

```mermaid
sequenceDiagram
    participant D as Dependabot
    participant GH as GitHub Repository
    participant CI as CI Pipeline
    participant R as Reviewer
    participant M as Main Branch
    participant SR as Semantic Release
    
    Note over D: Daily at 13:00 UTC
    D->>D: Scan pip and github-actions dependencies
    D->>GH: Create PR with "fix:" prefix
    D->>R: Auto-assign patrick.zippenfenig
    
    GH->>CI: Trigger semantic-pr-check.yml
    CI->>CI: Validate conventional commit format
    CI->>CI: Run test matrix (Python 3.9-3.14)
    CI->>CI: Execute quality checks (ruff, mypy)
    CI-->>GH: Report status checks
    
    R->>GH: Review and approve PR
    R->>M: Merge to main branch
    
    M->>SR: Trigger release workflow
    SR->>SR: Analyze "fix:" commits
    SR->>SR: Increment patch version
    SR->>GH: Create release and publish to PyPI
```

--------------------------------

### Release Workflow Permissions Configuration

Source: https://deepwiki.com/open-meteo/python-requests/4.2-release-management

Defines the permissions required for the release workflow, including write access to contents, issues, pull-requests, and id-token for OIDC. This is necessary for semantic-release to update repository files and publish to PyPI.

```yaml
# Permissions required for release operations
permissions:
  contents: write      # Update repository files
  issues: write       # Create/update issues
  pull-requests: write # Create/update PRs
  id-token: write     # OIDC token for PyPI publishing
```

--------------------------------

### Access current weather data with Variable enum filtering

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Access current weather data by iterating over variables and filtering with the openmeteo-sdk Variable enum and altitude values. Use this to retrieve specific current conditions like temperature and relative humidity at 2 meters.

```python
# Access current weather data
current = response.Current()
current_variables = list(map(lambda i: current.Variables(i), range(0, current.VariablesLength())))
 
# Filter specific variables using openmeteo-sdk Variable enum
current_temperature_2m = next(filter(
    lambda x: x.Variable() == Variable.temperature and x.Altitude() == 2, 
    current_variables
))
current_relative_humidity_2m = next(filter(
    lambda x: x.Variable() == Variable.relative_humidity and x.Altitude() == 2, 
    current_variables
))
 
# Extract values
print(f"Current temperature: {current_temperature_2m.Value()}")
print(f"Current humidity: {current_relative_humidity_2m.Value()}")
```

--------------------------------

### Extract hourly data as NumPy arrays with ValuesAsNumpy

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Extract hourly data as NumPy arrays using zero-copy conversion via ValuesAsNumpy(). Filter variables by Variable enum and altitude, and generate the time range from the hourly structure's Time, TimeEnd, and Interval.

```python
import numpy as np
 
# Access hourly data structure
hourly = response.Hourly()
hourly_time = range(hourly.Time(), hourly.TimeEnd(), hourly.Interval())
hourly_variables = list(map(lambda i: hourly.Variables(i), range(0, hourly.VariablesLength())))
 
# Extract NumPy arrays using zero-copy conversion
hourly_temperature_2m = next(filter(
    lambda x: x.Variable() == Variable.temperature and x.Altitude() == 2, 
    hourly_variables
)).ValuesAsNumpy()
 
hourly_precipitation = next(filter(
    lambda x: x.Variable() == Variable.precipitation, 
    hourly_variables
)).ValuesAsNumpy()
 
hourly_wind_speed_10m = next(filter(
    lambda x: x.Variable() == Variable.wind_speed and x.Altitude() == 10, 
    hourly_variables
)).ValuesAsNumpy()
```

--------------------------------

### Create pandas DataFrame from FlatBuffers time data

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Creates a pandas DataFrame from FlatBuffers time data and NumPy weather variable arrays. Uses pd.date_range with inclusive="left" to generate the time index from hourly.Time(), hourly.TimeEnd(), and hourly.Interval().

```python
import pandas as pd
 
# Create time index from FlatBuffers time data
hourly_data = {
    "date": pd.date_range(
        start=pd.to_datetime(hourly.Time(), unit="s"),
        end=pd.to_datetime(hourly.TimeEnd(), unit="s"),
        freq=pd.Timedelta(seconds=hourly.Interval()),
        inclusive="left"
    )
}
 
# Add weather variables from NumPy arrays
hourly_data["temperature_2m"] = hourly_temperature_2m
hourly_data["precipitation"] = hourly_precipitation
hourly_data["wind_speed_10m"] = hourly_wind_speed_10m
 
# Create DataFrame
hourly_dataframe_pd = pd.DataFrame(data=hourly_data)
```

--------------------------------

### OpenMeteoRequestsError

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Exception class raised for errors in the openmeteo-requests library. Contains a message string describing the error.

```APIDOC
## OpenMeteoRequestsError

### Description
Exception raised by the openmeteo-requests library.

### Attributes
- **message** (str) - Error message.

```

--------------------------------

### Use retry_requests.retry() for retry logic

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Used in the session parameter to add retry logic for automatic retry on network failures.

```python
`retry_requests.retry()`
```

--------------------------------

### Zero-copy conversion to NumPy array

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Used to convert FlatBuffers variable data to a NumPy array with zero-copy operations, suitable for numerical processing in data science workflows.

```python
# Zero-copy conversion to NumPy array
temperature_array = temperature_variable.ValuesAsNumpy()
```

--------------------------------

### Multi-Location Batch Request with open-meteo API

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Sends a batch request for multiple geographic locations in a single API call and iterates over the responses. The response object exposes Latitude() and Longitude() methods to identify each location.

```python
# Multiple locations in single request
params = {
    "latitude": [52.54, 48.85],  # Berlin, Paris
    "longitude": [13.41, 2.35],
    "hourly": ["temperature_2m", "precipitation"]
}
 
responses = om.weather_api("https://api.open-meteo.com/v1/forecast", params=params)
 
# Process each location response
for i, response in enumerate(responses):
    print(f"Location {i}: {response.Latitude()}°N {response.Longitude()}°E")
```

--------------------------------

### Create Polars DataFrame from time-series data

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Builds a Polars DataFrame using pl.datetime_range() and pl.select() for efficient construction, following a pattern similar to the pandas integration.

```python
dataframe = pl.select(
    date=pl.datetime_range(start, end, freq, closed="left"),
    temperature_2m=temperature_array,
    precipitation=precipitation_array
)
```

--------------------------------

### AsyncClient.close

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Asynchronously closes the HTTP session. Must be awaited when called. Unlike the synchronous client, the async client does not track connection state.

```APIDOC
## AsyncClient.close

### Description
Asynchronously closes the HTTP session. Must be awaited when called. Unlike the synchronous client, the async client does not track connection state.

### Method
async

### Signature
`async close() -> None`

### Parameters
None

### Returns
- **None**
```

--------------------------------

### PR Validation Workflow (Mermaid diagram)

Source: https://deepwiki.com/open-meteo/python-requests/4.2-release-management

Mermaid diagram showing the PR validation workflow. It illustrates GitHub events (pull_request_target opened, edited, synchronize) triggering the semantic-pr-check.yml action (amannn/action-semantic-pull-request@v5.5.3) with GITHUB_TOKEN, leading to valid or invalid title results and merge allowed/blocked outcomes.

```mermaid
graph LR
    subgraph "GitHub Events"
        PR_OPEN["pull_request_target<br/>opened"]
        PR_EDIT["pull_request_target<br/>edited"] 
        PR_SYNC["pull_request_target<br/>synchronize"]
    end
    
    subgraph "semantic-pr-check.yml"
        ACTION["amannn/action-semantic-pull-request@v5.5.3"]
        GITHUB_TOKEN["GITHUB_TOKEN"]
    end
    
    subgraph "Validation Results"
        VALID["✓ Valid Title<br/>feat: add new feature"]
        INVALID["✗ Invalid Title<br/>Add new feature"]
    end
    
    PR_OPEN --> ACTION
    PR_EDIT --> ACTION
    PR_SYNC --> ACTION
    GITHUB_TOKEN --> ACTION
    
    ACTION --> VALID
    ACTION --> INVALID
    
    VALID --> MERGE_ALLOWED["Merge Allowed"]
    INVALID --> MERGE_BLOCKED["Merge Blocked"]
```

--------------------------------

### Use requests_cache.CachedSession for data caching

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Used in the session parameter to enable data caching with persistent storage and reduced API calls.

```python
`requests_cache.CachedSession`
```

--------------------------------

### close() -> None

Source: https://deepwiki.com/open-meteo/python-requests/2.3-public-api-reference

Closes the HTTP session and marks the client as unavailable. After calling this method, subsequent requests will raise ConnectionError.

```APIDOC
## close() -> None

### Description
Closes the HTTP session and marks the client as unavailable. After calling this method, subsequent requests will raise `ConnectionError`. The client cannot be reused after closing.

### Method
`close`

### Parameters
None

### Returns
- **None**
```

--------------------------------

### Create Polars DataFrame from FlatBuffers time data

Source: https://deepwiki.com/open-meteo/python-requests/2.1-installation-and-basic-usage

Creates a Polars DataFrame using pl.datetime_range with closed="left" and native datetime handling. Converts FlatBuffers timestamps to timezone-aware datetime objects before building the DataFrame.

```python
import polars as pl
from datetime import datetime, timedelta, timezone
 
# Convert FlatBuffers timestamps to datetime objects
start = datetime.fromtimestamp(hourly.Time(), timezone.utc)
end = datetime.fromtimestamp(hourly.TimeEnd(), timezone.utc)
freq = timedelta(seconds=hourly.Interval())
 
# Create Polars DataFrame with datetime range
hourly_dataframe_pl = pl.select(
    date=pl.datetime_range(start, end, freq, closed="left"),
    temperature_2m=hourly_temperature_2m,
    precipitation=hourly_precipitation,
    wind_speed_10m=hourly_wind_speed_10m
)
```

--------------------------------

### Create pandas DataFrame from time-series data

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Constructs a pandas DataFrame for time-series data, using pd.date_range() for temporal indexing and NumPy arrays for values. Useful when integrating with pandas for analysis and visualization.

```python
hourly_data = {
    "date": pd.date_range(start, end, freq, inclusive="left"),
    "temperature_2m": temperature_array,
    "precipitation": precipitation_array
}
dataframe = pd.DataFrame(data=hourly_data)
```

--------------------------------

### FlatBuffers attribute access with function calls

Source: https://deepwiki.com/open-meteo/python-requests/2-user-guide

Shows that FlatBuffers objects require method calls to access attributes, unlike typical Python dictionaries. Use this when working with response objects from the Weather API.

```python
# FlatBuffers attribute access requires function calls
response.Latitude()    # Not: response.latitude
response.Elevation()   # Not: response.elevation
current.Time()         # Not: current.time
```

--------------------------------

### Custom Release Rule for Dependency Updates

Source: https://deepwiki.com/open-meteo/python-requests/4.2-release-management

Custom rule in .releaserc.json that triggers a patch release for build commits with scope 'deps'. Ensures dependency updates like 'build(deps): update requests' are released as patches.

```json
{
  "type": "build",
  "scope": "deps", 
  "release": "patch"
}
```
Tokens:
Raw