cotyledon

What it is and what it does

Cotyledon is a framework for building long-running services that need to manage multiple worker processes, handle Unix signals cleanly, and reload configuration without restarting. It was created as an alternative to oslo.service for projects that don't want eventlet's greenlet overhead; instead, it uses Python's standard multiprocessing module, ensuring predictable behavior across single-worker and multi-worker deployments. The framework handles worker spawning, supervision, graceful termination, daemon reloading on SIGHUP, rate limiting for worker creation, and sd-notify integration.

You use Cotyledon by subclassing its ServiceManager and defining your service logic. It manages the lifecycle of child processes, ensures only one service manager runs at a time (via a seatbelt mechanism), and provides separate APIs for terminating child processes versus the master process. Unlike frameworks built on eventlet, Cotyledon's code path is identical whether you run one worker or many, and it supports non-POSIX platforms through multiprocessing rather than os.fork alone.

Use it for:

• Build a telemetry or monitoring agent that spawns multiple worker processes to collect metrics from distributed systems.
• Create a message queue consumer service that scales horizontally by spawning workers to handle incoming tasks.
• Implement a daemon that reloads configuration on SIGHUP without restarting child processes or losing in-flight work.
• Develop a long-running background job processor that needs clean signal handling and process supervision.
• Run a service in a container or systemd environment where predictable process lifecycle and sd-notify support matter.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Cotyledon provides a framework for building long-running services with Unix signal handling, worker process spawning, supervision, daemon reloading, and rate-limited worker lifecycle management.

Yes. Cotyledon is actively maintained, has low install friction, carries no known vulnerabilities, and solves a real problem for services that need multiprocess management without eventlet's overhead. It is well-suited for OpenStack-style telemetry and monitoring workloads, and more broadly for any daemon or long-running service that needs robust worker lifecycle and signal handling. Install it if you are building a service that spawns multiple workers and want clean, predictable process management.

Install

cotyledon on PyPI

pip install cotyledon

uv add cotyledon

poetry add cotyledon

Installing cotyledon

Before you install

Low install friction with only two runtime dependencies (setproctitle and typing_extensions). Actively maintained with recent commits and a stable release history since 2016; supports current Python versions (3.9–3.13).

License in practice

Licensed under Apache-2.0 (permissive), allowing commercial and private use with minimal restrictions.

Quickstart

pip install cotyledon

from cotyledon import ServiceManager

class MyService(ServiceManager):
    def run(self):
        # long-running service logic
        pass

if __name__ == '__main__':
    service = MyService()
    service.run()

Requires Python 3.9 or later; designed for POSIX platforms (Linux) though multiprocessing support extends to non-POSIX systems.

Verify before relying

• Whether the framework supports graceful shutdown semantics beyond signal handling.
• Performance characteristics under high worker counts or rapid spawn/terminate cycles.
• Compatibility with containerized or orchestrated environments (Kubernetes, systemd).

Package facts

Evidence: cotyledon-2.2.0-py3-none-any.whl

Tags

More Distributed Computing packages