add

2026-10-15 20:36:59 +08:00
commit 6bf949949c
7923 changed files with 1369582 additions and 0 deletions
@@ -0,0 +1,144 @@
+.. _aiomysql-index:
+
+.. aiomysql documentation master file, created by
+   sphinx-quickstart on Sun Jun 11 16:24:33 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to aiomysql's documentation!
+====================================
+
+.. _GitHub: https://github.com/aio-libs/aiomysql
+.. _asyncio: http://docs.python.org/3.5/library/asyncio.html
+.. _aiopg: https://github.com/aio-libs/aiopg
+.. _Tornado-MySQL: https://github.com/PyMySQL/Tornado-MySQL
+.. _aio-libs: https://github.com/aio-libs
+
+
+**aiomysql** is a library for accessing a :term:`MySQL` database
+from the asyncio_ (PEP-3156/tulip) framework. It depends and reuses most parts
+of :term:`PyMySQL` . **aiomysql** tries to be like awesome aiopg_ library and preserve
+same api, look and feel.
+
+Internally **aiomysql** is copy of PyMySQL, underlying io calls switched
+to async, basically ``await`` and ``async def coroutine`` added in
+proper places. :term:`sqlalchemy` support ported from aiopg_.
+
+
+Features
+--------
+
+* Implements *asyncio* :term:`DBAPI` *like* interface for
+  :term:`MySQL`.  It includes :ref:`aiomysql-connection`,
+  :ref:`aiomysql-cursors` and :ref:`aiomysql-pool` objects.
+* Implements *optional* support for charming :term:`sqlalchemy`
+  functional sql layer.
+
+Basics
+------
+
+**aiomysql** based on :term:`PyMySQL` , and provides same api, you just need
+to use  ``await conn.f()`` instead of just call ``conn.f()`` for
+every method.
+
+Properties are unchanged, so ``conn.prop`` is correct as well as
+``conn.prop = val``.
+
+See example:
+
+.. code:: python
+
+    import asyncio
+    import aiomysql
+
+    loop = asyncio.get_event_loop()
+
+
+    async def test_example():
+        conn = await aiomysql.connect(host='127.0.0.1', port=3306,
+                                           user='root', password='', db='mysql',
+                                           loop=loop)
+
+        cur = await conn.cursor()
+        await cur.execute("SELECT Host,User FROM user")
+        print(cur.description)
+        r = await cur.fetchall()
+        print(r)
+        await cur.close()
+        conn.close()
+
+    loop.run_until_complete(test_example())
+
+
+Installation
+------------
+
+.. code::
+
+   pip3 install aiomysql
+
+.. note:: :mod:`aiomysql` requires :term:`PyMySQL` library.
+
+
+Also you probably want to use :mod:`aiomysql.sa`.
+
+.. _aiomysql-install-sqlalchemy:
+
+:mod:`aiomysql.sa` module is **optional** and requires
+:term:`sqlalchemy`. You can install *sqlalchemy* by running::
+
+  pip3 install sqlalchemy
+
+Source code
+-----------
+
+The project is hosted on GitHub_
+
+Please feel free to file an issue on `bug tracker
+<https://github.com/aio-libs/aiomysql/issues>`_ if you have found a bug
+or have some suggestion for library improvement.
+
+The library uses `GitHub Actions
+<https://github.com/aio-libs/aiomysql/actions>`_ for Continuous Integration
+and `Codecov <https://app.codecov.io/gh/aio-libs/aiomysql/branch/main>`_ for
+coverage reports.
+
+
+Dependencies
+------------
+
+- Python 3.9+
+- :term:`PyMySQL`
+- aiomysql.sa requires :term:`sqlalchemy`.
+
+
+Authors and License
+-------------------
+
+The ``aiomysql`` package is written by Nikolay Novik, :term:`PyMySQL` and
+aio-libs_ contributors. It's MIT licensed (same as PyMySQL).
+
+Feel free to improve this package and send a pull request to GitHub_.
+
+Contents:
+---------
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   connection
+   cursors
+   pool
+   tutorial
+   sa
+   examples
+   glossary
+   contributing
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`