Metadata-Version: 2.4
Name: e3sertools
Version: 0.4.0
Summary: A collection of helper functions to use alongside the other package
Author-email: kham@tuta.io
Maintainer-email: kham@tuta.io
License-Expression: Unlicense
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: unlicense
Requires-Dist: e3series<28,>=0.2.0
Dynamic: license-file

# Python package `e3sertools`
A small collection of helper functions to use alongside `e3series` package.

## Functionality
This package provides this functionality:

1. Ability to resolve PID of target E3 process in a meaningful way:
   check corresponding environment variable (`E3_SERIES_PID`),
   if it is not set then check parent processes,
   if nothing from above works then just ask a user which process to connect to.
   This functionality is available as `Application.resolve_e3_pid()`
   with `Application` from `e3sertools.extensions` module
   or `app.resolve_e3_pid()` with `app` from `e3sertools.contextvars`.
2. Control over COM-connection initialization and finalization by code.
   Initialization happens at Python wrapper initialization and
   finalization is available as `ReleaseComObject()` method.
   Both are implemented for `Job` class in `e3sertools.extensions` module.
   The class supports `ContextManager` protocol and closes connection on context exit.
3. Global context variables for `Application` and `Job` connections to reuse them between modules.
   Context variables for `Application` and `Job` classes are available as `app` and `job`
   from `e3sertools.contextvars` module.
4. [WIP] Proxy classes to reuse COM connections between different Python object instances.
   When these classes will be implemented their usage should improve COM interface
   perfomance and control over finalization of COM connections.


## Examples
```python
import e3series as e3
from e3sertools import contextvars

# Resolve PID of target E3.series application
pid = contextvars.app.resolve_e3_pid()
# Create COM connection to the target application by the PID
app = e3.Application(pid)
# Set the app as active context variable for usage in other functions & modules
contextvars.app.set(app)

# Create e3Job COM connection and use it as context manager
with contextvars.app.CreateJobObject() as job:
    # Set the created job object as current by corresponding context variable
    with contextvars.job.set(job):
        ...  # operate with the contextvars.job object
# Here the e3Job COM connection is automatically closed by context manager

# Usage of job object after closing connection leads to exception:
print(job.GetName())  # AttributeError: COM-connection has been closed already
```

Using the multi-variable `with` syntax the thing can be written more concisely:

```python
import e3series as e3
from e3sertools.contextvars import app, job

app.set(e3.Application(app.resolve_e3_pid()))
with app.CreateJobObject() as j, job.set(j):
    ...  # operate with the job object (even in other modules)
# Here the e3Job COM connection is closed by context manager
```
