Improvement in code quality before the 0.9.x branch was forked

.github/workflows/test.yml

@@ -14,8 +14,15 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install Requirements
         run: |
-          python -m pip install --upgrade pip setuptools wheel
-          pip install -r requirements-dev.txt
+          make venv
       - name: Run Tests
         run: |
-          python tests.py
+          case ${{ matrix.python-version }} in
+              3.7)
+                  echo "WARNING: skip pylint and black test in python 3.7"
+                  make test
+                  ;;
+              *)
+                  make black pylint test
+                  ;;
+          esac

.gitignore

@@ -10,3 +10,6 @@ venv/**/*
 *.sublime-*
 .coverage
 venv*
+
+.venv
+.tool-versions

.pylintrc

@@ -0,0 +1,29 @@
+# -*- coding: utf-8; mode: conf-unix -*-
+[MASTER]
+ignore=.git, .venv
+jobs=0
+
+[MESSAGES CONTROL]
+disable=duplicate-code,
+        missing-function-docstring,
+	missing-class-docstring,
+	missing-docstring,
+	too-few-public-methods,
+	too-many-arguments,
+	consider-using-f-string,
+	invalid-name,
+
+[FORMAT]
+max-line-length=120
+max-module-lines=2000
+expected-line-ending-format=LF
+
+[LOGGING]
+logging-modules=logging
+
+[MISCELLANEOUS]
+notes=
+
+[DESIGN]
+max-attributes=20
+

ACKNOWLEDGEMENTS.txt

@@ -1,9 +1,9 @@
-Enormous thanks to:
-Jeffrey Harris, for his incredible work on the original package
-Tim Baxter, for all his work maintaining vobject over the past few years
-Adieu, for keeping things alive on github
-Kristian Glass, for his enormous help with testing and Python3 matters
-Gustavo Niemeyer, for all his work on dateutil
-Dave Cridland, for helping talk about vobject and working on vcard
-TJ Gabbour, for putting his heart into parsing
-Sameen Karim and Will Percival, for maintaining the package at Eventable.
+Enormous thanks to:
+Jeffrey Harris, for his incredible work on the original package
+Tim Baxter, for all his work maintaining vobject over the past few years
+Adieu, for keeping things alive on github
+Kristian Glass, for his enormous help with testing and Python3 matters
+Gustavo Niemeyer, for all his work on dateutil
+Dave Cridland, for helping talk about vobject and working on vcard
+TJ Gabbour, for putting his heart into parsing
+Sameen Karim and Will Percival, for maintaining the package at Eventable.

Makefile

@@ -0,0 +1,63 @@
+# -*- coding: utf-8; mode: makefile-gmake -*-
+
+test:
+	.venv/bin/python tests.py
+
+clean:
+	rm -rf .venv
+
+# HINT:
+# - black is not supported in py2 and py3.7 support stopped in black v23.7.0
+#   https://github.com/psf/black/blob/main/CHANGES.md#2370
+# - option --skip-string-normalization protects (among other things),
+#   against deleting the unicode prefix in Python 2
+
+format: venv
+	- .venv/bin/python -m black --skip-string-normalization .
+	@echo "\n"
+	@echo "WARNING:"
+	@echo "  Not all modifications from black are compatible to Python v2.x !!!"
+	@echo "  E.g. don't merge patches of Python-2 unicode like: u'lorem ..' --> 'lorem ..'"
+	@echo "\n"
+
+black: venv
+	.venv/bin/python -m black --skip-string-normalization --check --diff .
+
+# HINT: pylint uses the AST (https://docs.python.org/3/library/ast.html) from
+# the python interpreter.  To lint a py2 code base a Python 2 interpreter is
+# needed.
+
+# pylint in py3.x: all rules are taken from .pylintrc, additional some options
+# disable to be py2 compatible
+pylint: venv
+	.venv/bin/python -m pylint --output-format=parseable \
+		--disable=useless-option-value,redundant-u-string-prefix,unnecessary-pass,super-with-arguments \
+		./vobject/ setup.py tests.py
+
+# pylint in py2.7: addtional to the rules from .pylintrc disable messages which
+# are only relevant in python 3
+# Latest pylint version for py2 is pylint v1.9.5
+pylint2.7: venv2.7
+	.venv/bin/python -m pylint --output-format=parseable \
+		--disable=bad-option-value,bad-continuation,superfluous-parens,old-style-class \
+		./vobject/ setup.py tests.py
+
+venv: clean
+	- asdf local python system
+	@python --version
+	@python -c "import sys; sys.version_info[0] == 3 or (sys.stderr.write('ERROR: python 3 is required!\n'), sys.exit(42))"
+	python -m venv .venv
+	.venv/bin/python -m pip install --upgrade pip setuptools wheel
+	.venv/bin/pip install -r requirements-dev.txt
+
+venv2.7: clean
+	- asdf local python 2.7.18
+	@python --version
+	@python -c "import sys; sys.version_info[0] == 2 or (sys.stderr.write('ERROR: python 2 is required!\n'), sys.exit(42))"
+	python -m pip install virtualenv
+	python -m virtualenv .venv
+	.venv/bin/python -m pip install --upgrade pip setuptools wheel
+	.venv/bin/pip install -r requirements-dev.txt
+
+
+.PHONY: test clean venv venv2.7 black pylint pylint2.7

README.md

@@ -57,12 +57,50 @@ VObject requires Python 2.7 or higher, along with the [dateutil](https://pypi.py
 
 # Running tests
 
-To run all tests, use:
+To format code and run all tests before creating a git-commit, use:
 
+```bash
+$ make format pylint test
 ```
-python tests.py
+To run the Python 2.7 test use:
+
+```bash
+$ make clean venv2.7 test pylint2.7
+```
+
+> [!CAUTION]
+> A python runtime that has [not yet reached EOL](https://endoflife.date/python) is required for development and testing!
+
+
+## Python 2.7
+
+If you want to test with Python 2.7 its recommended to manage runtime versions by [asdf](https://asdf-vm.com/).  If you have not installed, [download](https://asdf-vm.com/guide/getting-started.html#_2-download-asdf) and [install](https://asdf-vm.com/guide/getting-started.html#_3-install-asdf) asdf ([v0.14.0](https://github.com/asdf-vm/asdf/tags)):
+
+```bash
+$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
+$ echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
+$ echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
 ```
 
+Start a new shell and try to [install plugins](https://asdf-vm.com/guide/getting-started.html#install-the-plugin) / make sure you have the [required system dependencies](https://github.com/pyenv/pyenv/wiki#suggested-build-environment) installed before trying to install Python runtimes.
+
+```bash
+$ asdf update
+$ asdf plugin add python https://github.com/danhper/asdf-python.git
+$ asdf install python 2.7.18
+```
+
+Jump (`cd`) into vobject repos's root folder and configure asdf to use Python 2.7.18 in the vobject project.
+
+```bash
+$ cd /xyz/vobject/
+$ asdf local python 2.7.18
+$ python --version
+Python 2.7.18
+```
+
+With asdf you can install any (python) runtime, use `asdf list all python` to get a list of python runtimes available.  To use your system's Python in the vobject project use `asdf local python system`.
+
 
 # Usage
 

requirements-dev.txt

@@ -1,4 +1,7 @@
+black ==24.3.0; python_version >= "3.8"
 coverage
-python-dateutil >= 2.4.0
+pylint ==1.9.5; python_version=="2.7"
+pylint ==3.1.0; python_version >= "3.8"
+python-dateutil >=2.4.0
 setuptools
 wheel

setup.py

@@ -1,67 +1,68 @@
-"""
-VObject: module for reading vCard and vCalendar files
-
-Description
------------
-
-Parses iCalendar and vCard files into Python data structures, decoding the
-relevant encodings. Also serializes vobject data structures to iCalendar, vCard,
-or (experimentally) hCalendar unicode strings.
-
-Requirements
-------------
-
-Requires python 2.7 or later, dateutil 2.4.0 or later and six.
-
-Recent changes
---------------
-    - Revert too-strict serialization of timestamp values - broke too many other
-       implementations
-
-For older changes, see
-   - http://py-vobject.github.io/vobject/#release-history or
-   - http://vobject.skyhouseconsulting.com/history.html
-"""
-
-from setuptools import setup, find_packages
-
-doclines = (__doc__ or '').splitlines()
-
-setup(name = "vobject",
-      version = "0.9.7",
-      author = "Jeffrey Harris",
-      author_email = "jeffrey@osafoundation.org",
-      maintainer = "David Arnold",
-      maintainer_email="davida@pobox.com",
-      license = "Apache",
-      zip_safe = True,
-      url = "http://py-vobject.github.io/vobject/",
-      download_url = 'https://github.com/py-vobject/vobject/tarball/0.9.7',
-      bugtrack_url = "https://github.com/py-vobject/vobject/issues",
-      entry_points = {
-            'console_scripts': [
-                  'ics_diff = vobject.ics_diff:main',
-                  'change_tz = vobject.change_tz:main'
-            ]
-      },
-      include_package_data = True,
-      install_requires = ['python-dateutil >= 2.4.0', 'six'],
-      platforms = ["any"],
-      packages = find_packages(),
-      description = "A full-featured Python package for parsing and creating "
-                    "iCalendar and vCard files",
-      long_description = "\n".join(doclines[2:]),
-      keywords = ['vobject', 'icalendar', 'vcard', 'ics', 'vcs', 'hcalendar'],
-      test_suite="tests",
-      classifiers =  """
-      Development Status :: 5 - Production/Stable
-      Environment :: Console
-      Intended Audience :: Developers
-      License :: OSI Approved :: Apache Software License
-      Natural Language :: English
-      Operating System :: OS Independent
-      Programming Language :: Python
-      Programming Language :: Python :: 2.7
-      Programming Language :: Python :: 3
-      Topic :: Text Processing""".strip().splitlines()
-      )
+"""
+VObject: module for reading vCard and vCalendar files
+
+Description
+-----------
+
+Parses iCalendar and vCard files into Python data structures, decoding the
+relevant encodings. Also serializes vobject data structures to iCalendar, vCard,
+or (experimentally) hCalendar unicode strings.
+
+Requirements
+------------
+
+Requires python 2.7 or later, dateutil 2.4.0 or later and six.
+
+Recent changes
+--------------
+    - Revert too-strict serialization of timestamp values - broke too many other
+       implementations
+
+For older changes, see
+   - http://py-vobject.github.io/vobject/#release-history or
+   - http://vobject.skyhouseconsulting.com/history.html
+"""
+
+from setuptools import setup, find_packages
+
+doclines = (__doc__ or "").splitlines()
+
+setup(
+    name="vobject",
+    version="0.9.7",
+    author="Jeffrey Harris",
+    author_email="jeffrey@osafoundation.org",
+    maintainer="David Arnold",
+    maintainer_email="davida@pobox.com",
+    license="Apache",
+    zip_safe=True,
+    url="http://py-vobject.github.io/vobject/",
+    download_url="https://github.com/py-vobject/vobject/tarball/0.9.7",
+    bugtrack_url="https://github.com/py-vobject/vobject/issues",
+    entry_points={
+        "console_scripts": [
+            "ics_diff = vobject.ics_diff:main",
+            "change_tz = vobject.change_tz:main",
+        ]
+    },
+    include_package_data=True,
+    install_requires=["python-dateutil >= 2.4.0", "six"],
+    platforms=["any"],
+    packages=find_packages(),
+    description="A full-featured Python package for parsing and creating "
+    "iCalendar and vCard files",
+    long_description="\n".join(doclines[2:]),
+    keywords=["vobject", "icalendar", "vcard", "ics", "vcs", "hcalendar"],
+    test_suite="tests",
+    classifiers="""
+      Development Status :: 5 - Production/Stable
+      Environment :: Console
+      Intended Audience :: Developers
+      License :: OSI Approved :: Apache Software License
+      Natural Language :: English
+      Operating System :: OS Independent
+      Programming Language :: Python
+      Programming Language :: Python :: 2.7
+      Programming Language :: Python :: 3
+      Topic :: Text Processing""".strip().splitlines(),
+)