English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Python Module Configuration

Google App Engine provides a mechanism allowing users to specify their own values for constants and “hook functions” for use by some App Engine modules. Specifying your own values can change the default behavior of those modules based on the application's needs. The file where you specify these constants is `appengine_config.py`. After creating this file, you simply deploy it with your other code.

- Python Module Configuration with appengine_config.py
- Configurable App Engine Modules
- Configuring Your Own Modules with lib_config

## Python Module Configuration with appengine_config.py

Several App Engine modules are configurable using `appengine_config.py`.

To customize the modules, create a new `appengine_config.py` file in your application's root directory. To use this file, you need to define only those constants or hook functions you wish to override. After creating this file, run `appcfg.py update` to deploy it. The constants and/or hook functions will then be used by those modules internally.

To override a constant, prefix the constant's name with the module name and an underscore, then assign a value. For example, to edit overrides in appstats, you can define the value of KEY_PREFIX

    appstats_KEY_PREFIX = '__my_custom_prefix__'

Naming of overridden hook functions is similar in other modules. For example, in namespace_manager, you can override the hook function `default_namespace_for_request` in `appengine_config.py` as follows:

    import os
    def namespace_manager_default_namespace_for_request():
        return os.environ.get('HTTP_HOST', '')

## Configurable App Engine Modules

The modules listed below are configurable using `appengine_config.py`. By convention, hook functions are lowercase and constants are uppercase:

webapp (For advanced users. Not available in Python 2.7)

- django_setup()
  see `_django_setup()` in appengine/ext/webapp/__init__.py
- django_version (default `None`. Example value '1.2')
- add_wsgi_middleware(app) (default returns app)
  see `run_wsgi_app(app)` in appengine/ext/webapp/util.py

namespace_manager

- default_namespace_for_request() (default returns `None`)

appstats

- see `class ConfigDefaults` in appengine/ext/appstats/recording.py
- see example in appengine/ext/appstats/sample_appengine_config.py

datastore_admin

- BASE_PATH (default `'/_ah/datastore_admin'`)
- MAPREDUCE_PATH (default `'/_ah/mapreduce'`)
- CLEANUP_MAPREDUCE_STATE (default `True`)

remoteapi

- CUSTOM_ENVIRONMENT_AUTHENTICATION
- see `class ConfigDefaults` in appengine/ext/remote_api/handler.py

## Configuring Your Own Modules with lib_config

App Engine also allows you to configure your own modules with constants and hook functions defined in `appengine_config.py`. The `lib_config.register()` function allows you to both register the names of the user-overridable constants and hooks, and to define sensible defaults in case the users don't wish to override them. Internally, `lib_config.register()` attempts to import appengine_config. If successful, it replaces the specified module's defaults with those defined in `appengine_config.py`.

Example usage in my_module.py:

    from google.appengine.api import lib_config

    def _hook_function1_default():
       return 'baz'

    _config = lib_config.register('my_module', {'CONSTANT1': 'foo',
                                                'CONSTANT2': 'bar',
                                                'hook_function1': _hook_function1_default})

Now you can access a user's constants as

    _config.CONSTANT1
    _config.CONSTANT2

and call their hook function as

    _config.hook_function1()

Some programmers like to group their defaults into a class, e.g.

    class _ConfigDefaults(object):
      CONSTANT1 = 'foo'
      CONSTANT2 = 'bar'
      def hook_function1():
          return 'baz'

    _config = lib_config.register('my_module',  _ConfigDefaults.__dict__)

In order to override your defaults, a user could define (in `apphosting_config.py`)

    my_module_CONSTANT1 = 'foofoo'
    my_module_hook_function1 = lambda: 'bazbaz'

As a result, in my_module.py, the following will be true:

- _config.CONSTANT1 is now 'foofoo'
- _config.CONSTANT2 remains 'bar'
- _config.hook_function1() returns 'bazbaz'

The user overrides are available to my_module.py immediately after `lib_config.register()` returns.