Is Mamba meant to be a real MVC implementation?¶

That depends on the interpretation of the paragraph above. Mamba applications are implemented using a MVC like pattern as we separate our business logic from the view (that only knows about render HTML), the controllers receive inputs as HTTP requests and initiates responses by calling methods in model objects that interacts with different data sources, interpret that data and send results back to the view through the controller (or send it through JSON or sockets to third parties).

The last description can be defined as a MVC pattern implementation or not depending on the point of view. Anyway, Mamba isolates the logic of the data from the presentation of the data, that’s all that you are going to want to take care of.

The application directory¶

The application directory contains all our application Python code (with the exception of the shared packages and the ApplicationFactory)

The application directory contains three directories to implement the MVC pattern and a fourth one where to place all the code that doesn’t fit the MVC pattern and 3rd party libraries as well, all of them are Python packages:

• application/controller → Python package
• application/model → Python package
• application/view → Python package
• application/lib → Python package

The application directory is a package itself, meaning it contains an __init__.py file so you can add whatever other directory/package/module that you need. The application directory and all its contents are exported by default when you pack or install your application.

The config directory¶

The config contains the application configuration files. Those files must be valid JSON formatted files. There are two main configuration files on mamba:

• application.json, this is the main configuration file for the application, if you need to add some configurable parameter to your application, this is the file to place it
• database.json, this file is used to configure database connections and it parameters

A third file is used to tell Mamba that we want to include some Mamba shared package in our application:

• installed_packages.json, this file contains a list of installed Mamba shared packages that we want to use in our application

If you need to add some custom configuration file, you shoud place it inside this directory to follow convention.

The docs directory¶

The docs directory is used to store the application documentation. We use Sphinx as documentation system but you can use whatever you want.

The static directory¶

The static directory is used to store mainly images and other static data. You can use it to store and access CSS, JavaScript or HTML static files but is better if you do that using the templating system.

The test directory¶

The test directory contains your application unit tests and integration tests

The twisted directory¶

Twisted directory is used internally by mamba and Twisted to daemonize your mamba applications, you don’t have to care about this dIrectory and itS contents.

The logs directory¶

Mamba writes the log files in the logs directory if you don’t configure other behaviour by yourself.

The database URI¶

Mamba uses a valid URI as parameters to connect with the database.

"uri": "sqlite:"

"uri": "sqlite:foo"
"uri": "sqlite:/home/user/foo"
"uri": "sqlite:///foo"
"uri": "sqlite:///home/user/foo"

"uri": "sqlite:dummy?timeout=0.5"

"uri": "mysql://username:password@hostname:port/database_name"

"uri": "postgres://username:password@hostname:port/database_name"

Create or dump SQL schema from Mamba models¶

In Mamba we don’t create a schema config file that is then used to generate our model classes, instead of that, we define our model classes and then we generate our SQL schema using our already defined Python code.

To create our database structure in live or dump a SQL file with the schema (for whatever SQL backend we configured) we use the mamba-admin sql create subcommand in the command line interface, so for example to dump the schema into a file we should use:

$ mamba-admin sql create schema.sql

To dump it to the stdout:

$ mamba-admin sql create -d

And for create it in live in the database (this may delete all your previous data, be careful):

$ mamba-admin sql create -l

Dump SQL data from the database¶

If you ever used mysqldump you will be familiarized with mamba-admin sql dump command. It dumps the actual data into the database to the stdout. Doesn’t matter which database backend you are using, it works with SQLite, MySQL and PostgreSQL and you don’t need to have installed mysqldump command to dump MySQL databases:

$ mamba-admin sql dump > database-dump.sql

The above command will dump the database into a file in the current directory named database-dump.sql

Truncating all data in your database¶

Sometimes we need to truncate all tables in our database. For that scenario you can use the reset command:

$ mamba-admin sql reset --noquestions

The above command will reset all your data without any questions. So, please, be careful with this command.

Interactive Shell¶

In case you want to login into the database interactive shell, you can just issue this command and Mamba will take care of authentication details for you:

$ mamba-admin sql shell

Future plans¶

For next releases, a live database migration tool is intended to be added to the framework so the developer can just switch from a RDBMS to another one without losing his data.

How to use Storm in Mamba models?¶

Mamba’s enterprise system take care of any initialization that is needed by the underlying Storm library, we don’t have to care about create database connections or stores. We can use it with CPython or PyPy without any type of code modification.

store = self.store()

peter = User()
peter.name = u'Peter Griffin'

store = self.store()
store.add(peter)

>>> Store.of(peter) is store
True
>>> Store.of(User()) is store
False

store.commit()

store = self.store()
user = store.find(User, User.name == u'Peter Griffin').one()

pk_user = store.get(Person, 1)

>>> pk_user is user
True

store.find(User, User.name == u'Peter Griffin').set(name='Peter Sellers')

How do I use stores in an asynchronous way?¶

Just decorate your model methods with the @transact decorator and make sure to don’t return any Storm object from that method:

from mamba.application import model
from mamba.enteprise import Int, Unicode, transact


class Dummy(model.Model):

    __storm_table__ = 'dummy'

    id = Int(primary=True)
    name = Unicode()

    def __init__(self, name):
        self.name = unicode(name)

    @transact
    def get_last(self):
        """
        Get the last inserted row from the database.
        This is not thread safe
        """
        store = self.store()
        return store.find(Dummy).order_by(Dummy.id).last()

The get_last method above will retrieve the last inserted row in the database. As we are using the @transact decorator we can’t use Reference or ReferenceSet in the returned object because those are lazy evaluated and the object was created in a different thread. If we ever try to do that we will get an exception from Storm ZStore module.

If we don’t want to use an asynchronous operation we can just remove the @transact line and it will work perfectly synchronous, of course the limitations about using references with the returned object does not apply on this scenario.

How do I use a store from outside the model method?¶

Even if Mamba allows us to use Store objects everywhere, they are not suposed to be used outside the model but nothing stop you to use it in the controller or whatever other part of your application.

If you think that you need to use a store object from outside your model class,then you can do it in several ways:

1. Don’t decorate a method in your model with @transact and then return the store from it. As this store has been created in the same thread that the rest of the application you can use it anywhere.

2. Just retrieve a store object executing the database.store() object directly from your model at class level:

   from application.model.dummy import Dummy
   
   store = Dummy.store()
   dummy = store.get(Dummy, 1)
   

{
    "max_threads": 20,
    "min_threads": 5,
    "auto_adjust_pool_size": true,
    "drop_table_behaviours": {
        "drop_if_exists": false,
        "restrict": true,
        "cascade": true
    },
    "uri": {
      "operations": "postgres://user:password@host/dbname",
      "reports": "mysql://user:password@host/dbname"
    },
    "create_table_behaviours": {
        "create_table_if_not_exists": false,
        "drop_table": false
    }
}

Creating a new model¶

We can generate new model classes using the mamba-admin command line tool or adding a new file with a class that inherits from mamba.application.model.Model directly. If you use the command line, you have pass two arguments at least, the model name and the real database table that is related to:

$ mamba-admin model dummy dummy_table

The command above will create a new dummy.py file in the application/model directory with the following content:

# -*- encoding: utf-8 -*-
# -*- mamba-file-type: mamba-model -*-
# Copyright (c) 2013 - user <user@localhost>

"""
.. model:: Dummy
    :plarform: Linux
    :synopsis: None
.. modelauthor:: user <user@localhost>
"""

from mamba.enterprise import Int
from mamba.application import model


class Dummy(model.Model):
    """
    None
    """

    __storm_table__ = 'dummy_table'

    id = Int(primary=True, unsigned=True)

You can pass many parameters to the mamba-admin model subcommand. You can set the description of the model, the author name and email, the platforms that this model is compatible with and the classname you want for your model.

As you can see in the code that mamba-admin tool generated for us, we define a new class Dummy that inherits from mamba.application.model.Model class and define a static property named __storm_table__ that points to the real name of our database table, dummy_table in this case. The class define another static property id that is an instance of the Storm class storm.properties.Int with the parameters primary and unsigned as True.

Its possible to create subpackages to maintain our models under more order and control using a doted name for the model, for example:

$ mamba-admin model community.users users

The previous command will add a python package community in application/model so finally we can import it in our application with:

.. sourcecode:: python

from application.model.community import users

Mamba’s Storm properties¶

In mamba we define our database schema just creating new Python classes like the one in the example above. The following is a table of the available Storm types and their SQLite, MySQL/MariaDB and PostgreSQL equivalents:

All these properties except NativeEnum are common Storm properties. The NativeEnum property class is just a convenience class that we created to support legacy databases that uses native Enum types in the scenario where we can’t change this because the database is used by other applications that we can’t modify to switch to Int type.

Properties in deeper detail¶

A property is a Storm object that maps our classes properties with a related field in the database and perform several other operations as cache values among others.

All property classes define a class level property called variable_class that is an object that represents the value stored in the database as Python and is the part of the library that effectively map the Python representation of the value with the value itself as is stored in the database.

Variables are responsible for setting and getting values on and from the underlying database backend and perform any special operation that is needed to convert the native database types into Python ones.

from mamba.enterprise import Int
from mamba.application import model

class Dummy(model.Model):

    __storm_table__ = 'dummy'
    __mamba_async__ = False

    id = Int()
    status = Int()

from mamba.enterprise import Int
from mamba.application import model

class Dummy(model.Model):

    __storm_table__ = 'dummy'
    __storm_primary__ = 'id', 'status'

    id = Int()
    status = Int()

from mamba.enterprise import Int
from mamba.application import model

class Dummy(model.Model):

    __storm_table__ = 'dummy'
    __mamba_unique__ = (('id', 'status'), )

    id = Int()
    status = Int()

from mamba.enterprise import Int
from mamba.application import model

class Dummy(model.Model):

    __storm_table__ = 'dummy'
    __mamba_index__ = (('id', 'status'), )

    id = Int()
    status = Int()

name = Unicode(size=64)

name VARCHAR(64)

some_field = Decimal(size=(10, 2))  # using a tuple
some_field = Decimal(size=[10, 2])  # using a list
some_field = Decimal(size=10.2)     # using a float
some_field = Decimal(size='10,2')   # using a string
some_field = Decimal(size=10)       # using an int (precission is set to 2)

age = Int(size=2)

age INT(2)

Model operations¶

Create and insert a new object into the database is pretty straightforward, we just have to create a new instance of our model and call the create method on it:

>>> dummy = Dummy()
>>> dummy.name = u'The Dummy'
>>> dummy.create(async=False)

Read a model instance (or row) from the database is as easy as using the read method of the Model class with the id of the row we want to get from the database:

>>> dummy = Dummy.read(1, async=False)

Update is performed in the same easy way, we just modify our object and call the update method on it:

>>> dummy.name = u'Modified Dummy'
>>> dummy.update(async=False)

The delete operation is no different, we just call the delete method from our object (note that this doesn’t delete the object reference itself, only the databse row):

>>> dummy.delete()

>>> [c.name for c in Customer.all(async=False)]
>>> [c.name for c in Customer.find(Customer.age >= 30)]

References¶

We can define references between models (and between tables by extension) instantiating Reference and ReferenceSet objects in our model definition:

from mamba.application import model
from mamba.enterprise import Int, Reference

from application.model.dojo import Dojo

class Fighter(model.Model):

    __storm_table__ = 'fighter'
    __mamba_async__ = False  # we don't want go asynchronous as we are on terminal

    id = Int(primary=True, auto_increment=True, unsigned=True)
    dojo_id = Int(unsigned=True)
    dojo = Reference(dojo_id, Dojo.id)

In the previous example we defined a Fighter class that defines a many-to-one reference with the Dojo class imported from the dojo model. As this reference has been set we can use the following code to refer to the fighter’s dojo in our application:

>>> fighter = Fighter().read(1)
>>> print(fighter.dojo.id)
1
>>> print(fighter.dojo.name)
u'SuperDojo'

Many-to-many relationships are a bit more complex than the last example. Let’s continue with our previous fighter example to draw this operation:

from mamba.application import model
from mamba.enterprise import Join, Select, Not
from mamba.enterprise import Int, Unicode, Reference, ReferenceSet

from application.model.dojo import Dojo
from application.model.tournament import Tournament


class Fighter(model.Model):

    __storm_table__ = 'fighter'
    __mamba_async__ = False  # we don't want go asynchronous as we are on terminal

    id = Int(primary=True, auto_increment=True, unsigned=True)
    name = Unicode(size=128)
    dojo_id = Int(unsigned=true)
    dojo = Reference(dojo_id, Dojo.id)

    def __init__(self, name):
        self.name = name


class TournamentFighter(model.Model):

    __storm_table__ = 'tournament_fighter'
    __storm_primary__ = 'tournament_id', 'fighter_id'
    __mamba_async__ = False  # we don't want go asynchronous as we are on terminal

    tournament_id = Int(unsigned=True)
    fighter_id = Int(unsigned=True)

In the above example we defined a TournamentFighter class to reference tournaments and fighters in a many-to-many relationship. We defined a compound primary key with the tournament_id and fighter_id fields. To make the relationship real we have to add a ReferenceSet:

Tournament.fighters = ReferenceSet(
    Tournament.id, TournamentFighter.tournament_id,
    TournamentFighter.fighter_id, Fighter.id
)

We can also add the definition to the Tournament class definition directly but in that case we have to use special inheritance that we didn’t see yet, we will cover it later in this chapter. Since the reference set is created we can use it as follows:

>>> chuck = Fighter(u'Chuck Norris')
>>> bruce = Fighter(u'Bruce Lee')

>>> kung_fu_masters = Tournament(u'Kung Fu Masters Tournament')
>>> kung_fu_masters.fighters.add(chuck)
>>> kung_fu_masters.fighters.add(bruce)

>>> kung_fu_masters.fighters.count()
2

>>> store.get(TournamentFighters, (kung_fu_masters.id, chuck.id))
<TournamentFighter object at 0x...>

>>> [fighter.name for fighter in kung_fu_masters.fighters]
[u'Chuck Norris', u'Bruce Lee']

We can also create a reverse relationship between fighters and tournaments to know in which tournaments a fighter is figthing on:

>>> Fighter.tournaments = ReferenceSet(
    Fighter.id, TournamentFighter.fighter_id,
    TournamentFighter.tournament_id, Tournament.id
)

>>> [tournament.name for tournament in chuck.tournaments]
[u'Kung Fu Masters Tournament']

SQL Subselects¶

Sometimes we need to use subselects to retrieve some data, for example we may want to get all the fighters that are not actually figthing in any tournament:

>>> yip_man = Fighter(u'Yip Man')
>>> store.add(yip_man)

>>> [fighter.name for fighter in store.find(
        Fighter, Not(Fighter.id.is_in(Select(
            TournamentFighter.fighter_id, distinct=True))
        )
)]
[u'Yip Man']

You can split this operation in two steps for improved readability:

>>> subselect = Select(TournamentFighter.fighter_id, distinct=True)
>>> result = store.find(Fighter, Not(Fighter.id.is_in(subselect)))

SQL Joins¶

We can perform implicit or explicit joins. An implicit join that use the data in our previous examples may be:

>>> resutl = store.find(
    Dojo, Fighter.dojo_id == Dojo.id, Fighter.name.like(u'%Lee')
)

>>> [dojo.name for dojo in result]
[u'Bruce Lee awesome Dojo']

The same query using explicit joins should look like:

>>> join = [Dojo, Join(Fighter, Fighter.dojo_id == Dojo.id)]
>>> result = store.using(*join).find(Dojo, Fighter.name.like(u'%Lee'))

>>> [dojo.name for dojo in result]
[u'Bruce Lee awesome Dojo']

Or more compact syntax as:

>>> [dojo.name for dojo in store.using(
        Dojo, Join(Fighter, Fighter.dojo_id == Dojo.id)
    ).find(Dojo, Fighter.name.like(u'%Lee'))]
[u'Bruce Lee awesome Dojo']

Common SQL operations¶

Two common operations with SQL are just ordering and limiting results, you can also perform those operations using the underlying Storm ORM when you are using Mamba models. Order our results is really simple as you can see in the following example:

>>> result = store.find(Fighter)
>>> [fighter.name for fighter in result.order_by(Fighter.name)]
[u'Bruce Lee', u'Chuck Norris', u'Yip Man']

>>> [fighter.name for fighter in result.order_by(Desc(Fighter.name))]
[u'Yip Man', u'Chuck Norris', u'Bruce Lee']

In the example above we get all the records from the fighters database and order them by name and then order them by name in descendent way. As you can see Chuck Norris is always inmutable but that is just because he is Chuck Norris.

To limit the given results we just slice the result:

>>> [fighter.name for fighter in result.order_by(Fighter.name)[:2]]
[u'Bruce Lee', u'Chuck Norris']

Those slices are translated to OFFSET and LIMIT in the underlaying database SQL query by Storm so this last operation is translated to something like this for MySQL/MariaDB:

SELECT fighter.name FROM fighters LIMIT 2 OFFSET 0

Storm adds the possibility to use SQL expressions in an agnostic database backend way to perform those operations as well:

>>> result = store.execute(Select(Fighter.name, order_by=Desc(Fighter.name), limit=2))
>>> result.get_all()
[(u'Yip Man',), (u'Chuck Norris',)]

Multiple results¶

Sometimes is useful that we get more than one object from the underlying database using only one query:

>>> result = store.find(
    (Dojo, Fighter),
    Fighter.dojo_id == Dojo.id, Fighter.name.like(u'Bruce %')
)

>>> [(dojo.name, fighter.name) for dojo, fighter in result]
[(u'Bruce Lee awesome Dojo', u'Bruce Lee')]

Value auto reload and expression values¶

Storm offers a way to make values to be auto reloaded from the database when touched. This is performed assigning the AutoReload attribute to it

>>> from storm.locals import AutoReload

>>> steven = store.add(Person(u'Steven'))
>>> print(steven.id)
None

>>> steven.id = AutoReload
print(steven.id)

Steven has been autoflushed into the database. This is useful to making objects automatically flushed if necessary.

You can also assign what in the Storm project they call a “lazy expression” to any attribute. The expressions are flushed to the database when the attribute is accessed or when the object is flushed to the database.

>>> from storm.locals import SQL
>>> steven.name = SQL('(SELECT name || ? FROM fighter WHERE id=4)', (' Seagal',))
>>> steven.name
u'Steven Seagal'

Serialize¶

You can serialize Model objects either to a dictionary or to JSON. All references will be serialized correctly and you can specify, if you like, specify only the fields you’d like in a fields parameter or fields to exclude in a exclude parameter.

The json property is very simple, it returns a JSON representation of the model instance.

>>> customer = Customer.find(Customer.id == 2, async=False)
>>> customer.json
'{"name": "Austin Powers", "id": 2, "adresses": [{"street": "Memory Lane", "postcode": 60}]}'

The dict function supports more options, however.

>>> customer = Customer.find(Customer.id == 2, async=False)
>>> customer.dict(json=True)  # json property uses dict method internally
'{"name": "Austin Powers", "id": 2, "adresses": [{"street": "Memory Lane", "postcode": 60}]}'
>>> customer.dict(traverse=False, json=True)  # We don't want references
'{"name": "Austin Powers", "id": 2}'
>>> customer.dict(traverse=False, json=True, exclude=['name'])
'{"id": 2}'
>>> customer.dict(traverse=False, json=True, fields=['id', 'adresses.street'])  # Specify a single field in the reference
'"id": 2, "adresses": [{"street": "Memory Lane"}]}'

Queries debug¶

Sometimes is really useful to see which statement Storm is being executed behind the curtains. We can use a debug tracer that comes integrated in Storm itself. Using it is really easy:

>>> import sys
>>> from storm.tracer import debug

>>> debug(True, stream=sys.stdout)
>>> result = store.find(Fighter, Fighter.id == 1)
>>> list(result)
EXECUTE: 'SELECT fighter.id, fighter.name, fighter.dojo_id FROM fighters WHERE fighter.id = 1', ()
[<Fighter object at 0x...>]

>>> debug(False)
>>> list(result)
[<Fighter object at 0x...>]

Real SQL Queries¶

We can use real database dependant queries if we want to:

>>> result = store.execute('SELECT * FROM fighters')
>>> result.get_all()
[u'Bruce Lee', u'Chuck Norris', u'Yip Man', u'Steven Seagal']

The Storm base class¶

In some situations we are not going to be able to import every other model class into our local scope (mainly because circular import issues) to define Reference and ReferenceSet properties. In that scenario we can define these references using a stringfield version of the class and property names involved in the relationship.

To do that, we have to inherit our classes from the Storm base class as well as from Model class. There is another inconvenience related with this. When we inherit from both classes we have to define that the metaclass of the class that we are defining is MambaStorm to avoid metaclass collisions between mamba model and storm itself.

from mamba.enterprise import Int, Unicode, Reference, ReferenceSet

class Fighter(model.Model, Storm):

    __metaclass__ = model.MambaStorm
    __storm_table__ = 'fighters'

    id = Int(primary=True)
    name = Unicode()
    dojo_id = Int()
    dojo = Reference(dojo_id, 'Dojo.id')

How it works?¶

Every controller in a Mamba application inherits directly from the mamba.application.controller.Controller class. A controller can define action methods and regular methods.

• An action method is a method that is invoked by the underlying request routing system when our application receives a request. Each action in our controller has to fit in a route, we define routes using the route decorator and decorating the method to fit a route.
• A regular method is just a normal method that is not decorated and is usually some kind of helper method that helps our controllers to make its work.

A controller can define as many action and regular emthods as is needed and every controller action represents a single URL segment of the application.

@route('/')
def root(self, request. **kwargs):
    """Just an action method for the root of the controller
    """
    return Ok(sef.salutation())

def salutation(self):
    """Just a regular method used as helper for our controller class
    """

    return 'Hello World!'

Its possible to create subpackages to maintain our controllers under more order and control using a doted name for the controller, for example:

$ mamba-admin controller community.user_controller

The previous command will add a python package community in application/controller so finally we can import it in our application with:

.. sourcecode:: python

from application.controller.community.user_controller import UserController

Mamba create and handles an internal controller manager object that load all the controllers that are found in our application on initialization time and register all its routes with the routing system.

When a HTTP request is made from a client, it’s captured by the underlying Twisted routing mechanism that delegate its process to the main or root Mamba’s controller (that is defined internally into the framework) that pass it to the Mamba’s routing and templating system to locate, retrieve and render a response for the given request.

The response can be a HTML rendered page, text, a JSON structure, a XML Object or arbitrary binary data, that depends completely on the application and what the client is looking for. If Mamba can’t locate a valid action or resource for the given request, a 404 response will be returned back.

Controllers route¶

Every Mamba controller has to define a route for themselves, this route is their position in the web site path hierarchy and it must be a single path segment of the URL. A controller that doesn’t define a controller route is attached to the main Twisted Site object and becomes the root of the application. That means no Mamba’s default special behaviour is going to be available for the site if we don’t define it mannually in the controller that becomes the root.

The controller’s route can be defined when we create the controller using the mamba-admin controller sub-command or just editing the resulting file with our text editor. The argument for the mamba-admin command line tool is --route=<our route> so for example, the command:

$ mamba-admin controller --route=api webservice

Will create a new controller python script on application/controller/webservice.py with the following content:

# -*- encoding: utf-8 -*-
# -*- mamba-file-type: mamba-controller -*-
# Copyright (c) 2013 - damnwidget <damnwidget@localhost>

"""
.. controller:: Webservice
    :platform: Linux
    :synopsis: None

.. controllerauthor:: damnwidget <damnwidget@localhost>
"""

from mamba.web.response import Ok
from mamba.application import route
from mamba.application import controller


class Webservice(controller.Controller):
    """
    None
    """

    name = 'Webservice'
    __route__ = 'api'

    def __init__(self):
        """
        Put your initializarion code here
        """
        super(Webservice, self).__init__()

As you can see, the generated file already defines the controller’s route as 'api' but we can just modify that value to whatever other route that we want. If we use more than one single URL path segment the route is totally ignored and our controller is not registered in the system making it unavailable.

...
__route__ = 'api/socket'
...

The above example should end in the behaviour described above.

Controllers actions¶

Controllers can define arbitrary routes with the @route decorator that finally callbacks the decorated method. Those routes can be static routes (that only defines a path) or dynamic routes (that defines a path and wildcards for parameters).

# static route example
@route('/comments')
def comments(self, request, **kwargs):
    ...

# dynamic route example
@route('/comments/<int:comment_id>')
def read_comment(self, request, comment_id, **kwargs):
    ...

Controller actions can define more extensive route paths so we can for example register the following route for our Webservice example controller (defined in the last section):

...
@route('/contacts/add/<email>/<password>')
def add_contact(self, request, email, password, **kwargs):
    contact = new Contact(email, password)
    contact.create()

In the above example our final route path (as will be invoked from the web client) is http://localhost/api/contacts/add/john_doe@gmail.com/ultrasecret. This is:

Mamba’s default root¶

Mamba defines internally a default root route that points always to the index.html template view. Sometimes we need a controller to become the root of our application because we want to develop a full backend REST service or for whatever other reasson. When we do that, we are going to override all the Mamba’s auto insertion of mambaerized resources like CSS, LESS or JavaScript files.

If you are not going to use a frontend at all then you are just done, all is ok and you don’t have to care about but if you are planning to use Mamba’s templating system then you have to create a new index to recover the default root functionality.

First of all we have to create a new view for the controller using the mamba-admin view subcommand. Let’s imagine we defined a controller that becomes the root resource in our application and we call it Main and we use the default root action method as the / or index route:

class Main(controller.Controller):

    name = 'Main'
    __route__ = ''

    def __init__(self):
        """
        Put your initialization code here
        """
        super(Main, self).__init__()

    @route('/')
    def root(self, request, **kwargs):
        Ok('I am the Main, hello world!')

Then we generate a new view for the root action using the mamba-admin command line tool:

$ mamba-admin view root Main

This will generate a new file application/view/Main/root.html that will be our new index template for the whole application that inherits from the layout.html template. This view will know how to insert the mambaerized resources into our templates in automatic way.

Our last step is to just make a small change in the root action in the controller to make it render our new index:

from mamba.core import templating

class Main(controller.Controller):

    name = 'Main'
    __route__ = ''

    def __init__(self):
        """
        Put your initialization code here
        """
        super(Main, self).__init__()
        self.template = templating.Template(controller=self)

    @route('/')
    def root(self, request, **kwargs):
        return Ok(self.template.render().encode('utf-8'))

Nested Controllers¶

Sometimes we want to group different controllers under the same path (user, cart and actions under the api path for example), controllers can be attached to other controllers setting the __parent__ property to the route of the controller that we want to arrach it.

A container can (and should) define a controller’s __route__ just like any other controller. If the __route__ property is not set in an attached controller, this can lead to totally unpredictable and hard to debug weird behaviour in your routes dispatching.

You can add as much nested level as you wish.

from mamba.application import route
from mamba.application import controller
from mamba.web.response import BadRequest


class Api(controller.Controller):

    name = 'Api'
    isLeaf = False
    __route__ = 'api'

    def __init__(self):
        """Put your initialization code here
        """
        super(Api, self).__init__()

    @route('/')
    def root(self, request, **kwargs):
        return BadRequest()

from mamba.web.response import Ok
from mamba.application import route
from mamba.application import controller


class UserController(controller.Controller):
    """User Controller
    """

    name = 'User'
    __route__ = 'user'
    __parent__ = 'api'

    def __init__(self):
        """Put your initialization code here
        """
        super(UserController, self).__init__()

    @route('/')
    def root(self, request, **kwargs):
        return Ok('Give me users please!')

    @route('/test')
    def test(self, request, **kwargs):
        return Ok('TEST OK!')

from mamba.web.response import Ok
from mamba.application import route
from mamba.application import controller


class WalletController(controller.Controller):
    """Wallet Controller
    """

    name = 'Wallet'
    __route__ = 'wallet'
    __parent__ = 'api'

    def __init__(self):
        """Put your initialization code here
        """
        super(WalletController, self).__init__()

    @route('/<int:wallet_id>')
    def test(self, request, wallet_id, **kwargs):
        return Ok('Fake Wallet')

Going asynchronous¶

Mamba is just Twisted and Twisted is an asynchronous network framework. We can run operations asynchronous and return back callbacks from Twisted deferreds as we do in any normal Twisted application. We can do it always that we decorate a model method with the @transact decorator in our models.

from twisted.internet import defer

from mamba.application import route
from mamba.application.controller import Controller

from application import controller
from application.model.post import Post


class Blog(Controller):
    """
    Blog controller
    """

    name = 'Blog'
    __route__ = 'blog'

    def __init__(self):
        """
        Put your initialization code here
        """
        super(Blog, self).__init__()

    @route('/<int:post_id>/comments', method=['GET', 'POST'])
    @defer.inlineCallbacks
    def root(self, request, post_id, **kwargs):
        """Return back the comments for the given post
        """

        comments = yield Post().comments
        defer.returnValue(comments)

We just used the Twisted‘s @defer.inlineCallbacks decorator to yield results from asynchronous operations and then we returned back the value using defer.returnValue.

Returning values from controller actions¶

Surely the reader already noticed that we use an Ok object as return from our controller actions. The Ok class is one of the multiple built-in response objects that you can return from your application controllers.

Mamba defines 15 predefined types of response objects that set the content-type and other parameters of the HTTP response that our applications can return back to the web clients.

• Response dummy base response object, we can use this object to create ad-hoc responses on demand. All the rest of responses inherits from this class
• Ok - Ok 200 HTTP Response
• Created - Ok 201 HTTP Response
• Unknown - Unknown 209 HTTP Response (this HTTP code is not defined, mamba returns that when a route just returns None)
• MovedPermanently - Ok 301 HTTP Response
• Found - Ok 302 HTTP Response
• SeeOther - Ok 303 HTTP Response
• BadRequest - Error 400 HTTP Response
• Unauthorized - Error 401 HTTP Response
• Forbidden - Error 403 HTTP Response
• NotFound - Error 404 HTTP Response
• Conflict - Error 409 HTTP Response
• AlreadyExists - Error 409 HTTP Response (Conflict found in POST)
• InternalServerError - Internal Error 500 HTTP Response
• NotImplemented - Error 501 HTTP Response

Mamba return back some of those codes by itself in some situations, for example, if we try to use a route that exists but in a different HTTP method, we get a NotImplemented response object.

You can return whatever of these objects from your controller. Mamba take care of rendering it correctly to the web client. You can also return dictionaries and other objects. Mamba will try to convert whatever object you return from a controller into a serializable JSON structure with a default 200 OK HTTP response code and an ‘application/json’ encoding.

Controllers and routes¶

In Mamba there are two types of routes:

1. Static routes
2. Controller routes

The first one is used for Mamba to locate and render templates that do not depends on a controller, like an static HTML page or a main HTML page that loads JavaScript to create single page applications using AngularJS or whatever other library or framework.

The second one is used to create relationships between routes and actions in our application controllers. Those actions can end in some template rendering, some acces to the database, some communication with external services or whatever other action that we can think about.

Controller actions¶

Mamba distinguishes between two types of routes, static and dynamic routes. Static routes are all those routes that defines only a path part, for example:

@route('/blog')

Dynamic routes in the other hand, contains one or more wildcards:

@route('/blog/<post_id>')

# untyped wildcard
@route('/run/<action>')
def run(self, request, action, **kwargs):
    ...

# int wildcard
@route('/run/<action>/<int:post_id>')
def run(self, request, action, post_id, **kwargs):
    ...

# float wildcard
@route('/sum/<float:amount>')
def run(self, request, amount, **kwargs):
    ...

@route('/run')
def run(self, request, **kwargs):
    return Ok(kwargs.get('action'))

Jinja2 Documentation¶

Jinja2 has its own (and extensive) documentation, Mamba take cares of the initialization of the common contexts and loaders so you don’t have to take care yourself.

The Jinja2 documentation is available in it’s project web site, we recommend you read their documentation.

Mamba templating¶

Mamba implements its own wrapper around Jinja2 templating engine to integrate it with Mamba routing and controllers systems.

In Mamba, the only thing that you need to create and render a new template is create a Jinja2 template file into application/view/templates directory and point to it with your browsers or link it in another of your application pages.

Mamba define a default root template internally called root_page.html that is needed for the framework to insert the web resources that we add to the stylesheets and scripts directories into application/view. The layout that all the views in your application share inherit directly from this internal template.

Files inside the stylesheets and scripts directory must define an special file header for make it able to being automatic loaded by the styles and scripts managers and inserted in all your templates. Those special file headers are:

/*
 * -*- mamba-file-type: mamba-css -*-
 */

for css files and:

/*
 * -*- mamba-file-type: mamba-javascript -*-
 */

for JavaScript ones.

When we generate a new Mamba application with the mamba-admin command line tool, it creates a default layout.html file that is located inside the application/view directory. This file can be used as common layout for all your application pages and it must inherit directly from root_page.html.

The default content of the basic layout is as follows:

{% extends "root_page.html" %}
{% block head %}
    <!-- Put your head content here, without <head></head> tags -->
{{ super() }}
{% endblock %}
{% block body %}
    <!-- Put your body content here, without <body></body> tags -->
{% endblock %}
{% block scripts %}
    <!-- Put your loadable scripts here -->
{{ super() }}
{% endblock %}

We want to define all the common elements in our web site or web application in this file and then create new templates that inherit from this file. To create a new template for our application index we can do it with the mamba-admin command tool:

$ mamba-admin view index

The command above will generate a new index.html template file inside application/view/templates directory with the following content:

{% extends "layout.html" %}
    {% block content %}
    {{ super() }}

    <!--
        Copyright (c) 2013 - damnwidget <damnwidget@localhost>

        view: Index
            synopsis: None

        viewauthor: damnwidget <damnwidget@localhost>
    -->

    <h2>It works!</h2>

    {% endblock %}

As you can see, this new template file inherits from layout.html, as we already defined our web site layout we have only to take care of the content of this especific template or page, in this way we don’t need to rewrite unnecessary HTML code in every template in our web site.

We can create as many template files as we want for our application but those templates are just static templates their content is really inmutable. Sometimes this us just what you want because you are creating a single page application for example and what you need is just load some JavaScript files that really takes care of all the frontend related actions.

To generate dynamic content for our templates we need controllers and routes that call actions in those controllers and then render a view based in our template files.

The Mamba Template class¶

The way that Mamba controllers have to render our templates is just using the mamba.core.templating.Template class. We can render whatever template that we need instantiating those classes and calling their render method with the arguments that we need.

...
from mamba.core import interfaces, templating
...

class DummyController(Controller):
    """Just a dummy example controller
    """

    name = 'Dummy'
    __route__ = 'dummy'

    def __init__(self):
        super(DummyController, self).__init__()
        self.template = templating.Template(controller=self)

When we pass self as the controller argument to the constructor we are telling Mamba to look for templates also in the controller templates directory. Every template that is inside this directory hides whatever other template that is located in the general templates directory (application/view/templates) that has the same name.

$ mamba-admin view root DummyController

{% extends "layout.html" %}
    {% block content %}
    {{ super() }}

    <h2>Hello {{ name }}!</h2>

    {% endblock %}

@route('/')
def root(self, request, **kwargs):
    """Renders the DummyController main page
    """

    template_args = {'name': 'Mamba'}
    return Ok(self.template.render(**template_args).encode('utf-8'))

<ul class="nav">
  {% if menu %}
    {% macro selected_li(path, label, active, available, caller) -%}
    <li {% if active %} class="active" {% endif %}><a {% if not available %} data-toggle="modal" data-target="#notYetModal" {% endif %} href="{{ path }}">{{ label }}</a></li>
    {%- endmacro %}
    {% for link in menu_options %}
      {% call selected_li(link.path, link.label, link.active, link.available) %}
      {% endcall %}
    {% endfor %}
  {% else %}
    <li class="active"><a href="/index">Home</a></li>
    <li><a href="#gettingstart">Get started</a></li>
    <li><a href="#docs">Documentation</a></li>
    <li><a href="download">Download</a></li>
    <li><a href="#blog">Blog</a></li>
    <li><a href="contact">Contact</a></li>
  {% endif %}
</ul>

# Controllers should be placed here

"""
Some helper functions and stuff here to make our life easier
"""

HOME, GET_STARTED, DOCUMENTATION, DOWNLOAD, BLOG, CONTACT = range(6)

template_args = {
    'menu': True,
    'menu_options': [
        {'path': '/', 'label': 'Home', 'active': False, 'available': True},
        {
            'path': 'gettingstart', 'label': 'Get started',
            'active': False, 'available': True
        },
        {
            'path': 'docs', 'label': 'Documentation',
            'active': False, 'available': True
        },
        {
            'path': 'download', 'label': 'Download',
            'active': False, 'available': True
        },
        {'path': 'blog', 'label': 'Blog', 'active': False, 'available': True},
        {
            'path': 'contact', 'label': 'Contact',
            'active': True, 'available': True
        },
    ]
}


def toggle_menu(menu_entry):
    """
    Toggle all the active state menus that are not the given menu entry to
    inactive and set the given one as active

    :param menu_entry: the menu entry to active
    :type menu_entry: dict
    """

    menu = template_args['menu_options'][menu_entry]
    if menu['available'] is False:
        return

    for item in template_args['menu_options']:
        if item['active']:
            if item == menu:
                continue

            item['active'] = False

    menu['active'] = True

from application import controller

class Downloads(Controller):
...
    @route('/', method=['GET', 'POST'])
    @defer.inlineCallbacks
    def root(self, request, **kwargs):
        """Renders downloads main page
        """

        controller.toggle_menu(controller.DOWNLOAD)
        template_args = controller.template_args

        template_args['releases'] = yield Release().last_release_files()
        template_args['old_releases'] = yield Release().old_release_files()

        defer.returnValue(
            Ok(self.template.render(**template_args).encode('utf-8')))
...

Auto compiling LESS scripts¶

Mamba can auto-compile LESS scripts if the lessc tool has been installed on the system and it’s available to the user that is running the Mamba application. In case the lessc tool is not installed on the system, the raw contents of the less file are returned as fallback.

To add a LESS resource to our application we should just place the LESS file into the application/view/stylesheets directory with the following header:

/*
 * -*- mamba-file-type: mamba-less -*-
 */
 ...

Mamba will try to compile the LESS scripts that are placed in that directory and return it back as already ccompiled CSS contents to the browser in total transparent way.