diff -r 53dc81f933ed -r 985534bc6ab9 docs/source/site.rst --- a/docs/source/site.rst Thu Jan 11 16:57:23 2018 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,73 +0,0 @@ -.. _site: - -PyAMS site management -===================== - -PyAMS site management is based on the ZODB. - -On application startup, if PyAMS_utils package is included into Pyramid configuration, several operations take -place: - - - a custom **site factory** is defined - - - custom request methods are defined - - - a custom **traverser** handling **namespaces** is defined - - - a custom subscribers predicate based on interfaces support is defined - - - several adapters are registered, to handle annotations and key references - - - custom TALES extensions are registered. - -The site factory is an important component in this process. It is this factory which will define the application root -and create a **local site manager**. - -Pyramid application is loaded from ZODB's root via a key defined in Pyramid's configuration file; the key is named -*pyams.application_name* and it's default value is *application*. - -If the application can't be found, PyAMS is looking for an application class name in Pyramid's configuration file; the -class name configuration key is called *pyams.application_factory* and defined by default as -*pyams_utils.site.BaseSiteRoot*. PyAMS default site factory will then create the application, and add a local site -manager to it (see :ref:`zca`). - -After application creation, a :py:class:`NewLocalSiteCreatedEvent ` is -notified. Custom packages can subscribe to this event to register custom components. - - -*pyams_upgrade* command line script ------------------------------------ - -Pyramid allows to define custom command line scripts for application management. A script called *pyams_upgrade* is -provided by PyAMS_utils package; this script apply the same process as PyAMS site factory, but can also be used to -manage **database generations**. The idea behind this is just to allow custom packages to provide a way to check and -upgrade database configuration away from application startup process: - -.. code-block:: bash - - # ./bin/pyams_upgrade webapp/development.ini - - -A **site generation checker** is just a named utility providing :py:class:`pyams_utils.interfaces.site.ISiteGenerations` -interface. For example, **pyams_security** package provides such utility, to make sure that local site manager -contains a PyAMS security manager and a principal annotation utility: - -.. code-block:: python - - from pyams_utils.site import check_required_utilities - - REQUIRED_UTILITIES = ((ISecurityManager, '', SecurityManager, 'Security manager'), - (IPrincipalAnnotationUtility, '', PrincipalAnnotationUtility, 'User profiles')) - - @utility_config(name='PyAMS security', provides=ISiteGenerations) - class SecurityGenerationsChecker(object): - """I18n generations checker""" - - generation = 1 - - def evolve(self, site, current=None): - """Check for required utilities""" - check_required_utilities(site, REQUIRED_UTILITIES) - -:py:func:`check_required_utilities ` is a PyAMS_utils utility function which -can to used to verify that a set of local utilities are correctly registered with the given names and interfaces.