Added missing example for documentation

This commit is contained in:
Georg Richter
2020-06-08 13:08:55 +02:00
parent ba052adafa
commit 2b5695a7cf
9 changed files with 123 additions and 61 deletions

28
doc/examples/basic01.py Normal file
View File

@ -0,0 +1,28 @@
# Import MariaDB Connector/Python module
import mariadb
# Establish a connection
connection= mariadb.connect(user="myuser", database="test", host="localhost")
cursor= connection.cursor()
# Create a database table
cursor.execute("DROP TABLE IF EXISTS mytest")
cursor.execute("CREATE TABLE mytest(id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,"
"first_name VARCHAR(100), last_name VARCHAR(100))")
# Populate table with some data
cursor.execute("INSERT INTO mytest(first_name, last_name) VALUES (?,?)",
("Robert", "Redford"))
# retrieve data
cursor.execute("SELECT id, first_name, last_name FROM mytest")
# print content
row= cursor.fetchone()
print(*row, sep='\t')
# free resources
cursor.close()
connection.close()

View File

@ -15,25 +15,6 @@ The cursor class
Cursor methods
--------------
.. method:: execute(statement[, data [, \*\*kwargs]])
Parameters in SQL statement may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
marks (paramstyle='qmark'), however for compatibility reasons |MCP|
also supports the 'format' and 'pyformat' paramstyles
with the restriction, that different paramstyles can't be mixed within.
a statement
A reference to the operation will be retained by the cursor.
If the cursor was created with attribute prepared=True the statement
string for following execute operations will be ignored:
This is most effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).
By default result sets will not be buffered, so further operations on the
same connection will fail, unless the entire result set was read. For buffering
the entire result set an additional parameter *buffered=True* must be specified.
.. method:: callproc(procname, [ args]))
Executes a stored procedure.
@ -44,7 +25,7 @@ Cursor methods
:param procname: The name of the stored procedure
:type procname: string
:param args: A sequence which mist contain an entry for each parameter the procedure expects.
:param args: A sequence which must contain an entry for each parameter the procedure expects.
:type args: sequence
Example:
@ -68,6 +49,34 @@ Cursor methods
>>> cursor.fetchone()
('test',)
.. method:: execute(statement[, data [, buffered=False])
Executes a SQL statement.
Parameters in SQL statement may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
marks (paramstyle='qmark'), however for compatibility reasons |MCP|
also supports the 'format' and 'pyformat' paramstyles
with the restriction, that different paramstyles can't be mixed within.
a statement
:param statement: SQL statement
:type procname: string
:param args: A sequence which must contain an entry for each parameter the statement expects.
:type args: sequence
A reference to the operation will be retained by the cursor.
If the cursor was created with attribute prepared=True the statement
string for following execute operations will be ignored:
This is most effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).
By default result sets will not be buffered, so further operations on the
same connection will fail, unless the entire result set was read. For buffering
the entire result set an additional parameter *buffered=True* must be specified.
.. method:: executemany(statement, data)
Exactly behaves like .execute() but accepts a list of tuples, where each

View File

@ -15,6 +15,7 @@ client library for client server communication.
:caption: Contents:
install
usage
module
connection
cursor

View File

@ -15,25 +15,6 @@ The cursor class
Cursor methods
--------------
.. method:: execute(statement[, data [, \*\*kwargs]])
Parameters in SQL statement may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
marks (paramstyle='qmark'), however for compatibility reasons |MCP|
also supports the 'format' and 'pyformat' paramstyles
with the restriction, that different paramstyles can't be mixed within.
a statement
A reference to the operation will be retained by the cursor.
If the cursor was created with attribute prepared=True the statement
string for following execute operations will be ignored:
This is most effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).
By default result sets will not be buffered, so further operations on the
same connection will fail, unless the entire result set was read. For buffering
the entire result set an additional parameter *buffered=True* must be specified.
.. method:: callproc(procname, [ args]))
Executes a stored procedure.
@ -44,7 +25,7 @@ Cursor methods
:param procname: The name of the stored procedure
:type procname: string
:param args: A sequence which mist contain an entry for each parameter the procedure expects.
:param args: A sequence which must contain an entry for each parameter the procedure expects.
:type args: sequence
Example:
@ -68,6 +49,34 @@ Cursor methods
>>> cursor.fetchone()
('test',)
.. method:: execute(statement[, data [, buffered=False])
Executes a SQL statement.
Parameters in SQL statement may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
marks (paramstyle='qmark'), however for compatibility reasons |MCP|
also supports the 'format' and 'pyformat' paramstyles
with the restriction, that different paramstyles can't be mixed within.
a statement
:param statement: SQL statement
:type procname: string
:param args: A sequence which must contain an entry for each parameter the statement expects.
:type args: sequence
A reference to the operation will be retained by the cursor.
If the cursor was created with attribute prepared=True the statement
string for following execute operations will be ignored:
This is most effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).
By default result sets will not be buffered, so further operations on the
same connection will fail, unless the entire result set was read. For buffering
the entire result set an additional parameter *buffered=True* must be specified.
.. method:: executemany(statement, data)
Exactly behaves like .execute() but accepts a list of tuples, where each

View File

@ -15,6 +15,7 @@ client library for client server communication.
:caption: Contents:
install
usage
module
connection
cursor

View File

@ -57,25 +57,6 @@ closed or dropped all cursor objects bound to this connection became invalid.</p
<div class="section" id="cursor-methods">
<h2>Cursor methods<a class="headerlink" href="#cursor-methods" title="Permalink to this headline"></a></h2>
<dl class="method">
<dt id="execute">
<code class="sig-name descname">execute</code><span class="sig-paren">(</span><em class="sig-param">statement</em><span class="optional">[</span>, <em class="sig-param">data</em><span class="optional">[</span>, <em class="sig-param">**kwargs</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#execute" title="Permalink to this definition"></a></dt>
<dd><p>Parameters in SQL statement may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
marks (paramstyle=qmark), however for compatibility reasons MariaDB Connector/Python
also supports the format and pyformat paramstyles
with the restriction, that different paramstyles cant be mixed within.
a statement</p>
<p>A reference to the operation will be retained by the cursor.
If the cursor was created with attribute prepared=True the statement
string for following execute operations will be ignored:
This is most effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).</p>
<p>By default result sets will not be buffered, so further operations on the
same connection will fail, unless the entire result set was read. For buffering
the entire result set an additional parameter <em>buffered=True</em> must be specified.</p>
</dd></dl>
<dl class="method">
<dt id="callproc">
<code class="sig-name descname">callproc</code><span class="sig-paren">(</span><em class="sig-param">procname, [ args])</em><span class="sig-paren">)</span><a class="headerlink" href="#callproc" title="Permalink to this definition"></a></dt>
@ -87,7 +68,7 @@ parameters.</p>
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>procname</strong> (<em>string</em>) The name of the stored procedure</p></li>
<li><p><strong>args</strong> (<em>sequence</em>) A sequence which mist contain an entry for each parameter the procedure expects.</p></li>
<li><p><strong>args</strong> (<em>sequence</em>) A sequence which must contain an entry for each parameter the procedure expects.</p></li>
</ul>
</dd>
</dl>
@ -112,6 +93,34 @@ parameters.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="execute">
<code class="sig-name descname">execute</code><span class="sig-paren">(</span><em class="sig-param">statement[, data [, buffered=False]</em><span class="sig-paren">)</span><a class="headerlink" href="#execute" title="Permalink to this definition"></a></dt>
<dd><p>Executes a SQL statement.</p>
<p>Parameters in SQL statement may be provided as sequence or mapping and will be bound
to variables in the operation. Variables are specified as question
marks (paramstyle=qmark), however for compatibility reasons MariaDB Connector/Python
also supports the format and pyformat paramstyles
with the restriction, that different paramstyles cant be mixed within.
a statement</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>statement</strong> SQL statement</p></li>
<li><p><strong>args</strong> (<em>sequence</em>) A sequence which must contain an entry for each parameter the statement expects.</p></li>
</ul>
</dd>
</dl>
<p>A reference to the operation will be retained by the cursor.
If the cursor was created with attribute prepared=True the statement
string for following execute operations will be ignored:
This is most effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).</p>
<p>By default result sets will not be buffered, so further operations on the
same connection will fail, unless the entire result set was read. For buffering
the entire result set an additional parameter <em>buffered=True</em> must be specified.</p>
</dd></dl>
<dl class="method">
<dt id="executemany">
<code class="sig-name descname">executemany</code><span class="sig-paren">(</span><em class="sig-param">statement</em>, <em class="sig-param">data</em><span class="sig-paren">)</span><a class="headerlink" href="#executemany" title="Permalink to this definition"></a></dt>

View File

@ -54,6 +54,11 @@ client library for client server communication.</p>
<li class="toctree-l2"><a class="reference internal" href="install.html#test-suite">Test suite</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Basic usage</a><ul>
<li class="toctree-l2"><a class="reference internal" href="usage.html#connecting">Connecting</a></li>
<li class="toctree-l2"><a class="reference internal" href="usage.html#passing-parameters-to-sql-statements">Passing parameters to SQL statements</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="module.html">The mariadb module</a><ul>
<li class="toctree-l2"><a class="reference internal" href="module.html#exceptions">Exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="module.html#type-objects-and-constructors">Type objects and constructors</a></li>

Binary file not shown.

File diff suppressed because one or more lines are too long