Create an application

This document describes how to create an application using the Nagare framework.

In the following chapters, we will create the application named my_app.

1. Create the application skeleton

In a directory of your choice, create the application skeleton:

<NAGARE_HOME>/bin/nagare-admin create-app my_app

This command creates a my_app directory with the structure:

  • setup.py – setuptools configuration file
  • conf – directory with all the configuration files of the application
  • data – data directory, contains all the read/write data (database files for example) used by the application
  • static – static directory, contains all the read only data (images, css, js…) used by the application
  • my_app – source directory, contains the application source files

2. Configure your application

2.1. File setup.py

In your application directory, edit the setup.py file:

VERSION = '0.0.1'

from setuptools import setup, find_packages

setup(
      name = 'my_app',
      version = VERSION,
      author = '',
      author_email = '',
      description = '',
      license = '',
      keywords = '',
      url = '',
      packages = find_packages(),
      include_package_data = True,
      package_data = {'' : ['*.cfg']},
      zip_safe = False,
      install_requires = ('nagare',),
      entry_points = """
      [nagare.applications]
      my_app = my_app.app:app
      """
     )

Change the keywords of the setup() call (ie: author = ‘John Doe’, description = ‘This is my first application’…) to correctly describe your application.

Note that the install_requires keyword initially list the nagare package. Such that, if someone wants to install you application in a system where Nagare is not currently installed, it will be automatically downloaded and installed.

The available keywords are described into the Packaging and Distributing Projects documentation.

2.2. Application configuration file

Edit the conf/my_app.cfg file:

[application]
path = app my_app
name = my_app
debug = off

[database]
activated = off
uri = sqlite:///$here/../data/my_app.db
metadata = my_app.models:__metadata__
debug = off

Note

The structure and informations in this file are described with details in The application configuration file.

Briefly, the [application] section contains:

  • path – factory component reference, used by the framework to create the root component of the application
  • name – the url of the application (i.e http://localhost:8080/my_app)
  • debug – debug mode to (de)activate the web error page

and the [database] section contains:

  • activated – indicate if the application uses a database
  • uri – database URI for SQLAlchemy
  • metadata – reference to the SQLAlchemy metadata object
  • debug – debug mode to (de)activate the display of the SQL requests

3. Register your application to the Nagare framework

As the default generated setup.py declares a nagare.applications entry point, once installed, the application is automatically registered to Nagare.

So to register your application, go into the my_apps directory and simply enter the command:

<NAGARE_HOME>/bin/python setup.py develop

Note

The entry points you can declare in the setup.py file are described in Entry points.

You can check your application is correctly registered by launching the command:

<NAGARE_HOME>/bin/nagare-admin serve

which list all the applications known by the framework.

4. Create the database

Note

The document Database tier describes how to set and use a relational database with the framework.

If your application uses a database you will need to create the database tables prior to launch the application:

<NAGARE_HOME>/bin/nagare-admin create-db my_app

The options available with the create-db administrative command are:

-d, --debug to display of the generated SQL requests
--drop drop the tables if they exist, prior to re-create them
--no-populate don’t call the populate function after the tables creation

The database tables can be removed with the command:

<NAGARE_HOME>/bin/nagare-admin drop-db my_app

5. Launch your application

The following command launches the application:

<NAGARE_HOME>/bin/nagare-admin serve my_app

which becomes available at http://localhost:8080/my_app

These options are interesting when you are in development mode:

-d, --debug display a specialized web error page when an exception occur
--reload automatically reload the application when one of its source file is changed

Note

The nagare-admin guide lists the several administrative commands with all their options

6. Distribute your application

When your application is ready to be released, you can create a source distribution (tarball on Unix, ZIP file on Windows) with the command (into the my_apps directory):

<NAGARE_HOME>/bin/python setup.py sdist

The source distribution is created into the dist directory.

If you want to globally distribute your application, you can register on the central PyPI repository and uploaded it there.

You can also create a binary distribution (ie. a wheel) or a Windows installer for example, as explain in Packaging your Project