diff --git a/docs/index.rst b/docs/index.rst index c61c14f6d0..83a25acaf2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -218,3 +218,4 @@ Table Of Contents misc external contributing + tutorial/index diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst new file mode 100644 index 0000000000..040030c9e5 --- /dev/null +++ b/docs/tutorial/index.rst @@ -0,0 +1,84 @@ +Tutorial +======== + +.. contents:: + :local: + + +Purpose of Tutorial +------------------- + + +`@Arfey `_ +`wrote `_ : + +.. + + Tutorial is story about show how may looks project on aiohttp and how u need + to design it. The main documentation is about how work and why. + + + +Why does Aiohttp choose sharing settings? +----------------------------------------- + +There are `discussion `_ +(and `this `_ ) on +configurations for nested applictation (subapplication). Subapplications can be +separated entities, having their own configurations, for e.g. database or +cache purposes. + +Web developers want the main applictation to control the subapplications, +this requires a mechanism for the app to access the context. + +Centralization of configurations has the benefits listed as the following: + +1. **Easy management** + +In the case of subapplications exist, communication between main app and +subapplications is common. Aiohttp choose to set the configurations in +main app's context. Subapplications hence can access the settings at the +stage of initialization. + +This mechanism is similar to the implementation of Flask offering a 'g' variable. + +More details can be found `here `_ . + +2. **Keep it simple** + +Keeping a list of db connection instances at runtime can achieve it. But it +comes up ordering problems, like managing the lifecycle of things like a +database connection, scheduler, etc. + +Conclusion +^^^^^^^^^^ + +Making use of ``request.config_dict`` +(`#2949 `_ feature) is the way +out. + +An typical way to setup an app: + +.. code-block:: python + + async def init_pg(app): + conf = app['config']['postgres'] + engine = await aiopg.sa.create_engine( + database=conf['database'], + user=conf['user'], + password=conf['password'], + host=conf['host'], + port=conf['port'], + minsize=conf['minsize'], + maxsize=conf['maxsize'], + ) + app['db'] = engine + +Further discussion +^^^^^^^^^^^^^^^^^^ + +`cleanup_ctx` is the mechanism to handle a subapplication starting up and +cleaning up. The discussion is ongoing ` (issue +`#3876 `_). +`@mrasband `_ suggested to push subapplication +configurations to one of the key in the ``app`` mapping.