Skip to content

Commit 1c495ec

Browse files
krylosov-aakrylosov-aa
committed
update docs
1 parent ecc0df5 commit 1c495ec

File tree

20 files changed

+392
-350
lines changed

20 files changed

+392
-350
lines changed

‎README.md‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,28 @@
44

55
[DOCUMENTATION](https://krylosov-aa.github.io/context-async-sqlalchemy/)
66

7-
Provides a super convenient way to work with sqlalchemy in asynchronous
8-
applications. It takes care of the issues of managing the lifecycle of engine,
9-
session, and transactions without being a wrapper.
10-
11-
The main task is to get quick and easy access to the session and not worry
12-
about when to open and when to close it.
13-
14-
The key features are:
15-
16-
- Super easy to use
17-
- Automatically manages the lifecycle of engine, session, and transaction
18-
(autocommit/autorollback)
19-
- It doesn't interfere with manually opening and closing sessions and
20-
transactions when needed.
21-
- Does not depend on the web framework
22-
- It is not a wrapper over sqlalchemy
23-
- It is convenient to test
24-
- Host switching in runtime
25-
- It can manage multiple databases and multiple sessions to a single database
26-
- Provides tools for concurrent sql queries
27-
- Lazy initialization is everywhere
7+
Provides a super convenient way to work with SQLAlchemy in asynchronous
8+
applications.
9+
It handles the lifecycle management of the engine, sessions, and
10+
transactions.
11+
12+
The main goal is to provide quick and easy access to a session,
13+
without having to worry about opening or closing it when it’s not necessary.
14+
15+
Key features:
16+
17+
- Extremely easy to use
18+
- Automatically manages the lifecycle of the engine, sessions, and
19+
transactions (autocommit / autorollback)
20+
- Does not interfere with manually opening or closing sessions and
21+
transactions when needed
22+
- Framework-agnostic - works with any web framework
23+
- Not a wrapper around SQLAlchemy
24+
- Convenient for testing
25+
- Runtime host switching
26+
- Supports multiple databases and multiple sessions per database
27+
- Provides tools for running concurrent SQL queries
28+
- Fully lazy initialization
2829

2930

3031
## What does usage look like?

‎docs/404.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,19 +37,19 @@
3737
</li>
3838
</ul>
3939
<ul>
40-
<li class="toctree-l1"><a class="reference internal" href="/problem/">What problems it solves</a>
40+
<li class="toctree-l1"><a class="reference internal" href="/problem/">The Problem It Solves</a>
4141
</li>
4242
</ul>
4343
<ul>
44-
<li class="toctree-l1"><a class="reference internal" href="/getting_started/">Getting started</a>
44+
<li class="toctree-l1"><a class="reference internal" href="/getting_started/">Getting Started</a>
4545
</li>
4646
</ul>
4747
<ul>
48-
<li class="toctree-l1"><a class="reference internal" href="/examples">Usage examples</a>
48+
<li class="toctree-l1"><a class="reference internal" href="/examples">Usage Examples</a>
4949
</li>
5050
</ul>
5151
<ul>
52-
<li class="toctree-l1"><a class="reference internal" href="/concurrent_queries/">Concurrent sql queries</a>
52+
<li class="toctree-l1"><a class="reference internal" href="/concurrent_queries/">Concurrent SQL Queries</a>
5353
</li>
5454
</ul>
5555
<ul>

‎docs/concurrent_queries/index.html‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
66
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
77
<link rel="shortcut icon" href="../img/favicon.ico" />
8-
<title>Concurrent sql queries - context-async-sqlalchemy</title>
8+
<title>Concurrent SQL Queries - context-async-sqlalchemy</title>
99
<link rel="stylesheet" href="../css/theme.css" />
1010
<link rel="stylesheet" href="../css/theme_extra.css" />
1111
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
1212

1313
<script>
1414
// Current page data
15-
var mkdocs_page_name = "Concurrent sql queries";
15+
var mkdocs_page_name = "Concurrent SQL Queries";
1616
var mkdocs_page_input_path = "concurrent_queries.md";
1717
var mkdocs_page_url = null;
1818
</script>
@@ -44,19 +44,19 @@
4444
</li>
4545
</ul>
4646
<ul>
47-
<li class="toctree-l1"><a class="reference internal" href="../problem">What problems it solves</a>
47+
<li class="toctree-l1"><a class="reference internal" href="../problem">The Problem It Solves</a>
4848
</li>
4949
</ul>
5050
<ul>
51-
<li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting started</a>
51+
<li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting Started</a>
5252
</li>
5353
</ul>
5454
<ul>
55-
<li class="toctree-l1"><a class="reference internal" href="../examples">Usage examples</a>
55+
<li class="toctree-l1"><a class="reference internal" href="../examples">Usage Examples</a>
5656
</li>
5757
</ul>
5858
<ul class="current">
59-
<li class="toctree-l1 current"><a class="reference internal current" href="#">Concurrent sql queries</a>
59+
<li class="toctree-l1 current"><a class="reference internal current" href="#">Concurrent SQL Queries</a>
6060
<ul class="current">
6161
</ul>
6262
</li>
@@ -87,22 +87,22 @@
8787
<div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
8888
<ul class="wy-breadcrumbs">
8989
<li><a href=".." class="icon icon-home" aria-label="Docs"></a></li>
90-
<li class="breadcrumb-item active">Concurrent sql queries</li>
90+
<li class="breadcrumb-item active">Concurrent SQL Queries</li>
9191
</ul>
9292
<hr/>
9393
</div>
9494
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
9595
<div class="section" itemprop="articleBody">
9696

9797
<h1 id="concurrent-sql-queries">Concurrent sql queries</h1>
98-
<p>Concurrent query execution deserves special attention. In sqlalchemy,
99-
you cannot concurrently run multiple queries within the same session.
100-
You need to create a new session. The library provides 2 ways to execute
101-
queries concurrently very easily:</p>
98+
<p>Concurrent query execution deserves special attention.
99+
In SQLAlchemy, you can’t run multiple queries concurrently within the same
100+
session - you need to create a new one.</p>
101+
<p>The library provides two simple ways to execute queries concurrently:</p>
102102
<ul>
103-
<li>calling a function with a new context - <code>run_in_new_ctx</code></li>
104-
<li>get a new session that doesn't fit into the context at all -
105-
<code>new_non_ctx_atomic_session</code> or <code>new_non_ctx_session</code> </li>
103+
<li>Run a function in a new context - <code>run_in_new_ctx</code></li>
104+
<li>Create a new session that is completely independent of the current context -
105+
<code>new_non_ctx_atomic_session</code> or <code>new_non_ctx_session</code></li>
106106
</ul>
107107
<pre><code class="language-python">import asyncio
108108

@@ -180,7 +180,7 @@ <h1 id="concurrent-sql-queries">Concurrent sql queries</h1>
180180
</div>
181181
</div><footer>
182182
<div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
183-
<a href="../examples" class="btn btn-neutral float-left" title="Usage examples"><span class="icon icon-circle-arrow-left"></span> Previous</a>
183+
<a href="../examples" class="btn btn-neutral float-left" title="Usage Examples"><span class="icon icon-circle-arrow-left"></span> Previous</a>
184184
<a href="../master_replica" class="btn btn-neutral float-right" title="Master/Replica or several databases at the same time">Next <span class="icon icon-circle-arrow-right"></span></a>
185185
</div>
186186

‎docs/examples/index.html‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
66
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
77
<link rel="shortcut icon" href="../img/favicon.ico" />
8-
<title>Usage examples - context-async-sqlalchemy</title>
8+
<title>Usage Examples - context-async-sqlalchemy</title>
99
<link rel="stylesheet" href="../css/theme.css" />
1010
<link rel="stylesheet" href="../css/theme_extra.css" />
1111
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
1212

1313
<script>
1414
// Current page data
15-
var mkdocs_page_name = "Usage examples";
15+
var mkdocs_page_name = "Usage Examples";
1616
var mkdocs_page_input_path = "examples.md";
1717
var mkdocs_page_url = null;
1818
</script>
@@ -44,15 +44,15 @@
4444
</li>
4545
</ul>
4646
<ul>
47-
<li class="toctree-l1"><a class="reference internal" href="../problem">What problems it solves</a>
47+
<li class="toctree-l1"><a class="reference internal" href="../problem">The Problem It Solves</a>
4848
</li>
4949
</ul>
5050
<ul>
51-
<li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting started</a>
51+
<li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting Started</a>
5252
</li>
5353
</ul>
5454
<ul class="current">
55-
<li class="toctree-l1 current"><a class="reference internal current" href="#">Usage examples</a>
55+
<li class="toctree-l1 current"><a class="reference internal current" href="#">Usage Examples</a>
5656
<ul class="current">
5757
<li class="toctree-l2"><a class="reference internal" href="#basic-usage">Basic usage</a>
5858
</li>
@@ -66,7 +66,7 @@
6666
</li>
6767
</ul>
6868
<ul>
69-
<li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent sql queries</a>
69+
<li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent SQL Queries</a>
7070
</li>
7171
</ul>
7272
<ul>
@@ -95,7 +95,7 @@
9595
<div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
9696
<ul class="wy-breadcrumbs">
9797
<li><a href=".." class="icon icon-home" aria-label="Docs"></a></li>
98-
<li class="breadcrumb-item active">Usage examples</li>
98+
<li class="breadcrumb-item active">Usage Examples</li>
9999
</ul>
100100
<hr/>
101101
</div>
@@ -372,8 +372,8 @@ <h3 id="rollback">Rollback</h3>
372372
</div>
373373
</div><footer>
374374
<div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
375-
<a href="../getting_started" class="btn btn-neutral float-left" title="Getting started"><span class="icon icon-circle-arrow-left"></span> Previous</a>
376-
<a href="../concurrent_queries" class="btn btn-neutral float-right" title="Concurrent sql queries">Next <span class="icon icon-circle-arrow-right"></span></a>
375+
<a href="../getting_started" class="btn btn-neutral float-left" title="Getting Started"><span class="icon icon-circle-arrow-left"></span> Previous</a>
376+
<a href="../concurrent_queries" class="btn btn-neutral float-right" title="Concurrent SQL Queries">Next <span class="icon icon-circle-arrow-right"></span></a>
377377
</div>
378378

379379
<hr/>

‎docs/getting_started/index.html‎

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
66
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
77
<link rel="shortcut icon" href="../img/favicon.ico" />
8-
<title>Getting started - context-async-sqlalchemy</title>
8+
<title>Getting Started - context-async-sqlalchemy</title>
99
<link rel="stylesheet" href="../css/theme.css" />
1010
<link rel="stylesheet" href="../css/theme_extra.css" />
1111
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
1212

1313
<script>
1414
// Current page data
15-
var mkdocs_page_name = "Getting started";
15+
var mkdocs_page_name = "Getting Started";
1616
var mkdocs_page_input_path = "getting_started.md";
1717
var mkdocs_page_url = null;
1818
</script>
@@ -44,11 +44,11 @@
4444
</li>
4545
</ul>
4646
<ul>
47-
<li class="toctree-l1"><a class="reference internal" href="../problem">What problems it solves</a>
47+
<li class="toctree-l1"><a class="reference internal" href="../problem">The Problem It Solves</a>
4848
</li>
4949
</ul>
5050
<ul class="current">
51-
<li class="toctree-l1 current"><a class="reference internal current" href="#">Getting started</a>
51+
<li class="toctree-l1 current"><a class="reference internal current" href="#">Getting Started</a>
5252
<ul class="current">
5353
<li class="toctree-l2"><a class="reference internal" href="#configure-the-connection-to-the-database">Configure the connection to the database</a>
5454
</li>
@@ -64,11 +64,11 @@
6464
</li>
6565
</ul>
6666
<ul>
67-
<li class="toctree-l1"><a class="reference internal" href="../examples">Usage examples</a>
67+
<li class="toctree-l1"><a class="reference internal" href="../examples">Usage Examples</a>
6868
</li>
6969
</ul>
7070
<ul>
71-
<li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent sql queries</a>
71+
<li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent SQL Queries</a>
7272
</li>
7373
</ul>
7474
<ul>
@@ -97,7 +97,7 @@
9797
<div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
9898
<ul class="wy-breadcrumbs">
9999
<li><a href=".." class="icon icon-home" aria-label="Docs"></a></li>
100-
<li class="breadcrumb-item active">Getting started</li>
100+
<li class="breadcrumb-item active">Getting Started</li>
101101
</ul>
102102
<hr/>
103103
</div>
@@ -106,7 +106,7 @@
106106

107107
<h1 id="getting-started">Getting started</h1>
108108
<h2 id="configure-the-connection-to-the-database">Configure the connection to the database</h2>
109-
<p>for example for PostgreSQL database.py:</p>
109+
<p>For example, for PostgreSQL - database.py:</p>
110110
<pre><code class="language-python">from sqlalchemy.ext.asyncio import (
111111
async_sessionmaker,
112112
AsyncEngine,
@@ -153,7 +153,7 @@ <h2 id="configure-the-connection-to-the-database">Configure the connection to th
153153
)
154154
</code></pre>
155155
<h2 id="manage-database-connection-lifecycle">Manage Database connection lifecycle</h2>
156-
<p>Close the resources at the end of your application's life</p>
156+
<p>Close resources at the end of your application's lifecycle.</p>
157157
<p>Example for FastAPI:</p>
158158
<pre><code class="language-python">from contextlib import asynccontextmanager
159159
from typing import Any, AsyncGenerator
@@ -169,8 +169,9 @@ <h2 id="manage-database-connection-lifecycle">Manage Database connection lifecyc
169169
await connection.close() # Close the engine if it was open
170170
</code></pre>
171171
<h2 id="setup-middleware">Setup middleware</h2>
172-
<p>Middleware takes on the most important and complex work of managing context and sessions.</p>
173-
<p>You can use ready-made middlewares:</p>
172+
<p>Middleware handles the most important and complex part -
173+
managing context and sessions.</p>
174+
<p>You can use the ready-made middleware components:</p>
174175
<h3 id="fastapi">FastAPI</h3>
175176
<pre><code class="language-python">from context_async_sqlalchemy.fastapi_utils import (
176177
add_fastapi_http_db_session_middleware,
@@ -188,8 +189,9 @@ <h3 id="starlette">Starlette</h3>
188189
add_starlette_http_db_session_middleware(app)
189190
</code></pre>
190191
<h3 id="write-own">Write own</h3>
191-
<p>If there is no ready-made solution for you, don't worry! You can see
192-
<a href="../how_middleware_works">how it works</a> and write your own.</p>
192+
<p>If there’s no ready-made solution that fits your needs - don’t worry!
193+
You can check out <a href="../how_middleware_works">how it works</a> and implement your
194+
own.</p>
193195
<h2 id="use-it">Use it</h2>
194196
<pre><code class="language-python">from context_async_sqlalchemy import db_session
195197
from sqlalchemy import insert
@@ -216,19 +218,21 @@ <h2 id="use-it">Use it</h2>
216218
# The commit and closing of the session will occur automatically
217219
</code></pre>
218220
<h2 id="examples">Examples</h2>
219-
<p>The repository includes an example integration with FastAPI,
220-
which describes numerous workflows.
221+
<p>The repository includes an example integration with FastAPI, demonstrating
222+
various workflows:
221223
<a href="https://github.com/krylosov-aa/context-async-sqlalchemy/tree/main/examples/fastapi_example/routes">FastAPI example</a></p>
222-
<p>It also includes two types of test setups you can use in your projects.</p>
223-
<p>All library tests are in the examples, as we want to test not in the abstract
224-
but in the context of a real asynchronous web application.</p>
225-
<p><a href="https://github.com/krylosov-aa/context-async-sqlalchemy/tree/main/examples/fastapi_example/tests">FastAPI tests example</a></p>
224+
<p>It also contains two types of test setups that you can use in your own
225+
projects.</p>
226+
<p>All library tests are included within the examples - because we aim to
227+
test the functionality not in isolation, but in the context of a real
228+
asynchronous web application.
229+
<a href="https://github.com/krylosov-aa/context-async-sqlalchemy/tree/main/examples/fastapi_example/tests">FastAPI tests example</a></p>
226230

227231
</div>
228232
</div><footer>
229233
<div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
230-
<a href="../problem" class="btn btn-neutral float-left" title="What problems it solves"><span class="icon icon-circle-arrow-left"></span> Previous</a>
231-
<a href="../examples" class="btn btn-neutral float-right" title="Usage examples">Next <span class="icon icon-circle-arrow-right"></span></a>
234+
<a href="../problem" class="btn btn-neutral float-left" title="The Problem It Solves"><span class="icon icon-circle-arrow-left"></span> Previous</a>
235+
<a href="../examples" class="btn btn-neutral float-right" title="Usage Examples">Next <span class="icon icon-circle-arrow-right"></span></a>
232236
</div>
233237

234238
<hr/>

‎docs/how_middleware_works/index.html‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -44,19 +44,19 @@
4444
</li>
4545
</ul>
4646
<ul>
47-
<li class="toctree-l1"><a class="reference internal" href="../problem">What problems it solves</a>
47+
<li class="toctree-l1"><a class="reference internal" href="../problem">The Problem It Solves</a>
4848
</li>
4949
</ul>
5050
<ul>
51-
<li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting started</a>
51+
<li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting Started</a>
5252
</li>
5353
</ul>
5454
<ul>
55-
<li class="toctree-l1"><a class="reference internal" href="../examples">Usage examples</a>
55+
<li class="toctree-l1"><a class="reference internal" href="../examples">Usage Examples</a>
5656
</li>
5757
</ul>
5858
<ul>
59-
<li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent sql queries</a>
59+
<li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent SQL Queries</a>
6060
</li>
6161
</ul>
6262
<ul>
@@ -95,11 +95,11 @@
9595
<div class="section" itemprop="articleBody">
9696

9797
<h1 id="how-middleware-works">How middleware works</h1>
98-
<p>The biggest part of the work and magic happens in middleware.
99-
The library strives to provide ready-made solutions so that you don't have to
100-
worry. But they are not always there.
101-
Therefore, we will tell you how starlette middleware works,
102-
using the example of which you can write your own.</p>
98+
<p>Most of the work - and the “magic” - happens inside the middleware.
99+
The library aims to provide ready-made solutions so that you don’t have to
100+
worry about these details - but they’re not always available.</p>
101+
<p>So, let’s take a look at how Starlette middleware works.
102+
You can use this example as a reference to implement your own.</p>
103103
<pre><code class="language-python">from starlette.middleware.base import ( # type: ignore[attr-defined]
104104
Request,
105105
Response,

0 commit comments

Comments
 (0)