tendo

0.4.0 · active · verified Thu Apr 16

Tendo is a Python library that extends core functionality, providing tools such as transparent Unicode support for file operations, a `tee` implementation for concurrent output, and an improved `execfile` function. Its prominent `singleton` module ensures that only a single instance of a Python script or application can run at a time on a given machine, leveraging lock files for process management. As of version 0.4.0, it requires Python 3.8+ and uses `SingleInstance` as a context manager.

Common errors

```
ImportError: import of 'sys' halted; None in sys.modules
```
cause This error, often occurring during script shutdown, indicates that the `sys` module was garbage collected before `tendo.singleton.SingleInstance.__del__` could clean up its resources, particularly in Python 3.4+ with older `tendo` versions.

fix Upgrade `tendo` to the latest version. The refactoring to use a context manager in v0.4.0 and other internal improvements address such shutdown issues more robustly.
```
SingleInstanceException: Another instance is already running, quitting.
```
cause You are attempting to run a script that uses `tendo.singleton.SingleInstance` (with a specific `flavor_id` or default lock based on script path) while another instance of the same script is already active on the system.

fix This is often intended behavior. If you only want one instance, ensure previous runs are terminated. If you want multiple distinct instances of the same script, provide a unique `flavor_id` to `SingleInstance(flavor_id='unique_id')`. Wrap your `SingleInstance` usage in a `try...except SingleInstanceException` block to handle this gracefully.

Warnings

breaking The `tendo.singleton.SingleInstance` class was refactored in v0.4.0 to be a context manager. Direct instantiation without `with` is no longer the recommended or functional pattern.
Fix: Update your code to use `with SingleInstance():` instead of `me = SingleInstance()`.
breaking The minimum required Python version for `tendo` was raised from Python 3.6 to Python 3.8.
Fix: Ensure your Python environment is version 3.8 or newer before installing or upgrading to `tendo` v0.4.0+.
deprecated Older versions of `tendo` (prior to v0.3.0) used the deprecated 'U' mode in `open()` calls, which was removed in Python 3.9 and would cause errors.
Fix: Upgrade `tendo` to version 0.3.0 or higher. If unable to upgrade, avoid using Python 3.9+ with older `tendo` versions.

Install

pip install tendo Install latest version

Imports

SingleInstance
wrong:
```
from tendo import singleton; me = singleton.SingleInstance()
```
correct:
```
from tendo.singleton import SingleInstance
```
As of v0.4.0, SingleInstance is primarily designed to be used as a context manager.

Quickstart

This quickstart demonstrates how to use `tendo.singleton.SingleInstance` as a context manager to ensure only one instance of a Python script runs at a time. If a second instance attempts to acquire the lock, a `SingleInstanceException` is raised.

import time
import os
from tendo.singleton import SingleInstance, SingleInstanceException

# To demonstrate, use a unique flavor_id for this quickstart example.
# In a real application, you might use a consistent string like 'my_app_name'
# or rely on the default (based on script path) if appropriate.

try:
    # Acquire a single instance lock. If another instance is running, an exception is raised.
    with SingleInstance(flavor_id="my_tendo_quickstart_app"):
        print("Application started. This instance is the only one running.")
        print("Lock file location (typically in temp directory): .tendo-my_tendo_quickstart_app.lock")
        print("Sleeping for 10 seconds. Try running this script again in another terminal to see the SingleInstanceException.")
        time.sleep(10)
        print("Application finished.")
except SingleInstanceException:
    print("Another instance of this application with the same flavor_id is already running.")
    print("Exiting as only one instance is allowed.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →