Hatchbuild #377

fleetingbytes · 2022-11-26T14:19:23Z

Proposal to fix #373 (Use hatchling build backend)

I have moved everything except for flake8 settings and pycodestyle settings from setup.cfg to pyproject.toml

I have prepared these scripts:

style:fmt runs Black and isort (all files now have imports sorted by isort)
style:lint runs flake8 and pycodestyle
docs:build runs pdoc3 to build API documentation in the api-docs directory (added to .gitignore
docs:serve runs pdoc3 local server on localhost:8080 to observe API docs updated live as you update docstrings. However, this somehow does not work in this project and I don't know exactly how to solve the error. Maybe @tomschr can figure it out, the API documentation is rather nice
test:cov runs pytest-cov
test:no-cov runs pytest with --no-cov
test:tox_test runs tox

Scripts can be run with hatch run, e.g. hatch.run style:fmt.

All the test scripts fail because of python-semver\tests\coerce.py not being a proper Python file (invalid syntax). I don't know what the purpose of this file is, so I did not touch it. It makes tests fail even if you run then natively with tox, so repairing this is beyond the scope of this PR, methinks.

I changed the classifier Environment :: Web Environment to Environment :: Console as I think it's more fitting.

tomschr

Thanks @Nagidal for your work, very much appreciated! 👍

I've looked through the changes and left some comments below. Unfortunately, I saw this PR a bit too late, so I merged PR #375 already. I'm sorry! That might create conflicts in your branch. You need to rebase and resolve the conflicts. If you need help, let me know or I can do it for you.

Regarding the tests/coerce.py: That should be a link to docs/advanced/coerce.py. It is used in some doc tests. The link is currently broken, I see it has some strange characters at the end of the filename. If you correct these the tests should work again.

The overall change looks pretty good, I have only these two main concerns:

With the current pyproject.toml you can't build the user documentation. We need that. 🙂 That issue should be fixed and I've addressed it below.
The source codes have been changed. I would have expected that such a change wouldn't touch the source code at all. I think, this should also be fixed. This PR should NOT contain any changes to the Python code.

I would also like to see in this PR is the (user) documentation. The file BUILDING.rst should also be adapted.

Further ideas I would like to know, but we can do that in a later PR:

Change the Towncrier changelog. We need another entry in pyproject.toml where we can build, check, and create the changelog file.
~~Upload of wheel and source dist to PyPI.~~ (This seems to be already integrated in hatch)
~~Create test matrices to replace tox.~~ (Already in this PR, but the list needs to be checked again.)
Adapt the GitHub Actions to use hatch instead of tox could be discussed.

tomschr · 2022-11-26T15:14:39Z

changelog.d/373.trivial.rst

@@ -0,0 +1 @@
+Changed build backend to hatchling


We use Git log message style: all verbs are in simple present tense.
Furthermore, I would list some other parts that comes with changing the build backend.

Suggested change

Changed build backend to hatchling

Change build backend to hatchling.

* Replace ``"Environment :: Web Environment"`` with ``"Environment :: Console"`` as it is a better fit.

Ok, so I guess I should leave the classifier change out of the scope of this PR. We would probably make a separate issue for if and update the classifiers in a dedicated PR.

tomschr · 2022-11-26T15:38:11Z

pyproject.toml

+[tool.hatch.envs.docs]
+dependencies = [
+    "pdoc3"
+]
+
+[tool.hatch.envs.docs.scripts]
+build = "pdoc --html --output-dir api-docs src/semver --force"
+serve = "pdoc --http : python-semver"


This entry builds the API documentation, not the real documentation. With this current pyproject.toml nobody can build it. That is not good.

Apart from this, we have already an API documentation. It's integrated in the autogenerated Sphinx build. Why another API? Apart from the optical change, I don't see a need for pdoc at the moment. We should keep this to a minimum.

Sooo... we have here two options:

Completely replace pdoc with sphinx (that would be my favorite)

Rename the .docs to .apidoc as the name doesn't advertise the correct part. The .docs should be reserved only to the user documentation, not API docs.

If I continue with (1), I've added the requirements from the docs/requirements.txt file and changed the serve subcommand. This would end up with this:

Suggested change

[tool.hatch.envs.docs]

dependencies = [

"pdoc3"

]

[tool.hatch.envs.docs.scripts]

build = "pdoc --html --output-dir api-docs src/semver --force"

serve = "pdoc --http : python-semver"

[tool.hatch.envs.docs]

dependencies = [

"sphinx",

"sphinx-argparse",

"sphinx-autodoc-typehints",

]

[tool.hatch.envs.docs.scripts]

build = "make -C docs html"

linkcheck = "make -C docs linkcheck"

serve = "python3 -m webbrowser -t docs/_build/html/index.html"

Sorry, I forgot and overlooked that python-semver's documentation is made by sphinx. I will get rid of pdoc3 and bring in the sphinx API doc.

All good, absolutely no problem. 🫂 That why we have a review. 🙂

tomschr · 2022-11-26T15:43:00Z

pyproject.toml

+exclude_lines = [
+    "no cov",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]


I would prefer to change no cov to pragma: no cover as it is already used in the code.

Take cover the precision option from the .coveragerc file

Add additional lines which should be excluded (partly from .coveragerc).

Delete the file .coveragerc as it is not needed anymore.

Suggested change

exclude_lines = [

"no cov",

"if __name__ == .__main__.:",

"if TYPE_CHECKING:",

]

show_missing = true

precision = 1

exclude_lines = [

"pragma: no cover",

"if __name__ == .__main__.:",

"if TYPE_CHECKING:",

# note the use of single quote below to denote "raw" strings in TOML

'if not hasattr\(__builtins__, .cmp.\):',

'class .*\bProtocol\):',

'@(abc\.)?abstractmethod',

]

Here I did not check what python-semver's code actually uses to mark excluded lines. The "no cov" setting was copy-pasted from one of my pyproject.tomls. We shall of course have here the same comments which python-semver uses.

Hehe, no problem. I assumed it was copied from somewhere. You couldn't know these details, so no worries.

tomschr · 2022-11-26T16:11:32Z

changelog.d/374.bugfix.rst

@@ -0,0 +1,3 @@
+Correct Towncrier's config entries in the :file:`pyproject.toml` file.


This file was integrated as part of PR #375 and should not appear in this branch. You should remove this file and rebase your branch. Possibily you need to resolve conflicts.

I agree. Will do.

tomschr · 2022-11-26T16:13:53Z

pyproject.toml

@@ -40,42 +190,23 @@ template = "changelog.d/_template.rst"
 # issue_format = "`#{issue} <https://github.com/python-attrs/attrs/issues/{issue}>`_"
 # issue_format = ":gh:`{issue}`"

-  # [[tool.towncrier.type]]


The parts are already done by PR #375. The Towncrier parts below will possibly create a conflict when you rebase.

yup, I shall exclude the #375 changes from this PR. Until now I was only doing PRs for my one-man show projects, never interfering with anyone else's changes upstream, So I picked up these nasty habits of mixing in other unrelated changes into the PR. I'll correct this. Happy to work with you on a more complex project and learn to produce some more disciplined PRs.

tomschr · 2022-11-26T16:18:08Z

src/semver/__init__.py

@@ -4,36 +4,12 @@
 A Python module for semantic versioning. Simplifies comparing versions.
 """

-from ._deprecated import (


Why is the source code changed?

I'm not entirely sure why the change of pyproject.toml triggers a reformatting. It shouldn't. The source code is perfectly formatted and the black config wasn't changed. This PR is all about switching from setuptools to hatch(ling) and we should keep it as such.

Could you please check and revert these changes in the source code?

I accidentally ran the style:fmt script, which runs isort, and it reformatted (and sorted) the import statements. Using isort would be another suggestion, but again, out of scope of this PR. I'll revert these.

Again, no problem.
Actually, I was thinking about isort too. But as you said, we can do that in another PR. 👍

tomschr

I found some other minor issues and left some questions.

tomschr · 2022-11-26T17:51:09Z

pyproject.toml

+]
+maintainers = [
+    { name = "Sebastien Celles", email = "s.celles@gmail.com" },
+    { name = "Tom Schraitle" },


Does it not require an email address? You could use this:

Suggested change

{ name = "Tom Schraitle" },

{ name = "Tom Schraitle", email="tomschr@users.noreply.github.com" },

That's not necessary. According to PEP 621:

These fields accept an array of tables with 2 keys: name and email. [...] Both keys are optional.

tomschr · 2022-11-26T17:52:39Z

pyproject.toml

+tox_test = "tox"
+
+[[tool.hatch.envs.test.matrix]]
+python = ["310", "311"]


Why are Python 3.7, 3.8, 3.9 not in the list? This project supports 3.6/3.7 and later. Although we have a poll open to get rid of Python 3.6 (see #371).

Suggested change

python = ["310", "311"]

python = ["37", "38", "39", "310", "311",]

I thought I would sketch up just a little test matrix in pyproject.toml for the time being, to see how it works for you and your Github workflows. All tests and their environments neatly set up in tox and it is not necessary to migrate to a hatch test matrix right away. However, we can do this. I shall update the PR with a [3.7, ... 3.11] matrix.

tomschr · 2022-11-26T17:54:48Z

pyproject.toml

+[tool.mypy]
+# the mypy settings go here
+# To have the `py.typed` file installed with the package we had to include it
+# in the build metadata (see [tool.hatch.build])


I've tested it with these options:

Suggested change

# in the build metadata (see [tool.hatch.build])

# in the build metadata (see [tool.hatch.build])

enable_error_code = [

"ignore-without-code",

]

show_error_codes = true

warn_unused_ignores = true

implicit_reexport = true

pretty = true

follow_imports = "normal"

I've never used mypy, and I did not look thoroughly enough where your current mypy options were until now. But of course, we shall have these here now.

tomschr · 2022-11-26T17:57:45Z

pyproject.toml

+# in the build metadata (see [tool.hatch.build])
+
+[tool.pytest.ini_options]
+norecursedirs = ".git build .env/ env/ .pyenv/ .tmp/ .eggs/ venv/"


I think, the norecursedirs should be a list instead of a string?

Suggested change

norecursedirs = ".git build .env/ env/ .pyenv/ .tmp/ .eggs/ venv/"

norecursedirs = [

".git",

"build",

".env/",

"env/",

".pyenv/",

".tmp/",

".eggs/",

"venv/",

]

I couldn't tell from pytest's documentation whether norecursedirs accepts a list, or if it all must be one string (the same is not sure for addopts). I shall test if these config options understand lists and see.

tomschr · 2022-11-26T18:02:14Z

pyproject.toml

+[tool.coverage.run]
+branch = true
+parallel = true
+omit = [
+    # add files to exclude them from the coverage report, e.g.
+    # "src/semver/__about__.py"
+]


If I'm not mistaken, you need to tell coverage/pytest-cov where to find the source by using source. Furthermore, I would add semver/_types.py to the list of files to be excluded from coverage (it contains just type definitions):

Suggested change

[tool.coverage.run]

branch = true

parallel = true

omit = [

# add files to exclude them from the coverage report, e.g.

# "src/semver/__about__.py"

]

[tool.coverage.run]

source = [ "src/semver/*", ]

branch = true

parallel = true

omit = [

# add files to exclude them from the coverage report, e.g.

"src/semver/_types.py",

]

Furthermore, if you add config options to pyproject.toml you need to delete the file .coveragerc. That file isn't need anymore and we shouldn't have duplicate content.

ok, will do.

tomschr · 2022-11-26T18:05:54Z

pyproject.toml

+cov = "pytest -vx"
+no-cov = "cov --no-cov"
+tox_test = "tox"


I suspect something is missing here. When I run tox (or pytest), I can run it either with tests against all defined Python versions or a specific version. Running tox alone would always run all Python versions.

That takes some time, although not much. Nevertheless, it can slow down your development, especially if you want to get results fast. For example, I usually pick one version only and run my tests against that. After I've finished my code, I run it against all (or leave that to the GitHub Actions).

umm, sure. I think it would be convenient to use the test environment for testing only with Python 3.7, and have another test environment, e.g. testall with the complete matrix of Python versions.

For running tox with all its regular tests I will prepare a hatch run tox:test script.

fleetingbytes · 2022-11-26T19:06:11Z

I will try to correct this tomorrow, or by Monday latest. Thanks for all the suggestions and push-backs.

tomschr · 2022-11-26T19:09:21Z

Thank you very much. You're welcome. Take your time, no need to hurry. 🙂

tomschr requested changes Nov 26, 2022

View reviewed changes

fleetingbytes closed this Nov 27, 2022

fleetingbytes force-pushed the hatchbuild branch from 4ac2b09 to 4cf9d60 Compare November 27, 2022 00:32

fleetingbytes deleted the hatchbuild branch November 27, 2022 00:34

fleetingbytes mentioned this pull request Nov 27, 2022

Hatchbuild retry #379

Closed

-Changed build backend to hatchling
+Change build backend to hatchling.
+* Replace ``"Environment :: Web Environment"`` with ``"Environment :: Console"`` as it is a better fit.

		@@ -0,0 +1,3 @@
		Correct Towncrier's config entries in the :file:`pyproject.toml` file.

	{ name = "Tom Schraitle" },
	{ name = "Tom Schraitle", email="tomschr@users.noreply.github.com" },

	python = ["310", "311"]
	python = ["37", "38", "39", "310", "311",]

-# in the build metadata (see [tool.hatch.build])
+# in the build metadata (see [tool.hatch.build])
+enable_error_code = [
+    "ignore-without-code",
+]
+show_error_codes = true
+warn_unused_ignores = true
+implicit_reexport = true
+pretty = true
+follow_imports = "normal"

-norecursedirs = ".git build .env/ env/ .pyenv/ .tmp/ .eggs/ venv/"
+norecursedirs = [
+  ".git",
+  "build",
+  ".env/",
+  "env/",
+  ".pyenv/",
+  ".tmp/",
+  ".eggs/",
+  "venv/",
+]

Hatchbuild #377

Hatchbuild #377

Uh oh!

Conversation

fleetingbytes commented Nov 26, 2022 • edited by tomschr Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tomschr left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomschr Nov 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomschr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fleetingbytes Nov 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomschr Nov 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomschr Nov 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomschr Nov 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fleetingbytes commented Nov 26, 2022

Uh oh!

fleetingbytes commented Nov 26, 2022 •

edited by tomschr

Loading

tomschr left a comment •

edited

Loading

tomschr Nov 26, 2022 •

edited

Loading

fleetingbytes Nov 26, 2022 •

edited

Loading

tomschr Nov 26, 2022 •

edited

Loading

tomschr Nov 26, 2022 •

edited

Loading

tomschr Nov 26, 2022 •

edited

Loading