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

… infos
mhammond · Oct 4, 2024 · 4cf15f9 · 4cf15f9
1 parent 842fbef
commit 4cf15f9
Show file tree

Hide file tree

Showing 15 changed files with 61 additions and 54 deletions.
diff --git a/adodbapi/__init__.py b/adodbapi/__init__.py
@@ -36,6 +36,8 @@
     threadsafety as threadsafety,
 )
 
+version = "adodbapi v" + __version__
+
 
 def Binary(aString):
     """This function constructs an object capable of holding a binary (long) string value."""
@@ -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__
diff --git a/adodbapi/ado_consts.py b/adodbapi/ado_consts.py
@@ -1,5 +1,5 @@
-# ADO enumerated constants documented on MSDN:
-# http://msdn.microsoft.com/en-us/library/ms678353(VS.85).aspx
+"""ADO enumerated constants documented on MSDN: \
+http://msdn.microsoft.com/en-us/library/ms678353(VS.85).aspx"""
 
 # IsolationLevelEnum
 adXactUnspecified = -1

diff --git a/adodbapi/apibase.py b/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
 * http://sourceforge.net/projects/pywin32

diff --git a/adodbapi/examples/db_print.py b/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
 

diff --git a/adodbapi/examples/db_table_names.py b/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
 

diff --git a/adodbapi/is64bit.py b/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()

diff --git a/adodbapi/process_connect_string.py b/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
 

diff --git a/adodbapi/schema_table.py b/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
 

diff --git a/adodbapi/setup.py b/adodbapi/setup.py
@@ -1,14 +1,12 @@
-"""adodbapi -- a pure Python PEP 249 DB-API package using Microsoft ADO
+"""adodbapi - a pure Python PEP 249 DB-API package using Microsoft ADO
 
-Adodbapi can be run on CPython 3.5 and later.
+Adodbapi can be run on CPython 3.7 and later.
 """
 
 NAME = "adodbapi"
 MAINTAINER = "Vernon Cole"
 MAINTAINER_EMAIL = "[email protected]"
-DESCRIPTION = (
-    """A pure Python package implementing PEP 249 DB-API using Microsoft ADO."""
-)
+DESCRIPTION = "A pure Python package implementing PEP 249 DB-API using Microsoft ADO."
 URL = "http://sourceforge.net/projects/adodbapi"
 LICENSE = "LGPL"
 CLASSIFIERS = [

diff --git a/adodbapi/test/adodbapitest.py b/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
@@ -1584,8 +1587,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)
 

diff --git a/adodbapi/test/adodbapitestconfig.py b/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:
@@ -70,8 +73,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:

diff --git a/adodbapi/test/dbapi20.py b/adodbapi/test/dbapi20.py
@@ -1,14 +1,14 @@
 #!/usr/bin/env python
-""" Python DB API 2.0 driver compliance unit test suite.
+"""Python DB API 2.0 driver compliance unit test suite.
 
-    This software is Public Domain and may be used without restrictions.
+   This software is Public Domain and may be used without restrictions.
 
- "Now we have booze and barflies entering the discussion, plus rumours of
-  DBAs on drugs... and I won't tell you what flashes through my mind each
-  time I read the subject line with 'Anal Compliance' in it.  All around
-  this is turning out to be a thoroughly unwholesome unit test."
+"Now we have booze and barflies entering the discussion, plus rumours of
+ DBAs on drugs... and I won't tell you what flashes through my mind each
+ time I read the subject line with 'Anal Compliance' in it.  All around
+ this is turning out to be a thoroughly unwholesome unit test."
 
-    -- Ian Bicking
+   -- Ian Bicking
 """
 
 __version__ = "$Revision: 1.15.0 $"[11:-2]

diff --git a/adodbapi/test/is64bit.py b/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()

diff --git a/adodbapi/test/setuptestframework.py b/adodbapi/test/setuptestframework.py
@@ -1,10 +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()

diff --git a/adodbapi/test/test_adodbapi_dbapi20.py b/adodbapi/test/test_adodbapi_dbapi20.py
@@ -1,5 +1,7 @@
-print("This module depends on the dbapi20 compliance tests created by Stuart Bishop")
-print("(see db-sig mailing list history for info)")
+"""This module depends on the dbapi20 compliance tests created by Stuart Bishop
+(see db-sig mailing list history for info)"""
+
+print(__doc__)
 import platform
 import sys
 import unittest