Documentation update:

- added release notes
- added doctest support

doc/examples/basic01.py

@@ -1,8 +1,16 @@
 # Import MariaDB Connector/Python module
 import mariadb
 
+# connection parameters
+conn_params= {
+    "user" : "example_user",
+    "password" : "GHbe_Su3B8",
+    "host" : "localhost",
+    "database" : "test"
+}
+
 # Establish a connection
-connection= mariadb.connect(user="myuser", database="test", host="localhost")
+connection= mariadb.connect(**conn_params)
 
 cursor= connection.cursor()
 

doc/source/api.rst

@@ -0,0 +1,16 @@
+-------------
+API Reference
+-------------
+
+.. sectionauthor:: Georg Richter <georg@mariadb.com>
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   module
+   connection
+   cursor
+   pool
+   constants 
+

doc/source/index.rst

@@ -4,23 +4,36 @@ MariaDB Connector/Python
 
 .. sectionauthor:: Georg Richter <georg@mariadb.com>
 
-MariaDB Connector/Python enables python programs to access MariaDB and MySQL databases, using an API
-which is compliant with the Python |DBAPI|. It is written in C and uses MariaDB Connector/C
-client library for client server communication.
+.. testsetup::
+
+    import mariadb
+    conn_params= {
+        "host" : "localhost",
+        "database" : "test"
+    }
+
+    conn=mariadb.connect(**conn_params)
+    cursor=conn.cursor()
+    cursor.execute("CREATE USER IF NOT EXISTS example_user@localhost identified by 'GHbe_Su3B8'")
+    cursor.execute("grant all on test.* to example_user@localhost")
+    cursor.execute("DROP TABLE IF EXISTS book")
+    cursor.close()
+    conn.close()
+
+|MCP| enables python programs to access MariaDB and MySQL databases, using an API
+which is compliant with the Python |DBAPI|. It is written in C and Python and uses
+MariaDB Connector/C client library for client server communication.
 
 .. rubric:: Contents
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    install
    usage
-   module
-   connection
-   cursor
-   pool
-   constants 
+   pooling
+   api
    license
    release
 

doc/source/install.rst

@@ -8,8 +8,8 @@ Installation
 Prerequisites
 -------------
 - Python 3 (minimum supported version is 3.6)
-- MariaDB Server 10.x or MySQL Server
-- MariaDB Connector/C 3.1.5 or newer
+- MariaDB Server (>= 10.2) or MySQL Server (>= 5.7)
+- MariaDB Connector/C
 
 
 Build prerequisites
@@ -20,7 +20,7 @@ For Windows operating platforms the pypi.org download page provides binary versi
 - C compiler
 - Python development files (Usually they are installed with package **python-dev**). The minimum supported version of Python is 3.6
 - MariaDB Connector/C libraries and header files (Either from MariaDB server package or
-  from MariaDB Connector/C package).
+  from MariaDB Connector/C package). Minimum required version for |MCP| < 1.1.0 is 3.1.5, for later versions 3.2.4.
 - For Posix systems: TLS libraries, e.g. GnuTLS or OpenSSL (default)
 
 On Posix systems make sure that the path environment variable contains the directory which

doc/source/pool.rst

@@ -6,15 +6,6 @@ The ConnectionPool class
 
 .. autoclass:: mariadb.ConnectionPool
 
-.. testcode::
-
-    import mariadb
-
-    pool= mariadb.ConnectionPool(pool_name="mypool")
-    print(pool.max_size)
-
-.. testoutput::
-
 ----------------------
 ConnectionPool methods
 ----------------------

doc/source/pooling.rst

@@ -0,0 +1,72 @@
+==================
+Connection pooling
+==================
+
+A connection pool is a cache of connections to a database server where connections can be reused for future requests.
+Since establishing a connection is resource-expensive and time-consuming, especially when used inside a middle tier
+environment which maintains multiple connections and requires connections to be immediately available on the fly.
+
+Especially for server-side web applications, a connection pool is the standard way to maintain a pool of database connections
+which are reused across requests.
+
+
+---------------------------------------
+Configuring and using a connection pool
+---------------------------------------
+
+The typical way for creating and using a connection pool is
+
+1. Create (and configure) a connection pool
+2. Obtain a connection from connection pool
+3. Perform database operation(s) 
+4. Close the connection instance and return it to the connection pool.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creating a connection pool
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When creating a connection pool, the following parameters have to be provided:
+
+1. Connection pool specific parameters
+
+- pool_name: The name of the pool, if not specified |MCP| will raise an exception.
+- pool_size: The size of the pool, if not specified a default of 5 will be set.
+- pool_reset_session: If set to True, the connection will be resetted before returned to the pool
+
+2. Connection parameters
+
+- In addition to the connection pool specific parameters initialization method of ConnectionPool Class accepts the same parameters as the connect() method of mariadb module.
+
+*Example*:
+
+.. testcode::
+
+    import mariadb
+
+    # connection parameters
+    conn_params= {
+      "user" : "example_user",
+      "password" : "GHbe_Su3B8",
+      "database" : "test"
+    }
+
+    # create new pool
+    pool= mariadb.ConnectionPool(pool_name="myfirstpool", pool_size=5, **conn_params)
+    print("Pool size of '%s': %s" % (pool.pool_name, pool.pool_size))
+
+    # get a connection from pool
+    conn= pool.get_connection()
+
+    # print the default database for connection
+    print("Current database: %s" % conn.database)
+
+    # close connection and return it to pool
+    conn.close()
+
+*Output*:
+
+.. testoutput::
+
+    Pool size of 'myfirstpool': 5
+    Current database: test
+

doc/source/release.rst

@@ -1,21 +1,137 @@
 Release history
 ===============
 
-Stable releases (GA)
---------------------
+MariaDB Connector/Python 1.0.7
+------------------------------
+
+Release date: Jun 8 2021
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONPY-155: fixed crash in get_server_version method of connection class
+- CONPY-144: fixed crash in connection pool
+- CONPY-150: convert invalid date types (day, month or year=0) to NULL 
+
+MariaDB Connector/Python 1.0.6
+------------------------------
+
+Release date: Feb 24 2021
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONC-142: Fixed memory leak in connection class (server_version_info)
+- CONC-138, CONC-141: When using binary protocol, convert data to binary object only if the character set is BINARY (63), not if the flag was set and character set is a non binary character set.
+- Various build and travis related corrections/fixes. 
+
+MariaDB Connector/Python 1.0.5
+------------------------------
+
+Release date: Nov 25th 2020
+
+Notable changes:
+^^^^^^^^^^^^^^^^
+
+- CONPY-127: When establishing a new database connection the connect method now also supports None values instead of strings only.
+- CONPY-128: Added connection attribute server_version_info and (for compatibility) get_server_version() method. Both return a tuple, describing the version number of connected server in following format: (MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION)
+- CONPY-133: The internal parser now supports the full MariaDB comment syntax 
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONPY-126: Fixed memory leak in connection object
+- CONPY-130: Fixed DeprecationWarning: builtin type Row has no module attribute
+- CONPY-131: Fixed crash type_traverse() called for non-heap type Row (Python 3.6 only)
+- CONPY-132: Fixed memory leak in connection pool 
+
+MariaDB Connector/Python 1.0.4
+------------------------------
+
+Release date: Oct 20th 2020
+
+Notable changes:
+^^^^^^^^^^^^^^^^
+
+Binary wheel packages are now availble for Windows on http://pypi.org
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONPY-123: Free pending result sets when closing cursor
+- CONPY-124: Fix build when building against Connector/C < 3.1.8
+- CONPY-125: Build fix: replace obsolete ULONG_LONG_MAX definitions
+
+MariaDB Connector/Python 1.0.3
+------------------------------
+
+Release date: Oct 7th 2020
+
+Notable changes:
+^^^^^^^^^^^^^^^^
+
+- CONPY-117: Added support for data type conversion.
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONPY-116: Wrong type reporting for column type MYSQL_TYPE_JSON
+- CONPY-118: Removed statement allocation for text protocol
+- CONPY-119: Fixed memory leak when cursor result is dictionary
+
+MariaDB Connector/Python 1.0.2
+------------------------------
+
+Release date: Sept 18th 2020
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- Fixed datetime initialization
+- CONPY-108: Fixed memory leak
+- CONPY-110: Fixed memory overrun when passing ssl keyword to connect() method.
+
+MariaDB Connector/Python 1.0.1
+------------------------------
+
+Release date: August 18th 2020
+
+Notable changes:
+^^^^^^^^^^^^^^^^
+
+- CONPY-100: added binary option for cursor which allows to use binary protocol without passing parameters
+- CONPY-102: Default for autocommit is now off
+- CONPY-105: Behavior of rowcount and lastrowid atttributes now conforms to PEP-249
+
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONPY-82: Unlock mutex in case of ConnectionPool.add_connection failed
+- CONPY-83: Fixed missing reference increment in ConnectionPool class
+- CONPY-85: Fixed version checking in setup.py
+- CONPY-93: Release GIL before calling Python's memory allocation routine
+- CONPY-94: Support python subclasses for data binding 
+- CONPY-95: Added support for MYSQL_TYPE_BIT column type
+- CONPY-98: Return binary object when casting to binary
+- CONPY-99: Fixed memory leak in fetchall() method.
+- CONPY-101: Fixed negative reference count when using callproc() method.
+- CONPY-106: exception handling: type of exception depends now on error code instead of sqlstate
+- CONPY-107: convert negative time values to datetime.timedelta instances
 
 MariaDB Connector/Python 1.0.0
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
 
 Release date: June 24th 2020
 
-Notable Updates:
-  - CONPY-81: Fixed crash when switching between text and binary protocol with same cursor
-  - CONPY-80: Parameters in set_config() method of ConnectionPool class have to be checked against the list of DSN keywords
-  - CONPY-79: When inserting NULL values with executemany() method on a server which doesn't support BULK statements NULL values weren't inserted correctly.
-  - CONPY-78: Since MaxScale doesn't support bulk operations yet, we have to check servers extended capability flag to determine if this feature is supported or not.
-  - CONPY-76: Added aliases username, passwd and db to connection keywords.
-  - CONPY-70: set_config() method needs to check the passed parameter and raise an exception if the parameter type is not a dictionary.
-  - CONPY-72: When deallocating the connection pool class, we need to check beside pool_size if the array containing the connections is valid.
-  - Fixed bug when inserting negative integer values with cursor.execute() method
-  - CONPY-69: Set default character set (utf8mb4) with authentication packet 
+Issues fixed:
+^^^^^^^^^^^^^
+
+- CONPY-69: Set default character set (utf8mb4) with authentication packet 
+- CONPY-70: set_config() method needs to check the passed parameter and raise an exception if the parameter type is not a dictionary.
+- CONPY-72: When deallocating the connection pool class, we need to check beside pool_size if the array containing the connections is valid.
+- CONPY-76: Added aliases username, passwd and db to connection keywords.
+- CONPY-78: Since MaxScale doesn't support bulk operations yet, we have to check servers extended capability flag to determine if this feature is supported or not.
+- CONPY-79: When inserting NULL values with executemany() method on a server which doesn't support BULK statements NULL values weren't inserted correctly.
+- CONPY-80: Parameters in set_config() method of ConnectionPool class have to be checked against the list of DSN keywords
+- CONPY-81: Fixed crash when switching between text and binary protocol with same cursor
+- Fixed bug when inserting negative integer values with cursor.execute() method