argus-api-client 0.3.1__tar.gz → 0.4.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.
Files changed (18) hide show
  1. Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/argus_api_client-0.4.1-py3.7.egg-info/PKG-INFO +135 -0
  2. {argus-api-client-0.3.1/src → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages}/pyargus/__init__.py +1 -1
  3. Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/pyargus/__pycache__/__init__.cpython-37.pyc +0 -0
  4. Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/pyargus/__pycache__/api.cpython-37.pyc +0 -0
  5. Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/pyargus/__pycache__/client.cpython-37.pyc +0 -0
  6. Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/pyargus/__pycache__/models.cpython-37.pyc +0 -0
  7. {argus-api-client-0.3.1/src → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages}/pyargus/api.py +0 -1
  8. {argus-api-client-0.3.1/src → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages}/pyargus/models.py +4 -1
  9. argus-api-client-0.3.1/PKG-INFO +0 -40
  10. argus-api-client-0.3.1/README.md +0 -27
  11. argus-api-client-0.3.1/setup.cfg +0 -29
  12. argus-api-client-0.3.1/setup.py +0 -2
  13. argus-api-client-0.3.1/src/argus_api_client.egg-info/PKG-INFO +0 -40
  14. {argus-api-client-0.3.1/src/argus_api_client.egg-info → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/argus_api_client-0.4.1-py3.7.egg-info}/SOURCES.txt +0 -0
  15. {argus-api-client-0.3.1/src/argus_api_client.egg-info → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/argus_api_client-0.4.1-py3.7.egg-info}/dependency_links.txt +0 -0
  16. {argus-api-client-0.3.1/src/argus_api_client.egg-info → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/argus_api_client-0.4.1-py3.7.egg-info}/requires.txt +0 -0
  17. {argus-api-client-0.3.1/src/argus_api_client.egg-info → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages/argus_api_client-0.4.1-py3.7.egg-info}/top_level.txt +0 -0
  18. {argus-api-client-0.3.1/src → Users/mvold/d/argus/pyargus/.ve/lib/python3.7/site-packages}/pyargus/client.py +0 -0
@@ -0,0 +1,135 @@
1
+ Metadata-Version: 2.1
2
+ Name: argus-api-client
3
+ Version: 0.4.1
4
+ Summary: A Python API client library for the Argus alert aggregator server
5
+ Home-page: https://github.com/Uninett/pyargus
6
+ Author: Morten Brekkevold
7
+ License: Apache-2.0
8
+ Description: # Argus API Client
9
+
10
+ This is the official Python client library for the
11
+ [Argus](https://github.com/Uninett/Argus) API server.
12
+
13
+ The Argus server is an incident registry, capable of aggregating alerts from
14
+ multiple source systems. Argus also can send event notifications (via e-mail,
15
+ SMS, etc.) when incidents are created or resolved.
16
+
17
+ ## Usage examples
18
+
19
+ The pyargus library models [the official API endoints of
20
+ Argus](https://argus-server.readthedocs.io/en/latest/api.html) as methods on an
21
+ API client object.
22
+
23
+ At the moment, only the methods and models needed to interact with
24
+ incident-related endpoints are supported.
25
+
26
+ The `Client` class is found in `pyargus.client`, and the various supported data
27
+ models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
28
+ implemented in `pyargus.models.
29
+
30
+ ### Listing open incidents that have not been acknowledged
31
+
32
+ ```pycon
33
+ >>> from pyargus.client import Client
34
+ >>> c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
35
+ >>> for incident in c.get_incidents(open=True, acked=False):
36
+ ... print(incident)
37
+ ...
38
+ 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)
39
+ 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)
40
+ 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)
41
+ ```
42
+
43
+ As you can see, the arguments given to `get_incidents()` are translated
44
+ verbatim into the arguments supported by the `/incidents` endpoint in the API.
45
+
46
+ ### List only "my" incidents
47
+
48
+ The incidents API also has an `/incidents/mine` endpoint, which works just like
49
+ the `/incidents` endpoint, but searches onl only the incidents that were posted
50
+ by the connecting user. This is useful for glue services, when they need to
51
+ compare the list of open Argus incidents it has produced with the current list
52
+ of active alerts in its source system.
53
+
54
+ Example:
55
+
56
+ ```pycon
57
+ >>> from pyargus.client import Client
58
+ >>> c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
59
+ >>> for incident in c.get_my_incidents(open=True, acked=False):
60
+ ... print(incident)
61
+ ...
62
+ 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)
63
+ ```
64
+
65
+ ### Post a new incident
66
+
67
+ ```pycon
68
+ >>> from pyargus.client import Client
69
+ >>> from pyargus.models import Incident
70
+ >>> from datetime import datetime
71
+ >>> c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
72
+ >>> i = Incident(
73
+ ... description="The earth was demolished to make way for a hyperspace bypass",
74
+ ... start_time=datetime.now(),
75
+ ... tags={
76
+ ... "host": "earth.example.org",
77
+ ... }
78
+ ... )
79
+ >>> c.post_incident(i)
80
+ 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)
81
+ ```
82
+
83
+ The `post_incident()` method returns the full `Incident` record, as stored in
84
+ Argus. If you need it, you can get the incident ID from the the primary key
85
+ attribute `pk`, in case you need to address it directly later.
86
+
87
+ ### Close an existing incident
88
+
89
+ Incidents are closed by posting a *END* type event to an incident's event
90
+ log, with an optional timestamp. The `Client` class provides the follow
91
+ convenience method for this operation:
92
+
93
+ ```pycon
94
+ >>> from pyargus.client import Client
95
+ >>> from datetime import datetime
96
+ >>> c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
97
+ >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=datetime.now())
98
+ 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')
99
+ ```
100
+
101
+ ### Modify an existing incident
102
+
103
+ Argus does not allow modification of most an incident's attributes, but things
104
+ like the tag list can be changed. Modifications are made by constructing an
105
+ `Incident` object with the `pk` attribute set to the id of the incident you
106
+ wish you modify, and then adding values to the attributes you wish to modify:
107
+
108
+ ```pycon
109
+ >>> from pyargus.client import Client
110
+ >>> from pyargus.models import Incident
111
+ >>> from datetime import datetime
112
+ >>> c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
113
+ >>> i = Incident(
114
+ ... pk=8,
115
+ ... tags={
116
+ ... "host": "earth.example.org",
117
+ ... "location": "Milky way",
118
+ ... }
119
+ ... )
120
+ >>> c.update_incident(i)
121
+ 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)
122
+
123
+ ```
124
+
125
+ ## BUGS
126
+
127
+ * Doesn't provide high-level error handling yet.
128
+
129
+ Keywords: api,argus,client
130
+ Platform: UNKNOWN
131
+ Classifier: License :: OSI Approved :: Apache Software License
132
+ Classifier: Programming Language :: Python :: 3
133
+ Classifier: Programming Language :: Python :: 3.7
134
+ Requires-Python: >= 3.7, <4
135
+ Description-Content-Type: text/markdown
@@ -1,3 +1,3 @@
1
1
  """Argus API client library"""
2
2
 
3
- VERSION = "0.3.1"
3
+ VERSION = "0.4.1"
@@ -34,7 +34,6 @@ class IncidentResource(Resource):
34
34
  "retrieve": {"method": "GET", "url": "incidents/{}"},
35
35
  "update": {"method": "PATCH", "url": "incidents/{}"},
36
36
  "set_ticket_url": {"method": "PUT", "url": "incidents/{}/ticket_url/"},
37
- "metadata": {"method": "GET", "url": "incidents/metadata"},
38
37
  }
39
38
 
40
39
 
@@ -33,6 +33,7 @@ class Incident:
33
33
  source_incident_id: str = None
34
34
  details_url: str = None
35
35
  description: str = None
36
+ level: int = None
36
37
  ticket_url: str = None
37
38
  tags: dict = None
38
39
  stateful: bool = None
@@ -66,7 +67,7 @@ class Incident:
66
67
  result = {}
67
68
  for field in self.__dataclass_fields__:
68
69
  value = getattr(self, field)
69
- if value:
70
+ if value or field == "end_time":
70
71
  if field == "start_time" and isinstance(value, datetime):
71
72
  value = value.isoformat()
72
73
  if field == "end_time" and isinstance(value, datetime):
@@ -77,6 +78,8 @@ class Incident:
77
78
  tags = ("{}={}".format(k, v) for k, v in value.items())
78
79
  value = [{"tag": t} for t in tags]
79
80
  result[field] = value
81
+ if "tags" not in result: # API requires tags to be present, but it can be empty
82
+ result["tags"] = []
80
83
  return result
81
84
 
82
85
 
@@ -1,40 +0,0 @@
1
- Metadata-Version: 2.1
2
- Name: argus-api-client
3
- Version: 0.3.1
4
- Summary: A Python API client library for the Argus alert aggregator server
5
- Home-page: https://github.com/Uninett/pyargus
6
- License: Apache-2.0
7
- Description: Argus API Client
8
- ================
9
-
10
- This is the official Python client library for the
11
- [Argus](https://github.com/Uninett/Argus) API server.
12
-
13
- The Argus server is an incident registry, capable of aggregating alerts from
14
- multiple source systems. Argus also can send event notifications (via e-mail,
15
- SMS, etc.) when incidents are created or resolved.
16
-
17
- Usage examples
18
- ==============
19
-
20
- Listing open incidents that have not been acknowledged:
21
-
22
- ```python
23
- from pyargus.client import Client
24
-
25
- c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
26
- for incident in c.get_incidents(open=True, acked=False):
27
- print(incident)
28
- ```
29
-
30
-
31
- BUGS
32
- ====
33
- * Doesn't provide high-level error handling yet.
34
-
35
- Keywords: api,argus,client
36
- Platform: UNKNOWN
37
- Classifier: License :: OSI Approved :: Apache Software License
38
- Classifier: Programming Language :: Python :: 3
39
- Classifier: Programming Language :: Python :: 3.7
40
- Description-Content-Type: text/markdown
@@ -1,27 +0,0 @@
1
- Argus API Client
2
- ================
3
-
4
- This is the official Python client library for the
5
- [Argus](https://github.com/Uninett/Argus) API server.
6
-
7
- The Argus server is an incident registry, capable of aggregating alerts from
8
- multiple source systems. Argus also can send event notifications (via e-mail,
9
- SMS, etc.) when incidents are created or resolved.
10
-
11
- Usage examples
12
- ==============
13
-
14
- Listing open incidents that have not been acknowledged:
15
-
16
- ```python
17
- from pyargus.client import Client
18
-
19
- c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
20
- for incident in c.get_incidents(open=True, acked=False):
21
- print(incident)
22
- ```
23
-
24
-
25
- BUGS
26
- ====
27
- * Doesn't provide high-level error handling yet.
@@ -1,29 +0,0 @@
1
- [metadata]
2
- name = argus-api-client
3
- version = attr: pyargus.VERSION
4
- description = A Python API client library for the Argus alert aggregator server
5
- long_description = file: README.md
6
- long_description_content_type = text/markdown
7
- url = https://github.com/Uninett/pyargus
8
- keywords = api, argus, client
9
- license = Apache-2.0
10
- classifiers =
11
- License :: OSI Approved :: Apache Software License
12
- Programming Language :: Python :: 3
13
- Programming Language :: Python :: 3.7
14
-
15
- [options]
16
- install_requires =
17
- simple_rest_client
18
- iso8601
19
- package_dir =
20
- =src
21
- packages = find:
22
-
23
- [options.packages.find]
24
- where = src
25
-
26
- [egg_info]
27
- tag_build =
28
- tag_date = 0
29
-
@@ -1,2 +0,0 @@
1
- from setuptools import setup, find_packages
2
- setup()
@@ -1,40 +0,0 @@
1
- Metadata-Version: 2.1
2
- Name: argus-api-client
3
- Version: 0.3.1
4
- Summary: A Python API client library for the Argus alert aggregator server
5
- Home-page: https://github.com/Uninett/pyargus
6
- License: Apache-2.0
7
- Description: Argus API Client
8
- ================
9
-
10
- This is the official Python client library for the
11
- [Argus](https://github.com/Uninett/Argus) API server.
12
-
13
- The Argus server is an incident registry, capable of aggregating alerts from
14
- multiple source systems. Argus also can send event notifications (via e-mail,
15
- SMS, etc.) when incidents are created or resolved.
16
-
17
- Usage examples
18
- ==============
19
-
20
- Listing open incidents that have not been acknowledged:
21
-
22
- ```python
23
- from pyargus.client import Client
24
-
25
- c = Client(api_root_url="https://argus.example.org/api/v1", token="foobar")
26
- for incident in c.get_incidents(open=True, acked=False):
27
- print(incident)
28
- ```
29
-
30
-
31
- BUGS
32
- ====
33
- * Doesn't provide high-level error handling yet.
34
-
35
- Keywords: api,argus,client
36
- Platform: UNKNOWN
37
- Classifier: License :: OSI Approved :: Apache Software License
38
- Classifier: Programming Language :: Python :: 3
39
- Classifier: Programming Language :: Python :: 3.7
40
- Description-Content-Type: text/markdown