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