Metadata-Version: 1.0
Name: Trellis
Version: 0.7a2
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.7a1, many new features have been added to the Trellis API,
        and some old ones have been deprecated.  If you are upgrading from an older
        version, please see the `porting guide`_ for details.)
        
        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):
        ...     F = trellis.maintain(
        ...         lambda self: self.C * 1.8 + 32,
        ...         initially = 32
        ...     )
        ...     C = trellis.maintain(
        ...         lambda self: (self.F - 32)/1.8,
        ...         initially = 0
        ...     )
        ...     @trellis.perform
        ...     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`_
        
        * `Time, Event Loops, and Tasks`_
        
        * `Event-Driven Collections with the Trellis`_ (New features in 0.7a2)
        
        * `Software Transactional Memory (STM) And Observers`_
        
        * `Porting Code from Older Trellis Versions`_
        
        
        Release highlights for 0.7a2:
        
        * Removed APIs that were deprecated in 0.7a1
        
        * Rollback now occurs over an entire atomic operation, even if more than one
        recalc pass occurs within that atomic operation.
        
        * Added ``collections.Hub`` type for publish/subscribe operations similar to
        PyDispatcher, but in a declarative, callback-free, and extensible manner.
        
        * Various bugfixes
        
        
        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
        .. _Porting Code from Older Trellis Versions: http://peak.telecommunity.com/DevCenter/TrellisPorting
        .. _porting guide: http://peak.telecommunity.com/DevCenter/TrellisPorting
        
        .. _toc:
        
Platform: UNKNOWN
