1 .. _site:

     2 

     3 PyAMS site management

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

     5 

     6 PyAMS site management is based on the ZODB.

     7 

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

     9 place:

    10 

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

    12 

    13  - custom request methods are defined

    14 

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

    16 

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

    18 

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

    20 

    21  - custom TALES extensions are registered.

    22 

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

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

    25 

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

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

    28 

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

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

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

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

    33 

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

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

    36 

    37 

    38 *pyams_upgrade* command line script

    39 -----------------------------------

    40 

    41 Pyramid allows to define custom command line scripts for application management. A script called *pyams_upgrade* is

    42 provided by PyAMS_utils package; this script apply the same process as PyAMS site factory, but can also be used to

    43 manage **database generations**. The idea behind this is just to allow custom packages to provide a way to check and

    44 upgrade database configuration away from application startup process:

    45 

    46 .. code-block:: bash

    47 

    48     # ./bin/pyams_upgrade webapp/development.ini

    49 

    50 

    51 A **site generation checker** is just a named utility providing :py:class:`pyams_utils.interfaces.site.ISiteGenerations`

    52 interface. For example, **pyams_security** package provides such utility, to make sure that local site manager

    53 contains a PyAMS security manager and a principal annotation utility:

    54 

    55 .. code-block:: python

    56 

    57     from pyams_utils.site import check_required_utilities

    58 

    59     REQUIRED_UTILITIES = ((ISecurityManager, '', SecurityManager, 'Security manager'),

    60                           (IPrincipalAnnotationUtility, '', PrincipalAnnotationUtility, 'User profiles'))

    61 

    62     @utility_config(name='PyAMS security', provides=ISiteGenerations)

    63     class SecurityGenerationsChecker(object):

    64     """I18n generations checker"""

    65 

    66         generation = 1

    67 

    68         def evolve(self, site, current=None):

    69             """Check for required utilities"""

    70             check_required_utilities(site, REQUIRED_UTILITIES)

    71 

    72 :py:func:`check_required_utilities <pyams_utils.site.check_required_utilities>` is a PyAMS_utils utility function which

    73 can to used to verify that a set of local utilities are correctly registered with the given names and interfaces.