E3.series Python Examples

https://github.com/zuken-e3-gmbh/e3seriespythonexamples
Admin
Code examples and documentation for using the E3.series Python library (e3series), covering...
Tokens:8,949
Snippets:81
Trust Score:3.3
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install a specific version of e3series

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/EnvironmentSetup/README.md

Installs a specific version of the e3series package using pip with the --force-reinstall option to ensure reinstallation even if the version is already installed.

```bash
pip install --force-reinstall "e3series==0.1.0"
```

--------------------------------

### Install e3series from local .whl or tar.gz file

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/EnvironmentSetup/README.md

Installs the e3series package from a local .whl or tar.gz file. The --force-reinstall option ensures the package is reinstalled even if it is already up to date.

```bash
pip install --force-reinstall "C:\Users\<user>\Downloads\e3series-26.0.0.tar.gz"
```

--------------------------------

### Start DBE instance

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Start a new DBE (Database Editor) instance using StartArguments with dbe=True. The start() function ensures DBE is fully started before creating the DbeApplication object.

```python
startArgs = e3Tools.StartArguments()
startArgs.dbe = True
e3Pid = e3Tools.start(startArgs).pid
dbe = e3series.DbeApplication(e3Pid)
```

--------------------------------

### Install e3series package with pip

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/EnvironmentSetup/README.md

Installs the latest version of the e3series package using pip. The command may be named pip3 depending on the environment; ensure the correct pip instance is used, especially with multiple Python installations or virtual environments.

```bash
pip install e3series
```

--------------------------------

### Start E3.series with StartArguments

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Start a new E3.series instance with formboard enabled using StartArguments. The start() function ensures E3.series is fully started before creating the application object.

```python
startArgs = e3Tools.StartArguments()
startArgs.formboard = True
e3Pid = e3Tools.start(startArgs).pid
e3 = e3series.Application(e3Pid)
```

--------------------------------

### Start E3.series with string parameters

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Start a new E3.series instance using string parameters passed to start(). The start() function ensures E3.series is fully started before creating the application object.

```python
e3Pid = e3Tools.start(["/formboard"]).pid
e3 = e3series.Application(e3Pid)
```

--------------------------------

### Create IntFlag from Integer

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/E3Types/IntFlags.ipynb

Shows how to create an IntFlag instance directly from an integer, such as one returned from COM functions. The example uses BomType1(12345) and prints its representation.

```python
random_int = 12345
flag_from_int = BomType1(random_int)
print(f"Flag created from integer {random_int}: {repr(flag_from_int)}")
```

```text
Result:
Flag created from integer 12345: <BomType1.EXP_BOM_DEVICE|EXP_BOM_TERMINAL_STRIP|EXP_BOM_ASSEMBLY|EXP_BOM_ASSEMBLY_PART|EXP_BOM_CWI_PART|EXP_BOM_CABLE_DUCT: 12345>
```

--------------------------------

### Work with COM objects

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Example of working with COM objects: create a job, get sheet IDs, and iterate over sheets. Note that lists/tuples are 0-based, [out] parameters are returned in a tuple, and [IN] array parameters are lists.

```python
job = e3.CreateJobObject()
ret, allSheets = job.GetSheetIds()  # Multiple return parameters, if the return value is not needed you could also call job.GetSheetIds()[1]
sht = job.CreateSheetObject()
for shtId in allSheets:
    sht.SetId(shtId)
    sheetName = sht.GetName()
    print(f"Sheet with ID {shtId} is named {sheetName}.")
```

--------------------------------

### Use python -m pip if pip is not found

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/EnvironmentSetup/README.md

If pip is not found, prefix the command with 'python -m' to run pip as a module. This is a fallback for environments where pip is not directly accessible.

```bash
python -m pip install ...
```

--------------------------------

### IntFlags Bitwise Operations with BomType1

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/E3Types/IntFlags.ipynb

Shows how IntFlags like BomType1 support bitwise combinations and operations. The example prints flag values, combines flags with OR, and demonstrates bitwise inversion, AND, OR, and XOR. Useful for understanding how IntFlags behave like int-backed enums with multiple values.

```python
from e3series.types import BomType1, BomType2

# Flag-value relation:
print(f"Value of {BomType1.EXP_BOM_DEVICE.name}: {BomType1.EXP_BOM_DEVICE.value:#0{10}x}")
print(f"Value of {BomType1.EXP_BOM_CONN.name}: {BomType1.EXP_BOM_CONN.value:#0{10}x}")
print(f"Value of {BomType1.EXP_BOM_TUBE.name}: {BomType1.EXP_BOM_TUBE.value:#0{10}x}")

# Combination:
combined_flag = BomType1.EXP_BOM_DEVICE | BomType1.EXP_BOM_CONN | BomType1.EXP_BOM_TUBE
print(f"Value of combined flag {combined_flag.name}: {combined_flag.value:#0{10}x}")

# Short Representation for debugging purposes:
print(f"Short representation of combined flag: {repr(combined_flag)}")

# Different bitwise operations are supported:
inverted_flag = ~combined_flag
print(f"Bitwise Inversion: {repr(inverted_flag)}\n(Hex: {inverted_flag.value:#0{10}x})")
print(f"Bitwise AND with EXP_BOM_DEVICE: {repr(combined_flag & BomType1.EXP_BOM_DEVICE)}")
print(f"Bitwise OR with EXP_BOM_ASSEMBLY: {repr(combined_flag | BomType1.EXP_BOM_ASSEMBLY)}")
print(f"Bitwise XOR with EXP_BOM_CONN: {repr(combined_flag ^ BomType1.EXP_BOM_CONN)}")
print("etc.")
```

```text
Result:
Value of EXP_BOM_DEVICE: 0x00000001
Value of EXP_BOM_CONN: 0x00000002
Value of EXP_BOM_TUBE: 0x00010000
Value of combined flag EXP_BOM_DEVICE|EXP_BOM_CONN|EXP_BOM_TUBE: 0x00010003
Short representation of combined flag: <BomType1.EXP_BOM_DEVICE|EXP_BOM_CONN|EXP_BOM_TUBE: 65539>
Bitwise Inversion: <BomType1.EXP_BOM_TERMINAL|EXP_BOM_TERMINAL_STRIP|EXP_BOM_ASSEMBLY|EXP_BOM_ASSEMBLY_PART|EXP_BOM_CABLE|EXP_BOM_SGS_CONN|EXP_BOM_BLOCK|EXP_BOM_FIELD|EXP_BOM_DYN_SYM|EXP_BOM_CWI|EXP_BOM_CWI_PART|EXP_BOM_CABLE_DUCT|EXP_BOM_MOUNT|EXP_BOM_HOSE|EXP_BOM_HARNESS|EXP_BOM_VIEW|EXP_BOM_OVERBRAID|EXP_BOM_WIRE|EXP_BOM_CORE|EXP_BOM_COMPONENT|EXP_BOM_FEED_THROUGH|EXP_BOM_OVERBRAID_PART|EXP_BOM_CWI_HOST|EXP_BOM_CABLE_DUCT_INLET_OUTLET|EXP_BOM_SYSTEM_CABLE|EXP_BOM_PIN_TERMINAL|EXP_BOM_ADD_PART|EXP_BOM_PIN_WIRESEAL|EXP_BOM_ASSEMBLY_OWNER_WITH_COMPONENT: 4294901756>
(Hex: 0xfffefffc)
Bitwise AND with EXP_BOM_DEVICE: <BomType1.EXP_BOM_DEVICE: 1>
Bitwise OR with EXP_BOM_ASSEMBLY: <BomType1.EXP_BOM_DEVICE|EXP_BOM_CONN|EXP_BOM_ASSEMBLY|EXP_BOM_TUBE: 65555>
Bitwise XOR with EXP_BOM_CONN: <BomType1.EXP_BOM_DEVICE|EXP_BOM_TUBE: 65537>
etc.
```

--------------------------------

### Connect to running E3.series instance

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Connect to an already running E3.series instance. This connects to the first instance found in the running object table, normally the one started first. Use start() if you need a new instance.

```python
e3 = e3series.Application()
```

--------------------------------

### Print BomType of All Devices

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/E3Types/IntFlags.ipynb

Iterates over all device IDs in the project, retrieves each device's BomType using GetBomType, formats it with the helper, and prints and logs the message. Requires an active E3.series application and job/device objects.

```python
import e3series

app = e3series.Application()
job = app.CreateJobObject()
dev = job.CreateDeviceObject()

(ret, all_devices) = job.GetAllDeviceIds()
if ret == 0:
    print(f"Error getting all device IDs: Return code {ret}")
    exit(1)

for dev_id in all_devices:
    dev.SetId(dev_id)
    device_name = dev.GetName()
    message = f"BomType of {device_name}: {format_bom_type(dev.GetBomType())}"
    print(message)
    app.PutMessage(message)
```

```text
Result:
BomType of -Q1: BomType1: EXP_BOM_DEVICE|EXP_BOM_COMPONENT (0x00400001), BomType2: None (0x00000000)
BomType of -B1: BomType1: EXP_BOM_DEVICE|EXP_BOM_COMPONENT (0x00400001), BomType2: None (0x00000000)
BomType of -F1: BomType1: EXP_BOM_DEVICE|EXP_BOM_COMPONENT (0x00400001), BomType2: None (0x00000000)
BomType of -M1: BomType1: EXP_BOM_DEVICE|EXP_BOM_COMPONENT (0x00400001), BomType2: None (0x00000000)
BomType of Wires: BomType1: EXP_BOM_CABLE|EXP_BOM_SYSTEM_CABLE (0x08000040), BomType2: None (0x00000000)
BomType of -W1: BomType1: EXP_BOM_CABLE|EXP_BOM_COMPONENT (0x00400040), BomType2: None (0x00000000)
```

--------------------------------

### Connect to E3.series and get BOM as array

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PartsWithPandas/PandaParts.ipynb

Connects to an E3.series instance, creates a job object, and retrieves the BOM part list. If no job is open, the script exits. Prints each BOM line.

```python
import e3series

e3 = e3series.Application()                                 # Connect to that instance
job = e3.CreateJobObject()                                  # If no job is open we exit the script  
bom = job.GetBomPartList("", "4.1", 0, "", "", "", [""])[1] # Get the BOM from E3.series

for line in bom:
    print(line)
```

--------------------------------

### Using enums from e3series.types

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Example of using the ItemType enum from e3series.types. Enums are helpers; pass Enum.value to functions. This example requires at least one group in the open project.

```python
_, groups = job.GetGroupIds()
grp = job.CreateGroupObject()
grp.SetId(groups[0])        # requires at least one group in the open project
for item in grp.GetItems()[1]:
    itemType = e3Types.ItemType(job.GetItemType(item))
    print(f"The item {item} has the item type {itemType.name}")
```

--------------------------------

### Check Python interpreter path in PowerShell

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/CommonProblems/README.md

Use this command in a PowerShell (not as administrator) to see which Python interpreter is used. The output shows the path to the command, which helps identify the active Python installation.

```powershell
(Get-Command cmd).Path
```

--------------------------------

### Check Python interpreter and version in E3.series

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/CommonProblems/README.md

Use this script to identify which Python interpreter and version E3.series is using. It requires the e3series package and an active E3.series application. If e3series is not available, replace e3.PutMessage with print() and run with python.exe instead of pythonw.exe, adding a sleep or input to see the output.

```python
import e3series 
import sys
python_exec = sys.executable
python_version = sys.version
e3 = e3series.Application()
e3.PutMessage(f"Python:        {python_exec}")
e3.PutMessage(f"Version:       {python_version}")
```

--------------------------------

### Format BomType from GetBomType

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/E3Types/IntFlags.ipynb

Defines a helper function that takes the tuple returned by GetBomType and formats the BomType1 and BomType2 values into a human-readable string. It handles error return codes and prints the flag names and hex values.

```python
def format_bom_type(GetBomTypeReturn: tuple[int, tuple[int, ...]])-> str:
    return_code = GetBomTypeReturn[0]
    bom_type = (BomType1(GetBomTypeReturn[1][0]), BomType2(GetBomTypeReturn[1][1]))
    if return_code < 0:
        return f"Error: Return code {return_code}"
    msg = f"BomType1: {bom_type[0].name} ({bom_type[0].value:#0{10}x}), BomType2: {bom_type[1].name} ({bom_type[1].value:#0{10}x})"
    return msg
```

--------------------------------

### Import e3series and tools

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PrintToE3/PrintToE3.ipynb

Imports the e3series module and its tools submodule, along with sys for output redirection.

```python
import e3series
import e3series.tools as e3Tools
import sys
```

--------------------------------

### Import e3series tools and types

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Import the tools and types submodules for additional functionality and enums.

```python
import e3series.tools as e3Tools
import e3series.types as e3Types
```

--------------------------------

### Import e3series

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/Basics/basics.ipynb

Import the e3series module to access the E3.series COM interface.

```python
import e3series
```

--------------------------------

### Redirect print output to E3.series message window

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PrintToE3/PrintToE3.ipynb

Creates an E3.series application instance and redirects sys.stdout to an E3seriesOutput object, so all print statements appear in the E3.series message window.

```python
e3 = e3series.Application()
sys.stdout = e3Tools.E3seriesOutput(e3, sys.stdout)

print("Hello World!")
```

--------------------------------

### Redirect uncaught exceptions to E3.series message window

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PrintToE3/PrintToE3.ipynb

Redirects sys.stderr to an E3seriesOutput object with red color (255, 0, 0) to display uncaught exceptions in the E3.series message window.

```python
sys.stderr = e3Tools.E3seriesOutput(e3, sys.stderr, (255, 0, 0))
```

--------------------------------

### Save BOM to Excel file

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PartsWithPandas/PandaParts.ipynb

Prompts the user for a destination file using a file dialog and saves the DataFrame to an Excel file.

```python
from tkinter import filedialog
destination = filedialog.asksaveasfilename(defaultextension=".xlsx", filetypes=[("Excel files", "*.xlsx"), ("All files", "*.*")]) # Ask the user for a destination file
pandaBom.to_excel(destination)
```

--------------------------------

### Rename BOM columns and select relevant columns

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PartsWithPandas/PandaParts.ipynb

Renames the DataFrame columns using BomColumnNames.get_bom_default_column_names() and selects a subset of columns for display.

```python
import BomColumnNames
import e3series.tools as e3Tools
e3Tools.get_running_e3s
pandaBom.rename(columns=BomColumnNames.get_bom_default_column_names(), inplace=True) # Rename the columns

pandaBom = pandaBom[["Designation", "Assignment", "Location", "Component Name", "Device Type", "Quantity"]]
display(pandaBom)
```

--------------------------------

### Convert BOM to pandas DataFrame

Source: https://github.com/zuken-e3-gmbh/e3seriespythonexamples/blob/main/PartsWithPandas/PandaParts.ipynb

Converts the BOM array to a pandas DataFrame and displays it in a Jupyter Notebook.

```python
import pandas as pd
pandaBom = pd.DataFrame(bom) 
display(pandaBom) # Display the BOM in a Jupyter Notebook
```
Tokens:
Raw