neris-api-client 1.5.7__tar.gz → 1.6.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.
- {neris_api_client-1.5.7/src/neris_api_client.egg-info → neris_api_client-1.6.0}/PKG-INFO +63 -8
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/README.md +61 -6
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/pyproject.toml +2 -2
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client/client.py +5 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client/config.py +13 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client/models.py +2665 -3299
- {neris_api_client-1.5.7 → neris_api_client-1.6.0/src/neris_api_client.egg-info}/PKG-INFO +63 -8
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/LICENSE +0 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/setup.cfg +0 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client/__init__.py +0 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client.egg-info/SOURCES.txt +0 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client.egg-info/dependency_links.txt +0 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client.egg-info/requires.txt +0 -0
- {neris_api_client-1.5.7 → neris_api_client-1.6.0}/src/neris_api_client.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: neris_api_client
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.6.0
|
|
4
4
|
Summary: NERIS API Client
|
|
5
5
|
Author-email: Ben Coleman <ben.coleman@ul.org>, Joseph Pagani <joseph.pagani@ul.org>, Daniel Liu <daniel.liu@ul.org>, Matthew Sudol <matthew.sudol@ul.org>
|
|
6
6
|
Project-URL: Homepage, https://github.com/ulfsri/neris-api-client
|
|
@@ -8,7 +8,7 @@ Project-URL: Issues, https://neris.atlassian.net/servicedesk/customer/portal/3/g
|
|
|
8
8
|
Classifier: Programming Language :: Python :: 3
|
|
9
9
|
Classifier: License :: OSI Approved :: MIT License
|
|
10
10
|
Classifier: Operating System :: OS Independent
|
|
11
|
-
Requires-Python: >=3.
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
12
|
Description-Content-Type: text/markdown
|
|
13
13
|
License-File: LICENSE
|
|
14
14
|
Requires-Dist: requests
|
|
@@ -28,17 +28,36 @@ This API client does not directly follow semver practices. In order to remove co
|
|
|
28
28
|
|
|
29
29
|
## Installation
|
|
30
30
|
|
|
31
|
+
Requires Python 3.10 or later.
|
|
32
|
+
|
|
31
33
|
To install:
|
|
34
|
+
|
|
32
35
|
```bash
|
|
33
36
|
pip install neris-api-client
|
|
34
37
|
```
|
|
38
|
+
|
|
35
39
|
Package published on PyPi: [`NERIS API Client`](https://pypi.org/project/neris-api-client/)
|
|
36
40
|
|
|
41
|
+
## Model generation
|
|
42
|
+
|
|
43
|
+
Install the locked development dependencies with `pipenv sync --dev`. The
|
|
44
|
+
[generation script](./gen) downloads the live OpenAPI specification and overwrites
|
|
45
|
+
[models.py](./src/neris_api_client/models.py), then formats it with Black.
|
|
46
|
+
From a Bash shell, run `pipenv run bash gen`.
|
|
47
|
+
|
|
48
|
+
Schema downloads explicitly use the generator's HTTPX2 backend, which
|
|
49
|
+
datamodel-code-generator 0.76.2 labels experimental. HTTPX2 is pinned to 2.14.0
|
|
50
|
+
to retain Python 3.10 support; HTTPX2 2.15 and later require Python 3.11.
|
|
51
|
+
For manual `pipenv run datamodel-codegen` commands, include `--http-backend httpx2`
|
|
52
|
+
so an installed copy of HTTPX does not take precedence.
|
|
53
|
+
This development dependency does not change the client's Requests-based HTTP transport.
|
|
54
|
+
|
|
37
55
|
## Usage
|
|
38
56
|
|
|
39
57
|
**Auth with password `auth` flow**
|
|
40
58
|
|
|
41
59
|
All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=password`.
|
|
60
|
+
|
|
42
61
|
```python
|
|
43
62
|
from neris_api_client import NerisApiClient, Config
|
|
44
63
|
|
|
@@ -63,6 +82,7 @@ Provide MFA code for email_otp: ******
|
|
|
63
82
|
**Auth with `client_credentials` auth flow**
|
|
64
83
|
|
|
65
84
|
All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=client_credentials`.
|
|
85
|
+
|
|
66
86
|
```python
|
|
67
87
|
from neris_api_client import NerisApiClient, Config
|
|
68
88
|
|
|
@@ -87,8 +107,8 @@ entity = client.get_entity("FD24027240")
|
|
|
87
107
|
|
|
88
108
|
All variables prefixed are prefixed with `NERIS_`
|
|
89
109
|
|
|
90
|
-
|
|
91
|
-
|
|
110
|
+
- See [env.example](./examples/.env.example) for the parameter options.
|
|
111
|
+
- Store the `/env` file in the current working directory.
|
|
92
112
|
|
|
93
113
|
```python
|
|
94
114
|
from dotenv import load_dotenv
|
|
@@ -104,20 +124,55 @@ entity = client.get_entity("FD24027240")
|
|
|
104
124
|
|
|
105
125
|
## Additional config parameters
|
|
106
126
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
127
|
+
### `debug`
|
|
128
|
+
|
|
129
|
+
Controls whether the application outputs debug information.
|
|
130
|
+
|
|
131
|
+
### `validate`
|
|
132
|
+
|
|
133
|
+
Controls whether the client performs model validations.
|
|
134
|
+
|
|
135
|
+
### `ssl_verify`
|
|
136
|
+
|
|
137
|
+
Controls TLS certificate verification. `True`/unset verifies with the default certifi bundle, `False` disables
|
|
138
|
+
verification (not recommended), or pass a path to a custom CA bundle.
|
|
111
139
|
|
|
140
|
+
> **⚠️ Warning:** Setting `ssl_verify=False` disables all TLS certificate verification, including protection against
|
|
141
|
+
> man-in-the-middle attacks. Credentials, tokens, and incident data would be sent over a connection that cannot
|
|
142
|
+
> confirm it's actually talking to the NERIS API. Only use this as a last resort for local debugging, never in
|
|
143
|
+
> production, and prefer supplying a custom CA bundle path instead.
|
|
144
|
+
|
|
145
|
+
### Troubleshooting `SSLCertVerificationError` / `unable to get local issuer certificate`
|
|
146
|
+
|
|
147
|
+
If you see `SSLCertVerificationError: unable to get local issuer certificate`, your network traffic is likely passing
|
|
148
|
+
through a TLS-inspecting proxy or firewall (common in corporate networks and hosted notebook environments such as
|
|
149
|
+
ArcGIS Online Notebooks) that re-signs traffic with its own root certificate, which isn't trusted by Python's
|
|
150
|
+
default certificate bundle. To resolve this, obtain the proxy/organization's root CA certificate (as a `.pem` file)
|
|
151
|
+
from your network/IT administrator and point the client at it:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
client = NerisApiClient(
|
|
155
|
+
Config(
|
|
156
|
+
...,
|
|
157
|
+
ssl_verify="/path/to/corporate-ca-bundle.pem",
|
|
158
|
+
)
|
|
159
|
+
)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Or set the `NERIS_SSL_VERIFY` environment variable to the path of the CA bundle. If you don't have access to the CA
|
|
163
|
+
bundle, confirm with your network administrator that outbound HTTPS access to `api.neris.fsri.org` is allowed.
|
|
112
164
|
|
|
113
165
|
## Disclaimer
|
|
166
|
+
|
|
114
167
|
The models in this package are generated using [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator) and are not guaranteed
|
|
115
168
|
to contain all of the information present in the full specification. The generated models are used to validate request payloads prior to
|
|
116
169
|
API submission.
|
|
117
170
|
|
|
118
171
|
## Additional Information
|
|
172
|
+
|
|
119
173
|
To ask a question, make a suggestion, or otherwise get help with the NERIS API Client, please visit [the NERIS helpdesk](https://neris.atlassian.net/servicedesk/customer/portals).
|
|
120
174
|
|
|
121
175
|
**Beta sandbox users**:
|
|
176
|
+
|
|
122
177
|
- Be sure to use the base URL `https://api-test.neris.fsri.org/v1` with the NERIS API Client. You will not be able to authenticate requests in the other environments.
|
|
123
178
|
- For the beta testing period, your user is only authorized to perform actions on behalf of the FSRI Fire Department `FD24027214`.
|
|
@@ -10,17 +10,36 @@ This API client does not directly follow semver practices. In order to remove co
|
|
|
10
10
|
|
|
11
11
|
## Installation
|
|
12
12
|
|
|
13
|
+
Requires Python 3.10 or later.
|
|
14
|
+
|
|
13
15
|
To install:
|
|
16
|
+
|
|
14
17
|
```bash
|
|
15
18
|
pip install neris-api-client
|
|
16
19
|
```
|
|
20
|
+
|
|
17
21
|
Package published on PyPi: [`NERIS API Client`](https://pypi.org/project/neris-api-client/)
|
|
18
22
|
|
|
23
|
+
## Model generation
|
|
24
|
+
|
|
25
|
+
Install the locked development dependencies with `pipenv sync --dev`. The
|
|
26
|
+
[generation script](./gen) downloads the live OpenAPI specification and overwrites
|
|
27
|
+
[models.py](./src/neris_api_client/models.py), then formats it with Black.
|
|
28
|
+
From a Bash shell, run `pipenv run bash gen`.
|
|
29
|
+
|
|
30
|
+
Schema downloads explicitly use the generator's HTTPX2 backend, which
|
|
31
|
+
datamodel-code-generator 0.76.2 labels experimental. HTTPX2 is pinned to 2.14.0
|
|
32
|
+
to retain Python 3.10 support; HTTPX2 2.15 and later require Python 3.11.
|
|
33
|
+
For manual `pipenv run datamodel-codegen` commands, include `--http-backend httpx2`
|
|
34
|
+
so an installed copy of HTTPX does not take precedence.
|
|
35
|
+
This development dependency does not change the client's Requests-based HTTP transport.
|
|
36
|
+
|
|
19
37
|
## Usage
|
|
20
38
|
|
|
21
39
|
**Auth with password `auth` flow**
|
|
22
40
|
|
|
23
41
|
All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=password`.
|
|
42
|
+
|
|
24
43
|
```python
|
|
25
44
|
from neris_api_client import NerisApiClient, Config
|
|
26
45
|
|
|
@@ -45,6 +64,7 @@ Provide MFA code for email_otp: ******
|
|
|
45
64
|
**Auth with `client_credentials` auth flow**
|
|
46
65
|
|
|
47
66
|
All config parameters can be specified as environment variables prefixed with `NERIS_` e.g. `NERIS_GRANT_TYPE=client_credentials`.
|
|
67
|
+
|
|
48
68
|
```python
|
|
49
69
|
from neris_api_client import NerisApiClient, Config
|
|
50
70
|
|
|
@@ -69,8 +89,8 @@ entity = client.get_entity("FD24027240")
|
|
|
69
89
|
|
|
70
90
|
All variables prefixed are prefixed with `NERIS_`
|
|
71
91
|
|
|
72
|
-
|
|
73
|
-
|
|
92
|
+
- See [env.example](./examples/.env.example) for the parameter options.
|
|
93
|
+
- Store the `/env` file in the current working directory.
|
|
74
94
|
|
|
75
95
|
```python
|
|
76
96
|
from dotenv import load_dotenv
|
|
@@ -86,20 +106,55 @@ entity = client.get_entity("FD24027240")
|
|
|
86
106
|
|
|
87
107
|
## Additional config parameters
|
|
88
108
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
109
|
+
### `debug`
|
|
110
|
+
|
|
111
|
+
Controls whether the application outputs debug information.
|
|
112
|
+
|
|
113
|
+
### `validate`
|
|
114
|
+
|
|
115
|
+
Controls whether the client performs model validations.
|
|
116
|
+
|
|
117
|
+
### `ssl_verify`
|
|
118
|
+
|
|
119
|
+
Controls TLS certificate verification. `True`/unset verifies with the default certifi bundle, `False` disables
|
|
120
|
+
verification (not recommended), or pass a path to a custom CA bundle.
|
|
93
121
|
|
|
122
|
+
> **⚠️ Warning:** Setting `ssl_verify=False` disables all TLS certificate verification, including protection against
|
|
123
|
+
> man-in-the-middle attacks. Credentials, tokens, and incident data would be sent over a connection that cannot
|
|
124
|
+
> confirm it's actually talking to the NERIS API. Only use this as a last resort for local debugging, never in
|
|
125
|
+
> production, and prefer supplying a custom CA bundle path instead.
|
|
126
|
+
|
|
127
|
+
### Troubleshooting `SSLCertVerificationError` / `unable to get local issuer certificate`
|
|
128
|
+
|
|
129
|
+
If you see `SSLCertVerificationError: unable to get local issuer certificate`, your network traffic is likely passing
|
|
130
|
+
through a TLS-inspecting proxy or firewall (common in corporate networks and hosted notebook environments such as
|
|
131
|
+
ArcGIS Online Notebooks) that re-signs traffic with its own root certificate, which isn't trusted by Python's
|
|
132
|
+
default certificate bundle. To resolve this, obtain the proxy/organization's root CA certificate (as a `.pem` file)
|
|
133
|
+
from your network/IT administrator and point the client at it:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
client = NerisApiClient(
|
|
137
|
+
Config(
|
|
138
|
+
...,
|
|
139
|
+
ssl_verify="/path/to/corporate-ca-bundle.pem",
|
|
140
|
+
)
|
|
141
|
+
)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Or set the `NERIS_SSL_VERIFY` environment variable to the path of the CA bundle. If you don't have access to the CA
|
|
145
|
+
bundle, confirm with your network administrator that outbound HTTPS access to `api.neris.fsri.org` is allowed.
|
|
94
146
|
|
|
95
147
|
## Disclaimer
|
|
148
|
+
|
|
96
149
|
The models in this package are generated using [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator) and are not guaranteed
|
|
97
150
|
to contain all of the information present in the full specification. The generated models are used to validate request payloads prior to
|
|
98
151
|
API submission.
|
|
99
152
|
|
|
100
153
|
## Additional Information
|
|
154
|
+
|
|
101
155
|
To ask a question, make a suggestion, or otherwise get help with the NERIS API Client, please visit [the NERIS helpdesk](https://neris.atlassian.net/servicedesk/customer/portals).
|
|
102
156
|
|
|
103
157
|
**Beta sandbox users**:
|
|
158
|
+
|
|
104
159
|
- Be sure to use the base URL `https://api-test.neris.fsri.org/v1` with the NERIS API Client. You will not be able to authenticate requests in the other environments.
|
|
105
160
|
- For the beta testing period, your user is only authorized to perform actions on behalf of the FSRI Fire Department `FD24027214`.
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "neris_api_client"
|
|
7
|
-
version = "1.
|
|
7
|
+
version = "1.6.0"
|
|
8
8
|
authors = [
|
|
9
9
|
{ name="Ben Coleman", email="ben.coleman@ul.org" },
|
|
10
10
|
{ name="Joseph Pagani", email="joseph.pagani@ul.org"},
|
|
@@ -13,7 +13,7 @@ authors = [
|
|
|
13
13
|
]
|
|
14
14
|
description = "NERIS API Client"
|
|
15
15
|
readme = "README.md"
|
|
16
|
-
requires-python = ">=3.
|
|
16
|
+
requires-python = ">=3.10"
|
|
17
17
|
classifiers = [
|
|
18
18
|
"Programming Language :: Python :: 3",
|
|
19
19
|
"License :: OSI Approved :: MIT License",
|
|
@@ -49,8 +49,13 @@ class _NerisApiClient:
|
|
|
49
49
|
if config is None:
|
|
50
50
|
config = Config() # by default it loads from env
|
|
51
51
|
|
|
52
|
+
self._session = requests.Session()
|
|
52
53
|
self._session.headers.update({"User-Agent": config.user_agent})
|
|
53
54
|
|
|
55
|
+
# Allow overriding TLS verification for networks with TLS-inspecting proxies (e.g. custom CA bundle path, or False to disable).
|
|
56
|
+
if config.ssl_verify is not None:
|
|
57
|
+
self._session.verify = config.ssl_verify
|
|
58
|
+
|
|
54
59
|
match config.grant_type:
|
|
55
60
|
case GrantType.CLIENT_CREDENTIALS:
|
|
56
61
|
assert config.client_id is not None
|
|
@@ -25,6 +25,9 @@ class Config:
|
|
|
25
25
|
grant_type: GrantType | None = None
|
|
26
26
|
validate: bool | None = None
|
|
27
27
|
user_agent: str | None = None
|
|
28
|
+
# True/unset = verify with certifi's bundle, False = disable verification (insecure),
|
|
29
|
+
# or a path to a CA bundle/cert file for environments behind TLS-inspecting proxies.
|
|
30
|
+
ssl_verify: bool | str | None = None
|
|
28
31
|
|
|
29
32
|
def __post_init__(self):
|
|
30
33
|
# env var handling
|
|
@@ -33,6 +36,16 @@ class Config:
|
|
|
33
36
|
self.validate = self.validate if self.validate is not None else os.getenv("NERIS_VALIDATE") == "true"
|
|
34
37
|
self.user_agent = self.user_agent or os.getenv("NERIS_USER_AGENT", get_default_user_agent())
|
|
35
38
|
|
|
39
|
+
if self.ssl_verify is None:
|
|
40
|
+
env_ssl_verify = os.getenv("NERIS_SSL_VERIFY")
|
|
41
|
+
if env_ssl_verify:
|
|
42
|
+
if env_ssl_verify.lower() in ("true", "1", "yes"):
|
|
43
|
+
self.ssl_verify = True
|
|
44
|
+
elif env_ssl_verify.lower() in ("false", "0", "no"):
|
|
45
|
+
self.ssl_verify = False
|
|
46
|
+
else:
|
|
47
|
+
self.ssl_verify = env_ssl_verify # path to CA bundle/cert file
|
|
48
|
+
|
|
36
49
|
match os.getenv("NERIS_GRANT_TYPE"):
|
|
37
50
|
case GrantType.PASSWORD:
|
|
38
51
|
self.grant_type = self.grant_type or GrantType.PASSWORD
|