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 it’s 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 it’s 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

Code Coverage

Code Coverage and Tests need a special section this release. This is the first release where circuits now has the following coverage:

  • Python-2.6: 77%
  • Python-2.5: 76%

We’re well on our way to 100% !!!


  • Revamped environment, config and logger components
  • socket module cleanup.
    • API Changes:
      • Keyword argument ssl changed to secure
      • Attribute ssl changed to ssl
  • Allow the Daemon Component to daemonize an application by simply registering it but only if the application is already running.
  • Import Log Event to namespace
  • circuits.core: Cosmetic changes to poller components. Base Poller renamed from _Poller to BasePoller
  • circuits.core: Added new function utils.itercmp which returns an iterator that matches the given component.
  • Added a new Event Closed for Server components which gets sent when the listening socket has closed.
  • Added a _on_stopped event handler to close all client connections on a Server Component and close the connection on a Client Component when the system is terminated.
  • Streamline host and port methods.
  • circuits.web: Streamline host and port methods.

In both cases, the host attribute always returns socket.getsockname()[0]

  • circuits.core: Make default TIMEOUT 10ms This is the timeout period when we have no running Tick Functions.
  • scripts: Added circuits.bench, circuits.sniff and circuis.web scripts which are installed by distutils. circuits.web still gets installed by setuptools.
  • circuits.core: Add an on_ready event handler for the Bridge and set an attribute _bridge on the component being started in “process mode” so we can check whether it’s ready or not via the ready attribute on the Bridge instnace.
  • Makefile: Added graph rule using snakefood and ghostscript to produce a PDF of the architecture of the circuits library.
  • circuits.core: Make chop attribute work for when we’re logging to a logger
  • circuits.web: Set the Content-Type to “application/json” for all JSONController responses.
  • circuits.web: Allow HTTP status message to be customized so implementing WebSockets is a little eaiser.
  • circuits.web: Don’t presume to add a “Content-Type” header.
  • Added a new helper function tryimport which given a list of modules to try and import and an optional message; will try to import each module returning the first successful one. If none of the modules can be improted, a warning is useed with the optional message.
  • circuits.web: Restructured dispatchers. circuits.web.dispatchers is now it’s own package.
  • circuits.web: NEW WebSockets dispatcher.
  • circuits.web: Raise a RuntimeError exception if when trying to create an instance of the JSONRPC dispatcher we have no “json” support.
  • circuits.web: Raise a RuntimeError exception if when trying to create an instance of the Routes dispatcher we have no “routes” support.
  • circuits.web: Added support for passing body and headers to Request event
  • circuits.web: Only close the connection if Connection header has the value “close” for the Client.
  • circuits.web: Added a _on_write event handler to Client to allow direct writing to the underlying transport (eg: from a WebSockets client).

Bug Fixes

  • Fixed a bug when if we try to initiate a connection on a disconnected socket (eg: TCPClient) we get EBADF or EINVAL.
  • circuits.core: Fixed a bug with Event Handler Inheritence where overridden Event Handlers were not being picked up properly.
  • circuits.core: Fixed a minor bug in @future decorator where it wasn’t passing the correct channel and was starting non-pooled futures as processes instead.

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.5.tar.gz (510.5 kB view hashes)

Uploaded source

Built Distributions

circuits-1.5-py2.6.egg (393.0 kB view hashes)

Uploaded 2 6

circuits-1.5-py2.5.egg (392.6 kB view hashes)

Uploaded 2 5

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