Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc(Tutorial): Add explanation for app config (#4137) #4212

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -218,3 +218,4 @@ Table Of Contents
misc
external
contributing
tutorial/index
84 changes: 84 additions & 0 deletions docs/tutorial/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
Tutorial
========

.. contents::
:local:


Purpose of Tutorial
-------------------


`@Arfey <https://github.com/Arfey>`_
`wrote <https://github.com/aio-libs/aiohttp/issues/4137#issuecomment-538248544>`_ :

..

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 <https://github.com/aio-libs/aiohttp/issues/2689>`_
(and `this <https://github.com/aio-libs/aiohttp/issues/2412>`_ ) 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 <https://github.com/aio-libs/aiohttp/issues/2689>`_ .

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 <https://github.com/aio-libs/aiohttp/pull/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 <https://github.com/aio-libs/aiohttp/issues/3876>`_).
`@mrasband <https://github.com/mrasband>`_ suggested to push subapplication
configurations to one of the key in the ``app`` mapping.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@oktak thx for your contribution.

I'm not sure that it's what actually we need. But we can improve that.

  1. We don't need to create a new stage of documentation. Instead of that the better way will be add this information in place where is this used for the first time. I found this place.
  2. We can use Note block for that.
  3. Save all configuration and connection it's just convention (but best practice). We need so easy and shot explain why we need to use this approach and what benefits we get.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@asvetlov may be u will put here a list of some things which u want to show in this part of documentation.

As example:

  • this is helpful when you want to share your setting between subapp because ...

Of course, if you'll a free time.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are the author of #4137, not me.
I appreciate any docs improvement and happy to review but I have no such list of proposals in my memory.