Changeset 5649
- Timestamp:
- 11/02/08 22:34:37 (2 months ago)
- Files:
-
- docs/2.0/docs/main/Config.rst (modified) (4 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
docs/2.0/docs/main/Config.rst
r5151 r5649 1 1 TurboGears 2 Configuration 2 2 =================================== 3 4 TurboGears 2 provides a configuration system that attempts to be both extremely flexible for power users and very simple to use for standard projects. 5 6 Overview 7 -------------------------- 3 8 4 9 Like TurboGears 1, the application configuration is separated from the 5 10 deployment specific information. In TG2 there is a config module, containing 6 11 several configuration specific python files -- these are done in python not 7 as INI files, because they actually setup the TG2 application, it's associated 8 WSGI middleware. Besides which, these files are not intended to be edited by 9 application end-users. 10 11 All of this is similar to Pylons, but we've tried to make the configuration 12 as declarative as possible, and to move some of the code into the framework 13 to make end-user updates easier to process. 12 as INI files, because they actually setup the TG2 application and it's associated WSGI middleware. And these files are intended to be edited only by application developers, not by those deploying the application. 13 14 At the same time the deployment level configuration is done in simple .ini files. 15 16 All of this is similar to Pylons and to TurboGears 1, but slightly different from both. 17 18 Differences from TurboGears 1 19 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 20 21 Differences from Pylons 22 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 23 24 TG2 has done quite a bit of work to simplify the config module in a standard pylons quickstart, and to make the configuration in those files 25 as declarative as possible. This makes it easier to make small updates to the config, and allows us to move some of the code into the framework. This is particularly is important, as it allows the framework to evolve and change the middleware stack without forcing developers to constantly update their code with every release. 26 27 14 28 15 29 The config module … … 23 37 it belongs in the ini files. 24 38 25 Our hope is that 90% of applications don't need to edit any of the config module 26 files, but for those who do, the most common file to change is 39 Our hope is that 90% of applications don't need to edit any of the config module files, but for those who do, the most common file to change is 27 40 ``app_config.py`` 28 41 29 .. code:: Wiki-20/wiki20/config/app_cfg.py 30 :revision: 4842 42 .. code:: wiki_root/trunk/wiki20/config/app_cfg.py 31 43 :language: python 32 44 33 app_cfg.py exists primarily so that middleware.py and environment'py can import 34 and use the ``base_config`` object. 45 app_cfg.py exists primarily so that middleware.py and environment'py can import and use the ``base_config`` object. 35 46 36 The ``base_config`` object is an ``AppConfig()`` instance which acts either like a 37 normal object, or like a dictorary. ``AppConfig()`` profides some sane defaults 38 in it's ``__init__``, but more than that it provides us with several methods that 39 work on the config values to produce the two functions that setup your 40 TurboGears app. Since this is all done in your code, you can subclass or 41 overide ``AppConfig`` to get exactly the setup you want. 47 The ``base_config`` object is an ``AppConfig()`` instance which allows you to 48 access it's attributes like a normal object, or like a standard python dictorary. One of the reasons for this is that ``AppConfig()`` provides some defaults in it's ``__init__``. But equally important it provides us with several methods that work on the config values to produce the two functions that setup your TurboGears app. Since this is all done in your code, you can subclass or overide ``AppConfig`` to get exactly the setup you want. 42 49 43 The ``base_config`` object is special in that it transparently maps all 44 attribute access to an underlying dictionary. So, any attributes you add or 45 update will be automatically changed in the underlying dictionary. 50 The ``base_config`` object that's created in app_cfg.py should be used to set whatever configuration values that belong to the application itself and are required for all instances of this app, as distinct from the configuration values that you set in the development.ini or production.ini files that are intended to be editable by those who deploy the app. 46 51 47 If you'd prefer not t use this feature, you can just 48 treat it like a dictionary. As part of the app loading process the 49 ``base_config`` object will be merged in with the config values from the .ini file you're using 50 to launch your app, and placed in in ``pylons.config``. 52 As part of the app loading process the ``base_config`` object will be merged in with the config values from the .ini file you're using to launch your app, and placed in in ``pylons.config``. 51 53 52 In addition to the attributes on the ``base_config`` object there are a number of 53 methods which are used to setup the environment for you application, and to 54 create the actual Turbogears WSGI application, and all the middleware you need. 54 As we said, in addition to the attributes on the ``base_config`` object there are a number of methods which are used to setup the environment for you application, and tocreate the actual Turbogears WSGI application, and all the middleware you need. 55 55 56 You can override these methods to further customize you application, for various 57 advanced use cases, like adding custom middleware at arbitrary points in the 58 WSGI stack, or doing some unanticipated (by us) application environment 59 manipulation. 56 You can override base_config's methods to further customize you application's WSGI stack, for various advanced use cases, like adding custom middleware at arbitrary points in the WSGI pipeline, or doing some unanticipated (by us) application environment manipulation. And we'll look at the details of how that all works in the advanced configuration section of this document. 60 57 61 58 Setting up the base configuration for your app … … 92 89 Let's take a closer look at the development.ini file: 93 90 94 .. code:: Wiki-20/development.ini95 :revision: 484296 :language: ini97 91 98 92 These files are standard INI files, as used by Paste Deploy. The individual 99 93 sections are marked of with ``[]``'s. 100 94 95 There's complete Paste Deploy documentation available at: 96 97 http://pythonpaste.org/deploy/ 98 99 100 101 .. code:: wiki_root/trunk/development.ini 102 :language: ini 103 :section: default 101 104 102 105 .. seealso:: … … 105 108 <http://pythonpaste.org/deploy/>`_. 106 109 110 111 Advanced Configuration 112 =================================== 113 114 115 Modifying the environment loader and middleware stack 116 -------------------------------------------------------- 117 118 We've created a number of methods that you can use to override the way that particular pieces of the TG2 stack are configured. 119 120 .. automodule:: tg.configuration 121 .. autoclass:: AppConfig 122 :members: 107 123 108 124 Embedding a TG app inside another TG app
