Create semver package #304

tlaferriere · Oct 26, 2020

This closes #169. I am unsure of what to do with the doctests entrypoint, so I put it in its own file.

tomschr

Thanks Thomas for all your good work! Very much appreciated! 👍 ❤️

If we want to create a semver package, it is probably better to use a src-layout. Although there is some disagreement about that, I've read Ionel's and Hynek's blog posts and think it has some value.

That said, I would suggest to use this structure in our root folder:

src/
└── semver
    ├── cli.py
    ├── deprecated.py
    ├── __init__.py
    ├── __main__.py
    ├── _types.py
    └── version.py

Apart from that, I've commented on some parts. These are some ideas and I'd like to hear your opinion. 🙂

Another question: Did you pull from the upstream project? It looks like there are some old commits there. Not exactly sure how you set up your branch. I would recommend to try to be in sync with the upstream master branch first, otherwise it make things much harder later.

Thanks again!

changelog.d/290.deprecation.rst

semver/__init__.py

semver/doctest.py

semver/__init__.py

semver/version.py

setup.py

semver/__main__.py

tlaferriere · Oct 26, 2020

@tomschr Should I include the tests in the src directory?

tomschr · Oct 27, 2020

@tomschr Should I include the tests in the src directory?

No, tests shouldn't be part of the semver package IMHO. Ionel says in his Packaging a Python library article about the tests directory:

Module discovery tools will trip over your test modules.
Tests usually require additional dependencies to run, so they aren't useful by their own - you can't run them directly.
Tests are concerned with development, not usage.
It's extremely unlikely that the user of the library will run the tests instead of the library's developer.

Hynek thinks that too and probably a few other.

So these are all valid arguments for me to follow this approach. 😉

setup.py

tlaferriere · Oct 27, 2020

I kind of deleted setup.py in favor of setup.cfg because I found that it required hackery to make the importing of the metadata possible. As I went I found it pretty clean, so I ported all the config from setup.py. Let me know if that is problematic 😕

So you still see it even though I resolved the conversation @tomschr

tomschr

@tlaferriere This looks really good! 👍 Thanks Thomas for your hard work.

I have a couple of minor comments and questions. All can you find below. Apart from that, I have two things that I would like to discuss:

The documentation doesn't build yet. Addtionally, for some (unknown) reason, the API section is empty. 🤷‍♂️ To make the docs build again, we only need a small change here:

diff --git i/docs/conf.py w/docs/conf.py
index 3653ecc..71738da 100644
--- i/docs/conf.py
+++ w/docs/conf.py
@@ -19,7 +19,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../src/"))

The coverage degraded a bit from last release. We should add a short integration test for semver/__main__.py. It doesn't need to be necessarily in this PR.

---------- coverage: platform linux, python 3.6.10-final-0 -----------
Name                                                          Stmts   Miss Branch BrPart    Cover   Missing
-----------------------------------------------------------------------------------------------------------
.tox/py36/lib/python3.6/site-packages/semver/__about__.py         7      0      0      0   100.0%
.tox/py36/lib/python3.6/site-packages/semver/__init__.py          3      0      0      0   100.0%
.tox/py36/lib/python3.6/site-packages/semver/__main__.py          9      9      2      0     0.0%   7-19
.tox/py36/lib/python3.6/site-packages/semver/_deprecated.py      80      2     14      1    94.7%   182->184, 184-185
.tox/py36/lib/python3.6/site-packages/semver/_types.py            7      0      0      0   100.0%
.tox/py36/lib/python3.6/site-packages/semver/cli.py              60      0     10      0   100.0%
.tox/py36/lib/python3.6/site-packages/semver/version.py         230      1     70      1    99.3%   383->384, 384
-----------------------------------------------------------------------------------------------------------
TOTAL                                                           396     12     96      2    96.3%

Again, I like all the changes! Well done!

setup.py

setup.cfg

changelog.d/169.trivial.rst

src/semver/__about__.py

setup.cfg

src/semver/_deprecated.py

tomschr · Oct 28, 2020

If you solved the issues above, it would be great if you could clean up your commits. 👍 🙂

tlaferriere · Oct 29, 2020

@tomschr I think this could be a good opportunity to rename the VersionInfo to Version to address and close #305.

Split up changelog to make more sense. Incorporate suggestions and increase coverage to 100% in non-deprecated parts. Bump the dev part Co-authored-by: Tom Schraitle <tomschr@users.noreply.github.com> Run docformatter Fix path for docformatter Add stubby setup.py file for compatibility with python 3.6 Run black Deprecate cli functions imported from root Revert to `pysemver` as console script. Refactor __main__.py * add type hints for correctness * run black Refactor and integrate suggestion from @tomschr * Create :file:`src/semver/cli.py` for all CLI methods * Create :file:`src/semver/_deprecated.py` for the ``deprecated`` decorator and other deprecated functions * Create :file:`src/semver/__main__.py` to allow calling the CLI using :command:`python -m semver` * Create :file:`src/semver/_types.py` to hold type aliases * Create :file:`src/semver/version.py` to hold the :class:`VersionInfo` class and its utility functions * Create :file:`src/semver/__about__.py` for all the metadata variables Adapted infrastructure code to the new project layout. * Replace :file:`setup.py` with :file:`setup.cfg` because the :file:`setup.cfg` is easier to use * Adapt documentation code snippets where needed * Adapt tests * Changed the ``deprecated`` to hardcode the ``semver`` package name in the warning. Change path for docformatter and run it. Remove pyi inclusion from black sine we aren't using them Clean up after messy rebase Run black

Add documentation for Version rename

Create a separate file to describe how to migrate to new semver3.

With ideas from https://stackoverflow.com/a/62613202 * Use autosummary Sphinx extension * Extend docs/config.py * Ignore docs/_autosummary * Add module docstring * Add changelog entry * Improve custom.css for sidebar

Split changelog entries into semver 3 (new) and semver 2 (old).

tomschr

Thanks for the coverage and the other improvements! 👍 I have only some minor comments.

Currently, I'm working on improving the API documentation. Expect some commits. I think, I'm almost finished.

docs/coerce.py

tomschr · Oct 30, 2020

docs/coerce.py

-    :rtype: tuple(:class:`VersionInfo` | None, str)
+    :rtype: tuple(:class:`Version` | None, str)


I would completely remove this line as this is created automatically.

changelog.d/169.feature.rst

tomschr · Oct 30, 2020

changelog.d/169.deprecation.rst

@@ -0,0 +1 @@
+Deprecate CLI functions not imported from ``semver.cli``.


Shouldn't we add another file 305.deprecation.rst to describe the deprecation of VersionInfo > Version?

Oh, I see, you have that as a documentation issue. Hmn... not sure, if people will find it. IMHO it wouldn't hurt to add this here too.

I think I will just rename the file 305.doc.rst to 305.deprecation.rst.

tomschr · Oct 30, 2020

@tlaferriere I researched a bit and found (hopefully) a good solution. Due to changing semver from a package to a module there were some additional changes necessary.

The output looks a bit different now, but I think it's okay. Let me know if you think this should be changed. There are some warning messages that are a bit disturbing:

WARNING: missing attribute mentioned in :members: or __all__: module semver.__about__, attribute __about__
WARNING: missing attribute mentioned in :members: or __all__: module semver.cli, attribute __about__
WARNING: missing attribute mentioned in :members: or __all__: module semver.cli, attribute __author__
WARNING: missing attribute mentioned in :members: or __all__: module semver.cli, attribute __author_email__
WARNING: missing attribute mentioned in :members: or __all__: module semver.cli, attribute __maintainer__
WARNING: missing attribute mentioned in :members: or __all__: module semver.cli, attribute __maintainer_email__
WARNING: missing attribute mentioned in :members: or __all__: module semver.cli, attribute __description__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __version__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __about__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __author__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __author_email__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __maintainer__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __maintainer_email__
WARNING: missing attribute mentioned in :members: or __all__: module semver.version, attribute __description__

Maybe we need to introduce an __all__ variable. That isn't covered (yet) in the above commits.

Additionally, I've split the changelog into entries for semver3 and semver2. I think, this makes it easier.

Hope these changes make sense to you. 😄

Co-authored-by: Tom Schraitle <tomschr@users.noreply.github.com>

Acoording to the mentioned PEP: "Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing." Add package_data to setup.cfg to include this marker in dist and whl file.

Add missing module docstrings and correct function docstring to avoid warnings (just missing empty lines)

* Use sphinx-apidoc to build API documentation * Amend tox.ini and call sphinx-apidoc * Remove old autosummary; it turned out it was difficult to configure and returned warning messages which were hard to fix.

tomschr · Oct 31, 2020

@tlaferriere I've tried a different approach now. I removed all the autosummary stuff and used the sphinx-apidoc command (included in tox.ini and run before make). This gives me a little bit more control. With this approach, I get a "decent" API documentation which looks like this:

    Submodules
        semver.__about__ module
        semver.__main__ module
        semver._deprecated module
        semver.cli module
        semver.version module

As you can see, there are also some private modules (as semver._deprecated) listed. I can suppress them by removing the -P option in `tox.ini (line 73) which would gives this result:

    Submodules
        semver.cli module
        semver.version module

So I'm a bit unsure which would be better. I would have liked to have the content from semver.__about__. If you know a method let me know. 😉 What do you think about our API doc?

The above commits contains some improvements of docstrings in modules and functions. Hope I didn't commit anything useless by accident.

If you agree with my suggestions, we could arrange and squash the commits and I can merge it to master.

tlaferriere · Oct 31, 2020

Since some of the important metadata is imported in the __init__.py file, wouldn't it show up in the docs in there? Anyway, I saw the py.typed and pep-561 commit, and here I was thinking that just having type hints would basically enable checking for users 🤣. Well I learned something today 😀

tomschr · Oct 31, 2020

Since some of the important metadata is imported in the __init__.py file, wouldn't it show up in the docs in there?

Unfortunately not. If I remove the -P (for private) flag, they disappear. I've tried to add a .. autodata:: __version__. This kind of works, but that gave me this:

semver package

semver package major release 3.

A Python module for semantic versioning. Simplifies comparing versions.

semver.__version__ Semver version

    str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

    Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

which is of course nonsense as it kind of copies the docstring from the str object. 🤦

What I can do is to manually add that. Maybe with __version__ and a few others that would be okay. On the other side, with a name autodoc of this extension, I would expect that this could be done automatically. Maybe there is a configuration option. 🤔

Anyway, I saw the py.typed and pep-561 commit, and here I was thinking that just having type hints would basically enable checking for users. Well I learned something today

Haha, me too. I hope this makes sense. 😉

tlaferriere · Oct 31, 2020

Can't we just create a template that interpolates these variables? It's not like we're going to change the meaning or the usage of these variables very often 😉. They are accessible from the setup.cfg using the attr: keyword. Isn't there an equivalent for Sphinx? And it's not like we need the type info explicitly in the docs for these too badly.

tomschr · Oct 31, 2020

Well, my knowledge about Sphinx and autodoc is limited. I've tried several things, but either I got some warning messages (like the one above) or I didn't get what I wanted. 😉

The autodoc extension can be configured by a autodoc_default_options variable. However, that is limited.

And it's not like we need the type info explicitly in the docs for these too badly.

True. But it would be nice to have at least __version__ and SEMVER_SPEC_VERSION

* Unorthodox solution with sed * Remove obsolete config variables in docs/config.py * Add docs/_api/semver.__about__.rst as a placeholder

tomschr · Oct 31, 2020

I think I found a (somewhat) unorthodox solution. 😆 The API doc shows now only the public interface, but additionally the semver.__about__ module (with __version__ and SEMVER_SPEC_VERSION).

If you are okay with that, I would tomorrow squash all the commits into some useful history and merge it to master.

Any objections?

tlaferriere · Nov 1, 2020

An unorthodox solution is still a solution 😉. If it's that bad I guess we can open an issue with Sphinx for this use case. For now I think this should do. It appears we've got good timing for the second dev release 🎉

tomschr · Nov 1, 2020

Hehe, yes.If it turns out that it is bad, we can always publish a new dev release.

I'll go through the commits and try to come up with some decent history. As I heard no "stop" or other objections, I'll merge them to master. 😉

Thanks for all your contributions and efforts! 👍

tomschr · Nov 1, 2020

I just realized that it is not possible to rearrange the commits and force-push them into this pull request. I'll open a new branch and merge the commits from there.

tomschr · Nov 1, 2020

Closing this in favor of #306.

tomschr requested changes Oct 26, 2020

View reviewed changes

tomschr reviewed Oct 27, 2020

View reviewed changes

setup.py Outdated Show resolved Hide resolved

tomschr requested changes Oct 27, 2020

View reviewed changes

tomschr added Enhancement Not a bug, but increases or improves in value, quality, desirability, or attractiveness Release_3.x.y Only for the major release 3 labels Oct 27, 2020

tlaferriere force-pushed the 169-package branch 3 times, most recently from bb20850 to 932c190 Compare October 29, 2020 22:26

tlaferriere force-pushed the 169-package branch from 932c190 to 79e0c10 Compare October 29, 2020 22:38

Rename VersionInfo to Version to close python-semver#305

d38813d

Add documentation for Version rename

tlaferriere force-pushed the 169-package branch from 79e0c10 to d38813d Compare October 29, 2020 23:08

tlaferriere mentioned this pull request Oct 29, 2020

Create for semver 3.0.0-dev2 #302

Closed

tomschr added 4 commits October 30, 2020 14:44

Doc: Create new section of semver2 vs. semver3

e1b3851

Create a separate file to describe how to migrate to new semver3.

Improve API documentation

37c9e3b

With ideas from https://stackoverflow.com/a/62613202 * Use autosummary Sphinx extension * Extend docs/config.py * Ignore docs/_autosummary * Add module docstring * Add changelog entry * Improve custom.css for sidebar

Distinguish between changlog for version 2 and 3

5e5dd98

Split changelog entries into semver 3 (new) and semver 2 (old).

Document migration from semver2 to semver3

30a5568

tomschr reviewed Oct 30, 2020

View reviewed changes

Correct black and docformatter issues

8711494

tlaferriere and others added 5 commits October 30, 2020 12:36

Update changelog.d/169.feature.rst

fa7b440

Co-authored-by: Tom Schraitle <tomschr@users.noreply.github.com>

Update docs/coerce.py

7838196

Co-authored-by: Tom Schraitle <tomschr@users.noreply.github.com>

Fix Travis error in doctests

0b60d15

Support PEP-561 py.typed

4ef918d

Acoording to the mentioned PEP: "Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing." Add package_data to setup.cfg to include this marker in dist and whl file.

Add and improve docstrings

89df81e

Add missing module docstrings and correct function docstring to avoid warnings (just missing empty lines)

Improve API documentation (second attempt)

18b9cf9

* Use sphinx-apidoc to build API documentation * Amend tox.ini and call sphinx-apidoc * Remove old autosummary; it turned out it was difficult to configure and returned warning messages which were hard to fix.

tomschr added 3 commits October 31, 2020 23:31

Doc: Add semver version in footer

551eb3c

Add semver.__about__ to API doc

80f0d24

* Unorthodox solution with sed * Remove obsolete config variables in docs/config.py * Add docs/_api/semver.__about__.rst as a placeholder

Fix formatting

3c636f3

tomschr mentioned this pull request Nov 1, 2020

Create semver package (part 2) #306

Merged

tomschr closed this Nov 1, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create semver package #304

Create semver package #304

tlaferriere commented Oct 26, 2020

tomschr left a comment •

edited

Loading

tlaferriere commented Oct 26, 2020

tomschr commented Oct 27, 2020 •

edited

Loading

tlaferriere commented Oct 27, 2020

tomschr left a comment •

edited

Loading

tomschr commented Oct 28, 2020

tlaferriere commented Oct 29, 2020 •

edited

Loading

tomschr left a comment •

edited

Loading

tomschr Oct 30, 2020

tomschr Oct 30, 2020

tlaferriere Oct 30, 2020

tomschr commented Oct 30, 2020

tomschr commented Oct 31, 2020 •

edited

Loading

tlaferriere commented Oct 31, 2020

tomschr commented Oct 31, 2020 •

edited

Loading

tlaferriere commented Oct 31, 2020

tomschr commented Oct 31, 2020

tomschr commented Oct 31, 2020

tlaferriere commented Nov 1, 2020

tomschr commented Nov 1, 2020

tomschr commented Nov 1, 2020

tomschr commented Nov 1, 2020

		:rtype: tuple(:class:`VersionInfo` \| None, str)
		:rtype: tuple(:class:`Version` \| None, str)

		@@ -0,0 +1 @@
		Deprecate CLI functions not imported from ``semver.cli``.

Search code, repositories, users, issues, pull requests...

Create semver package #304

Create semver package #304

Conversation

tlaferriere commented Oct 26, 2020

tomschr left a comment • edited Loading

Choose a reason for hiding this comment

tlaferriere commented Oct 26, 2020

tomschr commented Oct 27, 2020 • edited Loading

tlaferriere commented Oct 27, 2020

tomschr left a comment • edited Loading

Choose a reason for hiding this comment

tomschr commented Oct 28, 2020

tlaferriere commented Oct 29, 2020 • edited Loading

tomschr left a comment • edited Loading

Choose a reason for hiding this comment

tomschr Oct 30, 2020

Choose a reason for hiding this comment

tomschr Oct 30, 2020

Choose a reason for hiding this comment

tlaferriere Oct 30, 2020

Choose a reason for hiding this comment

tomschr commented Oct 30, 2020

tomschr commented Oct 31, 2020 • edited Loading

tlaferriere commented Oct 31, 2020

tomschr commented Oct 31, 2020 • edited Loading

tlaferriere commented Oct 31, 2020

tomschr commented Oct 31, 2020

tomschr commented Oct 31, 2020

tlaferriere commented Nov 1, 2020

tomschr commented Nov 1, 2020

tomschr commented Nov 1, 2020

tomschr commented Nov 1, 2020

tomschr left a comment •

edited

Loading

tomschr commented Oct 27, 2020 •

edited

Loading

tomschr left a comment •

edited

Loading

tlaferriere commented Oct 29, 2020 •

edited

Loading

tomschr left a comment •

edited

Loading

tomschr commented Oct 31, 2020 •

edited

Loading

tomschr commented Oct 31, 2020 •

edited

Loading