Release 0.6.0

Author: pcisar

docs/changelog.txt

@@ -2,6 +2,29 @@
 Changelog
 #########
 
+Version 0.6.0
+=============
+
+* More documentation.
+* Initial support for Firebird 4+ (interfaces and other definitions). Includes support for
+  interface versions.
+* `Service` renamed to `Server`. Selected functionality moved to inner objects (relates to
+  FB4+ support).
+* New module: `~firebird.driver.config` - Driver configuration
+* New module: `~firebird.driver.interfaces` - Interface wrappers for Firebird new API
+* Changed module: `~firebird.driver.types`
+
+  - Interface wrapper moved to separate module
+  - Buffer managers moved to `~firebird.driver.core` module
+* Changed module: `~firebird.driver.core`
+
+  - `connect()`, `create_database()` and `connect_server()` now use driver configuration.
+  - Simplified/unified transaction isolation specification.
+  - Emit warnings when objects with allocated Firebird resources are disposed (by Python
+    GC) without prior call to `close()`.
+  - Trace instrumentation removed. Use dynamic trace configuration from firebird-base 0.6.0.
+  - `Connection` and `Transaction` information moved to inner objects accesible via `info`
+    properties (relates to FB4+ support).
 
 Version 0.5.0
 =============

docs/conf.py

@@ -23,10 +23,10 @@
 author = 'Pavel Císař'
 
 # The short X.Y version
-version = '0.5.0'
+version = '0.6.0'
 
 # The full version, including alpha/beta/rc tags
-release = '0.5.0'
+release = '0.6.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -54,7 +54,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'requirements.txt']
 
 default_role = 'py:obj'
 
@@ -97,7 +97,7 @@
     ],
 
     # Render the next and previous page links in navbar. (Default: true)
-    #'navbar_sidebarrel': True,
+    'navbar_sidebarrel': False,
 
     # Render the current pages TOC in the navbar. (Default: true)
     #'navbar_pagenav': True,
@@ -183,8 +183,9 @@
 
 # -- Options for intersphinx extension ---------------------------------------
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+# intersphinx
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
+                       'base': ('https://firebird-base.rtfd.io/en/latest', None)}
 
 # -- Options for todo extension ----------------------------------------------
 

docs/getting-started.txt

@@ -20,12 +20,11 @@ Run pip::
 
   $ pip install firebird-driver
 
-
 .. _setuptools: https://pypi.org/project/setuptools/
 .. _PYPI: https://pypi.org/
 .. _ctypes: http://docs.python.org/library/ctypes.html
 .. _pip: https://pypi.org/project/pip/
-
+.. _firebird-base: https://firebird-base.rtfd.io
 
 Quick-start Guide
 *****************
@@ -37,49 +36,90 @@ comprehensive in its coverage of anything else.
 The numerous advanced features of Firebird-driver are covered in another section of this
 documentation, which is not in a tutorial format, though it is replete with examples.
 
+Driver configuration
+====================
+
+The driver uses configuration built on top of `configuration system <firebird.base.config>`
+provided by `firebird-base`_ package. In addition to global settings, the configuration
+also includes the definition of connection parameters to Firebird servers and databases.
+
+The default configuration connects to embedded server using direct/local connection method.
+To access remote servers and databases (or local ones through remote protocols), it's
+neccessary to adjust default configuration, or `register` them in configuration manager.
+
+You can manipulate the configuration objects directly, or load configuration from files or
+strings (in `.ini-style` `ConfigParser` format).
 
 Connecting to a Database
 ========================
 
+**Example 1:**
 
-**Example 1**
-
-A database connection is typically established with code such as this:
+A simple database connection is typically established with code such as this:
 
 .. sourcecode:: python
 
     from firebird.driver import connect
 
-    # The server is named 'bison'; the database file is at '/temp/test.db'.
-    con = connect(dsn='bison:/temp/test.db', user='sysdba', password='pass')
+    # Attach to 'employee' database/alias using embedded server connection
+    con = connect('employee', user='sysdba', password='masterkey')
 
-    # Or, equivalently:
-    con = connect(host='bison', database='/temp/test.db',
-                  user='sysdba', password='pass')
+    # Attach to 'employee' database/alias using local server connection
+    from firebird.driver import driver_config
+    driver_config.server_defaults.host.value = 'localhost'
+    con = connect('employee', user='sysdba', password='masterkey')
 
+    # Set 'user' and 'password' via configuration
+    driver_config.server_defaults.user.value = 'SYSDBA'
+    driver_config.server_defaults.password.value = 'masterkey'
+    con = connect('employee')
 
-**Example 2**
+**Example 2:**
 
-Suppose we want to connect to the database in SQL Dialect 1 and specifying
-UTF-8 as the character set of the connection:
+A database connection typically uses specific configuration, and is established with code
+such as this:
 
 .. sourcecode:: python
 
-    from firebird.driver import connect
+    from firebird.driver import connect, driver_config
 
-    con = connect(
-        dsn='bison:/temp/test.db',
-        user='sysdba', password='pass',
-        dialect=1, # necessary for all dialect 1 databases
-        charset='UTF8' # specify a character set for the connection
-      )
+    # Register Firebird server
+    srv_cfg = """[local]
+    host = localhost
+    user = SYSDBA
+    password = masterkey
+    """
+    driver_config.register_server('local', srv_cfg)
+
+    # Register database
+    db_cfg = """[employee]
+    server = local
+    database = employee.fdb
+    protocol = inet
+    charset = utf8
+    """
+    driver_config.register_database('employee', db_cfg)
 
+    # Attach to 'employee' database
+    con = connect('employee')
+
+.. note::
+
+   Some parameters like 'user' and 'password' could be overriden with keyword parameters.
+   Few parameters like 'crypt_callback' or 'no_db_triggers' could be specified **ONLY**
+   as keyword arguments.
+
+Creating a Database
+===================
+
+A database is created using `~firebird.driver.core.create_database()` function.
+Like `~firebird.driver.core.connect()`, this function uses configuration for specification of
+database parameters like page size, sweep interval etc.
 
 Executing SQL Statements
 ========================
 
-For this section, suppose we have a table defined and populated by the
-following SQL code:
+For this section, suppose we have a table defined and populated by the following SQL code:
 
 .. sourcecode:: sql
 
@@ -92,7 +132,6 @@ following SQL code:
     insert into languages (name, year_released) values ('C',        1972);
     insert into languages (name, year_released) values ('Python',   1991);
 
-
 **Example 1**
 
 This example shows the *simplest* way to print the entire contents of
@@ -102,7 +141,7 @@ the `languages` table:
 
     from firebird.driver import connect
 
-    con = connect(database='/temp/test.db', user='sysdba', password='masterkey')
+    con = connect('test.fdb', user='sysdba', password='masterkey')
 
     # Create a Cursor object that operates in the context of Connection con:
     cur = con.cursor()
@@ -113,14 +152,12 @@ the `languages` table:
     # Retrieve all rows as a sequence and print that sequence:
     print(cur.fetchall())
 
-
 Sample output:
 
 .. sourcecode:: python
 
     [('C', 1972), ('Python', 1991)]
 
-
 **Example 2**
 
 Here's another trivial example that demonstrates various ways of fetching a single row at a time from a `SELECT`-cursor:
@@ -129,7 +166,7 @@ Here's another trivial example that demonstrates various ways of fetching a sing
 
     from firebird.driver import connect
 
-    con = connect(dsn='/temp/test.db', user='sysdba', password='masterkey')
+    con = connect('test.fdb', user='sysdba', password='masterkey')
 
     cur = con.cursor()
     SELECT = "select name, year_released from languages order by year_released"
@@ -145,8 +182,6 @@ Here's another trivial example that demonstrates various ways of fetching a sing
     for row in cur:
         print(f'{row[0]} has been publicly available since {row[1]}.')
 
-
-
 Sample output:
 
 .. sourcecode:: python
@@ -158,7 +193,6 @@ Sample output:
     C has been publicly available since 1972.
     Python has been publicly available since 1991.
 
-
 **Example 3**
 
 The following program is a simplistic table printer (applied in this example to `languages`):
@@ -170,7 +204,7 @@ The following program is a simplistic table printer (applied in this example to
     TABLE_NAME = 'languages'
     SELECT = f'select * from {TABLE_NAME} order by year_released'
 
-    con = connect(dsn='/temp/test.db', user='sysdba', password='masterkey')
+    con = connect('test.fdb', user='sysdba', password='masterkey')
 
     cur = con.cursor()
     cur.execute(SELECT)
@@ -212,7 +246,7 @@ Let's insert more languages:
 
     from firebird.driver import connect
 
-    con = connect(dsn='/temp/test.db', user='sysdba', password='masterkey')
+    con = connect('test.fdb', user='sysdba', password='masterkey')
 
     cur = con.cursor()
 

docs/index.txt

@@ -20,7 +20,7 @@ Content
 *******
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Contents:
 
    getting-started

docs/ref-config.txt

@@ -0,0 +1,31 @@
+.. module:: firebird.driver.config
+    :synopsis: Driver configuration
+
+======================
+firebird.driver.config
+======================
+
+This module contains firebird-driver configuration. Uses configuration classes from firebird-base
+package.
+
+Classes
+=======
+
+DriverConfig
+------------
+.. autoclass:: DriverConfig
+
+ServerConfig
+------------
+.. autoclass:: ServerConfig
+
+DatabaseConfig
+--------------
+.. autoclass:: DatabaseConfig
+
+Globals
+=======
+
+driver_config
+-------------
+.. autodata:: driver_config