11. Package Manager API

Module: typhoon.api.package_manager

Package Manager API contains a set of functions/methods to manipulate Typhoon packages, install new ones programmatically and uninstall/reinstall existing ones. This is most commonly used for creating scripts for testing and automating repetitive tasks, but its use is not restricted for these use cases only.

11.1. Examples

Following example illustrates how you can use Package Manager API.

11.1.1. Example

This example illustrates how to install a package from a disk, list all the installed packages, and at the end, uninstall them.

import os
sys.path.insert(0, os.path.split(os.path.abspath(os.path.join(os.path.realpath(__file__), '..','..', '..','..')))[0])
#
# Demonstrates the use of install, get_installed and uninstall functions
#
from typhoon.api.package_manager import package_manager as pkm

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
pkm.install_package(filename=package_path)

# Get all installed packages, and print them
all_packages = pkm.get_installed_packages()
print(f"All installed packages: {all_packages}")

# Cleanup
for package in all_packages:
    pkm.uninstall_package(package_name=package.package_name)

Script output:

All installed packages: [Package('Example Package', '1.0.1')]

11.2. API references

class PackageManagerAPI(*args, **kwargs)

Class provides methods to manipulate user packages.

create_example(title, model_file, panel_file, output_path, tags=None, description='', image_file='', app_note_file='', tests=None, test_resources=None, resources=None)

Create an example with given parameters and save it at output_path

Parameters
  • title – Example title

  • model_file – Path to model file

  • panel_file – Path to panel file

  • output_path – Path where example will be saved

  • tags – List of string tags

  • description – Example description

  • image_file – Path to image file

  • app_note_file – Path to application note document

  • tests – List of files representing tests

  • test_resources – List of files representing resources used in tests

  • resources – List of files representing resources

Raises

PkmApiException

Example:

#
# Demonstrates the use of get_installed_packages function
#
from typhoon.api.package_manager import package_manager as pkm
import os
import shutil

directory, __ = os.path.split(os.path.realpath(__file__))
root_folder = os.path.join(directory, "example_data")

title = "Example 3ph rectifier"
model_file = os.path.join(root_folder, "rectifier.tse")
panel_file = os.path.join(root_folder, "rectifier.cus")
output_path = os.path.join(root_folder, "output")
tags = ["rectifier", "example"]
description = "This example demonstrates a three-phase diode rectifier connected to the grid."
image_file = os.path.join(root_folder, "rectifier.svg")
app_note_file = os.path.join(root_folder, "rectifier.html")
tests = [os.path.join(root_folder, "example_tests")]
test_resources = []
resources = [os.path.join(root_folder, "data.json")]

try:
    example_path = pkm.create_example(
        title=title, model_file=model_file, panel_file=panel_file,
        output_path=output_path, tags=tags, description=description,
        image_file=image_file, app_note_file=app_note_file, tests=tests,
        test_resources=test_resources, resources=resources)
    print(f"1) Example successfully created at: "
          f"{os.path.relpath(example_path, root_folder)}")

except Exception as e:
    print(f"Exception occurred: {e}")
finally:
    print("2) Removing created example")
    if os.path.exists(output_path):
        shutil.rmtree(output_path)

Output

1) Example successfully created at: output\example 3ph rectifier
2) Removing created example
create_package(package_name, version, output_path, author='', description='', minimal_sw_version='', library_paths=None, resource_paths=None, example_paths=None, additional_files_paths=None, python_packages_paths=None, documentation_paths=None, documentation_landing_page='', release_notes_path='')

Create a package with given parameters and save it at output_path

Parameters
  • package_name – Package name

  • version – Package version

  • output_path – Path where package will be saved. If a directory path is passed, the package will be named “package_name - version.tpkg”. If a file path is passed, it must have a .tpkg extension.

  • author – Package author

  • description – Package description

  • minimal_sw_version – Minimal version of software in which package is supported

  • library_paths – List of paths representing libraries (directories/files)

  • resource_paths – List of paths representing library resources (directories/files)

  • example_paths – List of paths representing example directories

  • additional_files_paths – List of paths representing additional files (directories/files)

  • python_packages_paths – List of paths representing python packages (directories/files)

  • documentation_paths – List of paths representing package documentation (directories/files)

  • documentation_landing_page – Documentation landing page (must be included in documentation_paths)

  • release_notes_path – Path to release notes file (html, pdf..)

Raises

PkmApiException

Example:

#
# Demonstrates the use of get_installed_packages function
#
from typhoon.api.package_manager import package_manager as pkm
import os
import shutil

directory, __ = os.path.split(os.path.realpath(__file__))
root_folder = os.path.join(directory, "package_data")

package_name = "An example package"
version = "1.0.5"
author = "Typhoon HIL"
description = "An example package demonstrating API functionality."
library_paths = [os.path.join(root_folder, "libs")]
resource_paths = []
example_paths = [os.path.join(root_folder, "examples")]
additional_files_paths = [os.path.join(root_folder, "additional.txt")]
documentation_paths = [
    os.path.join(root_folder, "documentation")
]
documentation_landing_page = os.path.join(root_folder, "documentation",
                                          "index.html")
release_notes_path = os.path.join(root_folder, "release_notes.html")

python_packages_paths = []

output_path = os.path.join(root_folder, "output")

try:
    package_path = pkm.create_package(
        package_name=package_name, version=version, output_path=output_path,
        author=author, description=description, library_paths=library_paths,
        resource_paths=resource_paths, example_paths=example_paths,
        additional_files_paths=additional_files_paths,
        python_packages_paths=python_packages_paths,
        documentation_paths=documentation_paths,
        documentation_landing_page=documentation_landing_page,
        release_notes_path=release_notes_path)

    print(f"1) Package successfully created at: "
          f"{os.path.relpath(package_path, root_folder)}")

    print("2) Installing created package")
    pkm.install_package(filename=package_path)
    print("3) Successfully installed package")

    # Get all installed packages, and print them
    all_packages = pkm.get_installed_packages()
    print(f"4) All installed packages: {all_packages}")

    # Cleanup
    print("5) Uninstalling packages")
    for package in all_packages:
        pkm.uninstall_package(package_name=package.package_name)

except Exception as e:
    print(f"Exception occurred: {e}")
finally:
    print("6) Removing created package")
    if os.path.exists(output_path):
        shutil.rmtree(output_path)

Output

1) Package successfully created at: output\an example package.tpkg
2) Installing created package
3) Successfully installed package
4) All installed packages: [Package('An example package', '1.0.5')]
5) Uninstalling packages
6) Removing created package
get_installed_packages()

Returns iterable over installed packages.

Returns

Iterable over installed packages (Package).

Example:

#
# Demonstrates the use of the get_installed_packages function
#
from typhoon.api.package_manager import package_manager as pkm

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
pkm.install_package(filename=package_path)

# Get all installed packages
all_packages = pkm.get_installed_packages()
print(f"All installed packages: {all_packages}")

# Cleanup
all_packages = pkm.get_installed_packages()
for package in all_packages:
    pkm.uninstall_package(package_name=package.package_name)

Output

All installed packages: [Package('Example Package', '1.0.1')]
get_modified_packages()

Checks integrity of installed packages. Returns iterable over packages that have been modified.

Returns

Iterable over modified packages (Package).

Example:

#
# Demonstrates the use of get_modified_packages function
#
from typhoon.api.package_manager import package_manager as pkm
from typhoon.env_api import env_api
import shutil

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
pkm.install_package(filename=package_path)

# Validate no packages are modified prior to modification
print(f"Modified packages before modification: {pkm.get_modified_packages()}")

# Modify installed package
package_examples_path = env_api.get_pkm_examples_path()
shutil.rmtree(os.path.join(package_examples_path, "Example Package", "models", "Complex system"))

# Find modified packages after modification
print(f"Modified packages after modification: {pkm.get_modified_packages()}")

# Cleanup
all_packages = pkm.get_installed_packages()
for package in all_packages:
    pkm.uninstall_package(package_name=package.package_name)

Output

Traceback (most recent call last):
  File "package_manager_api_examples/get_modified_packages.example", line 6, in <module>
    from typhoon.env_api import env_api
ImportError: cannot import name 'env_api' from 'typhoon.env_api' (unknown location)
install_package(filename)

Installs a package located at filename, specified by parameter.

Parameters

filename – filename in which package is located.

Raises

PkmApiException

Example:

#
# Demonstrates the use of install_package function
#
from typhoon.api.package_manager import package_manager as pkm

# Get all installed packages
all_packages = pkm.get_installed_packages()
print(f"All installed packages: {all_packages}")

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
pkm.install_package(filename=package_path)

# Get all installed packages
all_packages = pkm.get_installed_packages()
print(f"All installed packages: {all_packages}")

# Cleanup
for package in all_packages:
    pkm.uninstall_package(package_name=package.package_name)

Output

All installed packages: []
All installed packages: [Package('Example Package', '1.0.1')]
reinstall_package(package_name)

Reinstall a package by name, specified by parameter package_name.

Parameters

package_name – name of the package to be reinstalled.

Raises

PkmApiException

Example:

#
# Demonstrates the use of the reinstall_package function
#
from typhoon.api.package_manager import package_manager as pkm
from typhoon.env_api import env_api
import shutil

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
pkm.install_package(filename=package_path)

# Validate no packages are modified prior to modification
print(f"Modified packages before modification: {pkm.get_modified_packages()}")

# Modify installed package
package_examples_path = env_api.get_pkm_examples_path()
shutil.rmtree(os.path.join(package_examples_path, "Example Package", "models", "Complex system"))

# Find modified packages after modification
print(f"Modified packages after modification: {pkm.get_modified_packages()}")

# Reinstall package
for package in pkm.get_modified_packages():
    pkm.reinstall_package(package_name=package.package_name)

# Find modified packages after reinstall
print(f"Modified packages after reinstall: {pkm.get_modified_packages()}")

# Cleanup
all_packages = pkm.get_installed_packages()
for package in all_packages:
    pkm.uninstall_package(package_name=package.package_name)

Output

Traceback (most recent call last):
  File "package_manager_api_examples/reinstall_package.example", line 6, in <module>
    from typhoon.env_api import env_api
ImportError: cannot import name 'env_api' from 'typhoon.env_api' (unknown location)
uninstall_package(package_name)

Uninstalls a package by name, specified by parameter package_name.

Parameters

package_name – name of the package to be uninstalled.

Raises

PkmApiException

Example:

#
# Demonstrates the use of uninstall_package function
#
from typhoon.api.package_manager import package_manager as pkm

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
pkm.install_package(filename=package_path)

# Get all installed packages
all_packages = pkm.get_installed_packages()
print(f"All installed packages: {all_packages}")

# Cleanup
for package in all_packages:
    pkm.uninstall_package(package_name=package.package_name)

# Get all installed packages
all_packages = pkm.get_installed_packages()
print(f"All installed packages after uninstall: {all_packages}")

Output

All installed packages: [Package('Example Package', '1.0.1')]
All installed packages after uninstall: []
validate_package(filename)

Validate a package located at filename, specified by parameter.

Parameters

filename – filename in which package is located.

Raises

PkmApiException

Example:

#
# Demonstrates the use of the validate_package function
#
from typhoon.api.package_manager import package_manager as pkm
from typhoon.api.package_manager.exception import PkmApiException

# First install a package
directory, __ = os.path.split(os.path.realpath(__file__))
package_path = os.path.join(directory, "package", "my_package.tpkg")
try:
    pkm.validate_package(filename=package_path)
    print("Package is valid")
except PkmApiException as exc:
    print(exc)

Output

Package is valid