VladPolskiy/mariadb-connector-python
1
0
Fork 0
mirror of https://github.com/mariadb-corporation/mariadb-connector-python.git synced 2025-08-11 02:43:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Georg Richter
2021-08-21 18:09:48 +02:00
parent 2ec4130bbe
commit aa6edc38cb
18 changed files with 206 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
doc/source/conf.py
View File

@ -13,6 +13,8 @@
import os
import sys
import mariadb
from typing import Sequence
from datetime import datetime
print(mariadb.__path__)
sys.path.insert(0, os.path.abspath('../..'))
sys.setrecursionlimit(1500)
@ -21,11 +23,13 @@ sys.setrecursionlimit(1500)
# -- Project information -----------------------------------------------------
project = 'MariaDB Connector/Python'
copyright = '2019-2021 MariaDB Corporation and Georg Richter'
copyright = '2019-%s MariaDB Corporation and Georg Richter' % datetime.now().year
author = 'Georg Richter'
# The full version, including alpha/beta/rc tags
release = '1.1.0-alpha'
release = mariadb.__version__
if len(mariadb.__version_info__) > 3:
release= release + "-" + mariadb.__version_info__[3]
# -- General configuration ---------------------------------------------------
@ -33,8 +37,7 @@ release = '1.1.0-alpha'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'recommonmark'
]
extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'recommonmark' ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

2
doc/source/connection.rst
View File

@ -13,7 +13,7 @@ Connection constructors
.. automethod:: mariadb.connections.Connection.cursor
.. versionadded:: 1.0.1
.. automethod:: mariadb.connections.Connection.xid(format_id: int, global_transaction_id: str, brach_qualifier: str)
.. automethod:: mariadb.connections.Connection.xid
------------------
Connection methods

2
doc/source/cursor.rst
View File

@ -1,5 +1,7 @@
The cursor class
====================
.. sectionauthor:: Georg Richter <georg@mariadb.com>
.. autoclass:: mariadb.cursors.Cursor
--------------

53
doc/source/pool.rst
View File

@ -1,53 +1,30 @@
========================
The ConnectionPool class
========================
.. sectionauthor:: Georg Richter <georg@mariadb.com>
.. class:: ConnectionPool
.. autoclass:: mariadb.ConnectionPool
MariaDB Connector/Python supports simple connection pooling.
A connection pool holds a number of open connections and handles thread safety
when providing connections to threads.
-----------------------
Connection pool methods
-----------------------
The size of a connection pool is configurable at creation time, but cannot be
changed afterwards. The maximum size of a connection pool is limited to 64 connections.
.. automethod:: mariadb.ConnectionPool.add_connection
.. method:: add_connection(connection)
.. automethod:: mariadb.ConnectionPool.close
Adds a connection object to the connection pool.
.. automethod:: mariadb.ConnectionPool.get_connection
In case that pool doesn't have a free slot or is not configured a PoolError
exception will be raised.
.. automethod:: mariadb.ConnectionPool.set_config
.. method:: close()
--------------------------
Connection pool attributes
--------------------------
Closes the pool and all connection inside the pool.
.. versionadded:: 1.0.1
.. autoattribute:: mariadb.ConnectionPool.max_size
.. method:: get_connection()
.. autoattribute:: mariadb.ConnectionPool.pool_size
Returns a connection from the connection pool or raises a PoolError if no
connection is available.
.. method:: set_config(\*\*kwargs)
Sets the connection configuration for the connection pool. For valid connection
arguments see :func:`mariadb.connect` method.
.. note::
This method doesn't create connections in the pool. To fill the pool one has to use
the :func:`add_connection` ḿethod.
.. data:: max_size
Returns the maximum allowed size of the pool
.. data:: pool_size
Returns the size of connection pool
.. data:: pool_name
Returns the name of the pool.
.. autoattribute:: mariadb.ConnectionPool.pool_name

2
docs/_sources/connection.rst.txt
View File

@ -13,7 +13,7 @@ Connection constructors
.. automethod:: mariadb.connections.Connection.cursor
.. versionadded:: 1.0.1
.. automethod:: mariadb.connections.Connection.xid(format_id: int, global_transaction_id: str, brach_qualifier: str)
.. automethod:: mariadb.connections.Connection.xid
------------------
Connection methods

2
docs/_sources/cursor.rst.txt
View File

@ -1,5 +1,7 @@
The cursor class
====================
.. sectionauthor:: Georg Richter <georg@mariadb.com>
.. autoclass:: mariadb.cursors.Cursor
--------------

53
docs/_sources/pool.rst.txt
View File

@ -1,53 +1,30 @@
========================
The ConnectionPool class
========================
.. sectionauthor:: Georg Richter <georg@mariadb.com>
.. class:: ConnectionPool
.. autoclass:: mariadb.ConnectionPool
MariaDB Connector/Python supports simple connection pooling.
A connection pool holds a number of open connections and handles thread safety
when providing connections to threads.
-----------------------
Connection pool methods
-----------------------
The size of a connection pool is configurable at creation time, but cannot be
changed afterwards. The maximum size of a connection pool is limited to 64 connections.
.. automethod:: mariadb.ConnectionPool.add_connection
.. method:: add_connection(connection)
.. automethod:: mariadb.ConnectionPool.close
Adds a connection object to the connection pool.
.. automethod:: mariadb.ConnectionPool.get_connection
In case that pool doesn't have a free slot or is not configured a PoolError
exception will be raised.
.. automethod:: mariadb.ConnectionPool.set_config
.. method:: close()
--------------------------
Connection pool attributes
--------------------------
Closes the pool and all connection inside the pool.
.. versionadded:: 1.0.1
.. autoattribute:: mariadb.ConnectionPool.max_size
.. method:: get_connection()
.. autoattribute:: mariadb.ConnectionPool.pool_size
Returns a connection from the connection pool or raises a PoolError if no
connection is available.
.. method:: set_config(\*\*kwargs)
Sets the connection configuration for the connection pool. For valid connection
arguments see :func:`mariadb.connect` method.
.. note::
This method doesn't create connections in the pool. To fill the pool one has to use
the :func:`add_connection` ḿethod.
.. data:: max_size
Returns the maximum allowed size of the pool
.. data:: pool_size
Returns the size of connection pool
.. data:: pool_name
Returns the name of the pool.
.. autoattribute:: mariadb.ConnectionPool.pool_name

27
docs/connection.html
View File

@ -98,17 +98,13 @@ the statement invoked with cursors execute() method.</p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.connections.Connection.xid">
<span class="sig-prename descclassname"><span class="pre">Connection.</span></span><span class="sig-name descname"><span class="pre">xid</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format_id</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">global_transaction_id</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">brach_qualifier</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.connections.Connection.xid" title="Permalink to this definition"></a></dt>
<span class="sig-prename descclassname"><span class="pre">Connection.</span></span><span class="sig-name descname"><span class="pre">xid</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">global_transaction_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">branch_qualifier</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.connections.Connection.xid" title="Permalink to this definition"></a></dt>
<dd><p>A transaction ID object suitable for passing to the .tpc_*()
methods of this connection.</p>
<dl class="simple">
<dt>Parameters:</dt><dd><ul class="simple">
<li><p>format_id: Format id. If not set default value <cite>0</cite> will be used.</p></li>
<li><p>global_transaction_id: Global transaction qualifier, which must be unique. The maximum length of the global transaction id is limited to 64 characters.</p></li>
<li><p>branch_qualifier: Branch qualifier which represents a local transaction identifier. The maximum length of the branch qualifier is limited to 64 characters.</p></li>
</ul>
</dd>
</dl>
<p>Parameters:
:param int format_id: Format id. If not set default value <cite>0</cite> will be used.
:param str global_transaction_id: Global transaction qualifier, which must be unique. The maximum length of the global transaction id is limited to 64 characters.
:param str branch_qualifier: Branch qualifier which represents a local transaction identifier. The maximum length of the branch qualifier is limited to 64 characters.</p>
</dd></dl>
</div>
@ -134,11 +130,12 @@ or cancelled by .rollback() method.</p>
<dt class="sig sig-object py" id="mariadb.connections.Connection.change_user">
<span class="sig-prename descclassname"><span class="pre">Connection.</span></span><span class="sig-name descname"><span class="pre">change_user</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">user</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">password</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">database</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.connections.Connection.change_user" title="Permalink to this definition"></a></dt>
<dd><p>Changes the user and default database of the current connection</p>
<dl class="simple">
<dt>Parameters:</dt><dd><ul class="simple">
<li><p>user: user name</p></li>
<li><p>password: password</p></li>
<li><p>database: name of default database</p></li>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>user</strong> (<em>-</em>) – user name</p></li>
<li><p><strong>password</strong> (<em>-</em>) – password</p></li>
<li><p><strong>database</strong> (<em>-</em>) – name of default database</p></li>
</ul>
</dd>
</dl>
@ -269,7 +266,7 @@ or the storage engine does not support transactions.”</p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.connections.Connection.select_db">
<span class="sig-prename descclassname"><span class="pre">Connection.</span></span><span class="sig-name descname"><span class="pre">select_db</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">new_db</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.connections.Connection.select_db" title="Permalink to this definition"></a></dt>
<span class="sig-prename descclassname"><span class="pre">Connection.</span></span><span class="sig-name descname"><span class="pre">select_db</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">new_db</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.connections.Connection.select_db" title="Permalink to this definition"></a></dt>
<dd><p>Gets the default database for the current connection.</p>
<p>The default database can also be obtained or changed by database attribute.</p>
</dd></dl>

20
docs/cursor.html
View File

@ -56,12 +56,20 @@
<h2>Cursor methods<a class="headerlink" href="#cursor-methods" title="Permalink to this headline"></a></h2>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.cursors.Cursor.callproc">
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">callproc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sp</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.callproc" title="Permalink to this definition"></a></dt>
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">callproc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sp</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">Sequence</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">()</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.callproc" title="Permalink to this definition"></a></dt>
<dd><p>Executes a stored procedure sp. The data sequence must contain an entry for
each parameter the procedure expects.</p>
<p>Input/Output or Output parameters have to be retrieved by .fetch methods,
the .sp_outparams attribute indicates if the result set contains output”
parameters</p>
the .sp_outparams attribute indicates if the result set contains output
parameters.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>sp</strong> – Name of stored procedure.</p></li>
<li><p><strong>data</strong> – Optional sequence containing data for placeholder substitution.</p></li>
</ul>
</dd>
</dl>
<p>Example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="go">&gt;&gt;&gt;cursor.execute(&quot;CREATE PROCEDURE p1(IN i1 VAR CHAR(20), OUT o2 VARCHAR(40))&quot;</span>
<span class="go"> &quot;BEGIN&quot;</span>
@ -85,7 +93,7 @@ parameters</p>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.cursors.Cursor.execute">
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">execute</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">statement</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffered</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.execute" title="Permalink to this definition"></a></dt>
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">execute</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">statement</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">Sequence</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffered</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.execute" title="Permalink to this definition"></a></dt>
<dd><p>Prepare and execute a SQL statement.</p>
<p>Parameters may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
@ -148,7 +156,7 @@ produce a result set or execute() wasn’t called before.</p>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.cursors.Cursor.fetchmany">
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">fetchmany</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.fetchmany" title="Permalink to this definition"></a></dt>
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">fetchmany</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">int</span></span> <span class="o"><span class="pre">=</span></span> <span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.fetchmany" title="Permalink to this definition"></a></dt>
<dd><p>Fetch the next set of rows of a query result, returning a sequence
of sequences (e.g. a list of tuples). An empty sequence is returned
when no more rows are available.</p>
@ -187,7 +195,7 @@ discarding any remaining rows from the current set.</p>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.cursors.Cursor.scroll">
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">scroll</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'relative'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.scroll" title="Permalink to this definition"></a></dt>
<span class="sig-prename descclassname"><span class="pre">Cursor.</span></span><span class="sig-name descname"><span class="pre">scroll</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="p"><span class="pre">:</span></span> <span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'relative'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.cursors.Cursor.scroll" title="Permalink to this definition"></a></dt>
<dd><p>Scroll the cursor in the result set to a new position according to mode.</p>
<p>If mode is “relative” (default), value is taken as offset to the current
position in the result set, if set to absolute, value states an absolute

30
docs/genindex.html
View File

@ -65,7 +65,7 @@
<h2 id="A">A</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="pool.html#ConnectionPool.add_connection">add_connection() (ConnectionPool method)</a>
<li><a href="pool.html#mariadb.ConnectionPool.add_connection">add_connection() (mariadb.ConnectionPool method)</a>
</li>
<li><a href="module.html#mariadb.apilevel">apilevel (in module mariadb)</a>
</li>
@ -107,7 +107,7 @@
</li>
<li><a href="connection.html#mariadb.connections.Connection.client_capabilities">client_capabilities (mariadb.connections.Connection attribute)</a>
</li>
<li><a href="pool.html#ConnectionPool.close">close() (ConnectionPool method)</a>
<li><a href="pool.html#mariadb.ConnectionPool.close">close() (mariadb.ConnectionPool method)</a>
<ul>
<li><a href="connection.html#mariadb.connections.Connection.close">(mariadb.connections.Connection method)</a>
@ -119,25 +119,19 @@
</li>
<li><a href="connection.html#mariadb.connections.Connection.commit">commit() (mariadb.connections.Connection method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="module.html#mariadb.connect">connect() (in module mariadb)</a>
</li>
<li><a href="connection.html#mariadb.connections.Connection">Connection (class in mariadb.connections)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="cursor.html#mariadb.cursors.Cursor.connection">connection (mariadb.cursors.Cursor attribute)</a>
</li>
<li><a href="connection.html#mariadb.connections.Connection.connection_id">connection_id (mariadb.connections.Connection attribute)</a>
</li>
<li><a href="pool.html#ConnectionPool">ConnectionPool (built-in class)</a>
<li><a href="pool.html#mariadb.ConnectionPool">ConnectionPool (class in mariadb)</a>
</li>
<li><a href="module.html#mariadb.ConnectionPool">ConnectionPool() (in module mariadb)</a>
</li>
<li><a href="pool.html#ConnectionPool.max_size">ConnectionPool.max_size (built-in variable)</a>
</li>
<li><a href="pool.html#ConnectionPool.pool_name">ConnectionPool.pool_name (built-in variable)</a>
</li>
<li><a href="pool.html#ConnectionPool.pool_size">ConnectionPool.pool_size (built-in variable)</a>
</li>
<li><a href="cursor.html#mariadb.cursors.Cursor">Cursor (class in mariadb.cursors)</a>
</li>
@ -287,7 +281,7 @@
<h2 id="G">G</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="pool.html#ConnectionPool.get_connection">get_connection() (ConnectionPool method)</a>
<li><a href="pool.html#mariadb.ConnectionPool.get_connection">get_connection() (mariadb.ConnectionPool method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
@ -344,9 +338,11 @@
<li><a href="module.html#module-mariadb">module</a>
</li>
</ul></li>
<li><a href="module.html#mariadb.mariadbapi_version">mariadbapi_version (in module mariadb)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="module.html#mariadb.mariadbapi_version">mariadbapi_version (in module mariadb)</a>
<li><a href="pool.html#mariadb.ConnectionPool.max_size">max_size (mariadb.ConnectionPool attribute)</a>
</li>
<li>
module
@ -392,10 +388,14 @@
<li><a href="cursor.html#mariadb.cursors.Cursor.paramcount">paramcount (mariadb.cursors.Cursor attribute)</a>
</li>
<li><a href="module.html#mariadb.paramstyle">paramstyle (in module mariadb)</a>
</li>
<li><a href="connection.html#mariadb.connections.Connection.ping">ping() (mariadb.connections.Connection method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="connection.html#mariadb.connections.Connection.ping">ping() (mariadb.connections.Connection method)</a>
<li><a href="pool.html#mariadb.ConnectionPool.pool_name">pool_name (mariadb.ConnectionPool attribute)</a>
</li>
<li><a href="pool.html#mariadb.ConnectionPool.pool_size">pool_size (mariadb.ConnectionPool attribute)</a>
</li>
<li><a href="module.html#mariadb.PoolError">PoolError</a>
</li>
@ -443,7 +443,7 @@
</li>
<li><a href="connection.html#mariadb.connections.Connection.server_version_info">server_version_info (mariadb.connections.Connection attribute)</a>
</li>
<li><a href="pool.html#ConnectionPool.set_config">set_config() (ConnectionPool method)</a>
<li><a href="pool.html#mariadb.ConnectionPool.set_config">set_config() (mariadb.ConnectionPool method)</a>
</li>
<li><a href="cursor.html#mariadb.cursors.Cursor.setinputsizes">setinputsizes() (mariadb.cursors.Cursor method)</a>
</li>

6
docs/index.html
View File

@ -76,7 +76,11 @@ client library for client server communication.</p>
<li class="toctree-l2"><a class="reference internal" href="cursor.html#cursor-attributes">Cursor attributes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="pool.html">The ConnectionPool class</a></li>
<li class="toctree-l1"><a class="reference internal" href="pool.html">The ConnectionPool class</a><ul>
<li class="toctree-l2"><a class="reference internal" href="pool.html#connection-pool-methods">Connection pool methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="pool.html#connection-pool-attributes">Connection pool attributes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="constants.html">Constants</a><ul>
<li class="toctree-l2"><a class="reference internal" href="constants.html#command">COMMAND</a></li>
<li class="toctree-l2"><a class="reference internal" href="constants.html#client">CLIENT</a></li>

BIN
docs/objects.inv
View File

Binary file not shown.

124
docs/pool.html
View File

@ -47,69 +47,80 @@
<div class="section" id="the-connectionpool-class">
<h1>The ConnectionPool class<a class="headerlink" href="#the-connectionpool-class" title="Permalink to this headline"></a></h1>
<dl class="py class">
<dt class="sig sig-object py" id="ConnectionPool">
<em class="property"><span class="pre">class</span> </em><span class="sig-name descname"><span class="pre">ConnectionPool</span></span><a class="headerlink" href="#ConnectionPool" title="Permalink to this definition"></a></dt>
<dd><p>MariaDB Connector/Python supports simple connection pooling.
A connection pool holds a number of open connections and handles thread safety
when providing connections to threads.</p>
<p>The size of a connection pool is configurable at creation time, but cannot be
changed afterwards. The maximum size of a connection pool is limited to 64 connections.</p>
<dt class="sig sig-object py" id="mariadb.ConnectionPool">
<em class="property"><span class="pre">class</span> </em><span class="sig-prename descclassname"><span class="pre">mariadb.</span></span><span class="sig-name descname"><span class="pre">ConnectionPool</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.ConnectionPool" title="Permalink to this definition"></a></dt>
<dd><p>Class defining a pool of database connections</p>
<p>MariaDB Connector/Python supports simple connection pooling.
A connection pool holds a number of open connections and handles
thread safety when providing connections to threads.</p>
<p>The size of a connection pool is configurable at creation time,
but cannot be changed afterwards. The maximum size of a connection
pool is limited to 64 connections.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><ul class="simple">
<li><p>pool_name (str) – Name of connection pool</p></li>
<li><p>pool_size (int)=5 – Size of pool. If not specified default value of 5 will be used. Maximum allowed number is 64.</p></li>
<li><p>pool_reset_connection (bool)=True – Will reset the connection before returning it to the pool. Default value is True.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<div class="section" id="connection-pool-methods">
<h2>Connection pool methods<a class="headerlink" href="#connection-pool-methods" title="Permalink to this headline"></a></h2>
<dl class="py method">
<dt class="sig sig-object py" id="ConnectionPool.add_connection">
<span class="sig-name descname"><span class="pre">add_connection</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">connection</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#ConnectionPool.add_connection" title="Permalink to this definition"></a></dt>
<dt class="sig sig-object py" id="mariadb.ConnectionPool.add_connection">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">add_connection</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">connection</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.ConnectionPool.add_connection" title="Permalink to this definition"></a></dt>
<dd><p>Adds a connection object to the connection pool.</p>
<p>In case that pool doesn’t have a free slot or is not configured a PoolError
exception will be raised.</p>
<p>In case that the pool doesn’t have a free slot or is not configured
a PoolError exception will be raised.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="ConnectionPool.close">
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#ConnectionPool.close" title="Permalink to this definition"></a></dt>
<dd><p>Closes the pool and all connection inside the pool.</p>
<dt class="sig sig-object py" id="mariadb.ConnectionPool.close">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.ConnectionPool.close" title="Permalink to this definition"></a></dt>
<dd><p>Closes connection pool and all connections.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.ConnectionPool.get_connection">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">get_connection</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.ConnectionPool.get_connection" title="Permalink to this definition"></a></dt>
<dd><p>Returns a connection from the connection pool or raises a PoolError
exception if a connection is not available.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="mariadb.ConnectionPool.set_config">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">set_config</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.ConnectionPool.set_config" title="Permalink to this definition"></a></dt>
<dd><p>Sets the connection configuration for the connection pool.
For valid connection arguments check the mariadb.connect() method.</p>
<p>Note: This method doesn’t create connections in the pool.
To fill the pool one has to use add_connection() ḿethod.</p>
</dd></dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.1.</span></p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="ConnectionPool.get_connection">
<span class="sig-name descname"><span class="pre">get_connection</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#ConnectionPool.get_connection" title="Permalink to this definition"></a></dt>
<dd><p>Returns a connection from the connection pool or raises a PoolError if no
connection is available.</p>
<div class="section" id="connection-pool-attributes">
<h2>Connection pool attributes<a class="headerlink" href="#connection-pool-attributes" title="Permalink to this headline"></a></h2>
<dl class="py attribute">
<dt class="sig sig-object py" id="mariadb.ConnectionPool.max_size">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">max_size</span></span><a class="headerlink" href="#mariadb.ConnectionPool.max_size" title="Permalink to this definition"></a></dt>
<dd><p>Returns the maximum size for connection pools.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="mariadb.ConnectionPool.pool_size">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">pool_size</span></span><a class="headerlink" href="#mariadb.ConnectionPool.pool_size" title="Permalink to this definition"></a></dt>
<dd><p>Returns the size of the connection pool.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="mariadb.ConnectionPool.pool_name">
<span class="sig-prename descclassname"><span class="pre">ConnectionPool.</span></span><span class="sig-name descname"><span class="pre">pool_name</span></span><a class="headerlink" href="#mariadb.ConnectionPool.pool_name" title="Permalink to this definition"></a></dt>
<dd><p>Returns the name of the connection pool.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="ConnectionPool.set_config">
<span class="sig-name descname"><span class="pre">set_config</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="pre">\*\*kwargs</span></em><span class="sig-paren">)</span><a class="headerlink" href="#ConnectionPool.set_config" title="Permalink to this definition"></a></dt>
<dd><p>Sets the connection configuration for the connection pool. For valid connection
arguments see <a class="reference internal" href="module.html#mariadb.connect" title="mariadb.connect"><code class="xref py py-func docutils literal notranslate"><span class="pre">mariadb.connect()</span></code></a> method.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This method doesn’t create connections in the pool. To fill the pool one has to use
the <a class="reference internal" href="#ConnectionPool.add_connection" title="ConnectionPool.add_connection"><code class="xref py py-func docutils literal notranslate"><span class="pre">add_connection()</span></code></a> ḿethod.</p>
</div>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="ConnectionPool.max_size">
<span class="sig-name descname"><span class="pre">max_size</span></span><a class="headerlink" href="#ConnectionPool.max_size" title="Permalink to this definition"></a></dt>
<dd><p>Returns the maximum allowed size of the pool</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="ConnectionPool.pool_size">
<span class="sig-name descname"><span class="pre">pool_size</span></span><a class="headerlink" href="#ConnectionPool.pool_size" title="Permalink to this definition"></a></dt>
<dd><p>Returns the size of connection pool</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="ConnectionPool.pool_name">
<span class="sig-name descname"><span class="pre">pool_name</span></span><a class="headerlink" href="#ConnectionPool.pool_name" title="Permalink to this definition"></a></dt>
<dd><p>Returns the name of the pool.</p>
</dd></dl>
</dd></dl>
</div>
@ -119,6 +130,15 @@ the <a class="reference internal" href="#ConnectionPool.add_connection" title="C
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The ConnectionPool class</a><ul>
<li><a class="reference internal" href="#connection-pool-methods">Connection pool methods</a></li>
<li><a class="reference internal" href="#connection-pool-attributes">Connection pool attributes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="cursor.html"
title="previous chapter">The cursor class</a></p>

2
docs/searchindex.js
View File

File diff suppressed because one or more lines are too long

14
mariadb/connectionpool.py
View File

@ -24,7 +24,7 @@ MAX_POOL_SIZE = 64
POOL_IDLE_TIMEOUT = 1800
class ConnectionPool(object):
"""
r"""
Class defining a pool of database connections
MariaDB Connector/Python supports simple connection pooling.
@ -34,8 +34,15 @@ class ConnectionPool(object):
The size of a connection pool is configurable at creation time,
but cannot be changed afterwards. The maximum size of a connection
pool is limited to 64 connections.
"""
:Keyword Arguments:
* pool_name (str) -- Name of connection pool
* pool_size (int)=5 -- Size of pool. If not specified default value of 5 will be used. Maximum allowed number is 64.
* pool_reset_connection (bool)=True -- Will reset the connection before returning it to the pool. Default value is True.
"""
def __init__(self, *args, **kwargs):
"""
@ -182,9 +189,6 @@ class ConnectionPool(object):
def set_config(self, **kwargs):
"""
:param dict configuration
configuration settings for pooled connection
Sets the connection configuration for the connection pool.
For valid connection arguments check the mariadb.connect() method.

10
mariadb/connections.py
View File

@ -177,7 +177,7 @@ class Connection(mariadb._mariadb.connection):
self._execute_command("BEGIN")
self._read_response()
def select_db(self, new_db):
def select_db(self, new_db: str):
"""
Gets the default database for the current connection.
@ -210,13 +210,15 @@ class Connection(mariadb._mariadb.connection):
class xid(tuple):
"""
xid(format_id, global_transaction_id, branch_qualifier)
A transaction ID object suitable for passing to the .tpc_*()
methods of this connection.
Parameters:
- format_id: Format id. If not set default value `0` will be used.
- global_transaction_id: Global transaction qualifier, which must be unique. The maximum length of the global transaction id is limited to 64 characters.
- branch_qualifier: Branch qualifier which represents a local transaction identifier. The maximum length of the branch qualifier is limited to 64 characters.
:param int format_id: Format id. If not set default value `0` will be used.
:param str global_transaction_id: Global transaction qualifier, which must be unique. The maximum length of the global transaction id is limited to 64 characters.
:param str branch_qualifier: Branch qualifier which represents a local transaction identifier. The maximum length of the branch qualifier is limited to 64 characters.
"""
def __new__(self, format_id, transaction_id, branch_qualifier):

23
mariadb/cursors.py
View File

@ -20,6 +20,7 @@
import mariadb, collections
from numbers import Number
from mariadb.constants import *
from typing import Sequence
PARAMSTYLE_QMARK= 1
PARAMSTYLE_FORMAT= 2
@ -146,19 +147,23 @@ class Cursor(mariadb._mariadb.cursor):
" doesn't match the number of data elements (%s)."\
% (len(self._paramlist), len(self._data)))
def callproc(self, sp: str, data=()):
def callproc(self, sp: str, data: Sequence =()):
"""
Executes a stored procedure sp. The data sequence must contain an entry for
each parameter the procedure expects.
Input/Output or Output parameters have to be retrieved by .fetch methods,
the .sp_outparams attribute indicates if the result set contains output"
parameters
the .sp_outparams attribute indicates if the result set contains output
parameters.
Args:
sp: Name of stored procedure.
data: Optional sequence containing data for placeholder substitution.
"""
# create statement
params= ""
if len(data):
if data and len(data):
params= ("?," * len(data))[:-1]
statement= "CALL %s(%s)" % (sp, params)
self._rowcount= 0
@ -200,7 +205,7 @@ class Cursor(mariadb._mariadb.cursor):
return super()._nextset()
def execute(self, statement: str, data=(), buffered=False):
def execute(self, statement: str, data: Sequence =(), buffered=False):
"""
Prepare and execute a SQL statement.
@ -376,7 +381,7 @@ class Cursor(mariadb._mariadb.cursor):
ret= row
return ret
def fetchmany(self, size=0):
def fetchmany(self, size: int =0):
"""
Fetch the next set of rows of a query result, returning a sequence
of sequences (e.g. a list of tuples). An empty sequence is returned
@ -416,7 +421,7 @@ class Cursor(mariadb._mariadb.cursor):
rows.append((row))
return rows
def scroll(self, value, mode="relative"):
def scroll(self, value: int, mode="relative"):
"""
Scroll the cursor in the result set to a new position according to mode.
@ -451,14 +456,14 @@ class Cursor(mariadb._mariadb.cursor):
self._seek(new_pos);
self._rownumber= new_pos;
def setinputsizes(self, size):
def setinputsizes(self, size: int):
"""
Required by PEP-249. Does nothing in MariaDB Connector/Python
"""
return
def setoutputsize(self, size):
def setoutputsize(self, size: int):
"""
Required by PEP-249. Does nothing in MariaDB Connector/Python
"""

60
mariadb/mariadb_protocol.py
View File

@ -1,60 +0,0 @@
#
# Copyright (C) 2021 Georg Richter and MariaDB Corporation AB
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Library General Public
# License as published by the Free Software Foundation; either
# version 2 of the License, or (at your option) any later version.
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Library General Public License for more details.
# You should have received a copy of the GNU Library General Public
# License along with this library; if not see <http://www.gnu.org/licenses>
# or write to the Free Software Foundation, Inc.,
# 51 Franklin St., Fifth Floor, Boston, MA 02110, USA
#
import struct
PROT_CMD_SLEEP= 0
PROT_CMD_QUIT= 1
PROT_CMD_INIT_DB= 2
PROT_CMD_QUERY= 3
PROT_CMD_FIELD_LIST= 4
PROT_CMD_CREATE_DB= 5
PROT_CMD_DROP_DB= 6
PROT_CMD_REFRESH= 7
PROT_CMD_SHUTDOWN= 8
PROT_CMD_STATISTICS= 9
PROT_CMD_PROCESS_INFO= 10
PROT_CMD_CONNECT= 11
PROT_CMD_PROCESS_KILL= 12
PROT_CMD_DEBUG= 13
PROT_CMD_PING= 14
PROT_CMD_TIME= 15,
PROT_CMD_DELAYED_INSERT= 16
PROT_CMD_CHANGE_USER= 17
PROT_CMD_BINLOG_DUMP= 18
PROT_CMD_TABLE_DUMP= 19
PROT_CMD_CONNECT_OUT = 20
PROT_CMD_REGISTER_SLAVE= 21
PROT_CMD_STMT_PREPARE= 22
PROT_CMD_STMT_EXECUTE= 23
PROT_CMD_STMT_SEND_LONG_DATA = 24
PROT_CMD_STMT_CLOSE= 25
PROT_CMD_STMT_RESET= 26
PROT_CMD_SET_OPTION= 27
PROT_CMD_STMT_FETCH= 28
PROT_CMD_DAEMON= 29
PROT_CMD_UNSUPPORTED= 30
PROT_CMD_RESET_CONNECTION= 31
PROT_CMD_STMT_BULK_EXECUTE= 250
def prot_length(buffer_size):
def send_command(socket, command, buffer):