argus-api-client 0.7.0__tar.gz → 0.9.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 (28) hide show
  1. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/PKG-INFO +206 -21
  2. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/README.md +199 -17
  3. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/pyproject.toml +19 -4
  4. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/PKG-INFO +206 -21
  5. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/SOURCES.txt +5 -1
  6. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/__init__.py +2 -1
  7. argus_api_client-0.9.0/src/pyargus/api.py +117 -0
  8. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/async_api.py +28 -5
  9. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/async_client.py +136 -15
  10. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/client.py +133 -15
  11. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/models.py +42 -12
  12. argus_api_client-0.9.0/src/pyargus/multivaluedict.py +251 -0
  13. argus_api_client-0.9.0/src/pyargus/time.py +10 -0
  14. argus_api_client-0.9.0/tests/test_api.py +28 -0
  15. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/tests/test_async_api.py +6 -0
  16. argus_api_client-0.9.0/tests/test_async_client.py +235 -0
  17. argus_api_client-0.9.0/tests/test_client.py +208 -0
  18. argus_api_client-0.9.0/tests/test_models.py +119 -0
  19. argus_api_client-0.9.0/tests/test_multivaluedict.py +413 -0
  20. argus_api_client-0.7.0/src/pyargus/api.py +0 -61
  21. argus_api_client-0.7.0/tests/test_api.py +0 -14
  22. argus_api_client-0.7.0/tests/test_async_client.py +0 -35
  23. argus_api_client-0.7.0/tests/test_client.py +0 -31
  24. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/LICENSE +0 -0
  25. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/setup.cfg +0 -0
  26. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/dependency_links.txt +0 -0
  27. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/requires.txt +0 -0
  28. {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/top_level.txt +0 -0
@@ -1,16 +1,19 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: argus-api-client
3
- Version: 0.7.0
3
+ Version: 0.9.0
4
4
  Summary: A Python API client library for the Argus alert aggregator server
5
5
  Author-email: Sikt - Kunnskapssektorens Tjenesteleverandør <kontakt@sikt.no>
6
6
  License-Expression: Apache-2.0
7
+ Project-URL: GitHub, https://github.com/Uninett/pyargus
8
+ Project-URL: Changelog, https://github.com/Uninett/pyargus/blob/master/CHANGELOG.md
9
+ Project-URL: Argus, https://network.geant.org/argus/
7
10
  Classifier: Programming Language :: Python :: 3
8
- Classifier: Programming Language :: Python :: 3.9
9
- Classifier: Programming Language :: Python :: 3.10
10
11
  Classifier: Programming Language :: Python :: 3.11
11
12
  Classifier: Programming Language :: Python :: 3.12
12
13
  Classifier: Programming Language :: Python :: 3.13
13
- Requires-Python: >=3.9
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Programming Language :: Python :: 3.15
16
+ Requires-Python: >=3.11
14
17
  Description-Content-Type: text/markdown
15
18
  License-File: LICENSE
16
19
  Requires-Dist: simple_rest_client
@@ -41,6 +44,8 @@ The `Client` class is found in `pyargus.client`, and the various supported data
41
44
  models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
42
45
  implemented in `pyargus.models`.
43
46
 
47
+ **Note:** Always pass timezone-aware `datetime` objects (e.g. `datetime.now(tz=timezone.utc)`) to the client. pyargus serializes datetimes verbatim, so a naive value reaches Argus without a UTC offset and gets recorded at the wrong time.
48
+
44
49
  ### Listing open incidents that have not been acknowledged
45
50
 
46
51
  ```pycon
@@ -49,9 +54,9 @@ implemented in `pyargus.models`.
49
54
  >>> for incident in c.get_incidents(open=True, acked=False):
50
55
  ... print(incident)
51
56
  ...
52
- Incident(pk=4, start_time=datetime.datetime(2021, 4, 4, 16, 37, 43, 293726, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202430', details_url='http://localhost/search/event/202430', description='uninett-gsw2 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'room': '100', 'organization': 'uninett.srv', 'host': 'uninett-gsw2.uninett.no'}, stateful=True, open=True, acked=False)
53
- Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202429', details_url='http://localhost/search/event/202429', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'host': 'uninett-gsw1.uninett.no', 'room': '100', 'organization': 'uninett.srv'}, stateful=True, open=True, acked=False)
54
- Incident(pk=2, start_time=datetime.datetime(2017, 8, 31, 14, 58, 31, 118794, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='184296', details_url='http://localhost/search/event/184296', description='Link DOWN on Gi0/3 at oldsmobile.lab (Simple is better than complex)', level=5, ticket_url='', tags={'room': '113', 'location': 'Teknobyen Innovasjonssenter', 'organization': 'uninett.testlab', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'linkState', 'alert_type': 'linkDown', 'host': 'oldsmobile.lab.uninett.no', 'interface': 'Gi0/3'}, stateful=True, open=True, acked=False)
57
+ Incident(pk=4, start_time=datetime.datetime(2021, 4, 4, 16, 37, 43, 293726, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202430', details_url='http://localhost/search/event/202430', description='uninett-gsw2 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('room', '100'), ('organization', 'uninett.srv'), ('host', 'uninett-gsw2.uninett.no')]), stateful=True, open=True, acked=False)
58
+ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202429', details_url='http://localhost/search/event/202429', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('host', 'uninett-gsw1.uninett.no'), ('room', '100'), ('organization', 'uninett.srv')]), stateful=True, open=True, acked=False)
59
+ Incident(pk=2, start_time=datetime.datetime(2017, 8, 31, 14, 58, 31, 118794, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='184296', details_url='http://localhost/search/event/184296', description='Link DOWN on Gi0/3 at oldsmobile.lab (Simple is better than complex)', level=5, ticket_url='', tags=MultiValueDict([('room', '113'), ('location', 'Teknobyen Innovasjonssenter'), ('organization', 'uninett.testlab'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'linkState'), ('alert_type', 'linkDown'), ('host', 'oldsmobile.lab.uninett.no'), ('interface', 'Gi0/3')]), stateful=True, open=True, acked=False)
55
60
  ```
56
61
 
57
62
  As you can see, the arguments given to `get_incidents()` are translated
@@ -73,7 +78,7 @@ Example:
73
78
  >>> for incident in c.get_my_incidents(open=True, acked=False):
74
79
  ... print(incident)
75
80
  ...
76
- Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=3, name='foobar, type='nav', user=4, base_url='http://localhost/'), source_incident_id='2716057', details_url='http://localhost/search/event/2716057', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'host': 'uninett-gsw1.uninett.no', 'room': '100', 'organization': 'uninett.srv'}, stateful=True, open=True, acked=False)
81
+ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=3, name='foobar, type='nav', user=4, base_url='http://localhost/'), source_incident_id='2716057', details_url='http://localhost/search/event/2716057', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('host', 'uninett-gsw1.uninett.no'), ('room', '100'), ('organization', 'uninett.srv')]), stateful=True, open=True, acked=False)
77
82
  ```
78
83
 
79
84
  ### Post a new incident
@@ -81,17 +86,17 @@ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzin
81
86
  ```pycon
82
87
  >>> from pyargus.client import Client
83
88
  >>> from pyargus.models import Incident
84
- >>> from datetime import datetime
89
+ >>> from pyargus.time import now as utcnow
85
90
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
86
91
  >>> i = Incident(
87
92
  ... description="The earth was demolished to make way for a hyperspace bypass",
88
- ... start_time=datetime.now(),
93
+ ... start_time=utcnow(),
89
94
  ... tags={
90
95
  ... "host": "earth.example.org",
91
96
  ... }
92
97
  ... )
93
98
  >>> c.post_incident(i)
94
- Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=5, ticket_url='', tags={'host': 'earth.example.org'}, stateful=False, open=False, acked=False)
99
+ Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=5, ticket_url='', tags=MultiValueDict([('host', 'earth.example.org')]), stateful=False, open=False, acked=False)
95
100
  ```
96
101
 
97
102
  The `post_incident()` method returns the full `Incident` record, as stored in
@@ -106,12 +111,26 @@ convenience method for this operation:
106
111
 
107
112
  ```pycon
108
113
  >>> from pyargus.client import Client
109
- >>> from datetime import datetime
114
+ >>> from pyargus.time import now as utcnow
110
115
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
111
- >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=datetime.now())
116
+ >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=utcnow())
112
117
  Event(pk=10, actor='testnav', description='The demolition was cancelled', incident=8, received=datetime.datetime(2021, 4, 22, 11, 47, 11, 978438, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), timestamp=datetime.datetime(2021, 4, 22, 11, 47, 11, 946076, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), type='END')
113
118
  ```
114
119
 
120
+ ### Restart an existing incident
121
+
122
+ Incidents are restarted by posting a *RES* type event to an incident's event
123
+ log, with an optional timestamp. The `Client` class provides the follow
124
+ convenience method for this operation:
125
+
126
+ ```pycon
127
+ >>> from pyargus.client import Client
128
+ >>> from pyargus.time import now as utcnow
129
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
130
+ >>> c.restart_incident(incident=8, description="The demolition was restarted", timestamp=utcnow())
131
+ Event(pk=10, actor='testnav', description='The demolition was restarted', incident=8, received=datetime.datetime(2021, 4, 22, 11, 47, 11, 978438, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), timestamp=datetime.datetime(2021, 4, 22, 11, 47, 11, 946076, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), type='RES')
132
+ ```
133
+
115
134
  ### Modify an existing incident
116
135
 
117
136
  Argus does not allow modification of most incident attributes, but things
@@ -132,10 +151,48 @@ wish you modify, and then adding values to the attributes you wish to modify:
132
151
  ... }
133
152
  ... )
134
153
  >>> c.update_incident(i)
135
- Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=None, ticket_url='', tags={'host': 'earth.example.org', 'location': 'Milky way'}, stateful=False, open=False, acked=False)
154
+ Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=None, ticket_url='', tags=MultiValueDict([('host', 'earth.example.org'), ('location', 'Milky way')]), stateful=False, open=False, acked=False)
155
+
156
+ ```
157
+
158
+ ### Working with multi-valued tags
136
159
 
160
+ Argus allows an incident to carry the same tag key more than once (for example
161
+ two different `host` values). The `tags` attribute is therefore a
162
+ `MultiValueDict` — a `dict` subclass that keeps every value while still behaving
163
+ like an ordinary dictionary for code that expects a single value per key.
164
+
165
+ Construct it from a sequence of `(key, value)` pairs (unlike a plain `dict`,
166
+ repeated keys are kept), or build it up with `add()`:
167
+
168
+ ```pycon
169
+ >>> from pyargus.models import Incident
170
+ >>> from pyargus.multivaluedict import MultiValueDict
171
+ >>> tags = MultiValueDict([("host", "a.example.org"), ("host", "b.example.org")])
172
+ >>> tags.add("location", "Milky way")
173
+ >>> i = Incident(description="Two hosts affected", tags=tags)
137
174
  ```
138
175
 
176
+ Reading a multi-valued key through the ordinary `[]`/`get()` interface returns
177
+ only the *last* value and emits a `DeprecationWarning`, because the other values
178
+ are dropped silently. Use `getlist()` to retrieve them all:
179
+
180
+ ```pycon
181
+ >>> tags.getlist("host") # every value for the key
182
+ ['a.example.org', 'b.example.org']
183
+ >>> tags["host"] # last value only; warns that values are dropped
184
+ 'b.example.org'
185
+ >>> tags["location"] # single-valued keys read normally, no warning
186
+ 'Milky way'
187
+ >>> tags.lists() # all keys with all of their values
188
+ [('host', ['a.example.org', 'b.example.org']), ('location', ['Milky way'])]
189
+ >>> tags.allitems() # every (key, value) pair, including repeats
190
+ [('host', 'a.example.org'), ('host', 'b.example.org'), ('location', 'Milky way')]
191
+ ```
192
+
193
+ Passing a plain `dict` as `tags` still works exactly as before, so existing code
194
+ needs no changes.
195
+
139
196
  ### Stateless incidents
140
197
 
141
198
  Argus supports a concept of "stateless" incidents. Stateless incidents
@@ -143,13 +200,13 @@ represent single points in time, and do not have an end time. To explicitly
143
200
  create stateless incidents, set the `end_time` attribute to the STATELESS
144
201
  sentinel, like so:
145
202
 
146
- ```python
147
- from datetime import datetime
203
+ ```pycon
148
204
  from pyargus.models import Incident, STATELESS
205
+ from pyargus.time import now as utcnow
149
206
 
150
207
  stateless_incident = Incident(
151
208
  description="Something happened",
152
- start_time=datetime.now(),
209
+ start_time=utcnow(),
153
210
  end_time=STATELESS
154
211
  )
155
212
  ```
@@ -161,11 +218,136 @@ If your argus server is running version 1.29.0 or newer you can request to get
161
218
  a new token (with a new expiration date) via API version 2. The token you are
162
219
  using to access the server with must still be valid.
163
220
 
221
+ There are two methods:
222
+
223
+ #### Use an existing, still valid token
224
+
225
+ You need to already have a token and client.
226
+
164
227
  ```python
165
228
  tokenobj = c.refresh_token()
229
+ # stash away token...
230
+ ```
231
+
232
+ `c` will be using the freshly fetched token after this.
233
+
234
+ #### Use a username/password
235
+
236
+ To get the token and expiry for stashing away:
237
+
238
+ ```python
239
+ from pyargus.client import login
240
+
241
+ tokenobj = login(
242
+ api_root_url="https://argus.example.org/api/v2",
243
+ username=username,
244
+ password=password,
245
+ )
246
+ # stash away token, then...
166
247
  c = Client(api_root_url="https://argus.example.org/api/v2", token=tokenobj.token)
167
- # save the contents of tokenobj in an environment variable, config file or
168
- # secrets file so that it is not lost on program exit
248
+ ```
249
+
250
+ To get a client directly, without opportunity to save the token:
251
+
252
+ ```python
253
+ from pyargus.client import Client
254
+
255
+ c = Client.login(
256
+ api_root_url="https://argus.example.org/api/v2",
257
+ username=username,
258
+ password=password,
259
+ )
260
+ ```
261
+
262
+ Note that `login` is a class method here.
263
+
264
+ ### Set a new token in an existing client
265
+
266
+ ```python
267
+ from pyargus.client import Client
268
+ # get a client that works with public endpoints
269
+ c = Client(api_root_url="https://argus.example.org/api/v2")
270
+
271
+ # get a token as a string from somewhere;
272
+ # * environment variable
273
+ # * secrets file
274
+ # * config file
275
+ # * command line argument
276
+ token = get_token_my_way()
277
+
278
+ # set it, replacing an existing one
279
+ c.set_token(token)
280
+ ```
281
+
282
+ `c` will be using the given token after this.
283
+
284
+ ### Send a heartbeat
285
+
286
+ A source system with no incidents to report looks exactly like one that has
287
+ crashed. Every glue service should therefore send a *heartbeat* on a regular
288
+ schedule to prove it is still alive. A heartbeat updates the source system's
289
+ `last_seen` timestamp on the server without posting an incident, so Argus can
290
+ tell a healthy-but-quiet source apart from a dead one.
291
+
292
+ ```python
293
+ c.send_heartbeat()
294
+ ```
295
+
296
+ The method returns `None` on success. On failure it raises an exception from
297
+ `simple_rest_client`, the HTTP client library that pyargus is built on; these
298
+ exceptions are defined in its `simple_rest_client.exceptions` module (for
299
+ example, `AuthError` for a `401` or `403` response).
300
+
301
+ #### Detecting whether the server supports heartbeats
302
+
303
+ The heartbeat endpoint requires an Argus server new enough to provide it.
304
+ Older servers don't fail cleanly on a `POST` — they reject it with a `403` that
305
+ is indistinguishable from an authentication error — so don't infer support from
306
+ the `send_heartbeat()` outcome. Instead, probe up front with
307
+ `supports_heartbeat()`, which issues a `GET` and returns whether the endpoint is
308
+ present:
309
+
310
+ ```python
311
+ if c.supports_heartbeat():
312
+ c.send_heartbeat()
313
+ ```
314
+
315
+ A long-running glue service can check once at startup and decide whether to
316
+ bother sending heartbeats at all:
317
+
318
+ ```python
319
+ c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
320
+ heartbeats_enabled = c.supports_heartbeat()
321
+ while running:
322
+ do_work()
323
+ if heartbeats_enabled:
324
+ c.send_heartbeat()
325
+ sleep(interval)
326
+ ```
327
+
328
+ ### Getting metadata about the server
329
+
330
+ This endpoint is public so it can be fetched without a token.
331
+
332
+ ```python
333
+ from pprint import pprint
334
+
335
+ from pyargus.client import Client
336
+
337
+ c = Client(api_root_url="https://argus.example.org/api/v2")
338
+ metadata = c.get_server_metadata()
339
+ pprint(vars(metadata))
340
+ ```
341
+
342
+ … which yields a structure looking like this (actual versions may differ):
343
+
344
+ ```python
345
+ {'available_api_versions': {'v3', 'v2'},
346
+ 'jsonapi_schema': {'stable': '/api/schema/',
347
+ 'v2': '/api/v2/schema/',
348
+ 'v3': '/api/v3/schema/'},
349
+ 'server_version': '2.10.2',
350
+ 'stable_api_version': 'v2'}
169
351
  ```
170
352
 
171
353
  ## Async usage
@@ -177,7 +359,7 @@ to try these examples interactively:
177
359
  ```pycon
178
360
  >>> from pyargus.async_client import AsyncClient
179
361
  >>> from pyargus.models import Incident
180
- >>> from datetime import datetime
362
+ >>> from pyargus.time import now as utcnow
181
363
  >>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
182
364
  >>> async for incident in c.get_incidents(open=True, acked=False):
183
365
  ... print(incident)
@@ -185,11 +367,14 @@ to try these examples interactively:
185
367
  Incident(pk=4, ...)
186
368
  >>> i = Incident(
187
369
  ... description="The earth was demolished to make way for a hyperspace bypass",
188
- ... start_time=datetime.now(),
370
+ ... start_time=utcnow(),
189
371
  ... tags={"host": "earth.example.org"},
190
372
  ... )
191
373
  >>> await c.post_incident(i)
192
374
  Incident(pk=8, ...)
375
+ >>> if await c.supports_heartbeat():
376
+ ... await c.send_heartbeat()
377
+ ...
193
378
  ```
194
379
 
195
380
  ## BUGS