[Docutils-develop] docutils latest version contains string

[Guenter Milde]

Dear David, dear Engelbert, dear Docutils developers,

docutils latest package version is 0.14rc1
while other packages try to parse the version (such as sphinx), it fails
due to parse error for int()

...

line 17, in sphinx/util/compat.py

docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
ValueError: invalid literal for int() with base 10: '14rc1'

Unfortunately, our friends as Sphinx still use this method.

So, while I agree that it is their fault (as long as our version complies
with PEP 440), it could also be considered an API change, as the
docstring says::

__version__ = ...
"""``major.minor.micro`` version number.

without referencing PEP440.

Can you please update docutils version to contains only integers (as
universal format)

We may decide that pre-releases are not important for users of "broken"
downstream packages.
However, Sphinx users are our "main customers" and excluding them from the
prerelease test sample goes against the very intention of the prerelease :-(


Fortunately, there is a chance to eat the cake and have it:

We can push the non-interger part of the pre-release segment into the
__version_details__:

Index: __init__.py
===================================================================
--- __init__.py (Revision 8090)
+++ __init__.py (Arbeitskopie)
@@ -52,7 +52,7 @@

__docformat__ = 'reStructuredText'

-__version__ = '0.14rc2'
+__version__ = '0.14'
"""``major.minor.micro`` version number.
The major number will be bumped when the project is feature-complete, and
later if there is a major change in the design or API.
@@ -60,7 +60,7 @@
The micro number is bumped for bug-fix releases.
"""

-__version_details__ = 'repository'
+__version_details__ = 'rc2'
"""Extra version details (e.g. 'snapshot 2005-05-29, r3410', 'repository',
'prerelease', 'release'), modified automatically & manually."""


With a small change to the "version template", the output of `rst2* --version`
remains PEP440-compliant, e.g.
``rst2html (Docutils 0.14-rc2, Python 2.7.13, on linux2)``

Index: frontend.py
===================================================================
--- frontend.py (Revision 8090)
+++ frontend.py (Arbeitskopie)
@@ -570,7 +570,7 @@

config_section = 'general'

- version_template = ('%%prog (Docutils %s [%s], Python %s, on %s)'
+ version_template = ('%%prog (Docutils %s-%s, Python %s, on %s)'
% (docutils.__version__, docutils.__version_details__,
sys.version.split()[0], sys.platform))
"""Default version message."""


However, functional test fail with this approach:

-<meta name="generator" content="Docutils 0.14rc2: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />

so we would need to either change the expected output or use the
"version_template" also in the "generator" generation.

David, Engelbert, what do you think?


Günter



------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please u

[jfbu]

Post by Guenter Milde
line 17, in sphinx/util/compat.py

docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
ValueError: invalid literal for int() with base 10: '14rc1'

Unfortunately, our friends as Sphinx still use this method.

Hi, for Sphinx 1.6.2 which was released yesterday there
had already been a fix in sphinx.util.docutils and
we tested with Docutils 0.14rc1 before release.

But we overlooked the deprecated module sphinx.util.compat
as quoted above.

It has been fixed at Sphinx upstream for next 1.6.3 release

If not used by extensions, this left-over causes no problem.

Best,

Jean-François
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please use "Reply All" to reply to the list.

[jfbu]

Dear Docutils developers,

Post by jfbu
[...]
Hi, for Sphinx 1.6.2 which was released yesterday there
had already been a fix in sphinx.util.docutils and
we tested with Docutils 0.14rc1 before release.
But we overlooked the deprecated module sphinx.util.compat
as quoted above.
It has been fixed at Sphinx upstream for next 1.6.3 release
If not used by extensions, this left-over causes no problem.

I forgot so say that Sphinx now uses does

tuple(LooseVersion(docutils.__version__).version)

with LooseVersion from distutils.version to parse
the docutils version string,

Thanks,

Jean-François


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please use "Reply All" to reply to the list.

[Guenter Milde]

Post by jfbu

Post by Guenter Milde
line 17, in sphinx/util/compat.py

docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
ValueError: invalid literal for int() with base 10: '14rc1'

Unfortunately, our friends as Sphinx still use this method.

Hi, for Sphinx 1.6.2 which was released yesterday there
had already been a fix in sphinx.util.docutils and
we tested with Docutils 0.14rc1 before release.
But we overlooked the deprecated module sphinx.util.compat
as quoted above.
It has been fixed at Sphinx upstream for next 1.6.3 release
If not used by extensions, this left-over causes no problem.

Good to know, thank you for the update.

David, Engelbert: do we still want to be conservative and support testing of
pre-releases with older Sphinxes or is it not worth the effort...

Günter


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please use "Reply All"

[engelbert gruber]

Post by Guenter Milde
David, Engelbert: do we still want to be conservative and support testing of
pre-releases with older Sphinxes or is it not worth the effort...

what does sphinx mean, do they have active branches ?

[Guenter Milde]

Post by engelbert gruber

Post by Guenter Milde
David, Engelbert: do we still want to be conservative and support
testing of pre-releases with older Sphinxes or is it not worth the
effort...

what does sphinx mean, do they have active branches ?

Our pre-relases only work with the latest Sphinx release. Some Sphinx
extensions require a module that is fixed in the development version
only.

I.e. "out in the wild", there are many users with Sphinx versions that will
not work with Docutils 0.14rc1 nor 0.14rc2.dev.

However, I will wait for Davids comment on the handling of
"__version_details__" until further action.


Günter

[David Goodger]

Post by Guenter Milde
David, Engelbert: do we still want to be conservative and support testing of
pre-releases with older Sphinxes or is it not worth the effort...

I think we should actively test only against the latest Sphinx (not older
versions) with pre-release Docutils. ISTM that Sphinx is updated
quickly enough and released with Docutils dependencies documented, so
it's not worth the effort. Any Sphinx user who updates their Docutils
to the latest will also be updating their Sphinx, so at worst we'll
see a short period of incompatibility, quickly resolved.

That's not to say that we should be changing our APIs willy-nilly. We
emphatically should not. We should strive not to make API changes
unless absolutely necessary.

In this case, a simple version string format change triggered an issue
in client code. It was a one-off issue that has already been resolved.
Let's move on.

David Goodger
<http://python.net/~goodger>

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop

Please use "Reply All" to reply to the list.

[Komiya Takeshi]

Hi Günter,

Post by Guenter Milde
Unfortunately, our friends as Sphinx still use this method.

Our latest release Sphinx-1.6.2 uses
``distutils.version.LooseVersion`` to parse version string. It
supports PEP 440 version strings.
So Sphinx does not prepend that.

Thanks,
Takeshi KOMIYA

Post by Guenter Milde
Dear David, dear Engelbert, dear Docutils developers,

docutils latest package version is 0.14rc1
while other packages try to parse the version (such as sphinx), it fails
due to parse error for int()

...
line 17, in sphinx/util/compat.py

docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
ValueError: invalid literal for int() with base 10: '14rc1'

Unfortunately, our friends as Sphinx still use this method.
So, while I agree that it is their fault (as long as our version complies
with PEP 440), it could also be considered an API change, as the
__version__ = ...
"""``major.minor.micro`` version number.
without referencing PEP440.

Can you please update docutils version to contains only integers (as
universal format)

We may decide that pre-releases are not important for users of "broken"
downstream packages.
However, Sphinx users are our "main customers" and excluding them from the
prerelease test sample goes against the very intention of the prerelease :-(
We can push the non-interger part of the pre-release segment into the
Index: __init__.py
===================================================================
--- __init__.py (Revision 8090)
+++ __init__.py (Arbeitskopie)
@@ -52,7 +52,7 @@
__docformat__ = 'reStructuredText'
-__version__ = '0.14rc2'
+__version__ = '0.14'
"""``major.minor.micro`` version number.
The major number will be bumped when the project is feature-complete, and
later if there is a major change in the design or API.
@@ -60,7 +60,7 @@
The micro number is bumped for bug-fix releases.
"""
-__version_details__ = 'repository'
+__version_details__ = 'rc2'
"""Extra version details (e.g. 'snapshot 2005-05-29, r3410', 'repository',
'prerelease', 'release'), modified automatically & manually."""
With a small change to the "version template", the output of `rst2* --version`
remains PEP440-compliant, e.g.
``rst2html (Docutils 0.14-rc2, Python 2.7.13, on linux2)``
Index: frontend.py
===================================================================
--- frontend.py (Revision 8090)
+++ frontend.py (Arbeitskopie)
@@ -570,7 +570,7 @@
config_section = 'general'
- version_template = ('%%prog (Docutils %s [%s], Python %s, on %s)'
+ version_template = ('%%prog (Docutils %s-%s, Python %s, on %s)'
% (docutils.__version__, docutils.__version_details__,
sys.version.split()[0], sys.platform))
"""Default version message."""
-<meta name="generator" content="Docutils 0.14rc2: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
so we would need to either change the expected output or use the
"version_template" also in the "generator" generation.
David, Engelbert, what do you think?
Günter
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
https://lists.sourceforge.net/lists/listinfo/docutils-develop
Please use "Reply All" to reply to the list.