-
-
Notifications
You must be signed in to change notification settings - Fork 2k
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
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -218,3 +218,4 @@ Table Of Contents | |
misc | ||
external | ||
contributing | ||
tutorial/index |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
Note
block for that.There was a problem hiding this comment.
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:
Of course, if you'll a free time.
There was a problem hiding this comment.
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.