From 1b5b5766649f4cb256188646cad98292e0ac6ffe Mon Sep 17 00:00:00 2001 From: Richard Bowman Date: Wed, 21 Apr 2021 11:28:30 +0100 Subject: [PATCH] Improved comments --- pyproject.toml | 11 +++- setup.py | 133 ++++++++++++------------------------------------- 2 files changed, 41 insertions(+), 103 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 96eaf8ff..64ac002c 100644 --- a/pyproject.toml +++ b/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/)' diff --git a/setup.py b/setup.py index 8399367b..73269b1a 100644 --- a/setup.py +++ b/setup.py @@ -1,9 +1,12 @@ -"""A setuptools based setup module. -See: +"""A setuptools based setup module for the OpenFlexure Microscope server + +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. -# Fields marked as "Optional" may be commented out. +# Not all arguments to `setup()` are required for upload to PyPI. +# 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 - # Denotes that our long_description is in Markdown; valid values are - long_description_content_type="text/markdown", # Optional (see note above) - # This should be a valid link to your project's main homepage. - # - # 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. - # + long_description=long_description, + long_description_content_type="text/markdown", + url="https://www.openflexure.org", # "home-page" metadata field + author="Joel Collins, Richard Bowman, Julian Stirling", + author_email="contact@openflexure.org", # For a list of valid classifiers, see https://pypi.org/classifiers/ - classifiers=[ # Optional - # # How mature is this project? Common values are - # # 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. + # NB declaring Python versions here doesn't affect dependency resolution - it's for info only. + classifiers=["License :: OSI Approved :: GNU General Public License v3 (GPLv3)"], keywords="raspberry pi arduino microscope", # Optional - packages=find_packages( - exclude=["contrib", "docs", "tests", "*node_modules*"] - ), # Required - # Specify which Python versions you support + packages=find_packages(exclude=["contrib", "docs", "tests", "*node_modules*"]), 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: - # https://packaging.python.org/en/latest/requirements.html + # These dependencies specify relatively flexible versions; Pipenv then resolves these + # 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 - # dependencies). Users will be able to install these using the "extras" - # syntax, for example: - # - # $ pip install sampleproject[dev] - # - # Similar to `install_requires` above, these must be valid existing - # projects. + ], + # "dev" specifies extra packages used for development (linting, testing, etc.) + # As with install_requires, these are relatively loose versions - Pipfile will then lock + # them to specific versions to enable consistent builds and testing. 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 - # 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 '/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: + # We create some "entry points" to make it easier to run important modules 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. - # - # 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 + }, + project_urls={ "Source": "https://gitlab.com/openflexure/openflexure-microscope-server" }, )