google.appengine.api.lib_config module

Summary

A mechanism for library configuration.

Whenever App Engine library code needs a user-configurable value, it should use the following protocol:

  1. Pick a prefix unique to the library module, for example: mylib.

  2. Call lib_config.register(prefix, mapping) with that prefix as the first argument and a dict mapping suffixes to default functions as the second.

  3. The register() function returns a configuration handle that is unique to this prefix. The configuration handle object has attributes that correspond to each of the suffixes given in the mapping. Call these functions to access the user’s configuration value. If the user didn’t configure a function, the default function from the mapping is called instead.

  4. Document the function name and its signature and semantics.

Users that want to provide configuration values should create a module named appengine_config.py in the top-level directory of their application and define functions as documented by various App Engine library components in that module. To change the configuration, edit the file and re-deploy the application. When using the SDK, no redeployment is required; the development server will pick up the changes the next time it handles a request.

Third party libraries can also use this mechanism. For casual use, calling the register() method with a unique prefix is acceptable. For more complex libraries, however, you should instantiate a new LibConfigRegistry instance that uses a different module name.

Example appengine_config.py file:

from somewhere import MyMiddleWareClass

def mylib_add_middleware(app):
  app = MyMiddleWareClass(app)
  return app

Example library use:

from google.appengine.api import lib_config

config_handle = lib_config.register(
    'mylib',
    {'add_middleware': lambda app: app})

def add_middleware(app):
  return config_handle.add_middleware(app)

Contents

class google.appengine.api.lib_config.LibConfigRegistry(modname)source

Bases: object

A registry containing library configuration values.

initialize(import_func=import_module)source

Tries to import the configuration module if it is not already imported.

This function always sets self._module to a value that is not None; either the imported module (if it was imported successfully) or a dummy object() instance (if an ImportError was raised) is used. Other exceptions are not caught.

When a dummy instance is used, the instance is also put in sys.modules. This usage allows us to detect when sys.modules was changed (as dev_appserver.py does when it notices source code changes) and retries the import_module in that case, while skipping it (for speed) if nothing has changed.

Parameters

import_func – Used for dependency injection.

register(prefix, mapping)source

Registers a set of configuration names.

Parameters

  • prefix – A shared prefix for the configuration names being registered. If the prefix doesn’t end in _, that character is appended.

  • mapping – A dict that maps suffix strings to default values.

Returns

A ConfigHandle instance.

You can re-register the same prefix: the mappings are merged, and for duplicate suffixes, the most recent registration is used.

reset()source

Drops the imported configuration module.

If the configuration module has not been imported, no operation occurs, and the next operation takes place.

class google.appengine.api.lib_config.ConfigHandle(prefix, registry)source

Bases: object

A set of configuration for a single library module or package.

Public attributes of instances of this class are configuration values. Attributes are dynamically computed (in __getattr__()) and cached as regular instance attributes.

google.appengine.api.lib_config.register(prefix, mapping)source

Register a set of configurations with the default config module.

Parameters

  • prefix – A shared prefix for the configuration names being registered. If the prefix doesn’t end in _, that character is appended.

  • mapping – A dict mapping suffix strings to default values.

Returns

A ConfigHandle instance.

google.appengine.api.lib_config.main()source

Dumps the configuration, using a CGI-style request handler.

Put this in your app.yaml file to enable (you can pick any URL):

- url: /lib_config
  script: $PYTHON_LIB/google/appengine/api/lib_config.py