You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -19,15 +19,31 @@ during a NANOG meeting that aimed to promote the usage of the iCalendar format.
19
19
proposed iCalendar format, the parser is straight-forward and there is no need to define custom logic, but this library
20
20
enables supporting other providers that are not using this proposed practice, getting the same outcome.
21
21
22
-
You can leverage on this library in your automation framework to process circuit maintenance notifications, and use the standarised output to handle your received circuit maintenance notifications in a simple way.
22
+
You can leverage this library in your automation framework to process circuit maintenance notifications, and use the standardized [`Maintenance`](https://github.com/networktocode/circuit-maintenance-parser/blob/develop/circuit_maintenance_parser/output.py) to handle your received circuit maintenance notifications in a simple way. Every `maintenance` object contains, at least, the following attributes:
23
+
24
+
-**provider**: identifies the provider of the service that is the subject of the maintenance notification.
25
+
-**account**: identifies an account associated with the service that is the subject of the maintenance notification.
26
+
-**maintenance_id**: contains text that uniquely identifies the maintenance that is the subject of the notification.
27
+
-**circuits**: list of circuits affected by the maintenance notification and their specific impact.
28
+
-**status**: defines the overall status or confirmation for the maintenance.
29
+
-**start**: timestamp that defines the start date of the maintenance in GMT.
30
+
-**end**: timestamp that defines the end date of the maintenance in GMT.
31
+
-**stamp**: timestamp that defines the update date of the maintenance in GMT.
32
+
-**organizer**: defines the contact information included in the original notification.
33
+
34
+
> Please, refer to the [BCOP](https://github.com/jda/maintnote-std/blob/master/standard.md) to more details about these attributes.
23
35
24
36
## Workflow
25
37
26
38
1. We instantiate a `Provider`, directly or via the `init_provider` method, that depending on the selected type will return the corresponding instance.
27
-
2. Each `Provider` have already defined multiple `Processors` that will be used to get the `Maintenances` when the `Provider.get_maintenances(data)` method is called.
28
-
3. Each `Processor` class can have a pre defined logic to combine the data extracted from the notifications and create the final `Maintenance` object, and receives a `List` of multiple `Parsers` that will be to `parse` each type of data.
29
-
4. Each `Parser` class supports one or more data types and implements the `Parser.parse()` method used to retrieve a `Dict` with the relevant key/values.
30
-
5. When calling the `Provider.get_maintenances(data)`, the `data` argument is an instance of `NotificationData` (which is just a collection of multiple `DataParts`, each one with a `type` and a `content`) that will be used by the corresponding `Parser` when the `Processor` will try to match them.
39
+
2. Get an instance of the `NotificationData` class. This instance groups together `DataParts` which each contain some content and a specific type (that will match a specific `Parser`). For example, a `NotificationData` might describe a received email message, with `DataParts` corresponding to the subject line and body of the email. There are factory methods to initialize a `NotificationData` describing a single chunk of binary data, as well as others to initialize one directly from a raw email message or `email.message.EmailMessage` instance.
40
+
3. Each `Provider` uses one or more `Processors` that will be used to build `Maintenances` when the `Provider.get_maintenances(data)` method is called.
41
+
4. Each `Processor` class uses one or more `Parsers` to process each type of data that it handles. It can have custom logic to combine the parsed data from multiple `Parsers` to create the final `Maintenance` object.
42
+
5. Each `Parser` class supports one or a set of related data types, and implements the `Parser.parse()` method used to retrieve a `Dict` with the relevant keys/values.
By default, there is a `GenericProvider` that support a `SimpleProcessor` using the standard `ICal``Parser`, being the easiest path to start using the library in case the provider uses the reference iCalendar standard.
33
49
@@ -66,15 +82,39 @@ By default, there is a `GenericProvider` that support a `SimpleProcessor` using
66
82
The library is available as a Python package in pypi and can be installed with pip:
67
83
`pip install circuit-maintenance-parser`
68
84
69
-
## Usage
85
+
## How to use it?
70
86
71
-
> Please, refer to the [BCOP](https://github.com/jda/maintnote-std/blob/master/standard.md) to understand the meaning
72
-
> of the output attributes.
87
+
The library requires two things:
73
88
74
-
## Python Library
89
+
- The `notificationdata`: this is the data that the library will check to extract the maintenance notifications. It can be simple (only one data type and content, such as an iCalendar notification) or more complex (with multiple data parts of different types, such as from an email).
90
+
- The `provider` identifier: used to select the proper `Provider` which contains the `processor` logic to take the proper `Parsers` and use the data that they extract. By default, the `GenericProvider` (used when no other provider type is defined) will support parsing of `iCalendar` notifications using the recommended format.
91
+
92
+
### Python Library
93
+
94
+
First step is to define the `Provider` that we will use to parse the notifications. As commented, there is a `GenericProvider` that implements the gold standard format and can be reused for any notification matching the expectations.
75
95
76
96
```python
77
-
from circuit_maintenance_parser import init_provider, NotificationData
97
+
from circuit_maintenance_parser import init_provider
However, usually some `Providers` don't fully implement the standard and maybe some information is missing, for example the `organizer` email or maybe a custom logic to combine information is required, so we allow custom `Providers`:
106
+
107
+
```python
108
+
ntt_provider = init_provider("ntt")
109
+
110
+
type(ntt_provider)
111
+
<class'circuit_maintenance_parser.provider.NTT'>
112
+
```
113
+
114
+
Once we have the `Provider` ready, we need to initialize the data to process, we call it `NotificationData` and can be initialized from a simple content and type or from more complex structures, such as an email.
115
+
116
+
```python
117
+
from circuit_maintenance_parser import NotificationData
Finally, with we retrieve the maintenances (it is a `List` because a notification can contain multiple maintenances) from the data calling the `get_maintenances` method from the `Provider` instance:
Notice that, either with the `GenericProvider` or `NTT` provider, we get the same result from the same data, because they are using exactly the same `Processor` and `Parser`. The only difference is that `NTT` notifications come without `organizer` and `provider` in the notification, and this info is fulfilled with some default values for the `Provider`, but in this case the original notification contains all the necessary information, so the defaults are not used.
Even though the library aims to include support for as many providers as possible, it's likely that not all the thousands of NSP are supported and you may need to add support for some new one. Adding a new `Provider` is quite straightforward, and in the following example we are adding support for an imaginary provider, ABCDE, that uses HTML notifications.
220
+
221
+
First step is creating a new file: `circuit_maintenance_parser/parsers/abcde.py`. This file will contain all the custom parsers needed for the provider and it will import the base classes for each parser type from `circuit_maintenance_parser.parser`. In the example, we only need to import `Html` and in the child class implement the methods required by the class, in this case `parse_html()` which will return a `dict` with all the data that this `Parser` can extract. In this case we have to helper methods, `_parse_bs` and `_parse_tables` that implement the logic to navigate the notification data.
222
+
223
+
```python
224
+
from typing import Dict
225
+
import bs4 # type:ignore
226
+
from bs4.element import ResultSet # type:ignore
227
+
from circuit_maintenance_parser.parser import Html
Next step is to create the new `Provider` by defining a new class in `circuit_maintenance_parser/provider.py`. This class that inherits from `GenericProvider` only needs to define two attributes:
244
+
245
+
-`_processors`: is a `list` of `Processor` instances that uses several data `Parsers`. In this example, we don't need to create a new custom `Processor` because the combined logic serves well (the most likely case), and we only need to use the new defined `HtmlParserABCDE1` and also the generic `EmailDateParser` that extract the email date. Also notice that you could have multiple `Processors` with different `Parsers` in this list, supporting several formats.
246
+
-`_default_organizer`: this is a default helper to fill the `organizer` attribute in the `Maintenance` if the information is not part of the original notification.
0 commit comments