10. 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.

10.1. Examples¶

Following example illustrates how you can use Package Manager API.

10.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')]

10.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='', website='', 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='', icon_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
website – Website of 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..)
icon_path – Path to package icon file (svg, png, jpg, bmp…)

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"
author_website = "typhoon-hil.com"
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")

icon_path = os.path.join(root_folder, "icon.svg")

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, website=author_website, 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,
        icon_path=icon_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

download_package(output_path, package_name, version='latest')¶

Returns iterable over packages available on Package Marketplace.

Parameters:

output_path (str) – Output directory/file path for downloaded package. If file is passed, it must have .tpkg extension. If not, it will have “[package_name]-[version].tpkg” format.
package_name (str) – name of the package to be downloaded.
version (str) – Package version. String “latest” can be used for
package. (latest version of the) –

Returns:

String file path of downloaded package

Raises:

PkmApiException –

Example:

#
# Demonstrates the use of download_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 download a package
directory, __ = os.path.split(os.path.realpath(__file__))
packages_directory = os.path.join(directory, "package")
opendss_path = pkm.download_package(output_path=packages_directory, package_name="OpenDSS")

# Then install a package
pkm.install_package(filename=opendss_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('OpenDSS', '0.5.0')]

get_available_packages(latest_version=True)¶

Returns iterable over packages available on Package Marketplace.

Parameters:

latest_version (bool) – If true, return only latest version of
Otherwise (the package.) –
version (return an object for each) –
available. (of the package) –

Returns:

Iterable over available packages (Package).

Example:

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

# Get all available packages (only latest versions)
all_packages = pkm.get_available_packages()
print(f"All available packages (only latest versions): {all_packages}")

# Get all available packages (all versions)
all_packages = pkm.get_available_packages(latest_version=False)
print(f"All available packages (all versions): {all_packages}")

Output

All available packages (only latest versions): [Package('Danfoss MyDrive HIL', '1.0.2'), Package('EVSE generic with OCPP in SCADA', '0.0.1'), Package('Energetic Macroscopic Representation', '0.1.0'), Package('HIL Academy Course - Digital Control of Grid-Tied Converters', '1.0.6'), Package('IEEE 34 node islanding with Artificial Neural Network', '0.2.0'), Package('OpenDSS', '0.5.0'), Package('OpenDSS and Typhoon HIL co-simulation', '0.2.0'), Package('Xyce', '0.4.0')]
All available packages (all versions): [Package('Danfoss MyDrive HIL', '1.0.2'), Package('EVSE generic with OCPP in SCADA', '0.0.1'), Package('Energetic Macroscopic Representation', '0.1.0'), Package('HIL Academy Course - Digital Control of Grid-Tied Converters', '1.0.6'), Package('IEEE 34 node islanding with Artificial Neural Network', '0.2.0'), Package('IEEE 34 node islanding with Artificial Neural Network', '0.1.0'), Package('OpenDSS', '0.5.0'), Package('OpenDSS and Typhoon HIL co-simulation', '0.2.0'), Package('OpenDSS and Typhoon HIL co-simulation', '0.1.0'), Package('Xyce', '0.4.0')]

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

Modified packages before modification: []
Modified packages after modification: [Package('Example Package', '1.0.1')]

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

Modified packages before modification: []
Modified packages after modification: [Package('Example Package', '1.0.1')]
Modified packages after reinstall: []

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

10. Package Manager API¶

10.1. Examples¶

10.1.1. Example¶

10.2. API references ¶

Table of Contents

Previous topic

This Page

10. Package Manager API¶

10.1. Examples¶

10.1.1. Example¶

10.2. API references¶

10.2. API references ¶