1 .. _config:

     2 

     3 PyAMS configuration

     4 ===================

     5 

     6 .. Note::

     7 

     8     PyAMS application configuration is done via several complementary ways:

     9 

    10         - via **Pyramid's configuration** files located in 'etc/' folder

    11 

    12         - via **ZCML files** .

    13 

    14         - via **Site Management** to setup Local utilities defined into ZODB (see :ref:`appmanage`)

    15 

    16 

    17 Pyramid's configuration files

    18 -----------------------------

    19 

    20 PyAMS is using default Pyramid's ini_ configuration files to define settings. When using default PyAMS scaffold, these

    21 INI files are stored into *etc* folder. Two files are created by scaffold: a development file (*development.ini*) and

    22 a production file (*production.ini*) which contain nearly the same directives, except for debug toolbar (activated only

    23 in development), Fanstatic configuration and logging.

    24 

    25 .. _ini: https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/project.html#development-ini

    26 

    27 These files are actually documented, but here are a few important directives:

    28 

    29 - **zodbconn.uri**: (ex: zconfig:/zodb-relstorage.conf)

    30 

    31 - **pyams.application_name**: Name of your own application

    32 - **pyams.application_factory**: Configuration module path to your custom application.

    33 

    34 - **pyams_xxx.tcp_handler** :  Adress of the tcp handler for the service associated to the pyams package

    35 - **pyams_xxx.start_handler**: True / False

    36 

    37 - **pyams_content.config.xxx_tool_factory** and **pyams_content.config.xxx_tool_name**: You can override default factory by defining these settings or by providing your own adapters.

    38 

    39 

    40 

    41 Pyramid's configuration files powered by PyAMS_utils

    42 ----------------------------------------------------

    43 

    44 On application startup, if PyAMS_utils package is included into Pyramid configuration, several operations take

    45 place:

    46 

    47  - a custom **site factory** is defined

    48 

    49  - custom request methods are defined

    50 

    51  - a custom **traverser** handling **namespaces** is defined

    52 

    53  - a custom subscribers predicate based on interfaces support is defined

    54 

    55  - several adapters are registered, to handle annotations and key references

    56 

    57  - custom TALES extensions are registered.

    58 

    59 The site factory is an important component in this process. It is this factory which will define the application root

    60 and create a **local site manager**.

    61 

    62 Pyramid application is loaded from ZODB's root via a key defined in Pyramid's configuration file; the key is named

    63 *pyams.application_name* and it's default value is *application*.

    64 

    65 If the application can't be found, PyAMS is looking for an application class name in Pyramid's configuration file; the

    66 class name configuration key is called *pyams.application_factory* and defined by default as

    67 *pyams_utils.site.BaseSiteRoot*. PyAMS default site factory will then create the application, and add a local site

    68 manager to it (see :ref:`zca`).

    69 

    70 After application creation, a :py:class:`NewLocalSiteCreatedEvent <pyams_utils.site.NewLocalSiteCreatedEvent>` is

    71 notified. Custom packages can subscribe to this event to register custom components.

    72 

    73 

    74 

    75 ZCML configuration files

    76 ------------------------

    77 

    78 Adding more ZCML configuration directives is not mandatory in any way but can be useful in several use cases. For

    79 example, templates can't be overriden via Python annotations without creating a new subclass; this can be done

    80 easily via ZCML.