From 7856dc15c570e108a11f362343f93b07d1667668 Mon Sep 17 00:00:00 2001 From: Mingwei Zhang Date: Fri, 25 Oct 2019 13:42:20 -0700 Subject: [PATCH 1/3] add high-level pybgpstream api doc --- docs/api_pybgpstream.rst | 163 +++++++++++++++++++++++++++++++++++++++ docs/conf.py | 4 +- docs/index.rst | 3 + 3 files changed, 168 insertions(+), 2 deletions(-) create mode 100644 docs/api_pybgpstream.rst diff --git a/docs/api_pybgpstream.rst b/docs/api_pybgpstream.rst new file mode 100644 index 0000000..dc47aa5 --- /dev/null +++ b/docs/api_pybgpstream.rst @@ -0,0 +1,163 @@ +pybgpstream +============ + +This document describes the API of the pybgpstream module, a high-level +interface to the C `libbgpstream` library, providing a more user-friendly +interaction with the low-level `_pybgpstream` API. + +.. py:module:: pybgpstream + +Example +---------- +.. code-block:: python + :linenos: + + import pybgpstream + + # create and configure the stream + stream = pybgpstream.BGPStream( + from_time="2017-07-07 00:00:00", until_time="2017-07-07 00:10:00 UTC", + collectors=["route-views.sg", "route-views.eqix"], + record_type="updates", + filter="peer 11666 and prefix more 210.180.0.0/16" + ) + + # add any additional (or dynamic) filters + # e.g. from peer AS 11666 regarding the more-specifics of 210.180.0.0/16: + # stream.parse_filter_string("peer 11666 and prefix more 210.180.0.0/16") + # or using the old filter interface: + # stream.add_filter("peer-asn", "11666") + # stream.add_filter("prefix-more", "210.180.0.0/16") + + # read elems + for elem in stream: + # record fields can be accessed directly from elem + # e.g. elem.time + # or via elem.record + # e.g. elem.record.time + print(elem) + + # alternatively, records and elems can be read in nested loops: + for rec in stream.records(): + # do something with rec (e.g., choose to continue based on timestamp) + print("Received %s record at time %d from collector %s" % (rec.type, rec.time, rec.collector)) + for elem in rec: + # do something with rec and/or elem + print(" Elem Type: %s" % elem.type) + + +BGPStream +--------- + +.. py:class:: BGPStream + + The BGP Stream class provides a single stream of BGP Records. + + + + .. py:attribute:: from_time + + Specify the beginning time of the stream. + The time string is parsed using `dateutil.parser.parse` function. + + .. py:attribute:: until_time + + Specify the ending time of the stream + The time string is parsed using `dateutil.parser.parse` function. + + .. py:attribute:: data_interface + + Specify the `data_interface` BGPStream should use for retrieving and processing data. + + .. py:attribute:: project + + Name of the project to retrive the data from. + + .. py:attribute:: projects + + Name of the projects to retrive the data from. + + .. py:attribute:: collector + + Name of the collector to retrive the data from. + + .. py:attribute:: collectors + + Name of the collectors to retrive the data from. + + .. py:attribute:: record_type + + Specify type of the record type to process: `update`, or `rib`. + + .. py:attribute:: recode_types + + Specify type of the record types to process: `update`, or `rib`. + + .. py:attribute:: filter + + The filter string. + + .. py:method:: records() + + Returns a stream of Record objects. + +BGPRecord +--------- + +.. py:class:: BGPRecord + + The BGPRecord is a wrapper around low-level `_pybgpstream.BGPRecord`. + + All attributes are read-only. + + .. py:attribute:: rec + + The corresponding `_pybgpstream.BGPRecord`. + + .. py:method:: __str__(self) + + .. code-block:: python + :linenos: + + return "%s|%s|%f|%s|%s|%s|%s|%s|%d" % (self.type, self.dump_position, self.time, + self.project, self.collector, self.router, self.router_ip, + self.status, self.dump_time) + + + +BGPElem +--------- + +.. py:class:: BGPElem + + + The BGPElem is a wrapper around low-level `_pybgpstream.BGPElem`. + + All attributes are read-only. + + .. py:attribute:: record + + The BGPRecord that contains the current BGPElem. + + .. py:method:: __str__(self) + + .. code-block:: python + :linenos: + + return "%s|%s|%f|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s|%s" % ( + self.record_type, + self.type, + self.time, + self.project, + self.collector, + self.router, + self.router_ip, + self.peer_asn, + self.peer_address, + self._maybe_field("prefix"), + self._maybe_field("next-hop"), + self._maybe_field("as-path"), + " ".join(self.fields["communities"]) if "communities" in self.fields else None, + self._maybe_field("old-state"), + self._maybe_field("new-state") + ) diff --git a/docs/conf.py b/docs/conf.py index 0888e7a..e1c1b99 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,6 +20,7 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../src')) +sys.path.insert(0, os.path.abspath('../pybgpstream')) # -- General configuration ------------------------------------------------ @@ -33,7 +34,6 @@ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', - 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. @@ -167,7 +167,7 @@ #html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +html_show_sourcelink = False # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True diff --git a/docs/index.rst b/docs/index.rst index 9780d90..56bcf76 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,3 +7,6 @@ Contents: :maxdepth: 1 api__pybgpstream + api_pybgpstream + +.. automodule:: pybgpstream From 9e6b1212517449cc2f0078c8d0e668efb94c923f Mon Sep 17 00:00:00 2001 From: Mingwei Zhang Date: Fri, 25 Oct 2019 13:45:04 -0700 Subject: [PATCH 2/3] undo unnecessary changes --- docs/conf.py | 4 ++-- docs/index.rst | 4 +--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e1c1b99..da09945 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,6 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../src')) -sys.path.insert(0, os.path.abspath('../pybgpstream')) # -- General configuration ------------------------------------------------ @@ -34,6 +33,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', + 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. @@ -167,7 +167,7 @@ #html_split_index = False # If true, links to the reST sources are added to the pages. -html_show_sourcelink = False +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True diff --git a/docs/index.rst b/docs/index.rst index 56bcf76..4a7a22b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,4 @@ Contents: :maxdepth: 1 api__pybgpstream - api_pybgpstream - -.. automodule:: pybgpstream + api_pybgpstream \ No newline at end of file From 4b5852d8ac34d63f296423a3a426dca2e29d95fe Mon Sep 17 00:00:00 2001 From: Mingwei Zhang Date: Fri, 25 Oct 2019 13:45:50 -0700 Subject: [PATCH 3/3] revert one more change --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index da09945..0888e7a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -167,7 +167,7 @@ #html_split_index = False # If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True +#html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True