Fix #1560 revisiting Firebird dialect docs

2 files changed, 35 insertions, 11 deletions

diff --git a/lib/sqlalchemy/dialects/firebird/base.py b/lib/sqlalchemy/dialects/firebird/base.py
index 7b0007b68..5cc837848 100644
--- a/lib/sqlalchemy/dialects/firebird/base.py
+++ b/lib/sqlalchemy/dialects/firebird/base.py
@@ -7,11 +7,10 @@
 """
 Support for the Firebird database.
 
-Connectivity is usually supplied via the kinterbasdb_
-DBAPI module.
+Connectivity is usually supplied via the kinterbasdb_ DBAPI module.
 
-Firebird dialects
------------------
+Dialects
+~~~~~~~~
 
 Firebird offers two distinct dialects_ (not to be confused with a
 SQLAlchemy ``Dialect``):
@@ -27,8 +26,8 @@ adjusts its representation of SQL accordingly.  However,
 support for dialect 1 is not well tested and probably has
 incompatibilities.
 
-Firebird Locking Behavior
--------------------------
+Locking Behavior
+~~~~~~~~~~~~~~~~
 
 Firebird locks tables aggressively.  For this reason, a DROP TABLE may
 hang until other transactions are released.  SQLAlchemy does its best
@@ -48,7 +47,7 @@ The above use case can be alleviated by calling ``first()`` on the
 all remaining cursor/connection resources.
 
 RETURNING support
------------------
+~~~~~~~~~~~~~~~~~
 
 Firebird 2.0 supports returning a result set from inserts, and 2.1 extends
 that to deletes and updates.
@@ -60,11 +59,7 @@ parameter when creating the queries::
                       firebird_returning=[empl.c.id, empl.c.salary]).execute().fetchall()
 
 
-.. [#] Well, that is not the whole story, as the client may still ask
-       a different (lower) dialect...
-
 .. _dialects: http://mc-computing.com/Databases/Firebird/SQL_Dialect.html
-.. _kinterbasdb: http://sourceforge.net/projects/kinterbasdb
 
 """
 
diff --git a/lib/sqlalchemy/dialects/firebird/kinterbasdb.py b/lib/sqlalchemy/dialects/firebird/kinterbasdb.py
index 6fbc1877c..4bbd2aafc 100644
--- a/lib/sqlalchemy/dialects/firebird/kinterbasdb.py
+++ b/lib/sqlalchemy/dialects/firebird/kinterbasdb.py
@@ -1,3 +1,32 @@
+# kinterbasdb.py
+# Copyright (C) 2005, 2006, 2007, 2008, 2009 Michael Bayer mike_mp@zzzcomputing.com
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+"""
+The most common way to connect to a Firebird engine is implemented by
+kinterbasdb__, currently maintained__ directly by the Firebird people.
+
+The connection URL is of the form
+``firebird[+kinterbasdb]://user:password@host:port/path/to/db[?key=value&key=value...]``.
+
+Kinterbasedb backend specific keyword arguments are:
+
+type_conv
+  select the kind of mapping done on the types: by default SQLAlchemy
+  uses 200 with Unicode, datetime and decimal support (see details__).
+
+concurrency_level
+  set the backend policy with regards to threading issues: by default
+  SQLAlchemy uses policy 1 (see details__).
+
+__ http://sourceforge.net/projects/kinterbasdb
+__ http://firebirdsql.org/index.php?op=devel&sub=python
+__ http://kinterbasdb.sourceforge.net/dist_docs/usage.html#adv_param_conv_dynamic_type_translation
+__ http://kinterbasdb.sourceforge.net/dist_docs/usage.html#special_issue_concurrency
+"""
+
 from sqlalchemy.dialects.firebird.base import FBDialect, FBCompiler
 from sqlalchemy.engine.default import DefaultExecutionContext