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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: neris_api_client
3
- Version: 1.5.7
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.8
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
- * See [env.example](./examples/.env.example) for the parameter options.
91
- * Store the `/env` file in the current working directory.
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
- | Parameter | Description |
108
- | --------- | ----------------------------------------------------------- |
109
- | debug | Controls whether the application outputs debug information. |
110
- | validate | Controls whether the client performs model validations. |
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
- * See [env.example](./examples/.env.example) for the parameter options.
73
- * Store the `/env` file in the current working directory.
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
- | Parameter | Description |
90
- | --------- | ----------------------------------------------------------- |
91
- | debug | Controls whether the application outputs debug information. |
92
- | validate | Controls whether the client performs model validations. |
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.5.7"
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.8"
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