docs: Add notes about future changes to tds_version default value.

[skip ci]
pymssql · Nov 8, 2015 · 641db4b · 641db4b
1 parent 999e0d9
commit 641db4b
Show file tree

Hide file tree

Showing 2 changed files with 78 additions and 56 deletions.
diff --git a/docs/ref/_mssql.rst b/docs/ref/_mssql.rst
@@ -91,7 +91,7 @@ Functions
         SET TEXTSIZE 2147483647; -- http://msdn.microsoft.com/en-us/library/aa259190%28v=sql.80%29.aspx
 
     .. versionadded:: 2.1.1
-        The *conn_properties* argument.
+        The *conn_properties* parameter.
 
     .. versionchanged:: 2.1.1
         Before 2.1.1, the initialization queries now specified by
@@ -108,6 +108,22 @@ Functions
     .. versionadded:: 2.1.1
         The ability to connect to Azure.
 
+    .. warning::
+        The *tds_version* parameter, added in version 2.0.0, has a default value
+        of '7.1'.
+
+        This will change with pymssql 2.2.0 when
+
+        * The default value will be changed to None
+        * The version of the TDS protocol to use by default won't be 7.1 anymore
+        * You won't able to rely on such default value nymore and will need to
+          either
+
+          * Specify it value explicitly or
+          * Configure it using facilities provided by FreeTDS (see `here
+            <http://www.freetds.org/userguide/freetdsconf.htm#TAB.FREETDS.CONF>`_
+            `and here <http://www.freetds.org/userguide/envvar.htm>`_)
+
 ``MSSQLConnection`` object properties
 -------------------------------------
 

diff --git a/docs/ref/pymssql.rst b/docs/ref/pymssql.rst
@@ -31,61 +31,67 @@ Functions
                       as_dict=False, host='', appname=None, port='1433',\
                       conn_properties, autocommit=False, tds_version='7.1')
 
-    Constructor for creating a connection to the database. Returns a
-    :class:`Connection` object.
-
-    :param server: database host
-    :type server: string
-    :param user: database user to connect as
-    :type user: string
-    :param password: user's password
-    :type password: string
-    :param database: the database to initially connect to
-    :type database: string
-    :param timeout: query timeout in seconds, default 0 (no timeout)
-    :type timeout: int
-    :param login_timeout: timeout for connection and login in seconds, default 60
-    :type login_timeout: int
-    :param charset: character set with which to connect to the database
-    :type charset: string
-    :keyword as_dict: whether rows should be returned as dictionaries instead of tuples
-    :type as_dict: boolean
-    :keyword appname: Set the application name to use for the connection
-    :type appname: string
-    :keyword port: the TCP port to use to connect to the server
-    :type port: string
-    :keyword conn_properties: SQL queries to send to the server upon connection
-                              establishment. Can be a string or another kind
-                              of iterable of strings. Default value: See
-                              :class:`_mssql.connect <_mssql.MSSQLConnection>`
-    :keyword autocommit: Whether to use default autocommiting mode or not
-    :type autocommit: boolean
-    :keyword tds_version: TDS protocol version to use.
-    :type tds_version: string
-
-    .. warning::
-        Currently, setting *timeout* or *login_timeout* have a process-wide
-        effect because the FreeTDS db-lib API functions used to implement such
-        timeouts have a global effect.
-
-    .. note::
-        If you need to connect to Azure:
-
-        * Use FreeTDS 0.91 or newer
-        * Make sure FreeTDS is built with SSL support
-        * Specify the database name you are connecting to in the ``connect()`` call
-
-    .. versionadded:: 2.1.1
-        The ability to connect to Azure.
-
-    .. versionadded:: 2.1.1
-        The *conn_properties* argument.
-
-    .. versionadded:: 2.1.1
-        The *autocommit* argument.
-
-    .. versionadded:: 2.1.2
-        The *tds_version* argument.
+   Constructor for creating a connection to the database. Returns a
+   :class:`Connection` object.
+
+   :param str server: database host
+   :param str user: database user to connect as
+   :param str password: user's password
+   :param str database: the database to initially connect to
+   :param int timeout: query timeout in seconds, default 0 (no timeout)
+   :param int login_timeout: timeout for connection and login in seconds, default 60
+   :param str charset: character set with which to connect to the database
+   :keyword conn_properties: SQL queries to send to the server upon connection
+                             establishment. Can be a string or another kind of
+                             iterable of strings.  Default value: See
+                             :class:`_mssql.connect() <_mssql.MSSQLConnection>`
+   :keyword bool as_dict: whether rows should be returned as dictionaries instead of tuples
+   :keyword str appname: Set the application name to use for the connection
+   :keyword str port: the TCP port to use to connect to the server
+   :keyword bool autocommit: Whether to use default autocommiting mode or not
+   :keyword str tds_version: TDS protocol version to use.
+
+   .. warning::
+       Currently, setting *timeout* or *login_timeout* has a process-wide
+       effect because the FreeTDS db-lib API functions used to implement such
+       timeouts have a global effect.
+
+   .. note::
+       If you need to connect to Azure:
+
+       * Use FreeTDS 0.91 or newer
+       * Make sure FreeTDS is built with SSL support
+       * Specify the database name you are connecting to in the ``connect()`` call
+
+   .. versionadded:: 2.1.1
+       The ability to connect to Azure.
+
+   .. versionadded:: 2.1.1
+       The *conn_properties* parameter.
+
+   .. versionadded:: 2.1.1
+       The *autocommit* parameter.
+
+   .. versionadded:: 2.1.2
+       The *tds_version* parameter.
+
+   .. warning::
+     The *tds_version* parameter, new in version 2.1.2, has a default value of
+     '7.1'. This is for consistency with the default value of the equally-named
+     parameter of the :class:`_mssql.connect() <_mssql.MSSQLConnection>`
+     function.
+
+     This will change with pymssql 2.2.0 when
+
+     * The default value will be changed to None
+     * The version of the TDS protocol to use by default won't be 7.1 anymore
+     * You won't able to rely on such default value nymore and will need to
+       either
+
+       * Specify it value explicitly or
+       * Configure it using facilities provided by FreeTDS (see `here
+         <http://www.freetds.org/userguide/freetdsconf.htm#TAB.FREETDS.CONF>`_
+         `and here <http://www.freetds.org/userguide/envvar.htm>`_)
 
 .. function:: get_dbversion()