Metadata-Version: 1.0
Name: Trellis
Version: 0.6a1
Summary: A simple "untwisted" approach to event-driven programming
Home-page: http://peak.telecommunity.com/DevCenter/Trellis
Author: Phillip J. Eby
Author-email: peak@eby-sarna.com
License: PSF or ZPL
Description: (NOTE: As of 0.6a1, many advanced parts of the Trellis API have changed
        significantly.  If you've done a lot with the 0.5 version API, we strongly
        suggest reading the new manuals, especially the parts dealing with state
        change.  Many old restrictions have been lifted, but some were replaced with
        new ones.)
        
        Whether it's an application server or a desktop application, any sufficiently
        complex system is event-driven -- and that usually means callbacks.
        
        Unfortunately, explicit callback management is to event-driven programming what
        explicit memory management is to most other kinds of programming: a tedious
        hassle and a significant source of unnecessary bugs.
        
        For example, even in a single-threaded program, callbacks can create race
        conditions, if the callbacks are fired in an unexpected order.  If a piece
        of code can cause callbacks to be fired "in the middle of something", both that
        code *and* the callbacks can get confused.
        
        Of course, that's why most GUI libraries and other large event-driven systems
        usually have some way for you to temporarily block callbacks from happening.
        This lets you fix or workaround your callback order dependency bugs...  at the
        cost of adding even *more* tedious callback management.  And it still doesn't
        fix the problem of forgetting to cancel callbacks...  or register needed ones
        in the first place!
        
        The Trellis solves all of these problems by introducing *automatic* callback
        management, in much the same way that Python does automatic memory management.
        Instead of worrying about subscribing or "listening" to events and managing
        the order of callbacks, you just write rules to compute values.  The Trellis
        "sees" what values your rules access, and thus knows what rules may need to be
        rerun when something changes -- not unlike the operation of a spreadsheet.
        
        But even more important, it also ensures that callbacks *can't* happen while
        code is "in the middle of something".  Any action a rule takes that would cause
        a new event to fire is *automatically* deferred until all of the applicable
        rules have had a chance to respond to the event(s) in progress.  And, if you
        try to access the value of a rule that hasn't been updated yet, it's
        automatically updated on-the-fly so that it reflects the current event in
        progress.
        
        No stale data.  No race conditions.  No callback management.  That's what the
        Trellis gives you.
        
        Here's a super-trivial example::
        
        >>> from peak.events import trellis
        
        >>> class TempConverter(trellis.Component):
        ...     trellis.values(
        ...         F = 32,
        ...         C = 0,
        ...     )
        ...     trellis.rules(
        ...         F = lambda self: self.C * 1.8 + 32,
        ...         C = lambda self: (self.F - 32)/1.8,
        ...     )
        ...     @trellis.observer
        ...     def show_values(self):
        ...         print "Celsius......", self.C
        ...         print "Fahrenheit...", self.F
        
        >>> tc = TempConverter(C=100)
        Celsius...... 100
        Fahrenheit... 212.0
        
        >>> tc.F = 32
        Celsius...... 0.0
        Fahrenheit... 32
        
        >>> tc.C = -40
        Celsius...... -40
        Fahrenheit... -40.0
        
        As you can see, each attribute is updated if the other one changes, and the
        ``show_values`` action is invoked any time the dependent values change...  but
        not if they don't::
        
        >>> tc.C = -40
        
        Since the value didn't change, none of the rules based on it were recalculated.
        
        Now, imagine all this, but scaled up to include rules that can depend on things
        like how long it's been since something happened...  whether a mouse button was
        clicked...  whether a socket is readable...  or whether a Twisted "deferred"
        object has fired.  With automatic dependency tracking that spans function
        calls, so you don't even need to *know* what values your rule depends on, let
        alone having to explicitly code any dependencies in!
        
        Imagine painless MVC, where you simply write rules like the above to update
        GUI widgets with application values... and vice versa.
        
        And then, you'll have the tiny beginning of a mere glimpse...  of what the
        Trellis can do for you.
        
        Other Python libraries exist which attempt to do similar things, of course;
        PyCells and Cellulose are two.  However, only the Trellis supports fully
        circular rules (like the temperature conversion example above), and intra-pulse
        write conflict detection.  The Trellis also uses less memory for each cell
        (rule/value object), and offers many other features that either PyCells or
        Cellulose lack.
        
        The Trellis package can can be `downloaded from the Python Package Index`_ or
        installed using `Easy Install`_, and it has a fair amount of documentation,
        including the following manuals:
        
        * `Developer's Guide and Tutorial`_ (Extensively revised for 0.6a1)
        
        * `Time, Event Loops, and Tasks`_ (NEW for 0.6a1)
        
        * `Event-Driven Collections with the Trellis`_ (NEW for 0.6a1)
        
        * `Software Transactional Memory (STM) And Observers`_ (NEW for 0.6a1)
        
        Questions, discussion, and bug reports for the Trellis should be directed to
        the `PEAK mailing list`_.
        
        .. _downloaded from the Python Package Index: http://pypi.python.org/pypi/Trellis#toc
        .. _Easy Install: http://peak.telecommunity.com/DevCenter/EasyInstall
        .. _PEAK mailing list: http://www.eby-sarna.com/mailman/listinfo/PEAK/
        .. _Developer's Guide and Tutorial: http://peak.telecommunity.com/DevCenter/Trellis#toc
        .. _Time, Event Loops, and Tasks: http://peak.telecommunity.com/DevCenter/TrellisActivity
        .. _Event-Driven Collections with the Trellis: http://peak.telecommunity.com/DevCenter/TrellisCollections
        .. _Software Transactional Memory (STM) And Observers: http://peak.telecommunity.com/DevCenter/TrellisSTM
        
        .. _toc:
        
Platform: UNKNOWN
