= Development Server =

Diva comes with a couple of simple shortcuts for running your application using the `WSGIServer` from the Python standalone library.

Assuming you have an `Application` subclass (see ApplicationObject), for example:

{{{
#!pycon
>>> from diva.core import Application
>>> class MyApp(Application):
...     pass
}}}

You can then run that application using the development server as follows, directly from the Python shell:

{{{
#!pycon
>>> import logging
>>> from diva.server import serve
>>> serve(MyApp(), log_level=logging.DEBUG)
[INFO] diva.server: Serving <__main__.MyApp object at 0x10f63f0> on 127.0.0.1:8080
}}}

== Command-Line Interface ==

It's also simple to enable your application to be run from the command-line, as shown in the following script:

{{{
#!python
import os
from diva.core import Application
from diva.server import main

class MyApp(Application):
    pass

if __name__ == '__main__':
    main(MyApp())
}}}

Now running that script will automatically launch a simple command-line interface complete with options:

{{{
$ python myapp.py --help
Usage: myapp.py [options]

Options:
  -h, --help            show this help message and exit
  -O name=value         set a configuration option
  -r, --auto-reload     automatically restart after code changes (default off)

  Network:
    -b HOST, --host=HOST
                        hostname or IP address to bind to (default 127.0.0.1)
    -p PORT, --port=PORT
                        port number to listen to (default 8080)
    -z, --zeroconf      advertise server over zeroconf (Bonjour or Avahi)

  Authentication:
    -B FILE, --basic=FILE
                        path to an unencrypted password file to use for basic
                        authentication
    -D FILE, --digest=FILE
                        path to a htdigest file to use for authentication
    --realm=REALM       name of the authentication realm (default "MyApp")
    --protect=PATH      path(s) to protect by authentication

  Logging:
    -v, --verbose       print as much as possible
    -q, --quiet         print as little as possible

}}}

You can use the `-O` option to set one or more configuration options, overriding any defaults set by the application. For example:

{{{
$ python myapp.py -Odebug=false -Ocsrf_protection=false
}}}

See ConfigOptions for a list of options made available by the framework, in addition to any custom options your application may support.

== Logging ==

The development server automatically sets up logging for you, with log messages being written to `stderr` (so they should just show up on the console where you started the server). The verbosity level of the log messages can be controlled with the command-line options `--verbose`/`-v` (for debug-level logging) and `--quiet`/`-q` (for error-level logging). The default is info-level logging.

If `simplejson` is installed, the development server also automatically enables [wiki:FirePHP] support for directing request-related log messages to the [http://www.getfirebug.com/ Firebug console] in the browser.

== Automatic Reloading ==

When the command-line interface is used, automatic restarting of the server can be enabled using the `--auto-reload` (or `-r`) option. This will cause the framework to look for changes to any loaded Python modules, as well as a couple of other files such as [UrlRouting routing configuration files] and [wiki:I18nAndL10n translation catalogs]. Whenever a change is detected the complete server process is restarted. Note that this will sometimes cause a short delay until the server is available again.

Applications can add their own files to the list of watched files using the `watch_file()` function.

== Authentication ==

The development server can inject a WSGI middle component that performs HTTP authentication (either Basic or Digest) against a specified password file. This is intended primarily for developing and testing authorization-sensitive parts of your application. In particular, this middleware is not intended to be used on production systems where security is critical.

The `--digest` option is used to specify the text file containing the credentials for digest authentication, in a format compatible with the [http://httpd.apache.org/docs/2.2/programs/htdigest.html Apache htdigest tool]. The ``--basic`` option allows you to use an unencrypted password file for even simpler setup. The `--realm` option can be used to specify a different realm, where the default is the name of the `Application` class. This realm needs to match the realm used in the digest file.

The format of the password file for Basic authentication is simple: one line per account, containing the username and the password (in the clear) separated by a colon. Note that this format is '''not compatible''' with the format generated by the [http://httpd.apache.org/docs/2.2/programs/htpasswd.html htpasswd] tool, which encrypts the passwords.

Finally, the `--protect` option can be used to require authentication only on the specified sub-resources. When the `--protect` option is not provided, the whole URI space will require authentication. When it is specified, authentication is only required on the specified paths. To protect more than one path, simply specifiy the option as often as you need.

For example:

{{{
$ ./myapp.py -rv --digest auth.digest --protect /login
}}}


== API Documentation ==

[[PythonDoc(trunk, diva.server)]]