docs/source/site.rst
changeset 72 9049384a2bd4
equal deleted inserted replaced
71:01d01045a2b7 72:9049384a2bd4
       
     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.