argus-api-client 0.6.0__tar.gz → 0.7.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 (24) hide show
  1. argus_api_client-0.7.0/PKG-INFO +211 -0
  2. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/README.md +27 -3
  3. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/pyproject.toml +19 -10
  4. argus_api_client-0.7.0/src/argus_api_client.egg-info/PKG-INFO +211 -0
  5. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/src/argus_api_client.egg-info/SOURCES.txt +6 -1
  6. argus_api_client-0.7.0/src/argus_api_client.egg-info/requires.txt +2 -0
  7. argus_api_client-0.7.0/src/pyargus/__init__.py +6 -0
  8. argus_api_client-0.7.0/src/pyargus/async_api.py +56 -0
  9. argus_api_client-0.7.0/src/pyargus/async_client.py +172 -0
  10. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/src/pyargus/client.py +7 -6
  11. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/src/pyargus/models.py +3 -1
  12. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/tests/test_api.py +1 -0
  13. argus_api_client-0.7.0/tests/test_async_api.py +17 -0
  14. argus_api_client-0.7.0/tests/test_async_client.py +35 -0
  15. argus_api_client-0.7.0/tests/test_client.py +31 -0
  16. argus_api_client-0.6.0/PKG-INFO +0 -387
  17. argus_api_client-0.6.0/src/argus_api_client.egg-info/PKG-INFO +0 -387
  18. argus_api_client-0.6.0/src/argus_api_client.egg-info/requires.txt +0 -13
  19. argus_api_client-0.6.0/src/pyargus/__init__.py +0 -3
  20. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/LICENSE +0 -0
  21. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/setup.cfg +0 -0
  22. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/src/argus_api_client.egg-info/dependency_links.txt +0 -0
  23. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/src/argus_api_client.egg-info/top_level.txt +0 -0
  24. {argus_api_client-0.6.0 → argus_api_client-0.7.0}/src/pyargus/api.py +0 -0
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.4
2
+ Name: argus-api-client
3
+ Version: 0.7.0
4
+ Summary: A Python API client library for the Argus alert aggregator server
5
+ Author-email: Sikt - Kunnskapssektorens Tjenesteleverandør <kontakt@sikt.no>
6
+ License-Expression: Apache-2.0
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3.9
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: simple_rest_client
17
+ Requires-Dist: iso8601
18
+ Dynamic: license-file
19
+
20
+ # Argus API Client
21
+ [![test badge](https://img.shields.io/github/actions/workflow/status/Uninett/pyargus/tox.yml?branch=master)](https://github.com/Uninett/pyargus/actions)
22
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
23
+
24
+ This is the official Python client library for the
25
+ [Argus](https://github.com/Uninett/Argus) API server.
26
+
27
+ The Argus server is an incident registry, capable of aggregating alerts from
28
+ multiple source systems. Argus also can send event notifications (via e-mail,
29
+ SMS, etc.) when incidents are created or resolved.
30
+
31
+ ## Usage examples
32
+
33
+ The pyargus library models [the official API endoints of
34
+ Argus](https://argus-server.readthedocs.io/en/latest/api.html) as methods on an
35
+ API client object.
36
+
37
+ At the moment, only the methods and models needed to interact with
38
+ incident-related endpoints are supported.
39
+
40
+ The `Client` class is found in `pyargus.client`, and the various supported data
41
+ models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
42
+ implemented in `pyargus.models`.
43
+
44
+ ### Listing open incidents that have not been acknowledged
45
+
46
+ ```pycon
47
+ >>> from pyargus.client import Client
48
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
49
+ >>> for incident in c.get_incidents(open=True, acked=False):
50
+ ... print(incident)
51
+ ...
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)
55
+ ```
56
+
57
+ As you can see, the arguments given to `get_incidents()` are translated
58
+ verbatim into the arguments supported by the `/incidents` endpoint in the API.
59
+
60
+ ### List only "my" incidents
61
+
62
+ The incidents API also has an `/incidents/mine` endpoint, which works just like
63
+ the `/incidents` endpoint, but searches only the incidents that were posted
64
+ by the connecting user. This is useful for glue services, when they need to
65
+ compare the list of open Argus incidents it has produced with the current list
66
+ of active alerts in its source system.
67
+
68
+ Example:
69
+
70
+ ```pycon
71
+ >>> from pyargus.client import Client
72
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
73
+ >>> for incident in c.get_my_incidents(open=True, acked=False):
74
+ ... print(incident)
75
+ ...
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)
77
+ ```
78
+
79
+ ### Post a new incident
80
+
81
+ ```pycon
82
+ >>> from pyargus.client import Client
83
+ >>> from pyargus.models import Incident
84
+ >>> from datetime import datetime
85
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
86
+ >>> i = Incident(
87
+ ... description="The earth was demolished to make way for a hyperspace bypass",
88
+ ... start_time=datetime.now(),
89
+ ... tags={
90
+ ... "host": "earth.example.org",
91
+ ... }
92
+ ... )
93
+ >>> 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)
95
+ ```
96
+
97
+ The `post_incident()` method returns the full `Incident` record, as stored in
98
+ Argus. If you need it, you can get the incident ID from the the primary key
99
+ attribute `pk`, in case you need to address it directly later.
100
+
101
+ ### Close an existing incident
102
+
103
+ Incidents are closed by posting a *END* type event to an incident's event
104
+ log, with an optional timestamp. The `Client` class provides the follow
105
+ convenience method for this operation:
106
+
107
+ ```pycon
108
+ >>> from pyargus.client import Client
109
+ >>> from datetime import datetime
110
+ >>> 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())
112
+ 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
+ ```
114
+
115
+ ### Modify an existing incident
116
+
117
+ Argus does not allow modification of most incident attributes, but things
118
+ like the tag list can be changed. Modifications are made by constructing an
119
+ `Incident` object with the `pk` attribute set to the id of the incident you
120
+ wish you modify, and then adding values to the attributes you wish to modify:
121
+
122
+ ```pycon
123
+ >>> from pyargus.client import Client
124
+ >>> from pyargus.models import Incident
125
+ >>> from datetime import datetime
126
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
127
+ >>> i = Incident(
128
+ ... pk=8,
129
+ ... tags={
130
+ ... "host": "earth.example.org",
131
+ ... "location": "Milky way",
132
+ ... }
133
+ ... )
134
+ >>> 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)
136
+
137
+ ```
138
+
139
+ ### Stateless incidents
140
+
141
+ Argus supports a concept of "stateless" incidents. Stateless incidents
142
+ represent single points in time, and do not have an end time. To explicitly
143
+ create stateless incidents, set the `end_time` attribute to the STATELESS
144
+ sentinel, like so:
145
+
146
+ ```python
147
+ from datetime import datetime
148
+ from pyargus.models import Incident, STATELESS
149
+
150
+ stateless_incident = Incident(
151
+ description="Something happened",
152
+ start_time=datetime.now(),
153
+ end_time=STATELESS
154
+ )
155
+ ```
156
+
157
+
158
+ ### Get a new authentication token
159
+
160
+ If your argus server is running version 1.29.0 or newer you can request to get
161
+ a new token (with a new expiration date) via API version 2. The token you are
162
+ using to access the server with must still be valid.
163
+
164
+ ```python
165
+ tokenobj = c.refresh_token()
166
+ 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
169
+ ```
170
+
171
+ ## Async usage
172
+
173
+ An `AsyncClient` is available for use in asyncio-based applications. It mirrors
174
+ the `Client` interface, but all methods are coroutines. Use `python -m asyncio`
175
+ to try these examples interactively:
176
+
177
+ ```pycon
178
+ >>> from pyargus.async_client import AsyncClient
179
+ >>> from pyargus.models import Incident
180
+ >>> from datetime import datetime
181
+ >>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
182
+ >>> async for incident in c.get_incidents(open=True, acked=False):
183
+ ... print(incident)
184
+ ...
185
+ Incident(pk=4, ...)
186
+ >>> i = Incident(
187
+ ... description="The earth was demolished to make way for a hyperspace bypass",
188
+ ... start_time=datetime.now(),
189
+ ... tags={"host": "earth.example.org"},
190
+ ... )
191
+ >>> await c.post_incident(i)
192
+ Incident(pk=8, ...)
193
+ ```
194
+
195
+ ## BUGS
196
+
197
+ * Doesn't provide high-level error handling yet.
198
+
199
+ ## Development
200
+
201
+ ### Code style
202
+
203
+ Pyargus uses *ruff* as a source code formatter. Ruff is part of the optional dev dependencies listed in
204
+ [pyproject.toml](./pyproject.toml)
205
+
206
+ A pre-commit hook will format new code automatically before committing.
207
+ To enable this pre-commit hook, run
208
+
209
+ ```console
210
+ $ pre-commit install
211
+ ```
@@ -2,10 +2,10 @@
2
2
  [![test badge](https://img.shields.io/github/actions/workflow/status/Uninett/pyargus/tox.yml?branch=master)](https://github.com/Uninett/pyargus/actions)
3
3
  [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
4
4
 
5
- This is the official Python client library for the
5
+ This is the official Python client library for the
6
6
  [Argus](https://github.com/Uninett/Argus) API server.
7
7
 
8
- The Argus server is an incident registry, capable of aggregating alerts from
8
+ The Argus server is an incident registry, capable of aggregating alerts from
9
9
  multiple source systems. Argus also can send event notifications (via e-mail,
10
10
  SMS, etc.) when incidents are created or resolved.
11
11
 
@@ -65,7 +65,7 @@ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzin
65
65
  >>> from datetime import datetime
66
66
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
67
67
  >>> i = Incident(
68
- ... description="The earth was demolished to make way for a hyperspace bypass",
68
+ ... description="The earth was demolished to make way for a hyperspace bypass",
69
69
  ... start_time=datetime.now(),
70
70
  ... tags={
71
71
  ... "host": "earth.example.org",
@@ -149,6 +149,30 @@ c = Client(api_root_url="https://argus.example.org/api/v2", token=tokenobj.token
149
149
  # secrets file so that it is not lost on program exit
150
150
  ```
151
151
 
152
+ ## Async usage
153
+
154
+ An `AsyncClient` is available for use in asyncio-based applications. It mirrors
155
+ the `Client` interface, but all methods are coroutines. Use `python -m asyncio`
156
+ to try these examples interactively:
157
+
158
+ ```pycon
159
+ >>> from pyargus.async_client import AsyncClient
160
+ >>> from pyargus.models import Incident
161
+ >>> from datetime import datetime
162
+ >>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
163
+ >>> async for incident in c.get_incidents(open=True, acked=False):
164
+ ... print(incident)
165
+ ...
166
+ Incident(pk=4, ...)
167
+ >>> i = Incident(
168
+ ... description="The earth was demolished to make way for a hyperspace bypass",
169
+ ... start_time=datetime.now(),
170
+ ... tags={"host": "earth.example.org"},
171
+ ... )
172
+ >>> await c.post_incident(i)
173
+ Incident(pk=8, ...)
174
+ ```
175
+
152
176
  ## BUGS
153
177
 
154
178
  * Doesn't provide high-level error handling yet.
@@ -1,35 +1,45 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
1
5
  [project]
2
6
  name = "argus-api-client"
3
7
  dynamic = ["version"]
4
8
  description = "A Python API client library for the Argus alert aggregator server"
5
9
  readme = "README.md"
6
10
  authors = [{name="Sikt - Kunnskapssektorens Tjenesteleverandør", email="kontakt@sikt.no"}]
7
- requires-python = ">=3.8"
8
- license = {file = "LICENSE"}
11
+ requires-python = ">=3.9"
12
+ license = "Apache-2.0"
13
+ license-files = ["LICENSE"]
9
14
  classifiers = [
10
- "License :: OSI Approved :: Apache Software License",
11
15
  "Programming Language :: Python :: 3",
12
- "Programming Language :: Python :: 3.8",
13
16
  "Programming Language :: Python :: 3.9",
14
17
  "Programming Language :: Python :: 3.10",
15
18
  "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
16
21
  ]
17
22
  dependencies = [
18
23
  "simple_rest_client",
19
24
  "iso8601",
20
25
  ]
21
26
 
22
- [project.optional-dependencies]
27
+ [dependency-groups]
28
+ test = [
29
+ "pytest",
30
+ "pytest-asyncio",
31
+ "pytest-cov",
32
+ "pytest-argus-server>=0.2.0",
33
+ ]
23
34
  dev = [
24
35
  "build",
25
36
  "coverage",
26
37
  "ipython",
27
- "isort",
28
38
  "pre-commit",
29
- "pytest",
30
39
  "ruff",
31
40
  "tox",
32
41
  "twine",
42
+ {include-group = "test"},
33
43
  ]
34
44
 
35
45
  [tool.setuptools.dynamic]
@@ -44,8 +54,7 @@ line-length = 88
44
54
  extend-exclude = [
45
55
  ".egg-info",
46
56
  ]
47
- output-format = "full"
48
57
 
49
58
  [tool.ruff.lint]
50
- select = ["E4", "E7", "E9", "F4", "F5", "F6", "F7", "F8", "F9"]
51
- ignore = ["F403", "F405"]
59
+ select = ["E4", "E7", "E9", "F", "I"]
60
+ fixable = ["I"]
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.4
2
+ Name: argus-api-client
3
+ Version: 0.7.0
4
+ Summary: A Python API client library for the Argus alert aggregator server
5
+ Author-email: Sikt - Kunnskapssektorens Tjenesteleverandør <kontakt@sikt.no>
6
+ License-Expression: Apache-2.0
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3.9
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: simple_rest_client
17
+ Requires-Dist: iso8601
18
+ Dynamic: license-file
19
+
20
+ # Argus API Client
21
+ [![test badge](https://img.shields.io/github/actions/workflow/status/Uninett/pyargus/tox.yml?branch=master)](https://github.com/Uninett/pyargus/actions)
22
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
23
+
24
+ This is the official Python client library for the
25
+ [Argus](https://github.com/Uninett/Argus) API server.
26
+
27
+ The Argus server is an incident registry, capable of aggregating alerts from
28
+ multiple source systems. Argus also can send event notifications (via e-mail,
29
+ SMS, etc.) when incidents are created or resolved.
30
+
31
+ ## Usage examples
32
+
33
+ The pyargus library models [the official API endoints of
34
+ Argus](https://argus-server.readthedocs.io/en/latest/api.html) as methods on an
35
+ API client object.
36
+
37
+ At the moment, only the methods and models needed to interact with
38
+ incident-related endpoints are supported.
39
+
40
+ The `Client` class is found in `pyargus.client`, and the various supported data
41
+ models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
42
+ implemented in `pyargus.models`.
43
+
44
+ ### Listing open incidents that have not been acknowledged
45
+
46
+ ```pycon
47
+ >>> from pyargus.client import Client
48
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
49
+ >>> for incident in c.get_incidents(open=True, acked=False):
50
+ ... print(incident)
51
+ ...
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)
55
+ ```
56
+
57
+ As you can see, the arguments given to `get_incidents()` are translated
58
+ verbatim into the arguments supported by the `/incidents` endpoint in the API.
59
+
60
+ ### List only "my" incidents
61
+
62
+ The incidents API also has an `/incidents/mine` endpoint, which works just like
63
+ the `/incidents` endpoint, but searches only the incidents that were posted
64
+ by the connecting user. This is useful for glue services, when they need to
65
+ compare the list of open Argus incidents it has produced with the current list
66
+ of active alerts in its source system.
67
+
68
+ Example:
69
+
70
+ ```pycon
71
+ >>> from pyargus.client import Client
72
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
73
+ >>> for incident in c.get_my_incidents(open=True, acked=False):
74
+ ... print(incident)
75
+ ...
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)
77
+ ```
78
+
79
+ ### Post a new incident
80
+
81
+ ```pycon
82
+ >>> from pyargus.client import Client
83
+ >>> from pyargus.models import Incident
84
+ >>> from datetime import datetime
85
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
86
+ >>> i = Incident(
87
+ ... description="The earth was demolished to make way for a hyperspace bypass",
88
+ ... start_time=datetime.now(),
89
+ ... tags={
90
+ ... "host": "earth.example.org",
91
+ ... }
92
+ ... )
93
+ >>> 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)
95
+ ```
96
+
97
+ The `post_incident()` method returns the full `Incident` record, as stored in
98
+ Argus. If you need it, you can get the incident ID from the the primary key
99
+ attribute `pk`, in case you need to address it directly later.
100
+
101
+ ### Close an existing incident
102
+
103
+ Incidents are closed by posting a *END* type event to an incident's event
104
+ log, with an optional timestamp. The `Client` class provides the follow
105
+ convenience method for this operation:
106
+
107
+ ```pycon
108
+ >>> from pyargus.client import Client
109
+ >>> from datetime import datetime
110
+ >>> 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())
112
+ 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
+ ```
114
+
115
+ ### Modify an existing incident
116
+
117
+ Argus does not allow modification of most incident attributes, but things
118
+ like the tag list can be changed. Modifications are made by constructing an
119
+ `Incident` object with the `pk` attribute set to the id of the incident you
120
+ wish you modify, and then adding values to the attributes you wish to modify:
121
+
122
+ ```pycon
123
+ >>> from pyargus.client import Client
124
+ >>> from pyargus.models import Incident
125
+ >>> from datetime import datetime
126
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
127
+ >>> i = Incident(
128
+ ... pk=8,
129
+ ... tags={
130
+ ... "host": "earth.example.org",
131
+ ... "location": "Milky way",
132
+ ... }
133
+ ... )
134
+ >>> 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)
136
+
137
+ ```
138
+
139
+ ### Stateless incidents
140
+
141
+ Argus supports a concept of "stateless" incidents. Stateless incidents
142
+ represent single points in time, and do not have an end time. To explicitly
143
+ create stateless incidents, set the `end_time` attribute to the STATELESS
144
+ sentinel, like so:
145
+
146
+ ```python
147
+ from datetime import datetime
148
+ from pyargus.models import Incident, STATELESS
149
+
150
+ stateless_incident = Incident(
151
+ description="Something happened",
152
+ start_time=datetime.now(),
153
+ end_time=STATELESS
154
+ )
155
+ ```
156
+
157
+
158
+ ### Get a new authentication token
159
+
160
+ If your argus server is running version 1.29.0 or newer you can request to get
161
+ a new token (with a new expiration date) via API version 2. The token you are
162
+ using to access the server with must still be valid.
163
+
164
+ ```python
165
+ tokenobj = c.refresh_token()
166
+ 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
169
+ ```
170
+
171
+ ## Async usage
172
+
173
+ An `AsyncClient` is available for use in asyncio-based applications. It mirrors
174
+ the `Client` interface, but all methods are coroutines. Use `python -m asyncio`
175
+ to try these examples interactively:
176
+
177
+ ```pycon
178
+ >>> from pyargus.async_client import AsyncClient
179
+ >>> from pyargus.models import Incident
180
+ >>> from datetime import datetime
181
+ >>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
182
+ >>> async for incident in c.get_incidents(open=True, acked=False):
183
+ ... print(incident)
184
+ ...
185
+ Incident(pk=4, ...)
186
+ >>> i = Incident(
187
+ ... description="The earth was demolished to make way for a hyperspace bypass",
188
+ ... start_time=datetime.now(),
189
+ ... tags={"host": "earth.example.org"},
190
+ ... )
191
+ >>> await c.post_incident(i)
192
+ Incident(pk=8, ...)
193
+ ```
194
+
195
+ ## BUGS
196
+
197
+ * Doesn't provide high-level error handling yet.
198
+
199
+ ## Development
200
+
201
+ ### Code style
202
+
203
+ Pyargus uses *ruff* as a source code formatter. Ruff is part of the optional dev dependencies listed in
204
+ [pyproject.toml](./pyproject.toml)
205
+
206
+ A pre-commit hook will format new code automatically before committing.
207
+ To enable this pre-commit hook, run
208
+
209
+ ```console
210
+ $ pre-commit install
211
+ ```
@@ -8,6 +8,11 @@ src/argus_api_client.egg-info/requires.txt
8
8
  src/argus_api_client.egg-info/top_level.txt
9
9
  src/pyargus/__init__.py
10
10
  src/pyargus/api.py
11
+ src/pyargus/async_api.py
12
+ src/pyargus/async_client.py
11
13
  src/pyargus/client.py
12
14
  src/pyargus/models.py
13
- tests/test_api.py
15
+ tests/test_api.py
16
+ tests/test_async_api.py
17
+ tests/test_async_client.py
18
+ tests/test_client.py
@@ -0,0 +1,2 @@
1
+ simple_rest_client
2
+ iso8601
@@ -0,0 +1,6 @@
1
+ """Argus API client library"""
2
+
3
+ from pyargus.async_client import AsyncClient as AsyncClient
4
+ from pyargus.client import Client as Client
5
+
6
+ VERSION = "0.7.0"
@@ -0,0 +1,56 @@
1
+ """Defines an async low-level API interface for Argus using simple_rest_client"""
2
+
3
+ from simple_rest_client.api import API
4
+ from simple_rest_client.resource import AsyncResource
5
+
6
+ from .api import (
7
+ ExpiringTokenResource,
8
+ IncidentAcknowledgementResource,
9
+ IncidentEventResource,
10
+ IncidentResource,
11
+ )
12
+
13
+
14
+ def async_connect(api_root_url: str, token: str, timeout: float = 2.0) -> API:
15
+ """Connects to an Argus API instance using async resources.
16
+
17
+ :returns: A connected simple_rest_client API object with async resources
18
+ """
19
+ headers = {"Authorization": "Token " + token}
20
+ argusapi = API(
21
+ api_root_url=api_root_url,
22
+ headers=headers,
23
+ timeout=timeout,
24
+ json_encode_body=True,
25
+ append_slash=True,
26
+ )
27
+ argusapi.add_resource(
28
+ resource_name="incidents", resource_class=AsyncIncidentResource
29
+ )
30
+ argusapi.add_resource(
31
+ resource_name="events", resource_class=AsyncIncidentEventResource
32
+ )
33
+ argusapi.add_resource(
34
+ resource_name="acknowledgements",
35
+ resource_class=AsyncIncidentAcknowledgementResource,
36
+ )
37
+ argusapi.add_resource(
38
+ resource_name="tokens", resource_class=AsyncExpiringTokenResource
39
+ )
40
+ return argusapi
41
+
42
+
43
+ class AsyncIncidentResource(AsyncResource):
44
+ actions = IncidentResource.actions
45
+
46
+
47
+ class AsyncIncidentEventResource(AsyncResource):
48
+ actions = IncidentEventResource.actions
49
+
50
+
51
+ class AsyncIncidentAcknowledgementResource(AsyncResource):
52
+ actions = IncidentAcknowledgementResource.actions
53
+
54
+
55
+ class AsyncExpiringTokenResource(AsyncResource):
56
+ actions = ExpiringTokenResource.actions