Improved comments

pyproject.toml

@@ -2,9 +2,16 @@
 requires = ["setuptools", "wheel"]
 build-backend = "setuptools.build_meta"
 
-
+# The [tool.poetry] metadata has been removed from this file, because 
+# we have switched to Pipenv for dependency management and setuptools
+# for the build system.  All metadata has been moved either to
+# Pipfile or setup.py.
+# The one key that doesn't map over nicely is the exclusion of 
+# the node_modules folder, i.e. the line below:
 #exclude = ["**/node_modules/"] # I've tried to put this in the "packages" key but not sure it works.
-
+# I have left it here in case we ever switch back to Poetry, but I 
+# don't believe it's critical at present, because we don't use 
+# the Python package - we distribute a tarball directly.
 
 [tool.black]
 exclude = '(\.eggs|\.git|\.venv|\venv|node_modules/)'

setup.py

@@ -1,9 +1,12 @@
-"""A setuptools based setup module.
+"""A setuptools based setup module for the OpenFlexure Microscope server
-See:
+
+This file was prepared according to:
 https://packaging.python.org/guides/distributing-packages-using-setuptools/
+
+
 """
 
-# Always prefer setuptools over distutils
+# the following imports, from the guide above, prefer `setuptools` to `distutils`
 from setuptools import setup, find_packages
 from os import path
 
@@ -13,68 +16,32 @@ here = path.abspath(path.dirname(__file__))
 with open(path.join(here, "README.md"), encoding="utf-8") as f:
     long_description = f.read()
 
-# Arguments marked as "Required" below must be included for upload to PyPI.
+# Not all arguments to `setup()` are required for upload to PyPI.
-# Fields marked as "Optional" may be commented out.
+# See the tutorial linked to at the top for which ones are needed.
 
 setup(
     name="openflexure-microscope-server",
     version="2.10.0b0",
     description="Python module, and Flask-based web API, to run the OpenFlexure Microscope.",
-    long_description=long_description,  # Optional, read from README.md
+    long_description=long_description,
-    # Denotes that our long_description is in Markdown; valid values are
+    long_description_content_type="text/markdown",
-    long_description_content_type="text/markdown",  # Optional (see note above)
+    url="https://www.openflexure.org",  # "home-page" metadata field
-    # This should be a valid link to your project's main homepage.
+    author="Joel Collins, Richard Bowman, Julian Stirling",
-    #
+    author_email="contact@openflexure.org",
-    # This field corresponds to the "Home-Page" metadata field:
-    # https://packaging.python.org/specifications/core-metadata/#home-page-optional
-    url="https://www.openflexure.org",  # Optional
-    # This should be your name or the name of the organization which owns the
-    # project.
-    author="Joel Collins, Richard Bowman, Julian Stirling",  # Optional
-    # This should be a valid email address corresponding to the author listed
-    # above.
-    author_email="contact@openflexure.org",  # Optional
-    # Classifiers help users find your project by categorizing it.
-    #
     # For a list of valid classifiers, see https://pypi.org/classifiers/
-    classifiers=[  # Optional
+    # NB declaring Python versions here doesn't affect dependency resolution - it's for info only.
-        #        # How mature is this project? Common values are
+    classifiers=["License :: OSI Approved :: GNU General Public License v3 (GPLv3)"],
-        #        #   3 - Alpha
-        #        #   4 - Beta
-        #        #   5 - Production/Stable
-        #        "Development Status :: 3 - Alpha",
-        #        # Indicate who your project is intended for
-        #        "Intended Audience :: Developers",
-        #        "Topic :: Software Development :: Build Tools",
-        #        # Pick your license as you wish
-        "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
-        #        # Specify the Python versions you support here. In particular, ensure
-        #        # that you indicate whether you support Python 2, Python 3 or both.
-        #        # These classifiers are *not* checked by 'pip install'. See instead
-        #        # 'python_requires' below.
-        #        "Programming Language :: Python :: 2",
-        #        "Programming Language :: Python :: 2.7",
-        #        "Programming Language :: Python :: 3",
-        #        "Programming Language :: Python :: 3.5",
-        #        "Programming Language :: Python :: 3.6",
-        #        "Programming Language :: Python :: 3.7",
-    ],
-    # This field adds keywords for your project which will appear on the
-    # project page. What does your project relate to?
-    #
-    # Note that this is a string of words separated by whitespace, not a list.
     keywords="raspberry pi arduino microscope",  # Optional
-    packages=find_packages(
+    packages=find_packages(exclude=["contrib", "docs", "tests", "*node_modules*"]),
-        exclude=["contrib", "docs", "tests", "*node_modules*"]
-    ),  # Required
-    # Specify which Python versions you support
     python_requires="== 3.7.*",
     # This field lists other packages that your project depends on to run.
     # Any package you put here will be installed by pip when your project is
     # installed, so they must be valid existing projects.
     #
-    # For an analysis of "install_requires" vs pip's requirements files see:
+    # These dependencies specify relatively flexible versions; Pipenv then resolves these
-    # https://packaging.python.org/en/latest/requirements.html
+    # to specific versions, and locks those versions in ``Pipfile``.  Usually, when you
+    # set up the project for development, you use those specific packages, rather than
+    # the looser specifications given here.
     install_requires=[
         "Flask ~= 1.0",
         "Pillow ~= 7.2.0",
@@ -93,15 +60,10 @@ setup(
         "labthings ~= 1.2.2",
         "typing-extensions ~= 3.7.4",  # Needed for some type-hints in Python < 3.8 (e.g. Literal)
         "RPi.GPIO ~= 0.7.0; platform_machine == 'armv7l'",
-    ],  # Optional
+    ],
-    # List additional groups of dependencies here (e.g. development
+    # "dev" specifies extra packages used for development (linting, testing, etc.)
-    # dependencies). Users will be able to install these using the "extras"
+    # As with install_requires, these are relatively loose versions - Pipfile will then lock
-    # syntax, for example:
+    # them to specific versions to enable consistent builds and testing.
-    #
-    #   $ pip install sampleproject[dev]
-    #
-    # Similar to `install_requires` above, these must be valid existing
-    # projects.
     extras_require={
         "dev": [
             "sphinxcontrib-httpdomain ~= 1.7",
@@ -112,52 +74,21 @@ setup(
             "poethepoet ~= 0.10.0",
             "freezegun ~= 1.0.0",
             "lxml ~= 4.6",
-            "black == 18.9b0",
+            "black == 18.9b0",  # Because black is in prerelease, giving a flexible version
+            # specifier causes all manner of problems.  A fixed version
+            # avoids issues with prereleases (which are normally not
+            # allowed by pipenv) but can be a bit of a pain sometimes!
         ]
-    },  # Optional
+    },
-    # If there are data files included in your packages that need to be
-    # installed, specify them here.
-    #
-    # Sometimes you’ll want to use packages that are properly arranged with
-    # setuptools, but are not published to PyPI. In those cases, you can specify
-    # a list of one or more dependency_links URLs where the package can
-    # be downloaded, along with some additional hints, and setuptools
-    # will find and install the package correctly.
-    # see https://python-packaging.readthedocs.io/en/latest/dependencies.html#packages-not-on-pypi
-    #
     dependency_links=[],
-    # If using Python 2.6 or earlier, then these have to be included in
+    # We create some "entry points" to make it easier to run important modules
-    # MANIFEST.in as well.
-    # package_data={"sample": ["package_data.dat"]},  # Optional
-    # Although 'package_data' is the preferred approach, in some case you may
-    # need to place data files outside of your packages. See:
-    # http://docs.python.org/3.4/distutils/setupscript.html#installing-additional-files
-    #
-    # In this case, 'data_file' will be installed into '<sys.prefix>/my_data'
-    # data_files=[("my_data", ["data/data_file"])],  # Optional
-    # To provide executable scripts, use entry points in preference to the
-    # "scripts" keyword. Entry points provide cross-platform support and allow
-    # `pip` to create the appropriate form of executable for the target
-    # platform.
-    #
-    # For example, the following would provide a command called `sample` which
-    # executes the function `main` from this package when invoked:
     entry_points={
         "console_scripts": [
             "ofm-serve=openflexure_microscope.api.app:ofm_serve",
             "ofm-rescue=openflexure_microscope.rescue.auto:main",
         ]
-    },  # Optional
+    },
-    # List additional URLs that are relevant to your project as a dict.
+    project_urls={
-    #
-    # This field corresponds to the "Project-URL" metadata fields:
-    # https://packaging.python.org/specifications/core-metadata/#project-url-multiple-use
-    #
-    # Examples listed include a pattern for specifying where the package tracks
-    # issues, where the source is hosted, where to say thanks to the package
-    # maintainers, and where to support the project financially. The key is
-    # what's used to render the link text on PyPI.
-    project_urls={  # Optional
         "Source": "https://gitlab.com/openflexure/openflexure-microscope-server"
     },
 )