apccapi 0.1.0__tar.gz → 0.1.1__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: apccapi
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: APCC Climate Information toolKit API package
5
5
  Home-page: https://www.apcc21.org
6
6
  Author: APEC Climate Center
@@ -58,14 +58,103 @@ request_url=https://apcc21.org/clikapi/request/apccdata
58
58
  status_url=https://apcc21.org/clikapi/request/status
59
59
  ```
60
60
 
61
- ## Test
61
+ ## Usage
62
62
 
63
- Perform a small test retrieve of MME data:
63
+ ### Quick start: dataset download helpers
64
+
65
+ Each helper submits the request, polls until it's done, downloads the
66
+ result, and returns the output file path (or raises on failure - see
67
+ [Error handling](#error-handling)).
68
+
69
+ ```python
70
+ import apccapi
71
+
72
+ apccapi.download_MME_3MONTH(
73
+ {
74
+ 'type': 'FORECAST',
75
+ 'method': 'SCM',
76
+ 'variable': ['prec', 't2m'],
77
+ 'period': ['Monthly mean'],
78
+ 'yearmonth': ['201909']
79
+ },
80
+ 'mme3.zip'
81
+ )
82
+
83
+ apccapi.download_MME_6MONTH(
84
+ {
85
+ 'type': 'FORECAST',
86
+ 'method': 'SCM',
87
+ 'variable': ['prec', 't2m'],
88
+ 'period': ['Monthly mean'],
89
+ 'yearmonth': ['201909']
90
+ },
91
+ 'mme6.zip'
92
+ )
93
+
94
+ apccapi.download_MME_MODEL(
95
+ {
96
+ 'type': 'FORECAST',
97
+ 'institute': 'APCC',
98
+ 'model': 'SCOPS',
99
+ 'variable': ['prec', 't2m'],
100
+ 'yearmonth': ['201909']
101
+ },
102
+ 'model.zip'
103
+ )
104
+
105
+ apccapi.download_CMIP5(
106
+ {
107
+ 'code': 'AD'
108
+ },
109
+ 'cmip5.zip'
110
+ )
111
+
112
+ apccapi.download_ERA5(
113
+ {
114
+ 'timestep': 'DAILY', # 'DAILY' | 'MONTHLY' | 'HOURLY'
115
+ 'level': 'single', # 'pressure' | 'single'
116
+ 'variable': 't2m',
117
+ 'year': '2020',
118
+ 'month': '12' # omit for 'MONTHLY'
119
+ },
120
+ 't2m_202012.nc'
121
+ )
122
+
123
+ apccapi.download_NCEP1(
124
+ {
125
+ 'timestep': 'DAILY', # 'DAILY' | 'MONTHLY'
126
+ 'level': 'pressure',
127
+ 'variable': 'air',
128
+ 'year': '2022' # only required for 'DAILY'
129
+ },
130
+ 'air.2022.nc'
131
+ )
132
+
133
+ apccapi.download_NCEP2(
134
+ {
135
+ 'timestep': 'DAILY',
136
+ 'level': 'pressure',
137
+ 'variable': 'air',
138
+ 'year': '2022'
139
+ },
140
+ 'air.2022.nc'
141
+ )
64
142
  ```
65
- $ python
66
- >>> import apccapi
67
- >>> c = apccapi.Client()
68
- >>> c.retrieve(
143
+
144
+ More runnable examples (one file per dataset) are in [`example/`](example/).
145
+
146
+ ### Low-level usage: `Client.retrieve`
147
+
148
+ The helpers above are thin wrappers around `Client.retrieve()`. Call it
149
+ directly when you need a `jobtype`/`dataset` combination that doesn't have
150
+ a dedicated helper yet, or the clipping jobtypes (`Clipping_MME`,
151
+ `Clipping_Model`):
152
+
153
+ ```python
154
+ import apccapi
155
+
156
+ c = apccapi.Client()
157
+ c.retrieve(
69
158
  {
70
159
  'jobtype': 'MME',
71
160
  'dataset': 'MME_3MONTH',
@@ -77,8 +166,50 @@ $ python
77
166
  },
78
167
  'mme3.zip'
79
168
  )
80
- >>>
169
+ ```
170
+
171
+ ### Clipping
172
+
173
+ `ClippingClient` calls a separate clipping/masking service and returns a
174
+ cropped PNG or NetCDF file for a bounding box:
175
+
176
+ ```python
177
+ import apccapi
178
+
179
+ c = apccapi.ClippingClient()
180
+ c.clip(
181
+ {
182
+ 'lead_month': '3-MON', # '3-MON' | '6-MON'
183
+ 'variable': 'prec', # prec, slp, sst, t2m, t850, z500
184
+ 'method': 'SCM', # SCM, GAUS
185
+ 'period': 'Monthly mean', # Monthly mean, Seasonal mean
186
+ 'iyear': '2021', # issued year
187
+ 'imonth': '2', # issued month
188
+ 'cowest': '188',
189
+ 'coeast': '191',
190
+ 'conorth': '-11',
191
+ 'cosouth': '-15',
192
+ 'return_type': 'png' # 'png' | 'nc'
193
+ }
194
+ )
195
+ ```
196
+
197
+ ### Error handling
198
+
199
+ Every failure (rejected request, job that ends in `Failed`, exhausted
200
+ retries, a broken download) raises `apccapi.ClikApiError` with the
201
+ server's own message, instead of failing silently:
202
+
203
+ ```python
204
+ import apccapi
81
205
 
206
+ try:
207
+ apccapi.download_ERA5(
208
+ {'timestep': 'MONTHLY', 'level': 'single', 'variable': 't2m', 'year': '2020'},
209
+ 't2m_2020.nc'
210
+ )
211
+ except apccapi.ClikApiError as e:
212
+ print('Request failed:', e)
82
213
  ```
83
214
 
84
215
  ## License
@@ -0,0 +1,197 @@
1
+ ## Installation
2
+
3
+ Install via pip with:
4
+
5
+ ```bash
6
+ $ pip install apccapi
7
+ ```
8
+
9
+ ## Configure (Linux)
10
+
11
+ Obtain your API key from the CLIK (Climate Information toolKit) at https://apcc21.org/clik/ and enter it into the apccapi.properties file, formatting it as follows:
12
+
13
+ ```
14
+ $ vi ~/apccapi.properties
15
+
16
+ key={your API key}
17
+ request_url=https://apcc21.org/clikapi/request/apccdata
18
+ status_url=https://apcc21.org/clikapi/request/status
19
+ ```
20
+
21
+ ## Configure (Windows)
22
+
23
+ Obtain your API key from the CLIK (Climate Information toolKit) at https://apcc21.org/clik/, and create the apccapi.properties file in your Windows Home directory (typically C:\Users\YourUserName) with the following format:
24
+
25
+ ```
26
+ key={your API key}
27
+ request_url=https://apcc21.org/clikapi/request/apccdata
28
+ status_url=https://apcc21.org/clikapi/request/status
29
+ ```
30
+
31
+ ## Usage
32
+
33
+ ### Quick start: dataset download helpers
34
+
35
+ Each helper submits the request, polls until it's done, downloads the
36
+ result, and returns the output file path (or raises on failure - see
37
+ [Error handling](#error-handling)).
38
+
39
+ ```python
40
+ import apccapi
41
+
42
+ apccapi.download_MME_3MONTH(
43
+ {
44
+ 'type': 'FORECAST',
45
+ 'method': 'SCM',
46
+ 'variable': ['prec', 't2m'],
47
+ 'period': ['Monthly mean'],
48
+ 'yearmonth': ['201909']
49
+ },
50
+ 'mme3.zip'
51
+ )
52
+
53
+ apccapi.download_MME_6MONTH(
54
+ {
55
+ 'type': 'FORECAST',
56
+ 'method': 'SCM',
57
+ 'variable': ['prec', 't2m'],
58
+ 'period': ['Monthly mean'],
59
+ 'yearmonth': ['201909']
60
+ },
61
+ 'mme6.zip'
62
+ )
63
+
64
+ apccapi.download_MME_MODEL(
65
+ {
66
+ 'type': 'FORECAST',
67
+ 'institute': 'APCC',
68
+ 'model': 'SCOPS',
69
+ 'variable': ['prec', 't2m'],
70
+ 'yearmonth': ['201909']
71
+ },
72
+ 'model.zip'
73
+ )
74
+
75
+ apccapi.download_CMIP5(
76
+ {
77
+ 'code': 'AD'
78
+ },
79
+ 'cmip5.zip'
80
+ )
81
+
82
+ apccapi.download_ERA5(
83
+ {
84
+ 'timestep': 'DAILY', # 'DAILY' | 'MONTHLY' | 'HOURLY'
85
+ 'level': 'single', # 'pressure' | 'single'
86
+ 'variable': 't2m',
87
+ 'year': '2020',
88
+ 'month': '12' # omit for 'MONTHLY'
89
+ },
90
+ 't2m_202012.nc'
91
+ )
92
+
93
+ apccapi.download_NCEP1(
94
+ {
95
+ 'timestep': 'DAILY', # 'DAILY' | 'MONTHLY'
96
+ 'level': 'pressure',
97
+ 'variable': 'air',
98
+ 'year': '2022' # only required for 'DAILY'
99
+ },
100
+ 'air.2022.nc'
101
+ )
102
+
103
+ apccapi.download_NCEP2(
104
+ {
105
+ 'timestep': 'DAILY',
106
+ 'level': 'pressure',
107
+ 'variable': 'air',
108
+ 'year': '2022'
109
+ },
110
+ 'air.2022.nc'
111
+ )
112
+ ```
113
+
114
+ More runnable examples (one file per dataset) are in [`example/`](example/).
115
+
116
+ ### Low-level usage: `Client.retrieve`
117
+
118
+ The helpers above are thin wrappers around `Client.retrieve()`. Call it
119
+ directly when you need a `jobtype`/`dataset` combination that doesn't have
120
+ a dedicated helper yet, or the clipping jobtypes (`Clipping_MME`,
121
+ `Clipping_Model`):
122
+
123
+ ```python
124
+ import apccapi
125
+
126
+ c = apccapi.Client()
127
+ c.retrieve(
128
+ {
129
+ 'jobtype': 'MME',
130
+ 'dataset': 'MME_3MONTH',
131
+ 'type': 'FORECAST',
132
+ 'method': 'SCM',
133
+ 'variable': ['prec', 't2m'],
134
+ 'period': ['Monthly mean'],
135
+ 'yearmonth': ['201909']
136
+ },
137
+ 'mme3.zip'
138
+ )
139
+ ```
140
+
141
+ ### Clipping
142
+
143
+ `ClippingClient` calls a separate clipping/masking service and returns a
144
+ cropped PNG or NetCDF file for a bounding box:
145
+
146
+ ```python
147
+ import apccapi
148
+
149
+ c = apccapi.ClippingClient()
150
+ c.clip(
151
+ {
152
+ 'lead_month': '3-MON', # '3-MON' | '6-MON'
153
+ 'variable': 'prec', # prec, slp, sst, t2m, t850, z500
154
+ 'method': 'SCM', # SCM, GAUS
155
+ 'period': 'Monthly mean', # Monthly mean, Seasonal mean
156
+ 'iyear': '2021', # issued year
157
+ 'imonth': '2', # issued month
158
+ 'cowest': '188',
159
+ 'coeast': '191',
160
+ 'conorth': '-11',
161
+ 'cosouth': '-15',
162
+ 'return_type': 'png' # 'png' | 'nc'
163
+ }
164
+ )
165
+ ```
166
+
167
+ ### Error handling
168
+
169
+ Every failure (rejected request, job that ends in `Failed`, exhausted
170
+ retries, a broken download) raises `apccapi.ClikApiError` with the
171
+ server's own message, instead of failing silently:
172
+
173
+ ```python
174
+ import apccapi
175
+
176
+ try:
177
+ apccapi.download_ERA5(
178
+ {'timestep': 'MONTHLY', 'level': 'single', 'variable': 't2m', 'year': '2020'},
179
+ 't2m_2020.nc'
180
+ )
181
+ except apccapi.ClikApiError as e:
182
+ print('Request failed:', e)
183
+ ```
184
+
185
+ ## License
186
+
187
+ MIT License
188
+
189
+ Copyright (c) 2019 - 2024, APEC Climate Center
190
+
191
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
192
+ copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
193
+
194
+ The above copyright notice and this permission notice shall be included in all
195
+ copies or substantial portions of the Software.
196
+
197
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -12,5 +12,5 @@ from .client import (
12
12
  from .clipping import ClippingClient
13
13
  from . import clipping
14
14
 
15
- __version__ = '0.1.0'
15
+ __version__ = '0.1.1'
16
16
  __author__ = 'APEC Climate Center'
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: apccapi
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: APCC Climate Information toolKit API package
5
5
  Home-page: https://www.apcc21.org
6
6
  Author: APEC Climate Center
@@ -58,14 +58,103 @@ request_url=https://apcc21.org/clikapi/request/apccdata
58
58
  status_url=https://apcc21.org/clikapi/request/status
59
59
  ```
60
60
 
61
- ## Test
61
+ ## Usage
62
62
 
63
- Perform a small test retrieve of MME data:
63
+ ### Quick start: dataset download helpers
64
+
65
+ Each helper submits the request, polls until it's done, downloads the
66
+ result, and returns the output file path (or raises on failure - see
67
+ [Error handling](#error-handling)).
68
+
69
+ ```python
70
+ import apccapi
71
+
72
+ apccapi.download_MME_3MONTH(
73
+ {
74
+ 'type': 'FORECAST',
75
+ 'method': 'SCM',
76
+ 'variable': ['prec', 't2m'],
77
+ 'period': ['Monthly mean'],
78
+ 'yearmonth': ['201909']
79
+ },
80
+ 'mme3.zip'
81
+ )
82
+
83
+ apccapi.download_MME_6MONTH(
84
+ {
85
+ 'type': 'FORECAST',
86
+ 'method': 'SCM',
87
+ 'variable': ['prec', 't2m'],
88
+ 'period': ['Monthly mean'],
89
+ 'yearmonth': ['201909']
90
+ },
91
+ 'mme6.zip'
92
+ )
93
+
94
+ apccapi.download_MME_MODEL(
95
+ {
96
+ 'type': 'FORECAST',
97
+ 'institute': 'APCC',
98
+ 'model': 'SCOPS',
99
+ 'variable': ['prec', 't2m'],
100
+ 'yearmonth': ['201909']
101
+ },
102
+ 'model.zip'
103
+ )
104
+
105
+ apccapi.download_CMIP5(
106
+ {
107
+ 'code': 'AD'
108
+ },
109
+ 'cmip5.zip'
110
+ )
111
+
112
+ apccapi.download_ERA5(
113
+ {
114
+ 'timestep': 'DAILY', # 'DAILY' | 'MONTHLY' | 'HOURLY'
115
+ 'level': 'single', # 'pressure' | 'single'
116
+ 'variable': 't2m',
117
+ 'year': '2020',
118
+ 'month': '12' # omit for 'MONTHLY'
119
+ },
120
+ 't2m_202012.nc'
121
+ )
122
+
123
+ apccapi.download_NCEP1(
124
+ {
125
+ 'timestep': 'DAILY', # 'DAILY' | 'MONTHLY'
126
+ 'level': 'pressure',
127
+ 'variable': 'air',
128
+ 'year': '2022' # only required for 'DAILY'
129
+ },
130
+ 'air.2022.nc'
131
+ )
132
+
133
+ apccapi.download_NCEP2(
134
+ {
135
+ 'timestep': 'DAILY',
136
+ 'level': 'pressure',
137
+ 'variable': 'air',
138
+ 'year': '2022'
139
+ },
140
+ 'air.2022.nc'
141
+ )
64
142
  ```
65
- $ python
66
- >>> import apccapi
67
- >>> c = apccapi.Client()
68
- >>> c.retrieve(
143
+
144
+ More runnable examples (one file per dataset) are in [`example/`](example/).
145
+
146
+ ### Low-level usage: `Client.retrieve`
147
+
148
+ The helpers above are thin wrappers around `Client.retrieve()`. Call it
149
+ directly when you need a `jobtype`/`dataset` combination that doesn't have
150
+ a dedicated helper yet, or the clipping jobtypes (`Clipping_MME`,
151
+ `Clipping_Model`):
152
+
153
+ ```python
154
+ import apccapi
155
+
156
+ c = apccapi.Client()
157
+ c.retrieve(
69
158
  {
70
159
  'jobtype': 'MME',
71
160
  'dataset': 'MME_3MONTH',
@@ -77,8 +166,50 @@ $ python
77
166
  },
78
167
  'mme3.zip'
79
168
  )
80
- >>>
169
+ ```
170
+
171
+ ### Clipping
172
+
173
+ `ClippingClient` calls a separate clipping/masking service and returns a
174
+ cropped PNG or NetCDF file for a bounding box:
175
+
176
+ ```python
177
+ import apccapi
178
+
179
+ c = apccapi.ClippingClient()
180
+ c.clip(
181
+ {
182
+ 'lead_month': '3-MON', # '3-MON' | '6-MON'
183
+ 'variable': 'prec', # prec, slp, sst, t2m, t850, z500
184
+ 'method': 'SCM', # SCM, GAUS
185
+ 'period': 'Monthly mean', # Monthly mean, Seasonal mean
186
+ 'iyear': '2021', # issued year
187
+ 'imonth': '2', # issued month
188
+ 'cowest': '188',
189
+ 'coeast': '191',
190
+ 'conorth': '-11',
191
+ 'cosouth': '-15',
192
+ 'return_type': 'png' # 'png' | 'nc'
193
+ }
194
+ )
195
+ ```
196
+
197
+ ### Error handling
198
+
199
+ Every failure (rejected request, job that ends in `Failed`, exhausted
200
+ retries, a broken download) raises `apccapi.ClikApiError` with the
201
+ server's own message, instead of failing silently:
202
+
203
+ ```python
204
+ import apccapi
81
205
 
206
+ try:
207
+ apccapi.download_ERA5(
208
+ {'timestep': 'MONTHLY', 'level': 'single', 'variable': 't2m', 'year': '2020'},
209
+ 't2m_2020.nc'
210
+ )
211
+ except apccapi.ClikApiError as e:
212
+ print('Request failed:', e)
82
213
  ```
83
214
 
84
215
  ## License
@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
5
5
 
6
6
  setuptools.setup(
7
7
  name="apccapi",
8
- version="0.1.0",
8
+ version="0.1.1",
9
9
  author="APEC Climate Center",
10
10
  author_email="joohyung@apcc21.org",
11
11
  description="APCC Climate Information toolKit API package",
apccapi-0.1.0/README.md DELETED
@@ -1,66 +0,0 @@
1
- ## Installation
2
-
3
- Install via pip with:
4
-
5
- ```bash
6
- $ pip install apccapi
7
- ```
8
-
9
- ## Configure (Linux)
10
-
11
- Obtain your API key from the CLIK (Climate Information toolKit) at https://apcc21.org/clik/ and enter it into the apccapi.properties file, formatting it as follows:
12
-
13
- ```
14
- $ vi ~/apccapi.properties
15
-
16
- key={your API key}
17
- request_url=https://apcc21.org/clikapi/request/apccdata
18
- status_url=https://apcc21.org/clikapi/request/status
19
- ```
20
-
21
- ## Configure (Windows)
22
-
23
- Obtain your API key from the CLIK (Climate Information toolKit) at https://apcc21.org/clik/, and create the apccapi.properties file in your Windows Home directory (typically C:\Users\YourUserName) with the following format:
24
-
25
- ```
26
- key={your API key}
27
- request_url=https://apcc21.org/clikapi/request/apccdata
28
- status_url=https://apcc21.org/clikapi/request/status
29
- ```
30
-
31
- ## Test
32
-
33
- Perform a small test retrieve of MME data:
34
- ```
35
- $ python
36
- >>> import apccapi
37
- >>> c = apccapi.Client()
38
- >>> c.retrieve(
39
- {
40
- 'jobtype': 'MME',
41
- 'dataset': 'MME_3MONTH',
42
- 'type': 'FORECAST',
43
- 'method': 'SCM',
44
- 'variable': ['prec', 't2m'],
45
- 'period': ['Monthly mean'],
46
- 'yearmonth': ['201909']
47
- },
48
- 'mme3.zip'
49
- )
50
- >>>
51
-
52
- ```
53
-
54
- ## License
55
-
56
- MIT License
57
-
58
- Copyright (c) 2019 - 2024, APEC Climate Center
59
-
60
- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
61
- copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
62
-
63
- The above copyright notice and this permission notice shall be included in all
64
- copies or substantial portions of the Software.
65
-
66
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
File without changes
File without changes
File without changes
File without changes