kaxil commented on a change in pull request #7483: [AIRFLOW-XXXX] Document new
session handling guidelines
URL: https://github.com/apache/airflow/pull/7483#discussion_r382563376
##########
File path: CONTRIBUTING.rst
##########
@@ -321,6 +326,47 @@ Your code must pass all the static code checks in Travis
CI in order to be eligi
The easiest way to make sure your code is good before pushing is to use
pre-commit checks locally
as described in the static code checks documentation.
+.. _coding_style:
+
+Coding style and best practices
+===============================
+
+Most of your coding style rules are enforced programmatically by flake8 and
pylint (which are run automatically
+on every pull request), but there are some rules that are not yet automated
and are more Airflow specific or
+semantic than style
+
+Database Session Handling
+-------------------------
+
+**Explicit is better than implicit.** If a function accepts a ``session``
parameter it should not commit the
+transaction itself. Session management is up to the caller.
+
+To make this easier there is the ``create_session`` helper:
+
+.. code-block:: python
+
+ from airflow.utils.db import create_session
+
+ def my_call(*args, session):
+ ...
+ # You MUST not commit the session here.
+
+ with create_session() as session:
+ my_call(*args, session=session)
+
+If this function is designed to be called by "end-users" (i.e. DAG authors)
then using the ``@provide_session`` wrapper is okay:
+
+.. code-block:: python
+
+ from airflow.utils.db import provide_session
+
+ ...
+
+ @session
Review comment:
```suggestion
@provide_session
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
