24.7.1 released

README.md

@@ -28,7 +28,7 @@ In order to use the pySROS library the following pre-requisites must be met:
 
 ## License ##
 
-Copyright 2021-2023 Nokia.
+Copyright 2021-2024 Nokia.
 
 The license is located [here](LICENSE.md).
 

docs/source/conf.py

@@ -10,8 +10,8 @@
 author = 'Nokia'
 
 # The full version, including alpha/beta/rc tags
-version = '24.3.1'
-release = '24.3.1'
+version = '24.7.1'
+release = '24.7.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/examples.rst

@@ -330,10 +330,10 @@ The following is an example of how to use these exceptions to handle specific er
    :caption: make_connection.py
    :name: make-connection-example
    :language: python
-   :emphasize-lines: 16-17, 26-64
+   :emphasize-lines: 15-16, 25-63
 
-.. Reviewed by PLM 20210902
-.. Reviewed by TechComms 20210902
+
+.. Reviewed by PLM 20240522
 
 
 Obtaining data and formatted output
@@ -345,9 +345,39 @@ various formats.
 .. Reviewed by PLM 20210902
 .. Reviewed by TechComms 20210902
 
+Obtaining data from the intended datastore
+******************************************
 
-Show SDP state and descriptions
-*******************************
+The ``intended`` datastore provides a read-only view into the expanded configuration.  On SR OS
+the ``intended`` datastore can be used to deliver a view of the expanded configuration as 
+created by configuration groups.  A configuration group is defined using the
+``/configure groups group <name>`` command and is applied using the ``apply-groups`` command.
+
+The following example creates a configuration group template and an interface.  The group is
+then applied to the interface and the configuration of that interface is obtained from both
+the ``running`` datastore and the ``intended`` datastore to demonstrate the difference:
+
+.. literalinclude:: ../../examples/intended_datastore_get.py
+   :caption: intended_datastore_get.py
+   :name: intended-datastore-get-example
+   :language: python
+   :emphasize-lines: 108-119
+
+The output shows that in the ``running`` configuration you can see the ``apply-groups`` statement that
+applies the template to the interface.  You cannot see the ``ip-mtu`` as this configuration item exists 
+in the template.  When displaying the configuration in the ``intended`` datastore the ``ip-mtu`` can be 
+seen applied to the interface and the ``apply-groups`` statement cannot be seen.  The output looks 
+like this:
+
+.. code-block:: python
+
+   Running: {'interface-name': Leaf('example-pysros'), 'apply-groups': LeafList(['test']), 'description': Leaf('Example interface')}
+   Intended: {'interface-name': Leaf('example-pysros'), 'description': Leaf('Example interface'), 'ip-mtu': Leaf(4444)}
+
+.. Reviewed by PLM 20240506
+
+Creating SR OS style show commands from configuration and state data
+********************************************************************
 
 This examples creates a new show command that displays a list of the SDPs and their ID, description,
 administrative state, operational state, and far-end IP address.
@@ -360,7 +390,7 @@ create SR OS style table output.
    :caption: show_sdp_with_description.py
    :name: show-sdp-with-description-example
    :language: python
-   :emphasize-lines: 12, 52-70, 84-94
+   :emphasize-lines: 15, 52-72, 82-96
 
 The example output for this application is shown here:
 
@@ -476,7 +506,7 @@ instantaneous data available.
    :caption: filesystem_example.py
    :name: filesystem-example
    :language: python
-   :emphasize-lines: 18-60
+   :emphasize-lines: 19-61
 
 The example output of this application is shown below.
 
@@ -502,6 +532,59 @@ The example output of this application is shown below.
 
 .. Reviewed by PLM 20220901
 
+.. _obtaining_user_inputs:
+
+Obtaining user input
+####################
+
+Some activities require the user to provide input into the Python application
+in order to progress.  In its simplest form, this may be confirmed with a yes/no 
+prompt before taking an action.  In other use-cases, the input required might 
+be more extensive.
+
+User input can be obtained in Python in a number of ways.  When a pySROS application
+is executed remotely, the standard Python libraries are available.  When executing
+on an SR OS node, pySROS provides the :py:func:`input` and :py:func:`sys.stdin.readline`
+procedures for obtaining input and the :py:mod:`getpass` module for obtaining password
+information (without displaying it to the screen).
+
+.. note::
+
+   The :py:func:`input` and :py:func:`getpass.getpass` functions are preferred for 
+   user input as they have better performance, particularly when using large inputs.
+
+Each of these methods interacts with the SR OS pager.  If the output delivered by 
+the Python application exceeds the screen length, the pager is activated.  The
+pager obtains the key-presses until the pager session is concluded.  At this point,
+the consumption of the key-presses returns to the Python application.
+
+.. note::
+
+   Caution should be taken when chaining Python applications together with the pipe 
+   modifier.  Only one Python application in this chain should request user input.
+
+This example prompts the user to reset a linecard of their choosing and then confirms
+that they wish to do this (using the :py:func:`input` function) before performing the 
+YANG-modeled operation using the :py:meth:`pysros.management.Connection.action` method.
+
+.. literalinclude:: ../../examples/reset_card.py
+   :caption: reset_card.py
+   :name: example-reset-card
+   :language: python3
+   :emphasize-lines: 24, 26
+
+This next example shows various options for obtaining user input.
+
+.. literalinclude:: ../../examples/user_input_example.py
+   :caption: user_input_example.py
+   :name: example-user-input
+   :language: python3
+
+
+.. Reviewed by PLM 20240612
+.. Reviewed by TechComms 20240612
+
+
 .. _Converting Data Formats:
 
 Converting data formats

docs/source/features/23.10.rst

@@ -1,6 +1,20 @@
 Release 23.10
 *************
 
+23.10.5
+#######
+
+* No additional features
+
+.. Reviewed by PLM 20240520
+
+23.10.4
+#######
+
+* No additional features
+
+.. Reviewed by PLM 20240326
+
 23.10.3
 #######
 
@@ -9,7 +23,6 @@ Release 23.10
 .. Reviewed by PLM 20240124
 .. Reviewed by TechComms 20240125
 
-
 23.10.2
 #######
 

docs/source/features/24.03.rst

@@ -0,0 +1,26 @@
+Release 24.3
+************
+
+24.3.3
+######
+
+* No additional features
+
+.. Reviewed by PLM 20240509
+.. Reviewed by TechComms 20210510
+
+24.3.2
+######
+
+* No additional features
+
+.. Reviewed by PLM 20240403
+.. Reviewed by TechComms 20240403
+
+24.3.1
+######
+
+* No additional features
+
+.. Reviewed by PLM 20240219
+.. Reviewed by TechComms 20240227

docs/source/features/24.07.rst

@@ -0,0 +1,16 @@
+Release 24.7
+************
+
+24.7.1
+######
+
+* Support for the ``intended`` NMDA datastore in :py:class:`pysros.management.Connection`
+* Support for :ref:`obtaining user inputs<obtaining_user_inputs>`
+    * Support for the :py:mod:`getpass` module for user inputs
+    * Support for the :py:func:`sys.stdin.readline` function for user inputs
+    * Support for the :py:func:`input` function for user inputs
+* Provides :py:func:`pysros.management.Connection.session_id` which returns the current
+  connections SR OS / NETCONF session-id
+
+.. Reviewed by PLM 20240523
+.. Reviewed by TechComms 20240529

docs/source/getpass.rst

@@ -0,0 +1,38 @@
+:mod:`getpass` --- Portable password input
+==========================================
+
+.. module:: getpass
+   :synopsis: Portable reading of passwords
+
+.. admonition:: Differences to Python
+   :class: attention
+
+   This module implements a subset of the upstream Python module.
+   For more information, refer to the original documentation: 
+   `getpass <https://docs.python.org/3.9/library/getpass.html>`_.
+
+This module is used when executing on SR OS only.  On a remote machine, the
+native Python `getpass <https://docs.python.org/3.9/library/getpass.html>`_ 
+module is used.
+
+The :mod:`getpass` module provides functions for user inputs of passwords
+without returning the characters to the screen.
+
+.. Reviewed by PLM 20240523
+.. Reviewed by TechComms 20240529
+
+Functions
+---------
+
+.. function:: getpass(prompt='Password: ')
+
+   Prompt the user for a password without echoing.  The user is prompted using
+   the string *prompt*, which defaults to ``'Password: '``.
+
+   :param prompt: Optional string prompt to provide the user guidance.
+   :type prompt: str, optional
+   :return: The inputted value
+   :rtype: str
+
+.. Reviewed by PLM 20240612
+.. Reviewed by TechComms 20240612

docs/source/index.rst

@@ -17,11 +17,13 @@ documentation will be updated accordingly.
 .. list-table::
    :header-rows: 0
 
-   * - pySROS release: 24.3.1
-   * - Document Number: 3HE 20087 AAAA TQZZA
+   * - pySROS release: 24.7.1
+   * - Document Number: 3HE 20087 AAAD TQZZA 
+
+.. Reviewed by PLM 20240506
+.. Reviewed by TechComms 20240529
+
 
-.. Reviewed by PLM 20240219
-.. Reviewed by TechComms 20240227
 
 .. toctree::
    :maxdepth: 2

docs/source/introduction.rst

@@ -607,7 +607,7 @@ Obtaining data
 Use the :py:meth:`pysros.management.Datastore.get` method to obtain model-driven data from an SR OS device.  
 This method takes a single JSON instance path (see the :ref:`modeled-paths` section) and returns a data structure.
 
-The :py:meth:`pysros.management.Datastore.get` method can be performed against the ``running`` or the ``candidate`` datastore
+The :py:meth:`pysros.management.Datastore.get` method can be performed against the ``running``, ``intended`` or ``candidate`` datastores
 when *configuration* data is required.  When *state* data is required, it can only be performed against the
 ``running`` datastore.
 
@@ -619,7 +619,7 @@ when *configuration* data is required.  When *state* data is required, it can on
 Example:
 
 .. code-block:: python
-   :caption: Get example using :py:meth:`pysros.management.Datastore.get`
+   :caption: Get example using :py:meth:`pysros.management.Datastore.get` from the ``running`` datastore
    :name: get-example
 
    >>> from pysros.management import connect
@@ -633,10 +633,7 @@ Example:
               'add-paths': Container({'ipv4': Container({'receive': Leaf(True), 'send': Leaf('multipaths')})}),
               'admin-state': Leaf('enable')})}, 'admin-state': Leaf('enable')})
 
-
-.. Reviewed by PLM 20210902
-.. Reviewed by TechComms 20210902
-
+.. Reviewed by PLM 20240506
 
 Configuring SR OS routers
 *************************

docs/source/modules.rst

@@ -23,6 +23,7 @@ Python versions of the library are used.
    uio
    uos
    uos.path
+   getpass
 
 .. Reviewed by PLM 20220628
 .. Reviewed by TechComms 20220706

examples/convert_example.py

@@ -12,12 +12,12 @@
 # Import sys library
 import sys
 
-# Import the connect method from the management pySROS sub-module
-from pysros.management import connect
-
 # Import the exceptions that are referenced so they can be caught on error.
 from pysros.exceptions import ModelProcessingError
 
+# Import the connect method from the management pySROS sub-module
+from pysros.management import connect
+
 
 class Data:  # pylint: disable=too-few-public-methods
     """Create an object containing the input data in the required format

examples/filesystem_example.py

@@ -12,6 +12,7 @@
 # pylint: disable=broad-except, eval-used, unspecified-encoding
 
 import sys
+
 from pysros.management import connect, sros
 
 

examples/get_all_router_and_vprn.py

@@ -6,10 +6,10 @@
 
 """Example to get all routers and VPRNs"""
 
-
 import sys
-from pysros.management import connect
+
 from pysros.exceptions import ModelProcessingError
+from pysros.management import connect
 from pysros.pprint import Table  # pylint: disable=no-name-in-module
 
 credentials = {

examples/get_all_vprn_routes_with_nexthop_ipv4_address.py

@@ -6,10 +6,11 @@
 
 """Example to get all VPRN routes with a given next-hop IP address"""
 
-import sys
 import ipaddress
-from pysros.management import connect
+import sys
+
 from pysros.exceptions import ModelProcessingError
+from pysros.management import connect
 from pysros.pprint import Table  # pylint: disable=no-name-in-module
 
 credentials = {