24.10.1 released

docs/source/conf.py

@@ -1,7 +1,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.relpath('../'))
-
+from pysros import __version__
 
 # -- Project information -----------------------------------------------------
 
@@ -10,9 +10,14 @@
 author = 'Nokia'
 
 # The full version, including alpha/beta/rc tags
-version = '24.7.1'
-release = '24.7.1'
-
+version = __version__
+release = __version__ 
+
+rst_epilog = """
+.. |pySROSProjectVersion| replace:: {versionnum}
+""".format(
+versionnum = version,
+)
 
 # -- General configuration ---------------------------------------------------
 

docs/source/ehs.rst

@@ -138,14 +138,13 @@ the event handling system (EHS).
       .. Reviewed by PLM 20220118
       .. Reviewed by TechComms 20220124
 
-.. class:: EventParams
+.. class:: pysros.ehs.EventParams
 
    The additional parameters of the specific :py:class:`pysros.ehs.Event`.
    This class is *read-only*.  Specific additional parameters may be
    accessed using standard Python subscript syntax.
 
-   .. Reviewed by PLM 20220118
-   .. Reviewed by TechComms 20220124
+   .. Reviewed by PLM 20240828
 
    .. py:method:: keys
 

docs/source/esm.rst

@@ -0,0 +1,59 @@
+
+The :mod:`pysros.esm` module provides functionality obtain data from the
+specific event that triggered the execution of a Python application from
+the SR OS subscriber management system.
+
+.. Reviewed by PLM 20240828
+
+.. note:: This module is available when executing on SR OS only. On a remote
+          machine, subscriber management functionality is not supported.
+
+.. Reviewed by PLM 20240828
+
+.. py:function:: pysros.esm.get_event
+
+   The subscriber management event that triggered the execution of the Python application.
+
+   :return: The Event object or None.
+   :rtype: :py:class:`pysros.esm.Event` or ``None``
+
+   .. Reviewed by PLM 20240828
+
+.. class:: pysros.esm.Event
+
+   The ESM :py:class:`pysros.esm.Event` Class for the event that triggered the execution of the
+   Python application.
+
+   .. py:attribute:: eventparameters
+
+      The additional parameters specific to the event that caused the
+      Python application to execute.
+
+      :type: :py:class:`pysros.ehs.EventParams`
+
+      .. Reviewed by PLM 20240828
+
+.. class:: pysros.esm.EventParams
+
+   The additional parameters of the specific :py:class:`pysros.esm.Event`.
+   This class is *read-only*.  Specific additional parameters may be
+   accessed using standard Python subscript syntax.
+
+   .. Reviewed by PLM 20240828
+
+   .. py:method:: keys
+
+      Obtain the additional parameters names.
+
+      :return: Additional parameters names for the Event.
+      :rtype: tuple(str)
+
+      .. Reviewed by PLM 20240828
+
+   .. describe:: params[key]
+
+      Return the value of the parameter *key*. If the parameter does not exist,
+      a :exc:`KeyError` is raised.
+
+      .. Reviewed by PLM 20240828
+

docs/source/features/22.10.rst

@@ -1,6 +1,18 @@
 Release 22.10
 *************
 
+22.10.9
+#######
+
+* No additional features
+
+.. Reviewed by PLM 20240627
+
+22.10.8
+#######
+
+* No additional features
+
 22.10.7
 #######
 
@@ -44,7 +56,7 @@ Release 22.10
 #######
 
 * :py:meth:`pysros.management.Connection.convert` method adds support for the
-  conversion of the input/output data of YANG modeled operations (actions).
+  conversion of the input/output data of YANG-modeled operations (actions).
 
 
 
@@ -53,7 +65,7 @@ Release 22.10
 
 * :py:meth:`pysros.management.Datastore.compare` method provides the ability to compare the
   uncommitted candidate configuration with the baseline configuration prior to a commit.
-* :py:meth:`pysros.management.Connection.action` method provides the ability to execute a YANG modeled
+* :py:meth:`pysros.management.Connection.action` method provides the ability to execute a YANG-modeled
   action (operation) on SR OS using modeled, structured data as both input and output.
 * Updates to the :py:class:`pysros.wrappers.Schema` and :py:class:`pysros.wrappers.SchemaType`
   to include additional YANG schema information,

docs/source/features/23.10.rst

@@ -1,6 +1,14 @@
 Release 23.10
 *************
 
+23.10.6
+#######
+
+* No additional features
+
+.. Reviewed by PLM 20240718
+.. Reviewed by TechComms 20240718
+
 23.10.5
 #######
 

docs/source/features/24.07.rst

@@ -1,6 +1,14 @@
 Release 24.7
 ************
 
+24.7.2
+######
+
+* No additional features
+
+.. Reviewed by PLM 20240814
+
+
 24.7.1
 ######
 

docs/source/features/24.10.rst

@@ -0,0 +1,21 @@
+Release 24.10
+*************
+
+24.10.1
+#######
+
+* Provides the :py:meth:`.Connection.list_paths` method to describe supported JSON instance
+  paths for the given :py:class:`.Connection` object.  Returns an iterator that can be used
+  to analyze or print the supported paths.
+* Provides :py:mod:`pysros` support from remote servers for alternative operating systems 
+  using standards-based NETCONF implementations, specifically, SR Linux.
+* Introduces the :py:mod:`pysros.esm` module to provide integration with Enhanced Subscriber
+  Management (ESM) of SR OS.  This module is available on SR OS only.  It is not supported
+  on a remote machine.
+
+  * Provides the :py:meth:`pysros.esm.get_event` method to obtain the data provided from the ESM
+    system that called the Python application.
+
+.. Reviewed by PLM 20240828
+.. Reviewed by TechComms 20240927
+

docs/source/index.rst

@@ -17,12 +17,11 @@ documentation will be updated accordingly.
 .. list-table::
    :header-rows: 0
 
-   * - pySROS release: 24.7.1
-   * - Document Number: 3HE 20087 AAAD TQZZA 
-
-.. Reviewed by PLM 20240506
-.. Reviewed by TechComms 20240529
+   * - pySROS release: |pySROSProjectVersion|
+   * - Document Number: 3HE 20087 AAAF TQZZA
 
+.. Reviewed by PLM 20240926
+.. Reviewed by TechComms 20240927
 
 
 .. toctree::

docs/source/introduction.rst

@@ -51,8 +51,13 @@ To use the pySROS libraries, the following pre-requisites must be met:
 All the required software is included and installed automatically on the SR OS node, including
 the Python 3 interpreter and all supported Python libraries.
 
-.. Reviewed by PLM 20210902
-.. Reviewed by TechComms 20210902
+The pySROS libraries have been tested to work with other Network Operating Systems (NOS) using
+standards-based NETCONF implementations, specifically, SR Linux.  When using alternative Network
+Operating Systems, the use of the :py:meth:`pysros.management.Datastore.lock` and 
+:py:meth:`pysros.management.Datastore.unlock` methods is strongly encouraged.
+
+.. Reviewed by PLM 20240926
+.. Reviewed by TechComms 20240927
 
 
 YANG modeling
@@ -126,6 +131,10 @@ See the following for examples:
    /openconfig-interfaces:interfaces/interface[name="1/1/c2/1"]/subinterfaces/subinterface[index=0]/openconfig-if-ip:ipv4/addresses
 
 
+Once a connection to the pySROS interface on the node has been established (see :ref:`making-a-connection`) the 
+:py:meth:`.Connection.list_paths` method can used to obtain a list of the supported YANG-modeled paths for that specific
+router in the JSON instance path format.
+
 .. Reviewed by PLM 20220901
 .. Reviewed by TechComms 20221012
 
@@ -555,6 +564,9 @@ See the :py:class:`pysros.wrappers.Annotations` class for more details.
 Getting Started
 ###############
 
+
+.. _making-a-connection:
+
 Making a connection
 *******************
 
@@ -601,6 +613,7 @@ Example:
 .. Reviewed by TechComms 20221012
 
 
+
 Obtaining data
 **************
 
@@ -724,12 +737,12 @@ Performing operations
 
 An operation refers to the execution of an activity on the SR OS node that is not that of
 obtaining data or configuring the device.  The method of performing operations on the SR OS
-node through the pySROS libraries is using YANG modeled actions.
+node through the pySROS libraries is using YANG-modeled actions.
 
-This approach allows for YANG modeled and structured data to be used on both input and
+This approach allows for YANG-modeled and structured data to be used on both input and
 output.  Both input and output are represented as pySROS data structures.
 
-To execute a YANG modeled operation, the :py:meth:`pysros.management.Connection.action`
+To execute a YANG-modeled operation, the :py:meth:`pysros.management.Connection.action`
 method should be used.
 
 The :py:meth:`pysros.management.Connection.action` method uses the YANG schema obtained as
@@ -779,7 +792,7 @@ If the ``do-something`` action was called with the input variables ``myinput-str
 look like this:
 
 .. code-block:: python
-   :caption: Example calling a YANG modeled action (operation)
+   :caption: Example calling a YANG-modeled action (operation)
    :name: calling-yang-action-example
 
    >>> from pysros.management import connect

docs/source/pysros.rst

@@ -57,6 +57,14 @@
 
 .. include:: ehs.rst
 
+:mod:`pysros.esm` - Functions for the enhanced subscriber management system (ESM)
+---------------------------------------------------------------------------------
+
+.. module:: pysros.esm
+   :synopsis: Functions for the SR OS enhanced subscriber management system (ESM)
+
+.. include:: esm.rst
+
 :mod:`pysros.syslog` - Functions for syslog event handling
 ----------------------------------------------------------
 

examples/convert_example.py

@@ -195,7 +195,7 @@ def converting(input_format, output_format, data, connection_object):
     """
     print("-" * 79)
     print("Converting", input_format, "to", output_format, "\n")
-    print("The path used as the YANG modeled root for the data is:")
+    print("The path used as the YANG-modeled root for the data is:")
     print(data.path, "\n")
     print("The payload is:")
     print(data.payload, "\n")

examples/show_router_bgp_asn.py

@@ -7,7 +7,7 @@
 # pylint: disable=import-error, import-outside-toplevel, line-too-long, too-many-branches, too-many-locals, too-many-statements
 
 """
-Tested on: SR OS 24.3.R1
+Tested on: SR OS 24.3.R2
 
 Show all BGP peers for an ASN.
 
@@ -221,6 +221,8 @@ def show_router_bgp_asn_output(connection_object, asn):
     num_down_neighbors = 0
     num_disabled_neighbors = 0
     for neighbor in sorted(bgp_config):
+        num_families = 0
+
         if asn == 0 or int(asn) == bgp_config[neighbor]["peer-as"].data:
             # Print line 1
             print(bright_cyan, end="")
@@ -270,7 +272,6 @@ def show_router_bgp_asn_output(connection_object, asn):
                 == "Established"
             ):
                 num_up_neighbors += 1
-                num_families = 0
                 for family in sorted(
                     bgp_stats[neighbor]["statistics"]["negotiated-family"]
                 ):

pysros/__init__.py

@@ -3,3 +3,5 @@
 __all__ = ("management", "exceptions", "wrappers", "pprint", )
 
 __doc__ = """Library for management of Nokia SR OS nodes."""
+
+__version__ = "24.10.1"

pysros/errors.py

@@ -3,7 +3,7 @@
 from .exceptions import (ActionTerminatedIncompleteError, InternalError,
                          InvalidPathError, JsonDecodeError,
                          ModelProcessingError, SrosConfigConflictError,
-                         SrosMgmtError, XmlDecodeError, make_exception)
+                         SrosMgmtError, XmlDecodeError, NotSupportedNodeMethodError, make_exception)
 
 __doc__ = """This module contains error definitions for pySROS.
 
@@ -22,7 +22,7 @@
 pysros_err_can_not_find_yang = (ModelProcessingError, "Cannot find yang '{yang_name}'")
 pysros_err_cannot_call_go_to_parent = (InvalidPathError, "Cannot call go_to_parent on root")
 pysros_err_cannot_delete_from_state = (SrosMgmtError, "Cannot delete from state tree")
-pysros_err_cannot_lock_and_unlock_running = (SrosMgmtError, "Cannot lock and unlock running or intended config")
+pysros_err_cannot_lock_and_unlock_readonly_ds = (SrosMgmtError, "Cannot lock and unlock read-only datastore")
 pysros_err_cannot_modify_config = (SrosMgmtError, "Cannot modify running or intended config")
 pysros_err_cannot_modify_state = (SrosMgmtError, "Cannot modify state tree")
 pysros_err_cannot_pars_path = (ModelProcessingError, "Cannot parse path {path!r}")
@@ -44,6 +44,7 @@
 pysros_err_filter_not_supported_on_leaves = (InvalidPathError, "Filter is not supported for leaves")
 pysros_err_filter_should_be_dict = (TypeError, "Filter argument should be a dict")
 pysros_err_filter_wrong_leaf_value = (TypeError, "Unsupported leaf filter for '{leaf_name}'")
+pysros_err_invalid_parse_error = (InvalidPathError, "Invalid character while parsing string")
 pysros_err_incorrect_leaf_value = (SrosMgmtError, "Invalid value for leaf {leaf_name}")
 pysros_err_invalid_align = (ValueError, "Invalid align: '{align}'")
 pysros_err_invalid_col_description = (TypeError, "Invalid column description")
@@ -55,6 +56,7 @@
 pysros_err_invalid_module_set_id_or_content_id = (RuntimeError, "Invalid module-set-id")
 pysros_err_invalid_operation_on_key = (InvalidPathError, "Operation cannot be performed on key")
 pysros_err_invalid_operation_on_leaflist = (InvalidPathError, "Operation cannot be performed on leaflist")
+pysros_err_invalid_path_error = (InvalidPathError, "Path does not exist in schema")
 pysros_err_invalid_path_operation_missing_keys = (InvalidPathError, "Cannot perform operation on list without specifying keys")
 pysros_err_invalid_rd_state = (InternalError, "Invalid database state")
 pysros_err_invalid_target = (ValueError, "Invalid target")
@@ -73,7 +75,7 @@
 pysros_err_no_data_found = (LookupError, "No data found")
 pysros_err_not_connected = (RuntimeError, "Not connected")
 pysros_err_not_found_slash_before_name = (InvalidPathError, "'/' not found before element name")
-pysros_err_path_should_be_string = (TypeError, "path argument should be a string")
+pysros_err_path_should_be_string = (TypeError, "Path argument should be a string")
 pysros_err_prefix_does_not_have_ns = (LookupError, "prefix '{prefix}' of '{name}' does not have corresponding namespace")
 pysros_err_root_path = (InvalidPathError, "Operation cannot be performed on root")
 pysros_err_target_should_be_list = (InvalidPathError, "Target should be a list")
@@ -121,3 +123,5 @@
 pysros_err_too_many_leaflist_annotations = (SrosMgmtError, "Too many annotations in leaflist")
 pysros_err_expected_type_but_got_another = (TypeError, "expected {expected} object but got {type_name}")
 pysros_err_annotation_invalid_module = (SrosMgmtError, "Invalid annotation module")
+pysros_err_ambiguous_model_node = (SrosMgmtError, "Ambiguous model node")
+pysros_err_unsupported_node_method = (NotSupportedNodeMethodError, "Method not supported by the node")

pysros/exceptions.py

@@ -98,6 +98,10 @@ class XmlDecodeError(Exception):
     pass
 
 
+class NotSupportedNodeMethodError(Exception):
+    """Exception raised when method which is not supported by box is called."""
+
+
 def make_exception(arg, **kwarg):
     """Create an exception.