Python ONAP SDK

an SDK to use ONAP programmatically with Python code

Description

ONAP SDK is a client library written in Python for building applications to work with ONAP. The project aims to provide a consistent and complete set of interactions with ONAP’s many services, along with complete documentation, examples, and tools.

Using few python commands, you should be able to onboard, distribute models, instantiate xNFs and many others. Check doc site to find out all the features.

Installation

You can install it using pip tool

$ pip install onapsdk

Development

Before you start, ensure you have Python installation in version 3.11 or higher. Please see the official Python documentation in case you have to upgrade or install certain Python version.

Setting up development environment

Clone the project. Inside the project folder create a new virtual environment and activate it:

$ python -m venv env
$ source env/bin/activate

On Windows, activate by executing the following:

$ .\env\Scripts\activate

When your virtual environment is ready, install required dependencies:

$ pip install -r requirements.txt

Developing

To use library functions directly from the source code, execute the following to point to the source folder in PYTHONPATH variable and run the interpreter:

$ PYTHONPATH=$PYTHONPATH:src/ python

On Windows:

$ $env:PYTHONPATH='src\';python

Verify that packages are accessible:

>>> import onapsdk

You can then start working with library functions as needed.

Testing

Install tox:

$ pip install tox

To run all unit test, lint and docstyle checks, inside the project folder simply execute tox:

$ tox

Please note that the above runs the unit tests with Python 3.11. To run them with another interpreter installed on your OS, name it explicitly, for example:

$ tox -e py312

Integration testing

It is possible to run integration tests using mock-servers project. Make sure Docker Compose is available on your system. Install required dependencies:

$ pip install pytest mock

Go to integration_tests/ directory and execute:

$ docker-compose up

Please note that docker-compose attempts to create subnet 172.20.0.0/24, so it can not be run if the scope is already allocated. Also, containers are not reachable by their IP addresses on Windows host since Docker for Windows does not support bridged network interface for Linux containers.

Once containers are running, execute the following in the project's directory:

$ PYTHONPATH=$PYTHONPATH:integration_tests/:src/ ONAP_PYTHON_SDK_SETTINGS="local_urls" pytest -c /dev/null --verbose --junitxml=pytest-integration.xml integration_tests

Please make sure all the test are passing before creating merge request.

Snapshots

Every merge to master publishes a snapshot to TestPyPI. Its version carries a PEP 440 development suffix taken from the Jenkins build number, for example 14.6.0.dev123, so that every merge gets a version of its own — a Python package index rejects a re-upload of a version it already holds. To install the latest snapshot:

$ pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ onapsdk

The extra index is needed because the dependencies are resolved from PyPI. A development version is a pre-release, so a plain pip install onapsdk never resolves to a snapshot.

Releasing

The release job does not build anything: it downloads one exact version from TestPyPI and re-uploads it to PyPI. That version must therefore be staged without a development suffix first, which the merge job no longer does. To cut a release:

1. Bump __version__ in src/onapsdk/version.py along with the value expected in tests/test_version.py, describe the release in CHANGELOG.md, and merge that.
2. Comment stage-release on any open change of this project. That triggers integration-python-onapsdk-pypi-stage-master, which builds the tip of master with the clean version and uploads it to TestPyPI.
3. Add releases/pypi-<version>-onapsdk.yaml with log_dir set to the stage build that uploaded it, for example integration-python-onapsdk-pypi-stage-master/12/. Merging that file triggers the release job, which publishes to PyPI and tags the repository.

Python ONAP SDK Changelog

v14.7.0

Fixed

• OnapService.send_message no longer logs credentials. It logged the request headers, including authorization, at DEBUG on every call and again at ERROR on every HTTP error. Sensitive headers (authorization, proxy-authorization, cookie, x-auth-token) are now masked in the debug log and in set_header, and the error log reports the HTTP error instead of the headers.

Changed

• The package now requires Python 3.11 or newer (python_requires = >=3.11). CI runs the unit tests on 3.11; 3.8 and 3.9, the only versions tested so far, are end-of-life. pip on an older interpreter keeps resolving onapsdk 14.6.0.

v14.6.0

There is no 14.5.0 release. The release pipeline had already staged a 14.5.0 artifact built before any of the changes below, and the index it stages to rejects re-uploads of a version that exists, so the version was skipped.

Added

• Acm class for the CLAMP automation composition management runtime API (commission, prime, instantiate, deploy and the matching teardown calls).
• Policy.get_policy_status for the PAP policy deployment status endpoint.
• CLAMP_ACM_URL setting pointing at the in-cluster runtime-acm service.

Changed

• Merge builds now publish their snapshot under a PEP 440 development version derived from the Jenkins build number, for example 14.6.0.dev123, so a merge no longer fails once a version has been staged. Cutting a release now needs the clean version staged with a stage-release comment first, because the release job downloads that exact version rather than building it; see the README.
• Every function and method in the package now carries a return annotation, so type checkers no longer skip their bodies. This is an annotation-only change with one exception: OnapService.get_guis is declared as returning GuiList, the type all of its overrides already returned.

Fixed

• DeletionRequest.send_request and its VfModuleDeletionRequest and NetworkDeletionRequest overrides declared return types that were wrong: Deletion and VfModuleDeletion do not exist at all, and the network variant claimed VnfDeletionRequest. Each now names the class it actually returns. Type hints only; the objects returned are unchanged.
• 48 docstrings documented a parameter or return type that disagreed with the annotation, including [type] placeholders on the six update_informations_from_sdc* methods and platform/project in onapsdk.so.instantiation, which take a name string rather than the Platform/Project object the docstrings named.
• onapsdk.so.instantiation could not be imported before another onapsdk module: an import cycle through the eager re-exports in onapsdk.aai.business raised ImportError. The A&AI business re-exports are now resolved lazily; the package exposes the same names as before.

v14.4.0

Added

• add opentelemetry @tracer decorator to Service.distributions method

Removed

• remove dependency on cryptography and pyOpenSSL since they are not actually used in the project

v1.0

Documentation

Main new features:

• Onboard a simple service via SDC
• Instantiate a simple service via SO using GR API
• Instantiate a simple service via NBI
• create business objects in AAI