Documentation

Getting started with Python scripting

5 min read

Pulsonix can generate a Python library which facilitates communication with the Scripting API. This library can be used to easily write Python scripts which use the API.

Setup

To access the scripting API using Python, you must first:

  • Install Python: An installation guide is available. The generated client requires Python 3.10+.
  • Install dependencies: The generated library requires the pywin32 module to be installed. It can be installed on the command prompt with py -m pip install pywin32, assuming that you have the Python launcher installed.
  • Generate a Python package: the Scripting Dashboard can be used to generate a Python package which you can install.
  • Install the package: the generated package can be installed globally via the Scripting Dashboard. You can also choose to install it manually if a more specific system configuration.
  • Enable scripting server hosting: This is also done via the Scripting Dashboard. Ensure that Pulsonix is running and the scripting server is active before running scripts.

Writing, editing and running scripts

Python scripts using the Scripting API can be created, edited and run with typical Python development tools and development environments. Information on working with Python scripts can be found in the Python Scripting FAQ.

Importing the library

If the library was generated and saved as a package, then you can use import pulsonix in any Python script to connect to Pulsonix and gain access to scripting functionality.

Using the client

The Python client attempts to wrap over the Scripting API in a way that will feel familiar if you have experience programming in Python:

  • The pulsonix library will automatically try to connect to Pulsonix when a script tries to make an API call. Exceptions are used if connections fail.
  • The object oriented structure of the API is mirrored directly with Python classes which store an ID. Note that the classes should not be instantiated manually.
  • API Methods are implemented as simple methods on the Python classes, properties are implemented using the @property decorator and enumerations are implemented using the Enum and Flag Python classes.
  • Methods and properties are generated with type hints to assist auto-complete and error checking features.
  • Methods on the Application object are implemented as global functions in the pulsonix namespace.
  • API documentation is inserted as Python docstrings to provide easy access to documentation in most integrated development environments.
  • X and Y are added as properties to DesignItem to provide easy access to positions.
  • Since enumerations are often used as property names, enumerations are named in snake_case for the Python client to prevent name clashes.
  • When API errors are received, they are converted to and thrown as Python exceptions, making errors easy to handle. Non-fatal exceptions contain error codes so that errors can be handled in specific ways, and the error codes are available as a Python Enum.
  • Most primitive API types have 1:1 conversions to Python types, but the Point and Rectangle types are implemented as Python classes.
  • Optional method parameters in the API are keyword arguments in Python methods.
  • The client library automatically requests the real type of received object IDs and constructs them with that type.

For information on which functions and classes are available, as well as how to use them, see the Scripting Reference.

Example script

Below is an example API script that assumes you have installed the client as a package. More reference scripts are available in the Examples folder installed with the product.

import pulsonix, subprocess

# Layout to use for the report.
format_string = "{0:<30} | {1:<10} | {2:<8} | {3:<8} | {4:<8} | {5}\n"

# Get the design currently in view
design = pulsonix.ActiveDocument()
if not design:
    print("No open designs.")
    quit(1)

# Open a file to save the report to
report_path = f"{design.BasePathName} - (PNP Top).txt"
print("Creating report at", report_path)
with open(report_path, "w") as report:
    # Add headings to the report
    report.write(format_string.format("Part", "Name", "X", "Y", "Angle", "Side"))
    report.write("\n")
    # Prepare the list of components, grouping by part and component name
    components = design.Components
    components.sort(key=lambda x: x.Name)
    components.sort(key=lambda x: x.Part.Name)
    # Report on only components for the top side
    components = [comp for comp in components if comp.Layer.Side == pulsonix.Layer.side.top]
    for comp in components:
        # Write out the details
        report.write(format_string.format(
            comp.Part.Name, 
            comp.Name, 
            design.DsuToStringX(comp.Instance.X, useOrigin=True), 
            design.DsuToStringY(comp.Instance.Y, useOrigin=True), 
            comp.Instance.Angle, 
            comp.Layer.Side.name))

# Open a text editor on the created report to view it
subprocess.call(["explorer", report_path])

Client architecture

The file __init__.py (or pulsonix.py if imported as a library) contains classes and functions which use api_caller, api_getter and api_setter from psxutils.py.

  • __init__.py or pulsonix.py contains only classes and functions, so this is what you should import for general use. It also contains documentation for the API functionality.
  • psxutils.py contains code API wrapper types, exception types and functions to make API calls. This file can be used as reference material or a dependency for custom API clients.

Scripting overview | API Interaction | Scripting Dashboard | Python Scripting FAQ | Running Python scripts

Backlinks