Skip to main content

Asynchronous Component based Event Application Framework

Project description


circuits is a Lightweight Event driven and Asynchronous Application Framework for the Python Programming Language with a strong Component Architecture.

circuits also includes a lightweight, high performance and scalable HTTP/WSGI web server as well as various I/O and Networking components.

To take full advantage of circuits and its architecture, circuits requires that your application be designed in terms of components and their interactions (events) with each other. An application written using the circuits application framework is maintainable, scalable and easy to develop.

The circuits framework has a certain elegance making it a rather attracting feature. New features are built into the framework with this in mind and circuits “eats its own dog food” by having a feature-rich library of components built atop the core components.


Project website:

PyPI page:


  • event driven
  • concurrency support
  • compnoent archiecture
  • asynchronous I/O components
  • no required external dependencies
  • full featured web framework (circuits.web)


circuits has no dependencies beyond the Python Standard Library.

Some dependencies should be optionally installed if deployed on a Python-2.5 environment such as processing for multiprocessing concurrency support and for JSON support the simplejson package.


The simplest and recommended way to install circuits is with pip. You may install the latest stable release from PyPI with pip:

> pip install circuits

If you do not have pip, you may use easy_install:

> easy_install circuits

Alternatively, you may download the source package from the circuits Page on PyPI or the circuits Downloads page on the circuits Website; extract it and install using:

> python install


circuits is licensed under the MIT License.


I welcome any questions or feedback about bugs and suggestions on how to improve circuits. Let me know what you think about circuits. I am on twitter @therealprologic.

Do you have suggestions for improvement? Then please Create an Issue with details of what you would like to see. I’ll take a look at it and work with you to either incorporate the idea or find a better solution.


There is also a small community of circuits enthusiasts that you may find on the circuits IRC Channel and the circuits Mailing List.

Release Notes - circuits-1.6 (oceans)

Python 3 Support

This is the third attempt at getting Python 3 support for circuits working while still maintaining Python 2 compatibility. This release finally adds full support for Python 3 as well as maintaining compatibility with Python 2.6 and 2.7 with the same code-base.


Python 2.5 support has been dropped as of this release and will no longer be supported in future. There may be a maintenance branch specifically for Python 2.5 if required.

Greenlet Support

circuits now includes two new primitives which work by integrating greenlet.

  • .waitEvent(...) – Wait for the given event to complete.
  • .callEvent(...) – Call event handlers for the given event.


These new primitives add (as long as greenlet is installed) the ability to write semi-synchronous code in your event handlers while still taking full advantage of the asynchronous and component framework that circuits has to offer.

Code Coverage

circuits now has 80% test coverage on all supported versions of Python including Python 2.6, Python 2.7 and Python 3.2


  • Added an example WebSockets server using circuits.web
  • Added support for specifying a Poll instance to use when using the @future decorator to create “future” event handlers.
  • Added add_section, has_section and set methods to app.config.Config Component.
  • Added support for running test suite with distutils python test.
  • Added a _on_signal event handler on the BaseEnvironment Component so that environments can be reloaded by listening to SIGHUP signals.
  • Added support for using absolute paths in app.env.Environment.
  • Added support in circuits.web HTTP protocol to limit the no. of header fragments. This prevents OOM exploits.
  • Added a ticks limit to waitEvent
  • Added deprecation warnings for .push .add and .remove methods
  • NEW Loader Component in circuits.core for simple plugin support.
  • NEW app.env and app.config modules including a new app.startup modules integrating a common startup for applications.
  • NEW KQueue poller

Bug Fixes

  • Fixed Issue #17
  • Renamed circuits.web.main module to circuits.web.__main__ so that python -m circuits.web just works.
  • Fixed and Server.port properties in
  • Fixed Issue #19
  • Fixed app.Daemon Component to correctly open the stderr file.
  • Fixed triggering of Success events.
  • Fixed duplicate broadcast handler in UDPServer
  • Fixed duplicate Disconnect event from being triggered twice on Client socket components.
  • Removed dynamic timeout code from Select poller.
  • Fixed a bug in the circuits.web HTTP protocol where headers were not being buffered per client.
  • Fixes a missing Event Closed() not being triggered for UDPServer.
  • Make underlying UDPServer socket reusable by setting SO_REUSEADDR
  • Fixes Server socket being discarded twice on close + disconnect
  • Socket.write now expects bytes (bytes for python3 and str for python2)
  • Better handling of encoding in HTTP Component (allow non utf-8 encoding)
  • Always encode http headers in utf-8
  • Fixes error after getting socket.ERRCONNREFUSED
  • Allows TCPClient to bind to a specific port
  • Improved docs
  • Handles closing of udpserver socket when no client is connected
  • Adds an unregister handler for components
  • Allows utils.kill to work from a different thread
  • Fixes bug when handling “*” in channels and targets
  • Fixes a bug that could occur when unregistering components
  • Fixes for CPU usage problems when using circuits with no I/O pollers and using a Timer for timed events

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

circuits-1.6.tar.gz (987.5 kB view hashes)

Uploaded source

Built Distributions

circuits-1.6-py3.2.egg (430.2 kB view hashes)

Uploaded 3 2

circuits-1.6-py2.6.egg (434.7 kB view hashes)

Uploaded 2 6

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page