Skip to content

Commit

Permalink
sh*t pypi does not want literalinclude
Browse files Browse the repository at this point in the history
  • Loading branch information
Fabien Coelho authored and zx80 committed Aug 20, 2024
1 parent 76f4420 commit 4871352
Showing 1 changed file with 50 additions and 9 deletions.
59 changes: 50 additions & 9 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -123,9 +123,19 @@ Install from `pypi <https://pypi.org/project/aiosql>`__, for instance by running
Then write parametric SQL queries in a file and execute it from Python methods,
eg this *greetings.sql* file:

.. literalinclude:: ../../example/greetings.sql
:language: sql
:caption: Greetings Queries
.. code:: sql
-- name: get_all_greetings
-- Get all the greetings in the database
select greeting_id, greeting
from greetings
order by 1;
-- name: get_user_by_username^
-- Get a user from the database using a named parameter
select user_id, username, name
from users
where username = :username;
This example has an imaginary SQLite database with greetings and users.
It prints greetings in various languages to the user and showcases the basic
Expand All @@ -135,16 +145,47 @@ in python code.
You can use ``aiosql`` to load the queries in this file for use in your Python
application:

.. literalinclude:: ../../example/greetings.py
:language: python
:caption: Synchronous Queries
.. code:: python
import aiosql
import sqlite3
queries = aiosql.from_path("greetings.sql", "sqlite3")
with sqlite3.connect("greetings.db") as conn:
user = queries.get_user_by_username(conn, username="willvaughn")
# user: (1, "willvaughn", "William")
for _, greeting in queries.get_all_greetings(conn):
# scan: (1, "Hi"), (2, "Aloha"), (3, "Hola"), …
print(f"{greeting}, {user[2]}!")
# Hi, William!
# Aloha, William!
#
Or even in an asynchroneous way, with two SQL queries running in parallel
using ``aiosqlite`` and ``asyncio``:

.. literalinclude:: ../../example/greetings_async.py
:language: python
:caption: Asynchronous Queries
.. code:: python
import asyncio
import aiosql
import aiosqlite
queries = aiosql.from_path("greetings.sql", "aiosqlite")
async def main():
# Parallel queries!!!
async with aiosqlite.connect("greetings.db") as conn:
greetings, user = await asyncio.gather(
queries.get_all_greetings(conn),
queries.get_user_by_username(conn, username="willvaughn")
)
for _, greeting in greetings:
print(f"{greeting}, {user[2]}!")
asyncio.run(main())
It may seem inconvenient to provide a connection on each call.
You may have a look at the `AnoDB <https://github.com/zx80/anodb>`__ `DB`
Expand Down

0 comments on commit 4871352

Please sign in to comment.