PyPI 官网下载 | circuits-1.3.1.tar.gz

Tutorial ======== Overview -------- Welcome to the circuits tutorial. Let's get a few things out of the way... As mentioned in the README (*included in the circuits distribution*) and in the introduction to this documentation, circuits is: a **Lightweight** **Event** driven **Framework** for the `Python Programming Language <http://www.python.org/>`_ with a strong **Component** Architecture. There is a certain style to programming with the circuits framework. It might be a little foreign at first, but once you get the hang of it, it's actually fairly straight forward. In circuits, you implement a functional system by implementing smaller functional components that interact together to produce more complex behavior. For example, Component A might be responsible for doing a set of tasks, while Component B is responsible for another set of tasks. The two components might occasionally communicate some information (*by passing messages/events*) to cooperate accomplishing bigger tasks. Designing your system/application this way encourages a decoupled design and components in circuits are designed to help accomplish this. This is called the **Component Architecture**. The three most important things in circuits are; * Events * Components * Interaction between components Oh and by the way... In case you're confused, circuits is completely asynchronous in nature. This means things are performed in a highly concurrent way and circuits encourages concurrent and distributed programming. Without further ado, let's start introducing concepts in circuits... Events ------ In circuits, information is passed around components in the form of events (*or messages*). circuits defines an Event class which is used to create an actual Event object which holds Event data and properties about that event. The Event object is what is passed around a system of components and also what is passed to other processes or remote nodes (*by using a Bridge*). Creating an event ~~~~~~~~~~~~~~~~~ To create an event, simply create an instance of the Event class and pass any required data to its constructor. For example: .. code-block:: python e = Event(1, 2, 3, op="add") This creates an Event object containing two pieces of data: * A list containing the numbers: 1, 2, 3 * A string "add" whoose key is ``op`` (*stored as kwargs*). The Event class's constructor is defined as: .. code-block:: python class Event(object): def __init__(self, ``*args, **kwargs``): ... **Note**: Normally you would subclass ``Event`` and create your own classes of events with appropriate docstrings describing what the event is and what it's used for. You may even create constraints in the args and keyword args that can be passed to it during initialization. Using an Event ~~~~~~~~~~~~~~ Once an Event object is created, you can push/fire it into a system by calling the ``.push(...)`` or ``.fire(...)`` method on any Component in the system or Manager. For example: .. code-block:: python :linenos: from circuits import Event, Manager m = Manager() e = Event("foo") m.push(e) m.push(Event("bar")) Now this doesn't do anything very useful by itself, but we'll get to more useful things later... Event Handlers -------------- In order to do useful things with events and components we need a way to create **Event Handlers** that react to events. In circuits there are two types of handlers: **Listeners** and **Filters**. A Listener is an Event Handler that simply "listens" for an Event while a Filter is an Event Handler with a higher priority than Listeners and is capable of filtering the Event from other handlers. To create an Event Handler (*a Listener*) simply use the ``handler(...)`` decorator on a Component: .. code-block:: python :linenos: from circuits import handler, Component class System(Component): @handler("hello") def onHello(self): print "Hello World!" This will create a Component called ``System`` that defines an Event Handler that listens to the channel "hello". **Note:** * The Component automatically defines methods to be Event Handlers that listen to a channel that is the name of the method. If a Component defines a method called ``foo``, an an Event Handler will be created that listens to the channel "foo". Components ---------- What makes circuits unique in its own way is its **Component Architecture**. The "circuits way" (tm) is to create components that represent different functional parts of your system or application. One of the key concepts is to create more complex components from simpler components. This is a bit different to subclassing and using multiple inheritance in OOP (*Object Orientated Programming*). Components are registered to one another in a directed graph/structure giving a system/application great flexibility. Components can be registered and unregistered at run-time and even modified. A Component is also a Manager and every Component can be run independently. There are three ways in which you can start a Component/Manager: * ``.run()``: running in the main thread. * ``.start()``: running in a new separate thread. * ``.start(process=True)``: running in a new separate process. Let's look at a few common things that components are used for... Defining a new Component ~~~~~~~~~~~~~~~~~~~~~~~~ To define a new (*more complex*) Component, simply create a new class that derives from ``Component``: .. code-block:: python :linenos: from circuits import Component class System(Component): """My System Component""" Registering Components ~~~~~~~~~~~~~~~~~~~~~~ Components are registered to one another or a Manager by simply calling the ``.register(...)`` method of a Component or by using the short-hand ``+`` or ``+=`` syntax. For example: .. code-block:: python :linenos: from circuits import handler, Event, Component, Debugger class Add(Event): """Add Event""" class Print(Event): """Print Event""" end = "print_ended", class Adder(Component): @handler("add") def onAdd(self, x, y): self.push(Print(x + y)) class Printer(Component): @handler("print") def onPrint(self, s): print s class System(Component): def __init__(self): super(System, self).__init__() Debugger().register(self) self += (Adder() + Printer()) def started(self, component, mode): self.push(Add(4, 5)) def print_ended(self, e, h, v): raise SystemExit, 0 System().run() Although this example above seems quite complex and uses quite a few of circuits' features, it is actually quite simple. You can learn more about some of the features used above in later documentation but the key things here are lines 28 and 29 showing the different ways of registering components. Here's the output of the above example system/application: .. code-block:: sh $ python demo.py <Registered[*:registered] [<Debugger/* (queued=0, channels=1, handlers=1) [S]>, <System/* (queued=0, channels=5, handlers=5) [R]>] {}> <Registered[*:registered] [<Printer/* (queued=0, channels=1, handlers=1) [S]>, <Adder/* (queued=0, channels=2, handlers=2) [S]>] {}> <Registered[*:registered] [<Adder/* (queued=0, channels=2, handlers=2) [S]>, <System/* (queued=0, channels=5, handlers=5) [R]>] {}> <Started[*:started] [<System/* (queued=0, channels=5, handlers=5) [R]>, None] {}> <Add[*:add] [4, 5] {}> <Print[*:print] [9] {}> 9 <End[*:print_ended] [<Print[*:print] [9] {}>, <bound method Printer.onPrint of <Printer/* (queued=0, channels=1, handlers=1) [S]>>, None] {}> Don't worry about understanding the output above right now. Most of this is events flowing through the system and printed to the screen by the Debugger Component so you can see what's going on. Running/Starting Components ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As stated, y