<commit_before>.. _configuration:

Configuration
=============
Pecan is very easy to configure. As long as you follow certain conventions;
using, setting and dealing with configuration should be very intuitive.

Python files is what the framework uses to get the values from configuration
files. These files need to specify the values in a key/value way (Python
dictionaries) or if you need simple one-way values you can also specify them as
direct variables (more on that below).

Even if you want custom configuration values, you need to get them in the
configuration file as dictionaries.

No Configuration
----------------
What happens when no configuration is passed? Or if you are missing some values?
Pecan fills in anything that you might have left behind, like specific values or  
even if you leave them out completely. This includes
**app** and **server** but will not, however, include any custom configurations.

Defaults
--------
Below is the complete default values the framework uses::


    server = {
        'port' : '8080',
        'host' : '0.0.0.0'
    }

    app = {
        'root' : None,
        'static_root' : 'public', 
        'template_path' : '',
        'debug' : False
    }



.. _application_configuration:

Application Configuration
-------------------------
This is the part of the configuration that is specific to your application.
Things like debug mode, Root Controller and possible Hooks, should be specified
here. This is what is used when the framework is wrapping your application into
a valid WSGI app.

A typical application configuration would look like this::

    app = {
        'root' : RootController(),
        'static_root' : 'public', 
        'template_path' : 'project/templates',
        'debug' : True 
    }

Let's look at each value and what it means:

**app** is a reserved variable name for the configuration, so make sure you are
not overriding, otherwise you will get default values.

**root** Needs the Root Controller of your application, this where your main
class that points to all the spots in your application should be. Rememeber
that you are passing the actual object so you would need to import it at the
top of the file. In the example configuration, this would be something like::

    from myproject.controllers.root import RootController

**static_root** Points to the directory where your static files live in.

**template_path** The path where your templates are. 

**debug** Enables ``WebError`` to have full tracebacks in the browser (this is
OFF by default).

Any application specifics should go in here in the case that your environment
required it.


.. _server_configuration:

Server Configuration
--------------------
Depending on the WSGI server you choose, you will need some values. As shown
before, Pecan has already some defaults and they would look like this::

    server = {
        'port' : '8080',
        'host' : '0.0.0.0'
    }

There is not too much going on there, it is just specifying the port and the 
host it should use to serve the application. Any other values that you might
need can get added as key/values to that same dictionary so the server of your
choosing can use them.

.. _accessibility:

Accessibility 
--------------
You can access any configuration values at runtime importing ``conf`` from
``pecan``. This includes custom, application and server specific values.
Below is an example on how to access those values for an application::

    >>> from pecan import conf
    >>> conf.app.root
    <test_project.controllers.root.RootController object at 0x10292b0d0>
    >>> conf.app.static_root
    'public'
    >>> conf.app.template_path
    'test_project/templates'
    >>> conf.app.debug
    True



Custom and Single Values
------------------------
There might be times when you do not need to have a dictionary to specify some
values because all you need is a simple key that holds a value. For example, if
you needed to specify a global administrator, you could do so like this within
the configuration file::

    administrator = 'foo_bar_user'

And it would be accessible like this::

    >>>> from pecan import conf
    >>>> conf.administrator
    'foo_bar_user'

Similarly, if I had a custom ``foo`` entry on my configuration file once the 
app is running I can access ``foo`` values like::

    >>> from pecan import conf
    >>> conf.foo.bar
    True
    >>> conf.foo.baz
    False
    >>> conf.foo
    Config({'bar': True, 'baz': False})


Fully Valid Dictionaries
------------------------
In certain situations you might want to deal with keys and values but in strict
dictionary form. The ``Config`` object has a helper method for this purpose
that will return a dictionary representation of itself including nested values.

Below is a representation of how you can access the ``as_dict`` method and what
should return as a result (shortened for brevity):

::

    >>> from pecan import conf
    >>> conf
    Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
    >>> conf.as_dict()
    {'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...]
    

Prefixing Values
----------------
The ``as_dict`` method allows you to pass an optional argument if you need to
prefix the keys in the returned dictionary. This is a single argument in string
form and it works like this (shortened for brevity):

::

    >>> from pecan import conf
    >>> conf
    Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
    >>> conf.as_dict('prefixed_')
    {'prefixed_app': {'prefixed_errors': {}, 'prefixed_template_path': '', 'prefixed_static_root': 'prefixed_public', [...]<commit_msg>Proof-reading configuration docs.<commit_after>.. _configuration:

Configuration
=============
Pecan is very easy to configure. As long as you follow certain conventions;
using, setting and dealing with configuration should be very intuitive.

Python files is what the framework uses to get the values from configuration
files. These files need to specify the values in a key/value way (Python
dictionaries) or if you need simple one-way values you can also specify them as
direct variables (more on that below).

Even if you want custom configuration values, you need to get them in the
configuration file as dictionaries.

No Configuration
----------------
What happens when no configuration is passed? Or if you are missing some values?
Pecan fills in anything that you might have left behind, like specific values or  
even if you leave them out completely. This includes
**app** and **server** but will not, however, include any custom configurations.

Defaults
--------
Below is the complete default values the framework uses::


    server = {
        'port' : '8080',
        'host' : '0.0.0.0'
    }

    app = {
        'root' : None,
        'static_root' : 'public', 
        'template_path' : '',
        'debug' : False
    }



.. _application_configuration:

Application Configuration
-------------------------
This is the part of the configuration that is specific to your application.
Things like debug mode, Root Controller and possible Hooks, should be specified
here. This is what is used when the framework is wrapping your application into
a valid WSGI app.

A typical application configuration would look like this::

    app = {
        'root' : RootController(),
        'static_root' : 'public', 
        'template_path' : 'project/templates',
        'debug' : True 
    }

Let's look at each value and what it means:

**app** is a reserved variable name for the configuration, so make sure you are
not overriding, otherwise you will get default values.

**root** Needs the Root Controller of your application. Remember that you are
passing an object instance, so you'll need to import it at the top of the file.
In the example configuration, this would look something like::

    from myproject.controllers.root import RootController

**static_root** Points to the directory where your static files live.

**template_path** Points to the directory where your template files live.

**debug** Enables ``WebError`` to have full tracebacks in the browser (this is
OFF by default).


.. _server_configuration:

Server Configuration
--------------------
Pecan provides some defaults.  Change these to alter the host and port your
WSGI app is served on.::

    server = {
        'port' : '8080',
        'host' : '0.0.0.0'
    }

.. _accessibility:

Accessing Configuration at Runtime 
----------------------------------
You can access any configuration values at runtime via ``pecan.conf``.
This includes custom, application and server-specific values.
Below is an example on how to access those values from your application::


Custom and Single Values
------------------------
There might be times when you do not need a dictionary, but instead a simple
value. For example, if you needed to specify a global administrator, you could
do so like this within the configuration file::

    administrator = 'foo_bar_user'

And it would be accessible in `pecan.conf` like::

    >>>> from pecan import conf
    >>>> conf.administrator
    'foo_bar_user'


Fully Valid Dictionaries
------------------------
In certain situations you might want to deal with keys and values, but in strict
dictionary form. The ``Config`` object has a helper method for this purpose
that will return a dictionary representation of itself including nested values.

Below is a representation of how you can access the ``as_dict`` method and what
should return as a result (shortened for brevity):

::

    >>> from pecan import conf
    >>> conf
    Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
    >>> conf.as_dict()
    {'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...]
    

Prefixing Values
----------------
``Config.as_dict`` allows you to pass an optional argument if you need to
prefix the keys in the returned dictionary. This is a single argument in string
form and it works like this (shortened for brevity):

::

    >>> from pecan import conf
    >>> conf
    Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
    >>> conf.as_dict('prefixed_')
    {'prefixed_app': {'prefixed_errors': {}, 'prefixed_template_path': '', 'prefixed_static_root': 'prefixed_public', [...]
{'fraction_non_alphanumeric': 0.11434351218572392, 'fraction_numerical': 0.003853193333975532, 'mean_word_length': 3.230643846780766, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 83, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5298279', 'n_tokens_mistral': 2693, 'n_tokens_neox': 2586, 'n_words': 1318}