volt-client 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. volt_client-1.0.0/PKG-INFO +131 -0
  2. volt_client-1.0.0/README-client.md +103 -0
  3. volt_client-1.0.0/README.md +176 -0
  4. volt_client-1.0.0/pyproject.toml +50 -0
  5. volt_client-1.0.0/setup.cfg +4 -0
  6. volt_client-1.0.0/src/volt_client/__init__.py +28 -0
  7. volt_client-1.0.0/src/volt_client/client.py +826 -0
  8. volt_client-1.0.0/src/volt_client.egg-info/PKG-INFO +131 -0
  9. volt_client-1.0.0/src/volt_client.egg-info/SOURCES.txt +15 -0
  10. volt_client-1.0.0/src/volt_client.egg-info/dependency_links.txt +1 -0
  11. volt_client-1.0.0/src/volt_client.egg-info/requires.txt +10 -0
  12. volt_client-1.0.0/src/volt_client.egg-info/top_level.txt +1 -0
  13. volt_client-1.0.0/tests/test_curves.py +86 -0
  14. volt_client-1.0.0/tests/test_data_endpoints.py +126 -0
  15. volt_client-1.0.0/tests/test_health.py +40 -0
  16. volt_client-1.0.0/tests/test_rate_limiting.py +66 -0
  17. volt_client-1.0.0/tests/test_security.py +263 -0
volt_client-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,131 @@
1
+ Metadata-Version: 2.4
2
+ Name: volt-client
3
+ Version: 1.0.0
4
+ Summary: Python client for Volt Power Analytics API - Access energy market time series data
5
+ Author-email: Volt Power Analytics <support@voltanalytics.no>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://voltpoweranalytics.com
8
+ Project-URL: Documentation, https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs
9
+ Project-URL: Repository, https://github.com/Volt-Power-Analytics/volt-api
10
+ Keywords: energy,api,time-series,power,market,data
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Scientific/Engineering
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ Requires-Dist: polars>=0.20.0
21
+ Requires-Dist: requests>=2.28.0
22
+ Requires-Dist: orjson>=3.9.0
23
+ Provides-Extra: pandas
24
+ Requires-Dist: pandas>=2.0.0; extra == "pandas"
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7.4.0; extra == "dev"
27
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
28
+
29
+ # Volt Client
30
+
31
+ Python client for the Volt Power Analytics API - Access energy market time series data.
32
+
33
+ ## Installation
34
+
35
+ ```bash
36
+ pip install volt-client
37
+ ```
38
+
39
+ ## Quick Start
40
+
41
+ ```python
42
+ import os
43
+ from volt_client import VoltClient
44
+
45
+ # Initialize with your API key
46
+ client = VoltClient(api_key=os.environ["VOLT_API_KEY"])
47
+
48
+ # Get spot prices
49
+ df = client.get_actual(
50
+ "price spot no1 nordpool eur mwh min60 actual",
51
+ start_date="2024-01-01",
52
+ end_date="2024-12-31"
53
+ )
54
+ print(df.head())
55
+ ```
56
+
57
+ ## Features
58
+
59
+ - Simple Python interface for Volt Power Analytics API
60
+ - Support for historical data, forecasts, and forward curves
61
+ - Bulk queries for efficient data retrieval
62
+ - Timezone conversion and server-side aggregation
63
+ - Returns pandas DataFrames (or polars for better performance)
64
+
65
+ ## Usage Examples
66
+
67
+ ### Historical Data
68
+
69
+ ```python
70
+ # Single curve
71
+ df = client.get_actual(
72
+ "price spot no1 nordpool eur mwh min60 actual",
73
+ start_date="2024-01-01",
74
+ end_date="2024-12-31",
75
+ tz="Europe/Oslo",
76
+ agg="daily",
77
+ agg_func="avg"
78
+ )
79
+
80
+ # Multiple curves (bulk query - much faster)
81
+ df = client.get_actual(
82
+ ["price spot no1...", "price spot no2...", "price spot no3..."],
83
+ start_date="2024-01-01",
84
+ end_date="2024-12-31"
85
+ )
86
+ ```
87
+
88
+ ### Forecast Data
89
+
90
+ ```python
91
+ df = client.get_fcast(
92
+ "price no1 volt emps mid-term fcast",
93
+ start_date="2025-01-01",
94
+ end_date="2025-12-31",
95
+ freq="weekly" # Returns percentiles: avg, p10, p25, p50, p75, p90
96
+ )
97
+ ```
98
+
99
+ ### Forward Curves
100
+
101
+ ```python
102
+ df = client.get_closing("price future no1 nasdaq eur mwh close")
103
+ ```
104
+
105
+ ### Performance Tips
106
+
107
+ For large datasets, use polars mode (10x faster):
108
+
109
+ ```python
110
+ client = VoltClient(api_key="...", use_polars=True)
111
+ df = client.get_actual(...) # Returns polars DataFrame
112
+ ```
113
+
114
+ ## API Reference
115
+
116
+ | Method | Description |
117
+ |--------|-------------|
118
+ | `get_actual(curve, start, end)` | Get historical/actual data |
119
+ | `get_fcast(curve, start, end)` | Get forecast data |
120
+ | `get_closing(curve)` | Get forward curve prices |
121
+ | `search(area=None)` | Search available curves |
122
+ | `get_areas()` | List accessible areas |
123
+ | `get_groups()` | List accessible groups |
124
+
125
+ ## Documentation
126
+
127
+ Full documentation: https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs
128
+
129
+ ## Support
130
+
131
+ Contact: support@voltanalytics.no
volt_client-1.0.0/README-client.md ADDED
@@ -0,0 +1,103 @@
1
+ # Volt Client
2
+
3
+ Python client for the Volt Power Analytics API - Access energy market time series data.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install volt-client
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ```python
14
+ import os
15
+ from volt_client import VoltClient
16
+
17
+ # Initialize with your API key
18
+ client = VoltClient(api_key=os.environ["VOLT_API_KEY"])
19
+
20
+ # Get spot prices
21
+ df = client.get_actual(
22
+ "price spot no1 nordpool eur mwh min60 actual",
23
+ start_date="2024-01-01",
24
+ end_date="2024-12-31"
25
+ )
26
+ print(df.head())
27
+ ```
28
+
29
+ ## Features
30
+
31
+ - Simple Python interface for Volt Power Analytics API
32
+ - Support for historical data, forecasts, and forward curves
33
+ - Bulk queries for efficient data retrieval
34
+ - Timezone conversion and server-side aggregation
35
+ - Returns pandas DataFrames (or polars for better performance)
36
+
37
+ ## Usage Examples
38
+
39
+ ### Historical Data
40
+
41
+ ```python
42
+ # Single curve
43
+ df = client.get_actual(
44
+ "price spot no1 nordpool eur mwh min60 actual",
45
+ start_date="2024-01-01",
46
+ end_date="2024-12-31",
47
+ tz="Europe/Oslo",
48
+ agg="daily",
49
+ agg_func="avg"
50
+ )
51
+
52
+ # Multiple curves (bulk query - much faster)
53
+ df = client.get_actual(
54
+ ["price spot no1...", "price spot no2...", "price spot no3..."],
55
+ start_date="2024-01-01",
56
+ end_date="2024-12-31"
57
+ )
58
+ ```
59
+
60
+ ### Forecast Data
61
+
62
+ ```python
63
+ df = client.get_fcast(
64
+ "price no1 volt emps mid-term fcast",
65
+ start_date="2025-01-01",
66
+ end_date="2025-12-31",
67
+ freq="weekly" # Returns percentiles: avg, p10, p25, p50, p75, p90
68
+ )
69
+ ```
70
+
71
+ ### Forward Curves
72
+
73
+ ```python
74
+ df = client.get_closing("price future no1 nasdaq eur mwh close")
75
+ ```
76
+
77
+ ### Performance Tips
78
+
79
+ For large datasets, use polars mode (10x faster):
80
+
81
+ ```python
82
+ client = VoltClient(api_key="...", use_polars=True)
83
+ df = client.get_actual(...) # Returns polars DataFrame
84
+ ```
85
+
86
+ ## API Reference
87
+
88
+ | Method | Description |
89
+ |--------|-------------|
90
+ | `get_actual(curve, start, end)` | Get historical/actual data |
91
+ | `get_fcast(curve, start, end)` | Get forecast data |
92
+ | `get_closing(curve)` | Get forward curve prices |
93
+ | `search(area=None)` | Search available curves |
94
+ | `get_areas()` | List accessible areas |
95
+ | `get_groups()` | List accessible groups |
96
+
97
+ ## Documentation
98
+
99
+ Full documentation: https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs
100
+
101
+ ## Support
102
+
103
+ Contact: support@voltanalytics.no
volt_client-1.0.0/README.md ADDED
@@ -0,0 +1,176 @@
1
+ # Volt API
2
+
3
+ FastAPI-based time series data API with ClickHouse backend for Volt Power Analytics.
4
+
5
+ ## Features
6
+
7
+ - **Time Series Data**: Retrieve historical and forecast data for power market curves
8
+ - **Forward Curves**: Access closing/settlement prices for futures contracts
9
+ - **Bulk Queries**: Efficient multi-curve queries in a single request
10
+ - **Timezone Support**: Full timezone handling with server-side aggregation
11
+ - **Rate Limiting**: Configurable rate limits to prevent abuse
12
+ - **Access Control**: Fine-grained permissions by area, group, and usage rights
13
+
14
+ ## Quick Start
15
+
16
+ ### Local Development
17
+
18
+ ```bash
19
+ # Clone the repository
20
+ git clone https://github.com/voltpoweranalytics/volt-api.git
21
+ cd volt-api
22
+
23
+ # Create virtual environment
24
+ python -m venv .venv
25
+ source .venv/bin/activate # On Windows: .venv\Scripts\activate
26
+
27
+ # Install dependencies
28
+ pip install -e ".[dev]"
29
+
30
+ # Copy environment template and configure
31
+ cp .env.example .env
32
+ # Edit .env with your ClickHouse credentials
33
+
34
+ # Run the server
35
+ DEV_MODE=true uvicorn volt_api.main:app --reload
36
+ ```
37
+
38
+ ### Docker
39
+
40
+ ```bash
41
+ # Build the image
42
+ docker build -t volt-api .
43
+
44
+ # Run the container
45
+ docker run -p 8000:8000 --env-file .env volt-api
46
+ ```
47
+
48
+ ## API Endpoints
49
+
50
+ ### Health & Info
51
+ - `GET /health` - Health check
52
+ - `GET /curves` - List available curves
53
+ - `GET /areas` - List available areas
54
+ - `GET /groups` - List available groups
55
+
56
+ ### Data Retrieval
57
+ - `GET /data/actual` - Get historical data for a single curve
58
+ - `GET /data/closing` - Get forward curve data
59
+ - `GET /data/settlement` - Alias for `/data/closing`
60
+ - `GET /data` - Bulk query for multiple curves by ID
61
+
62
+ ### Parameters
63
+
64
+ | Parameter | Description | Example |
65
+ |-----------|-------------|---------|
66
+ | `curve_name` | Curve identifier | `price spot no1 entso-e eur/mwh min60 actual` |
67
+ | `start_date` | Start date (YYYY-MM-DD) | `2024-01-01` |
68
+ | `end_date` | End date (YYYY-MM-DD) | `2024-12-31` |
69
+ | `tz` | Timezone | `Europe/Oslo`, `CET` |
70
+ | `agg` | Aggregation frequency | `hourly`, `daily`, `monthly` |
71
+ | `agg_func` | Aggregation function | `avg`, `sum`, `min`, `max` |
72
+
73
+ ## Authentication
74
+
75
+ The API supports two authentication methods:
76
+
77
+ ### API Key (Recommended)
78
+ ```python
79
+ import httpx
80
+
81
+ headers = {"X-API-Key": "volt_your_api_key_here"}
82
+ response = httpx.get(
83
+ "https://api.voltpoweranalytics.com/data/actual",
84
+ params={
85
+ "curve_name": "price spot no1 entso-e eur/mwh min60 actual",
86
+ "start_date": "2024-01-01",
87
+ "end_date": "2024-12-31"
88
+ },
89
+ headers=headers
90
+ )
91
+ data = response.json()
92
+ ```
93
+
94
+ ### JWT Token (Dashboard Users)
95
+ ```python
96
+ import httpx
97
+
98
+ headers = {"Authorization": "Bearer your_jwt_token"}
99
+ response = httpx.get(
100
+ "https://api.voltpoweranalytics.com/data/actual",
101
+ params={"curve_name": "...", "start_date": "2024-01-01"},
102
+ headers=headers
103
+ )
104
+ ```
105
+
106
+ ## Python Client
107
+
108
+ ```python
109
+ from volt_api.client import VoltClient
110
+
111
+ client = VoltClient(
112
+ base_url="https://api.voltpoweranalytics.com",
113
+ api_key="volt_your_api_key_here"
114
+ )
115
+
116
+ # Get single curve
117
+ df = client.get_actual(
118
+ "price spot no1 entso-e eur/mwh min60 actual",
119
+ "2024-01-01", "2024-12-31",
120
+ tz="Europe/Oslo"
121
+ )
122
+
123
+ # Get multiple curves (bulk query - much faster)
124
+ df = client.get_actual(
125
+ ["price spot no1 entso-e eur/mwh min60 actual",
126
+ "price spot no2 entso-e eur/mwh min60 actual"],
127
+ "2024-01-01", "2024-12-31"
128
+ )
129
+
130
+ # Get forward curve
131
+ df = client.get_closing("price future epad no1 nasdaq eur/mwh m close")
132
+ ```
133
+
134
+ ## Testing
135
+
136
+ ```bash
137
+ # Run all tests
138
+ pytest
139
+
140
+ # Run with coverage
141
+ pytest --cov=src/volt_api --cov-report=html
142
+
143
+ # Run specific test file
144
+ pytest tests/test_health.py -v
145
+ ```
146
+
147
+ ## Environment Variables
148
+
149
+ | Variable | Description | Default |
150
+ |----------|-------------|---------|
151
+ | `CLICKHOUSE_HOST` | ClickHouse server host | Required |
152
+ | `CLICKHOUSE_PORT` | ClickHouse server port | `8443` |
153
+ | `CLICKHOUSE_USER` | ClickHouse username | `default` |
154
+ | `CLICKHOUSE_PASSWORD` | ClickHouse password | Required |
155
+ | `DEV_MODE` | Bypass authentication | `false` |
156
+ | `RATE_LIMIT_DATA` | Rate limit for data endpoints | `45/minute` |
157
+ | `CORS_ORIGINS` | Allowed CORS origins | See `.env.example` |
158
+
159
+ ## Deployment
160
+
161
+ The API is designed to run on Azure App Service with GitHub Actions CI/CD.
162
+
163
+ ### Manual Deployment
164
+
165
+ 1. Create Azure Web App with container support
166
+ 2. Configure environment variables in Azure
167
+ 3. Push to main branch to trigger deployment
168
+
169
+ ### GitHub Actions Secrets
170
+
171
+ - `AZURE_WEBAPP_PUBLISH_PROFILE_STAGING`
172
+ - `AZURE_WEBAPP_PUBLISH_PROFILE_PRODUCTION`
173
+
174
+ ## License
175
+
176
+ Proprietary - Volt Power Analytics
volt_client-1.0.0/pyproject.toml ADDED
@@ -0,0 +1,50 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "volt-client"
7
+ version = "1.0.0"
8
+ description = "Python client for Volt Power Analytics API - Access energy market time series data"
9
+ readme = "README-client.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ authors = [
13
+ {name = "Volt Power Analytics", email = "support@voltanalytics.no"}
14
+ ]
15
+ keywords = ["energy", "api", "time-series", "power", "market", "data"]
16
+ classifiers = [
17
+ "Development Status :: 5 - Production/Stable",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Topic :: Scientific/Engineering",
24
+ ]
25
+ dependencies = [
26
+ "polars>=0.20.0",
27
+ "requests>=2.28.0",
28
+ "orjson>=3.9.0",
29
+ ]
30
+
31
+ [project.optional-dependencies]
32
+ pandas = [
33
+ "pandas>=2.0.0",
34
+ ]
35
+ dev = [
36
+ "pytest>=7.4.0",
37
+ "ruff>=0.1.0",
38
+ ]
39
+
40
+ [project.urls]
41
+ "Homepage" = "https://voltpoweranalytics.com"
42
+ "Documentation" = "https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs"
43
+ "Repository" = "https://github.com/Volt-Power-Analytics/volt-api"
44
+
45
+ [tool.setuptools.packages.find]
46
+ where = ["src"]
47
+ include = ["volt_client*"]
48
+
49
+ [tool.setuptools.package-data]
50
+ volt_client = ["py.typed"]
volt_client-1.0.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
volt_client-1.0.0/src/volt_client/__init__.py ADDED
@@ -0,0 +1,28 @@
1
+ """
2
+ Volt Client - Python client for Volt Power Analytics API.
3
+
4
+ Usage:
5
+ from volt_client import VoltClient
6
+
7
+ client = VoltClient(api_key="volt_your_api_key")
8
+ df = client.get_actual("price spot no1 nordpool eur mwh min60 actual", "2024-01-01", "2024-12-31")
9
+ """
10
+
11
+ from volt_client.client import (
12
+ DataFrame,
13
+ VoltAccessError,
14
+ VoltClient,
15
+ VoltClientError,
16
+ VoltCurveNotFoundError,
17
+ VoltEmptyDataError,
18
+ )
19
+
20
+ __version__ = "1.0.0"
21
+ __all__ = [
22
+ "VoltClient",
23
+ "VoltClientError",
24
+ "VoltAccessError",
25
+ "VoltCurveNotFoundError",
26
+ "VoltEmptyDataError",
27
+ "DataFrame",
28
+ ]