Metadata-Version: 1.0
Name: avalanche
Version: 0.1.1
Summary: Web Framework with a focus on testability and reusability
Home-page: http://packages.python.org/avalanche/overview.html
Author: Eduardo Naufel Schettino
Author-email: schettino72@gmail.com
License: MIT
Description: =========
        Overview
        =========
        
        Avalanche is a Python web-framework built on top of `webapp2 <http://webapp-improved.appspot.com>`_.
        It uses `Jinja2 <http://jinja.pocoo.org/>`_ as a default template system and
        does not includes any persistence layer.
        
        
        Avalanche goals (or why another web framework?)
        ================================================
        
        Avalanche design focus on testability and reusability.
        
        Of course Avalanche does not do miracles. Testability and reusability will
        ultimately depends on the application code. But the framework
        have a big role on setting up the *right* path.
        
        The goals are presented below, hopefully after reading the design and tutorial
        it will be clear to you how these goals are achieved.
        
        
        Testability
        -------------
        
        Avalanche was designed in a way that it makes it possible (easier for you) to
        write *good* unit-tests for your code. That is not only making it easy to write
        tests. A unit-test should:
        
          * give a clear error message when it fails
          * fail only when the feature under test is broken, not on every code change
          * be fast
        
        
        
        Reusability
        -------------
        
        Mostly every framework claims that reusability is one of their design goals.
        Here "reusability" means source-code reusability.
        
        Many frameworks provide some mechanisms for reusable/plugable *sub-applications*
        however it is not always easy to re-use
        these applications source code in case you need to configure/modify it.
        Plugable applications is also a very important feature but as of now
        Avalanche has no support for that.
        
        It should not only be possible to write reusable code, the code should be
        reusable on the *first* time you write it.
        You should not be advised to write the code in one way,
        and than later have to modify it to make it reusable.
        I.e. it is opposed to saying "Use *view* (handler) functions". And than...
        "if you want your *views* to be re-usable convert them to class-based *views*!".
        
        
        
        Project Details
        ===============
        
        * `Website/docs <http://packages.python.org/avalanche>`_
        
        * This is an open-source project (`MIT license <http://opensource.org/licenses/mit-license.php>`_) written in python.
        
        * Download from `PyPi <http://pypi.python.org/pypi/avalanche>`_
        
        * Project management (bug tracker, feature requests and source code ) on `bitbucket <https://bitbucket.org/schettino72/avalanche>`_.
        
        * Questions and feedback on `google group <https://groups.google.com/d/forum/python-avalanche>`_.
        
        
        
        Avalanche Design
        ====================
        
        .. warning::
        
          Avalanche is on early stages of development (alpha). The API might change
          in the future and there is no guarantee it will keep compatibility.
        
        
        beyond MVC (model-view-controller)
        -----------------------------------
        
        `MVC <http://en.wikipedia.org/wiki/Model-view-controller>`_ is a software
        architectural pattern created with the goal to isolate "domain logic" from
        the user interface. This separation of concern enables the creation of better
        application code. This pattern was very successful for many desktop frameworks
        and so served as a reference to the creation of web-frameworks. The problem is
        that this architecture can not be mapped directly to the way web-applications
        work.
        
        Even the so-called MVC frameworks are not really MVC. So let's just keep the
        MVC's goal. That is to write clean, re-usable and testable code.
        
        
        web applications
        ------------------
        
        Essentially all a web-application do is to receive a
        `HTTP <http://en.wikipedia.org/wiki/HTTP>`_ request, process it and generate a HTTP response.
        
        ::
        
                              +------------------+
          HTTP Request ------>| web application  + ----->  HTTP Response
                              +------------------+
        
        Sending and receiving HTTP is handled by a web-server. Let's take a closer
        look into what the web application does:
        
        
        
        ::
        
                            +------+      +-------+
          HTTP request ---->|router|----->|handler|----> HTTP response
                            +------+      +-------+
        
        The *router* will check the URL of the request and dispatch it to a request
        *handler* that will create the response. Avalanche uses the webapp2 router.
        
        
        request handlers styles
        ------------------------
        
        There are mainly 3 styles of request handlers.
          * a single function
          * a class method
          * a class
        
        Avalanche (and webapp2) uses the third style, a class. Using a class as request
        handler suits better our goals because it provides a greater flexibility, easier
        to modify/extend and re-use parts of the handler.
        
        
        request handler processing
        ---------------------------
        
        The request handler processing can be divided in 3 stages:
        
        ::
        
                       +-----------------+                        +-----------------+                  +----------+
          request ---->| param converter |---- param objects ---->| context builder |--- context ----->| renderer |----> response
                       +-----------------+                        +-----------------+                  +----------+
        
        
        1) param converter - get parameters from HTTP request
        
          HTTP is a text protocol, the application will typically get some
          parameters from the request and convert string values into some native data
          types. These parameters are taken from the URI path, URI query, post-data,
          cookies, etc.
        
        
        2) context builder - processing
        
          Context is a term used to represent the data that will be used by a renderer.
        
          This processing is the application logic. It will often access a persistence
          layer (sometimes called *Model*) but this is entirely up to the application code
          and the framework has no role on that.
        
          A web page is often composed of several elements so sometimes it makes sense to
          divide the work into more than one "context builder".
        
        
        3) renderer - generate output
        
          The renderer will convert the result of the processing into text for the HTTP
          response. This stage might be skipped if the response is a HTTP redirect. The
          renderer will typically use a template system to generate HTML code or convert
          the data to JSON.
        
        
        On avalanche you should write code for the 3 stages of the handler separately and
        let the framework glue the different parts together.
        
        
        Move on to the tutorial to see how it looks like.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
