| 1 |
.. _aiomysql-index: |
| 2 |
|
| 3 |
.. aiomysql documentation master file, created by |
| 4 |
sphinx-quickstart on Sun Jun 11 16:24:33 2023. |
| 5 |
You can adapt this file completely to your liking, but it should at least |
| 6 |
contain the root `toctree` directive. |
| 7 |
|
| 8 |
Welcome to aiomysql's documentation! |
| 9 |
==================================== |
| 10 |
|
| 11 |
.. _GitHub: https://github.com/aio-libs/aiomysql |
| 12 |
.. _asyncio: http://docs.python.org/3.5/library/asyncio.html |
| 13 |
.. _aiopg: https://github.com/aio-libs/aiopg |
| 14 |
.. _Tornado-MySQL: https://github.com/PyMySQL/Tornado-MySQL |
| 15 |
.. _aio-libs: https://github.com/aio-libs |
| 16 |
|
| 17 |
|
| 18 |
**aiomysql** is a library for accessing a :term:`MySQL` database |
| 19 |
from the asyncio_ (PEP-3156/tulip) framework. It depends and reuses most parts |
| 20 |
of :term:`PyMySQL` . **aiomysql** tries to be like awesome aiopg_ library and preserve |
| 21 |
same api, look and feel. |
| 22 |
|
| 23 |
Internally **aiomysql** is copy of PyMySQL, underlying io calls switched |
| 24 |
to async, basically ``await`` and ``async def coroutine`` added in |
| 25 |
proper places. :term:`sqlalchemy` support ported from aiopg_. |
| 26 |
|
| 27 |
|
| 28 |
Features |
| 29 |
-------- |
| 30 |
|
| 31 |
* Implements *asyncio* :term:`DBAPI` *like* interface for |
| 32 |
:term:`MySQL`. It includes :ref:`aiomysql-connection`, |
| 33 |
:ref:`aiomysql-cursors` and :ref:`aiomysql-pool` objects. |
| 34 |
* Implements *optional* support for charming :term:`sqlalchemy` |
| 35 |
functional sql layer. |
| 36 |
|
| 37 |
Basics |
| 38 |
------ |
| 39 |
|
| 40 |
**aiomysql** based on :term:`PyMySQL` , and provides same api, you just need |
| 41 |
to use ``await conn.f()`` instead of just call ``conn.f()`` for |
| 42 |
every method. |
| 43 |
|
| 44 |
Properties are unchanged, so ``conn.prop`` is correct as well as |
| 45 |
``conn.prop = val``. |
| 46 |
|
| 47 |
See example: |
| 48 |
|
| 49 |
.. code:: python |
| 50 |
|
| 51 |
import asyncio |
| 52 |
import aiomysql |
| 53 |
|
| 54 |
loop = asyncio.get_event_loop() |
| 55 |
|
| 56 |
|
| 57 |
async def test_example(): |
| 58 |
conn = await aiomysql.connect(host='127.0.0.1', port=3306, |
| 59 |
user='root', password='', db='mysql', |
| 60 |
loop=loop) |
| 61 |
|
| 62 |
cur = await conn.cursor() |
| 63 |
await cur.execute("SELECT Host,User FROM user") |
| 64 |
print(cur.description) |
| 65 |
r = await cur.fetchall() |
| 66 |
print(r) |
| 67 |
await cur.close() |
| 68 |
conn.close() |
| 69 |
|
| 70 |
loop.run_until_complete(test_example()) |
| 71 |
|
| 72 |
|
| 73 |
Installation |
| 74 |
------------ |
| 75 |
|
| 76 |
.. code:: |
| 77 |
|
| 78 |
pip3 install aiomysql |
| 79 |
|
| 80 |
.. note:: :mod:`aiomysql` requires :term:`PyMySQL` library. |
| 81 |
|
| 82 |
|
| 83 |
Also you probably want to use :mod:`aiomysql.sa`. |
| 84 |
|
| 85 |
.. _aiomysql-install-sqlalchemy: |
| 86 |
|
| 87 |
:mod:`aiomysql.sa` module is **optional** and requires |
| 88 |
:term:`sqlalchemy`. You can install *sqlalchemy* by running:: |
| 89 |
|
| 90 |
pip3 install sqlalchemy |
| 91 |
|
| 92 |
Source code |
| 93 |
----------- |
| 94 |
|
| 95 |
The project is hosted on GitHub_ |
| 96 |
|
| 97 |
Please feel free to file an issue on `bug tracker |
| 98 |
<https://github.com/aio-libs/aiomysql/issues>`_ if you have found a bug |
| 99 |
or have some suggestion for library improvement. |
| 100 |
|
| 101 |
The library uses `GitHub Actions |
| 102 |
<https://github.com/aio-libs/aiomysql/actions>`_ for Continuous Integration |
| 103 |
and `Codecov <https://app.codecov.io/gh/aio-libs/aiomysql/branch/main>`_ for |
| 104 |
coverage reports. |
| 105 |
|
| 106 |
|
| 107 |
Dependencies |
| 108 |
------------ |
| 109 |
|
| 110 |
- Python 3.9+ |
| 111 |
- :term:`PyMySQL` |
| 112 |
- aiomysql.sa requires :term:`sqlalchemy`. |
| 113 |
|
| 114 |
|
| 115 |
Authors and License |
| 116 |
------------------- |
| 117 |
|
| 118 |
The ``aiomysql`` package is written by Nikolay Novik, :term:`PyMySQL` and |
| 119 |
aio-libs_ contributors. It's MIT licensed (same as PyMySQL). |
| 120 |
|
| 121 |
Feel free to improve this package and send a pull request to GitHub_. |
| 122 |
|
| 123 |
Contents: |
| 124 |
--------- |
| 125 |
|
| 126 |
.. toctree:: |
| 127 |
:maxdepth: 2 |
| 128 |
:titlesonly: |
| 129 |
|
| 130 |
connection |
| 131 |
cursors |
| 132 |
pool |
| 133 |
tutorial |
| 134 |
sa |
| 135 |
examples |
| 136 |
glossary |
| 137 |
contributing |
| 138 |
|
| 139 |
Indices and tables |
| 140 |
================== |
| 141 |
|
| 142 |
* :ref:`genindex` |
| 143 |
* :ref:`modindex` |
| 144 |
* :ref:`search` |