genserver
______ ______ _____
\ \ \ \ / ____/__ ____ / ___/___ ______ _____ _____
\ \ \ \ / / __/ _ \/ __ \\__ \/ _ \/ ___/ | / / _ \/ ___/
/ / / / / /_/ / __/ / / /__/ / __/ / | |/ / __/ /
/_/_/_/ \____/\___/_/ /_/____/\___/_/ |___/\___/_/
Python GenServer Implementation
genserver is a Python library that provides a robust and easy-to-use implementation of the GenServer pattern, inspired by Erlang/OTP. GenServers are a fundamental building block for building concurrent and fault-tolerant applications. They encapsulate state, handle asynchronous messages, and simplify concurrent programming.
This library aims to bring the power and elegance of the GenServer model to Python developers, enabling them to build more resilient and scalable applications.
Features
- Core GenServer Pattern: Implements the essential GenServer behaviors: state management, message handling (cast and call), and lifecycle callbacks (init, terminate).
- Asynchronous Messaging (Cast): Send non-blocking messages to the GenServer for asynchronous operations and state updates.
- Synchronous Messaging (Call): Send blocking messages and receive responses, enabling request-response style interactions with the GenServer.
- State Management: GenServers manage their own internal state, simplifying concurrent access and data consistency.
- Error Handling: Includes robust error handling within the GenServer loop and user-defined handlers, with logging and custom exception types.
- Timeouts: Supports timeouts for
stopandcalloperations, preventing indefinite blocking. - Type Hinting: Written with type hints for improved code clarity, maintainability, and static analysis.
- Well-Tested: Comes with a comprehensive suite of unit tests to ensure reliability and correctness.
- Production-Ready: Designed for building robust and scalable applications.
Installation
You can install genserver from PyPI using pip:
pip install genserver
Note: The PyPI package name is genserver to avoid namespace conflicts. When importing in Python, you will use import genserver.
Usage
python test_application.py or
Here's a simple example demonstrating how to use genserver to create a counter server:
import time
import logging
from genserver import GenServer, GenServerError, GenServerTimeoutError
# Configure logging (optional)
logging.basicConfig(level=logging.INFO)
class CounterServer(GenServer[int]): # State is an integer
def init(self) -> int:
return 0 # Initial count is 0
def handle_cast(self, message: dict, state: int) -> int:
action = message.get("action")
if action == "increment":
return state + 1
elif action == "decrement":
return state - 1
else:
return super().handle_cast(message, state) # Default unhandled cast
def handle_call(self, message: dict, state: int) -> tuple[int, int]:
action = message.get("action")
if action == "get_count":
return state, state # Return current count
elif action == "increment_and_get":
new_state = state + 1
return new_state, new_state # Increment and return new count
else:
raise NotImplementedError(f"Call action '{action}' not implemented: {action}")
if __name__ == "__main__":
counter = CounterServer()
counter.start()
counter.cast({"action": "increment"})
counter.cast({"action": "increment"})
count = counter.call({"action": "get_count"})
print(f"Current Count: {count}") # Output: Current Count: 2
new_count = counter.call({"action": "increment_and_get"})
print(f"Incremented Count: {new_count}") # Output: Incremented Count: 3
counter.stop()
print("Counter Server Stopped.")
To run this example, save it as a Python file (e.g., counter_example.py) and execute it from your terminal:
python counter_example.py
Key GenServer Methods:
start(*args, **kwargs): Starts the GenServer process. Callsinit(*args, **kwargs)in a new thread.stop(timeout=None): Stops the GenServer gracefully, waiting for the thread to join (with optional timeout).cast(message): Sends an asynchronous message to the GenServer's mailbox (no response expected).messagemust be a dictionary.call(message, timeout=None): Sends a synchronous message and waits for a response (with optional timeout).messagemust be a dictionary.
User-Defined Callbacks (Override in Subclasses):
init(*args, **kwargs) -> State: Initialization callback. Return the initial state.handle_cast(message: dict, state: State) -> State: Handles asynchronous cast messages. Return the new state.handle_call(message: dict, state: State) -> tuple[Any, State]: Handles synchronous call messages. Return a tuple containing the response and the new state.terminate(state: State): Termination callback, called when the GenServer is stopping.
Running Tests
To run the unit tests for genserver, you will need to install pytest. If you haven't already, install it using:
pip install pytest
Then, navigate to the root directory of the genserver library (where setup.py is located) and run pytest from your terminal:
pytest
This will discover and run all tests located in the tests/ directory. You should see output indicating the test results.
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests
Metadata
Release files for genserver 0.2.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| genserver-0.2.7.tar.gz | 12.3 kB | Without provenance | Details for genserver-0.2.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| genserver-0.2.7-py3-none-any.whl | Python 3 | none | any | Details for genserver-0.2.7-py3-none-any.whl |
Total release size: 21.3 kB
Release files / genserver-0.2.7.tar.gz
| Download URL | genserver-0.2.7.tar.gz |
|---|---|
| Size | 12.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1b96400d95b6df6b71c849f4c6fda4cdb5355227ff17a8b424f760abf9641182
|
|
BLAKE2b-256 checksum How to use checksums |
610decbb93462be8d62c40bdad46697fa6f07d316d48c32eec7019a41ecb4c64
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Release files / genserver-0.2.7-py3-none-any.whl
| Download URL | genserver-0.2.7-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b20f7aa300a69760a3e76a98136f2b49870b63ad1743fd1f81036713a5acf82b
|
|
BLAKE2b-256 checksum How to use checksums |
d1cf6d30fb4e758af8ff77f1eed625f5bf48a111f50c5bfc4262252eeb93c664
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Security for genserver 0.2.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.