rfctr(build): modernize build and docs

- Add GitHub Actions CI.
- Get docs working.
- Update tox config.

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          version: "0.4.15"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Test with pytest + behave
+        run: |
+          uv run pytest --cov-report term-missing --cov=opcdiag --cov=tests tests
+          uv run behave

HISTORY.rst

@@ -1,6 +1,12 @@
 History
 =======
 
+1.1.0 (2024-09-22)
+------------------
+
+* Modernize and repackage with support for Python 3.
+
+
 1.0.0 (2014-01-14)
 ------------------
 

Makefile

@@ -1,43 +1,53 @@
-BEHAVE  = behave
 PACKAGE = opcdiag
-PYTHON  = python
-SETUP   = $(PYTHON) ./setup.py
 
 .PHONY: accept clean coverage readme register test sdist upload
 
 help:
 	@echo "Please use \`make <target>' where <target> is one or more of"
-	@echo "  accept    run acceptance tests using behave"
-	@echo "  clean     delete intermediate work product and start fresh"
-	@echo "  coverage  run nosetests with coverage"
-	@echo "  readme    update README.html from README.rst"
-	@echo "  register  update metadata (README.rst) on PyPI"
-	@echo "  test      run tests using setup.py"
-	@echo "  sdist     generate a source distribution into dist/"
-	@echo "  upload    upload distribution tarball to PyPI"
-
+	@echo "  accept      run acceptance tests using behave"
+	@echo "  build       generate a source distribution and wheel into dist/"
+	@echo "  clean       delete intermediate work product and start fresh"
+	@echo "  cleandocs   delete generated HTML documentation"
+	@echo "  coverage    run unit tests with coverage"
+	@echo "  docs        generate HTML documentation with Sphinx"
+	@echo "  test        run unit tests"
+	@echo "  test-upload upload distribution artifacts in dist/ to Test-PyPI"
+	@echo "  upload      upload distribution artifacts in dist/ to PyPI"
+
+.PHONY: accept
 accept:
-	$(BEHAVE) --stop
+	uv run behave --stop
+
+.PHONY: build
+build:
+	rm -rf dist
+	uv build
 
+.PHONY: clean
 clean:
 	find . -type f -name \*.pyc -exec rm {} \;
 	rm -rf dist *.egg-info .coverage .DS_Store
 
-coverage:
-	py.test --cov-report term-missing --cov=$(PACKAGE) tests/
-
-readme:
-	rst2html README.rst >README.html
-	open README.html
+.PHONY: cleandocs
+cleandocs:
+	$(MAKE) -C docs clean
 
-register:
-	$(SETUP) register
+.PHONY: coverage
+coverage:
+	uv run pytest --cov-report term-missing --cov=$(PACKAGE) --cov=tests tests/
 
-sdist:
-	$(SETUP) sdist
+.PHONY: docs
+docs:
+	$(MAKE) -C docs html
 
+.PHONY: test
 test:
-	$(SETUP) test
+	uv run pytest tests
+
+.PHONY: test-upload
+test-upload: build
+	uv run twine upload --repository testpypi dist/*
 
+.PHONY: upload
 upload:
-	$(SETUP) sdist upload
+	uv run twine upload dist/*

docs/conf.py

@@ -15,9 +15,9 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath(".."))
+import tomli
 
-from opcdiag import __version__
+sys.path.insert(0, os.path.abspath(".."))
 
 # -- General configuration --------------------------------------------------
 
@@ -46,7 +46,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = __version__
+with open("../pyproject.toml", "rb") as f:
+    toml = tomli.load(f)
+version = toml["project"]["version"]
 # The full version, including alpha/beta/rc tags.
 release = version
 

docs/index.rst

@@ -4,7 +4,7 @@ opc-diag
 
 Release v\ |version| (:ref:`Installation <install>`)
 
-.. include:: ../README.rst
+.. include:: ../README.md
 
 
 User Guide

docs/install.rst

@@ -12,22 +12,6 @@ command line::
 
    $ pip install opc-diag
 
-There are, however, some common difficulties:
-
-|opcd| depends on the ``lxml`` Python package, which cannot reliably be
-installed by ``pip`` or ``easy_install`` on Windows. Building it from source
-requires a compiler and other items the typical Windows user will not have
-installed. Therefore we recommend Windows users manually install |lxml| using
-a GUI installer before installing |opcd|. For that, the precompiled binaries at
-http://www.lfd.uci.edu/~gohlke/pythonlibs/ have been the best source so far.
-
-|lxml| depends on the ``libxslt`` and ``libxml2`` libraries. If those are not
-present the |lxml| build will fail during the install. Linux users shouldn't
-have too much trouble as these libraries are commonly installed by default. If
-not, ``yum`` or ``apt-get`` is your friend for getting them installed. OS
-X users running recent versions may also find these already installed. If not,
-they can be installed using Homebrew.
-
 
 Getting the Code
 ----------------

pyproject.toml

@@ -1,6 +1,10 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
 [project]
 name = "opc-diag"
-version = "1.0.0"
+version = "1.1.0"
 authors = [{name = "Steve Canny", email = "[email protected]"}]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -61,14 +65,17 @@ filterwarnings = [
 looponfailroots = ["src", "tests"]
 norecursedirs = [
     ".git",
+    ".ruff_cache",
     "dist",
     "docs",
     "features",
     "src",
+    "typings",
+    ".tox",
 ]
 python_files = ["test_*.py"]
 python_classes = ["Test", "Describe"]
-python_functions = ["it_", "its_", "they_", "and_", "but_"]
+python_functions = ["test_", "it_", "its_", "they_", "and_", "but_"]
 
 [tool.ruff]
 exclude = []
@@ -102,10 +109,17 @@ known-local-folder = ["helpers"]
 
 [tool.uv]
 dev-dependencies = [
+    "alabaster<0.7.14",
     "behave>=1.2.6",
+    "jinja2==2.11.3",
+    "markupsafe==0.23",
     "pyright>=1.1.381",
+    "pytest-cov>=5.0.0",
     "pytest>=8.3.3",
     "ruff>=0.6.7",
+    "sphinx==1.8.6",
+    "tox>=4.20.0",
+    "twine>=5.1.1",
     "types-lxml>=2024.9.16",
 ]
 

src/opcdiag/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.0.0"  # pragma: no cover

src/opcdiag/controller.py

@@ -17,10 +17,7 @@ class OpcController:
     """
 
     def browse(self, pkg_path: str, uri_tail: str):
-        """
-        Display pretty-printed XML contained in package item with URI ending
-        with *uri_tail* in package at *pkg_path*.
-        """
+        """Display pretty-printed XML of part with *uri_tail* in package at `pkg_path`."""
         pkg = Package.read(pkg_path)
         pkg_item = pkg.find_item_by_uri_tail(uri_tail)
         item_presenter = ItemPresenter(pkg_item)

src/opcdiag/model.py

@@ -162,7 +162,11 @@ def blob(self, value: bytes):
     @property
     def element(self) -> etree._Element:
         """Return an lxml.etree Element obtained by parsing the XML in this item's blob."""
-        return etree.fromstring(self._blob)
+        element = etree.fromstring(self._blob)
+        # -- this handles some odd cases where the XML was hand edited and some whitespace
+        # -- tail-text was left.
+        etree.indent(element)
+        return element
 
     @property
     def is_content_types(self) -> bool:

src/opcdiag/view.py

@@ -15,10 +15,7 @@ def _write(text: str):
 
 
 class OpcView:
-    """
-    Interfaces to the console by formatting command results for proper
-    display.
-    """
+    """Interfaces to the console by formatting command results for proper display."""
 
     @staticmethod
     def item_diff(diff: str):
@@ -43,12 +40,9 @@ def package_diff(
         _write(text)
 
     @staticmethod
-    def pkg_item(pkg_item: ItemPresenter):
-        """
-        Display the text value of pkg_item, adding a linefeed at the end to
-        make the terminal happy.
-        """
-        text = "%s\n" % pkg_item.text
+    def pkg_item(presenter: ItemPresenter):
+        """Display the text value of pkg_item, adding a linefeed at end to make terminal happy."""
+        text = "%s\n" % presenter.text
         _write(text)
 
     @staticmethod

tests/test_phys_pkg.py

@@ -116,14 +116,14 @@ def it_can_create_a_new_empty_directory(self):
         """Note: tests integration with filesystem"""
         # case: created if does not exist
         # ------------------------------
-        if os.path.exists(DELETEME_DIR):
+        if os.path.exists(DELETEME_DIR):  # pragma: no cover
             shutil.rmtree(DELETEME_DIR)
         PhysPkg._clear_or_make_dir(FOOBAR_DIR)
         assert os.path.exists(FOOBAR_DIR)
 
         # case: re-created if exists
         # ------------------------------
-        if os.path.exists(DELETEME_DIR):
+        if os.path.exists(DELETEME_DIR):  # pragma: no cover
             shutil.rmtree(DELETEME_DIR)
         os.makedirs(FOOBAR_DIR)
         with open(FOOBAR_FILEPATH, "w") as f:

tox.ini

@@ -1,26 +1,10 @@
-#
-# tox.ini
-#
-# Copyright (C) 2012, 2013 Steve Canny [email protected]
-#
-# This module is part of python-opc and is released under the MIT License:
-# http://www.opensource.org/licenses/mit-license.php
-#
-# Configuration for tox and pytest
-
-[pytest]
-norecursedirs = doc *.egg-info features .git opcdiag .tox
-python_classes = Test Describe
-python_functions = test_ it_ they_
-
 [tox]
-envlist = py26, py27, py33
+envlist = py39, py310, py311, py312
 
 [testenv]
 deps =
     behave
     lxml
-    mock
     pytest
 
 commands =