adodbapi: improve module docstrings, top-of-file comments and version infos

adodbapi/__init__.py

@@ -36,24 +36,26 @@
     threadsafety as threadsafety,
 )
 
+version = "adodbapi v" + __version__
+
 
 def Binary(aString):
     """This function constructs an object capable of holding a binary (long) string value."""
     return bytes(aString)
 
 
 def Date(year, month, day):
-    "This function constructs an object holding a date value."
+    """This function constructs an object holding a date value."""
     return dateconverter.Date(year, month, day)
 
 
 def Time(hour, minute, second):
-    "This function constructs an object holding a time value."
+    """This function constructs an object holding a time value."""
     return dateconverter.Time(hour, minute, second)
 
 
 def Timestamp(year, month, day, hour, minute, second):
-    "This function constructs an object holding a time stamp value."
+    """This function constructs an object holding a time stamp value."""
     return dateconverter.Timestamp(year, month, day, hour, minute, second)
 
 
@@ -76,6 +78,3 @@ def TimestampFromTicks(ticks):
     ticks value (number of seconds since the epoch;
     see the documentation of the standard Python time module for details)."""
     return Timestamp(*time.gmtime(ticks)[:6])
-
-
-version = "adodbapi v" + __version__

adodbapi/ado_consts.py

@@ -1,6 +1,6 @@
-# ADO enumerated constants documented on MSDN:
-# https://learn.microsoft.com/en-us/sql/ado/reference/ado-api/ado-enumerated-constants
-# TODO: Update to https://learn.microsoft.com/en-us/sql/ado/reference/ado-api/ado-enumerated-constants
+"""ADO enumerated constants documented on MSDN: \
+http://msdn.microsoft.com/en-us/library/ms678353(VS.85).aspx"""
+# TODO: Update to constants in https://learn.microsoft.com/en-us/sql/ado/reference/ado-api/ado-enumerated-constants
 
 # IsolationLevelEnum
 adXactUnspecified = -1

adodbapi/adodbapi.py

@@ -157,7 +157,6 @@ def format_parameters(ADOparameters, show_value=False):
 
 def _configure_parameter(p, value, adotype, settings_known):
     """Configure the given ADO Parameter 'p' with the Python 'value'."""
-
     if adotype in api.adoBinaryTypes:
         p.Size = len(value)
         p.AppendChunk(value)
@@ -227,7 +226,7 @@ class Connection:
 
     @property
     def dbapi(self):  # a proposed db-api version 3 extension.
-        "Return a reference to the DBAPI module for this Connection."
+        """Return a reference to the DBAPI module for this Connection."""
         return api
 
     def __init__(self):  # now define the instance attributes
@@ -439,18 +438,18 @@ def __getattr__(self, item):
             )
 
     def cursor(self):
-        "Return a new Cursor Object using the connection."
+        """Return a new Cursor Object using the connection."""
         self.messages = []
         c = Cursor(self)
         return c
 
     def _i_am_here(self, crsr):
-        "message from a new cursor proclaiming its existence"
+        """message from a new cursor proclaiming its existence"""
         oid = id(crsr)
         self.cursors[oid] = crsr
 
     def _i_am_closing(self, crsr):
-        "message from a cursor giving connection a chance to clean up"
+        """message from a cursor giving connection a chance to clean up"""
         try:
             del self.cursors[id(crsr)]
         except:
@@ -580,11 +579,11 @@ def __next__(self):
         raise StopIteration
 
     def __enter__(self):
-        "Allow database cursors to be used with context managers."
+        """Allow database cursors to be used with context managers."""
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        "Allow database cursors to be used with context managers."
+        """Allow database cursors to be used with context managers."""
         self.close()
 
     def _raiseCursorError(self, errorclass, errorvalue):
@@ -771,7 +770,6 @@ def get_returned_parameters(self):
         """with some providers, returned parameters and the .return_value are not available until
         after the last recordset has been read.  In that case, you must coll nextset() until it
         returns None, then call this method to get your returned information."""
-
         # store procedures may return altered parameters, including an added "return value" item
         retLst = []
         for p in tuple(self.cmd.Parameters):

adodbapi/apibase.py

@@ -1,4 +1,4 @@
-"""adodbapi.apibase - A python DB API 2.0 (PEP 249) interface to Microsoft ADO
+"""adodbapi - A python DB API 2.0 (PEP 249) interface to Microsoft ADO
 
 Copyright (C) 2002 Henrik Ekelund, version 2.1 by Vernon Cole
 * https://sourceforge.net/projects/pywin32
@@ -183,24 +183,24 @@ def ComDateFromTuple(self, t, microseconds=0):
         return integerPart + fractPart
 
     def DateObjectFromCOMDate(self, comDate):
-        "Returns an object of the wanted type from a ComDate"
+        """Returns an object of the wanted type from a ComDate"""
         raise NotImplementedError  # "Abstract class"
 
     def Date(self, year, month, day):
-        "This function constructs an object holding a date value."
+        """This function constructs an object holding a date value."""
         raise NotImplementedError  # "Abstract class"
 
     def Time(self, hour, minute, second):
-        "This function constructs an object holding a time value."
+        """This function constructs an object holding a time value."""
         raise NotImplementedError  # "Abstract class"
 
     def Timestamp(self, year, month, day, hour, minute, second):
-        "This function constructs an object holding a time stamp value."
+        """This function constructs an object holding a time stamp value."""
         raise NotImplementedError  # "Abstract class"
         # all purpose date to ISO format converter
 
     def DateObjectToIsoFormatString(self, obj):
-        "This function should return a string in the format 'YYYY-MM-dd HH:MM:SS:ms' (ms optional)"
+        """This function should return a string in the format 'YYYY-MM-dd HH:MM:SS:ms' (ms optional)"""
         try:  # most likely, a datetime.datetime
             s = obj.isoformat(" ")
         except (TypeError, AttributeError):
@@ -253,7 +253,7 @@ def __init__(self):  # caution: this Class gets confused by timezones and DST
         self.types.add(time.struct_time)
 
     def DateObjectFromCOMDate(self, comDate):
-        "Returns ticks since 1970"
+        """Returns ticks since 1970"""
         if isinstance(comDate, datetime.datetime):
             return comDate.timetuple()
         else:
@@ -477,7 +477,7 @@ def __init__(self, aDict: Mapping[Iterable[int] | int, Callable[[object], object
     def __setitem__(
         self, adoType: Iterable[int] | int, cvtFn: Callable[[object], object]
     ):
-        "set a single item, or a whole iterable of items"
+        """set a single item, or a whole iterable of items"""
         if isinstance(adoType, Iterable):
             # user passed us an iterable, set them individually
             for type in adoType:

adodbapi/examples/db_print.py

@@ -1,4 +1,4 @@
-"""db_print.py -- a simple demo for ADO database reads."""
+"""A simple demo for ADO database reads."""
 
 import sys
 

adodbapi/examples/db_table_names.py

@@ -1,4 +1,4 @@
-"""db_table_names.py -- a simple demo for ADO database table listing."""
+"""A simple demo for ADO database table listing."""
 
 import sys
 

adodbapi/is64bit.py

@@ -1,13 +1,13 @@
-"""is64bit.Python() --> boolean value of detected Python word size. is64bit.os() --> os build version"""
-
 import sys
 
 
 def Python():
+    """boolean value of detected Python word size."""
     return sys.maxsize > 2147483647
 
 
 def os():
+    """os build version"""
     import platform
 
     pm = platform.machine()

adodbapi/process_connect_string.py

@@ -1,4 +1,4 @@
-"""a clumsy attempt at a macro language to let the programmer execute code on the server (ex: determine 64bit)"""
+"""A clumsy attempt at a macro language to let the programmer execute code on the server (ex: determine 64bit)"""
 
 from . import is64bit
 

adodbapi/schema_table.py

@@ -1,9 +1,8 @@
-"""call using an open ADO connection --> list of table names"""
-
 from . import adodbapi
 
 
 def names(connection_object):
+    """call using an open ADO connection --> list of table names"""
     ado = connection_object.adoConn
     schema = ado.OpenSchema(20)  # constant = adSchemaTables
 

adodbapi/setup.py

@@ -1,15 +1,9 @@
-"""adodbapi -- a pure Python PEP 249 DB-API package using Microsoft ADO
+__doc__ = """adodbapi - A pure Python package implementing PEP 249 DB-API using Microsoft ADO."""
 
-Adodbapi can be run on CPython 3.8 and later.
-"""
-
-NAME = "adodbapi"
+NAME, DESCRIPTION = __doc__.split(" - ", 1)
 MAINTAINER = "Vernon Cole"
 MAINTAINER_EMAIL = "vernondcole@gmail.com"
-DESCRIPTION = (
-    """A pure Python package implementing PEP 249 DB-API using Microsoft ADO."""
-)
-URL = "https://sourceforge.net/projects/adodbapi"
+URL = "http://sourceforge.net/projects/adodbapi"
 LICENSE = "LGPL"
 CLASSIFIERS = [
     "Development Status :: 5 - Production/Stable",
@@ -50,7 +44,6 @@ def setup_package():
         description=DESCRIPTION,
         url=URL,
         keywords="database ado odbc dbapi db-api Microsoft SQL",
-        ##        download_url=DOWNLOAD_URL,
         long_description=open("README.txt").read(),
         license=LICENSE,
         classifiers=CLASSIFIERS,

adodbapi/test/adodbapitest.py

@@ -1,27 +1,30 @@
-"""Unit tests version 2.6.1.0 for adodbapi"""
+"""\
+Unit tests for adodbapi
+-----------------------
 
-"""
-    adodbapi - A python DB API 2.0 interface to Microsoft ADO
+adodbapi - A python DB API 2.0 interface to Microsoft ADO
 
-    Copyright (C) 2002  Henrik Ekelund
+Copyright (C) 2002  Henrik Ekelund
 
-    This library is free software; you can redistribute it and/or
-    modify it under the terms of the GNU Lesser General Public
-    License as published by the Free Software Foundation; either
-    version 2.1 of the License, or (at your option) any later version.
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
 
-    This library is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-    Lesser General Public License for more details.
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
 
-    You should have received a copy of the GNU Lesser General Public
-    License along with this library; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
-    Updates by Vernon Cole
+Updates by Vernon Cole
 """
 
+__version__ = "2.6.1.0"
+
 import copy
 import datetime
 import decimal
@@ -42,7 +45,7 @@ def randomstring(length):
 
 
 class CommonDBTests(unittest.TestCase):
-    "Self contained super-simple tests in easy syntax, should work on everything between mySQL and Oracle"
+    """Self contained super-simple tests in easy syntax, should work on everything between mySQL and Oracle"""
 
     def setUp(self):
         self.engine = "unknown"
@@ -1532,8 +1535,8 @@ def __exit__(self, exc_type, exc_val, exc_tb):
     mysuite = copy.deepcopy(suite)
     with cleanup_manager():
         defaultDateConverter = adodbapi.dateconverter
-        print(__doc__)
-        print("Default Date Converter is %s" % (defaultDateConverter,))
+        print(str(__doc__).split("\n")[0], "version", __version__)
+        print(f"Default Date Converter is {defaultDateConverter}")
         dateconverter = defaultDateConverter
         unittest.TextTestRunner().run(mysuite)
 

adodbapi/test/adodbapitestconfig.py

@@ -1,5 +1,4 @@
-# Configure this to _YOUR_ environment in order to run the testcases.
-"testADOdbapiConfig.py v 2.6.2.B00"
+"""Configure this to _YOUR_ environment in order to run the testcases."""
 
 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 # #
@@ -14,11 +13,15 @@
 import platform
 import random
 import sys
+from pathlib import Path
 
 import is64bit
 import setuptestframework
 import tryconnection
 
+__version__ = "2.6.2.B00"
+version = f"{Path(__file__).name} v{__version__}"
+
 print("\nPython", sys.version)
 node = platform.node()
 try:
@@ -66,8 +69,9 @@
 
 import adodbapi  # will (hopefully) be imported using the "pth" discovered above
 
-print(adodbapi.version)  # show version
-print(__doc__)
+# show versions
+print(adodbapi.version)
+print(version)
 
 verbose = False
 for a in sys.argv:

adodbapi/test/dbapi20.py

@@ -777,7 +777,7 @@ def help_nextset_setUp(self, cur):
         # cur.execute(sql)
 
     def help_nextset_tearDown(self, cur):
-        "If cleaning up is needed after nextSetTest"
+        """If cleaning up is needed after nextSetTest"""
         raise NotImplementedError("Helper not implemented")
         # cur.execute("drop procedure deleteme")
 

adodbapi/test/is64bit.py

@@ -1,13 +1,13 @@
-"""is64bit.Python() --> boolean value of detected Python word size. is64bit.os() --> os build version"""
-
 import sys
 
 
 def Python():
+    """boolean value of detected Python word size."""
     return sys.maxsize > 2147483647
 
 
 def os():
+    """os build version"""
     import platform
 
     pm = platform.machine()

adodbapi/test/setuptestframework.py

@@ -1,11 +1,12 @@
-#!/usr/bin/python2
-# Configure this in order to run the testcases.
-"setuptestframework.py v 2.6.0.8"
+#!/usr/bin/env python
+"""Configure this in order to run the testcases."""
 
 import os
 import shutil
 import tempfile
 
+__version__ = "2.6.0.8"
+
 
 def maketemp():
     temphome = tempfile.gettempdir()