Merge pull request #276 from candango/develop

Merging develop to master.

README.md

@@ -11,16 +11,39 @@
 
 ## Introduction
 
+Firenado is a Python web framework that encapsulates and extends
+[Tornado](http://www.tornadoweb.org) organizing the application in
+components also adding a server side session layer, yaml based configuration
+files as other features common that will help developers building web
+applications and services.
+
 Firenado is a web framework that extends the original Tornado Web framework
 adding new features like loose couple components, server side session layer, 
 yaml based configuration files and more.
 
 ## Installation
 
+Installing Firenado will only force the installation of pyyaml, Tornado and
+six. We call it the basic installation:
+
 ```
 pip install firenado
 ```
 
+It is possible to install extra packages as redis-py, sqlalchemy and pexpect.
+
+To install only redis-py:
+
+```
+pip install firenado[redis]
+```
+
+Complete installation:
+
+```
+pip install firenado[pexpect, redis, sqlalchemy]
+```
+
 ## Usage
 
 Creating and running a new application:
@@ -31,14 +54,15 @@ cd helloworld
 firenado app run
 ```
 
-By default an application will be created with a redis based session and a 
-redis data source defied and linked to the session.
+An application will be created with the redis based session engine
+and a redis data source linked to the session.
 
-Firenado don't install redispy so it is necessary to either install it or turn
-the session as file based. You can disable the session engine too.
+Firenado won't install redis-py so it is necessary to inform the extra
+requirement parameter or install it separately. It is possible to change 
+the session to a file based engine or disable the session engine completely.
 
-To change the session type to file go to helloworld/conf/firenado.yml and
-change the session definition to:
+In order to change the session type to file go to helloworld/conf/firenado.yml
+and change the session definition to:
 
 ```yaml
 # Session types could be:
@@ -53,8 +77,8 @@ session:
   path: /tmp
 ```
 
-If your helloworld project isn't on the python path just go 
-helloworld/conf/firenado.yml and configure the application settings:
+If your helloworld project isn't located in the python path just go 
+helloworld/conf/firenado.yml and changed it to:
 
 ```yaml
 app:
@@ -73,4 +97,4 @@ Firenado is one of [Candango Open Source Group](http://www.candango.org/projects
 the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
 
 This web site and all documentation is licensed under [Creative
-Commons 3.0](http://creativecommons.org/licenses/by/3.0/).
+Commons 3.0](http://creativecommons.org/licenses/by/3.0/).

README.rst

@@ -34,9 +34,11 @@ Firenado Framework
 Introduction
 ------------
 
-Firenado is a web framework that extends the original Tornado Web framework
-adding new features like loose couple components, server side session layer,
-yaml based configuration files and more.
+Firenado is a Python web framework that encapsulates and extends
+`Tornado <http://www.tornadoweb.org>`_ organizing the application in
+components also adding a server side session layer, yaml based configuration
+files as other features common that will help developers building web
+applications and services.
 
 
 Installation

docs/components.rst

@@ -1,24 +1,22 @@
 Components
 ==========
 
-Firenado is organized in components. A component is a unit that will provide
-additional to an application.
+Firenado is organized in components that could be distributed as a full
+application or loose-coupled parts made to be shared between applications.
 
-The idea behind a component is that we can create a full application or
-loose-coupled parts of logic that could be shared between applications.
+A component could provide new handlers, templates, services, models as other
+resources to an application in an organized manner.
 
-A component could provide new handlers and mappings, templates, services,
-models and other resources to an application in an organized manner.
-
-A Firenado application is defined in the app.component parameter in the
-application configuration file:
+An application is a component and it is defined into the app.component
+parameter in the app application configuration file:
 
 .. code-block:: yaml
 
    app:
      component: skell
 
-Components are mapped into the application configuration file:
+Components are mapped into the framework, system or application configuration
+files. They are defined by the component section:
 
 .. code-block:: yaml
 
@@ -52,7 +50,7 @@ Disabled components are not available at run time.
 
 
 Before and after handler methods
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 
 For all handler returned by the component it is possible to implement the
 methods before_handler and after_handler that will be executed before and after

docs/conf.py

@@ -47,17 +47,17 @@
 
 # General information about the project.
 project = u'Firenado Framework'
-copyright = u'2015, Flavio Garcia'
+copyright = u'2015-2019, Flavio Garcia'
 author = u'Flavio Garcia'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.0.1'
+version = '0.1.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.0.1.0'
+release = '0.1.7.7'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/configuration.rst

@@ -4,23 +4,29 @@ Configuration
 Firenado extends the Tornado web framework which uses ini files to help
 developers to configure theirs applications.
 
-As the ini configuration from Tornado is pretty easy and straight forward to
-use, ini files(specially the one Tornado offers) just define key/value
-structures.
+Besides the fact the ini configuration from Tornado is pretty easy and straight
+forward to use, it just define key/value structures.
 
-If someone wants to define hierarchical configuration structures it is
-necessary create indexes that represent the hierarchy(i.e.
-my.hierarchical.index) but the file will be read as key/value. Either the
-developer assumes the index is structured hierarchically or some extra
-development is needed to represent this data as should be in memory.
+Let's assume that someone wants to define hierarchical configuration structures
+. It is necessary create indexes that represent the hierarchy(i.e.
+my.hierarchical.index) and the file will be organized in a key/value manner.
+In this case the developer assumes the index is structured hierarchically or
+some extra development is needed to represent this data as should be in memory.
 
-This is not a problem if the application configuration is simple but if the
-project requires lots of configurable parameters than you need a better option.
+A key/value structure isn't a problem if the application configuration is
+simple. When a project requires lots of configurable parameters ini files can
+be overwhelming.
 
-Firenado uses yaml files instead. TODO give the yaml benefits.
+Firenado uses yaml files instead that are organized in a hierarchical structure
+and can define lists and dictionaries values instead of only strings. With yaml
+boolean and numeric values are resolved with the same time when we consume them
+in the python side.
+
+A Firenado application is defined by a configuration file. This file will
+define application aspects like session, data sources or the port to listen.
+The application file will overload configuration set by framework and system
+levels.
 
-The app is bootstraped using the app configuration file. This file will
-overload default parameters defined by the framework and system levels.
 
 The framework config file will define the framework parts like:
 
@@ -51,5 +57,10 @@ the application
 .. toctree::
    :maxdepth: 2
 
-   configuration/firenado
-   configuration/component
+   configuration/app
+   configuration/components
+   configuration/data
+   configuration/data
+   configuration/management
+   configuration/log
+   configuration/session

docs/configuration/app.rst

@@ -0,0 +1,179 @@
+Application
+===========
+
+The application configuration section set properties to the application to be
+launched by Firenado.
+
+The configuration items will set aspects like application data sources or
+addresses and ports to listen for requests.
+
+
+Here is an example of an app section:
+
+.. code-block:: yaml
+
+   app:
+    component: "myapp"
+    data:
+      sources:
+        - session
+        - mydata
+    port: 9091
+
+
+Configuration Items
+~~~~~~~~~~~~~~~~~~~
+
+addresses
+~~~~~~~~~
+
+List of addresses the application will be listen for requests.
+
+- Type: list
+- Default value: ["::", "0.0.0.0"]
+
+component
+~~~~~~~~~
+
+Firenado component to be set as the application component. This is the main
+application's component.
+
+When running `firenado proj init <project_name>` command a component is created
+in the app.py file and set as in the conf/firenado.yml file.
+
+- Type: string
+- Default value: None
+
+.. code-block:: yaml
+
+   app:
+    component: "myapp"
+
+data
+~~~~
+
+Dictionary containing application data related properties.
+
+sources
+~~~~~~~
+
+List of data sources to be created into the application during the launch
+process. The list items are names of data sources defined in the configuration
+data section.
+
+Data sources can be defined in system and application levels.
+
+- Type: list
+- Default value: []
+
+.. code-block:: yaml
+
+   app:
+    data:
+      sources:
+        - mydata
+        - session
+
+pythonpath
+~~~~~~~~~~
+
+Paths to be added to PYTHONPATH environment variable during the application
+launch process.
+
+- Type: string
+- Default value: None
+
+.. code-block:: yaml
+
+   app:
+    pythonpath: "..:/a/path/somewhere:"
+
+
+port
+~~~~
+
+Port the application will be listen for requests.
+
+- Type: int
+- Default value: 8888
+
+.. code-block:: yaml
+
+   app:
+    port: 9092
+
+process
+~~~~~~~
+
+Configuration to fork the Tornado process to be launched by Firenado.
+
+If the num_processes value is set to None the ioloop will be started without
+forking.
+
+If num_processes is set to a value bigger than 0 the ioloop will be forked with
+this amount as number of child processes. If num_processes is set to zero the
+number of cpu will be used to fork the main process.
+
+The max_restarts value will only be used if num_processes is not none.
+
+- Type: dictionary
+- Default value: {'num_processes': None, 'max_restarts': 100}
+
+.. code-block:: yaml
+
+   app:
+    process:
+      num_processes: 4
+      max_restarts: 150
+
+- See:
+
+ - https://www.tornadoweb.org/en/stable/process.html#tornado.process.fork_processes
+ - https://www.tornadoweb.org/en/stable/httpserver.html#tornado.httpserver.HTTPServer
+
+settings
+~~~~~~~~
+
+Settings to be passed to the Tornado application to be launched by Firenado.
+
+- Type: dictionary
+- Default value: {}
+
+.. code-block:: yaml
+
+   app:
+    settings:
+      cookie_secret: "kljasdf;lkasjdf;lasdkfjasd;lfkjasdf;lkasdjfasd"
+      debug: true
+      xsrf_cookies: true
+
+- See:
+
+ - http://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings
+
+socket
+~~~~~~
+
+Unix socket path the application will be listen. When socket is defined either
+addresses and port are ignored.
+
+- Type: string
+- Default value: None
+
+.. code-block:: yaml
+
+   app:
+    pythonpath: "/tmp/myapp_socket"
+
+wait_before_shutdown
+~~~~~~~~~~~~~~~~~~~~
+
+Time in seconds to wait before trigger the application shutdown.
+
+- Type: int
+- Default value: 0
+
+.. code-block:: yaml
+
+   app:
+    wait_before_shutdown: 5