date:20200918

[Python-Dev] The Python documentation is now compatible with Sphinx 3.2 and newer

2020-09-18 Thread Victor Stinner

Hi,

The Python 3.8, 3.9 and 3.10 documentation can now be built with
Sphinx 3.2+, and Sphinx 2 is still supported. Sphinx 3.0 and 3.1 are
not supported.

On our continuous integration (CI), the Python 3.10 documentation is
now built with Sphinx 3 (version 3.2.1), whereas the Python 3.8 and
Python 3.9 documentation is still built with Sphinx 2 (just updated to
version 2.4.4). Also, the Sphinx version is now only pinned in a
single file (Doc/requirements.txt), rather than 3 files
(Doc/requirements.txt, .travis.yml and Doc/Makefile).

Thanks to everyone who helped to fix all these documentation build issues!

--

Sphinx 3.0 released in April 2020 is backward incompatible with Sphinx
2: the C domain is stricter, and it is no longer possible to build the
Python documentation with Sphinx 3.0.

I discussed with the Sphinx maintainers. They accepted to add two new
options to Sphinx 3.2 to add an opt-in Sphinx 2 compatibility mode:

# bpo-40204: Allow Sphinx 2 syntax in the C domain
c_allow_pre_v3 = True

# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
# Python documentation is built with -W (warnings treated as errors).
c_warn_on_allowed_pre_v3 = False

I modified Doc/conf.py to use these options.

I also fixed other real documentation issues, discovered by stricter Sphinx 3:
https://bugs.python.org/issue40204

--

By the way, all warnings produced during the documentation build have
been fixed as well:
https://bugs.python.org/issue35293

It took two years (I created the issue in November 2018) to fix all
these warnings! Multiple projects got fixes:

* Update our Doc/tools/extensions/pyspecific.py extension to fix
Sphinx RemovedInSphinx40Warning, by Dong-hee Na
* jinja2: 
https://github.com/pallets/jinja/commit/31bf9b7e71c3fee3b7866ffdc0f70f4525a490d9
(import collections ABC)
* python-babel: https://github.com/python-babel/babel/pull/609 (import
collections ABC)
* docutils: https://sourceforge.net/p/docutils/bugs/373/ (version 0.16
fixed SyntaxWarning on invalid escape sequence)
* etc.

--

The last remaining minor issue is my proposition to also update Sphinx
in docsbuild-scripts (docs.python.org):
https://github.com/python/docsbuild-scripts/issues/95

Victor
-- 
Night gathers, and now my watch begins. It shall not end until my death.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/MY5EDNHE7FSOULBRIUATB2V4FRKFQDNE/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The Python documentation is now compatible with Sphinx 3.2 and newer

2020-09-18 Thread Guido van Rossum

Thanks Victor! This is a great improvement.

On Fri, Sep 18, 2020 at 8:50 AM Victor Stinner  wrote:

> Hi,
>
> The Python 3.8, 3.9 and 3.10 documentation can now be built with
> Sphinx 3.2+, and Sphinx 2 is still supported. Sphinx 3.0 and 3.1 are
> not supported.
>
> On our continuous integration (CI), the Python 3.10 documentation is
> now built with Sphinx 3 (version 3.2.1), whereas the Python 3.8 and
> Python 3.9 documentation is still built with Sphinx 2 (just updated to
> version 2.4.4). Also, the Sphinx version is now only pinned in a
> single file (Doc/requirements.txt), rather than 3 files
> (Doc/requirements.txt, .travis.yml and Doc/Makefile).
>
> Thanks to everyone who helped to fix all these documentation build issues!
>
> --
>
> Sphinx 3.0 released in April 2020 is backward incompatible with Sphinx
> 2: the C domain is stricter, and it is no longer possible to build the
> Python documentation with Sphinx 3.0.
>
> I discussed with the Sphinx maintainers. They accepted to add two new
> options to Sphinx 3.2 to add an opt-in Sphinx 2 compatibility mode:
>
> # bpo-40204: Allow Sphinx 2 syntax in the C domain
> c_allow_pre_v3 = True
>
> # bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
> # Python documentation is built with -W (warnings treated as errors).
> c_warn_on_allowed_pre_v3 = False
>
> I modified Doc/conf.py to use these options.
>
> I also fixed other real documentation issues, discovered by stricter
> Sphinx 3:
> https://bugs.python.org/issue40204
>
> --
>
> By the way, all warnings produced during the documentation build have
> been fixed as well:
> https://bugs.python.org/issue35293
>
> It took two years (I created the issue in November 2018) to fix all
> these warnings! Multiple projects got fixes:
>
> * Update our Doc/tools/extensions/pyspecific.py extension to fix
> Sphinx RemovedInSphinx40Warning, by Dong-hee Na
> * jinja2:
> https://github.com/pallets/jinja/commit/31bf9b7e71c3fee3b7866ffdc0f70f4525a490d9
> (import collections ABC)
> * python-babel: https://github.com/python-babel/babel/pull/609 (import
> collections ABC)
> * docutils: https://sourceforge.net/p/docutils/bugs/373/ (version 0.16
> fixed SyntaxWarning on invalid escape sequence)
> * etc.
>
> --
>
> The last remaining minor issue is my proposition to also update Sphinx
> in docsbuild-scripts (docs.python.org):
> https://github.com/python/docsbuild-scripts/issues/95
>
> Victor
> --
> Night gathers, and now my watch begins. It shall not end until my death.
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/MY5EDNHE7FSOULBRIUATB2V4FRKFQDNE/
> Code of Conduct: http://python.org/psf/codeofconduct/
>


-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/BFZ6O2JI7DL6OUAAF5SLHWCSPFT5R2CF/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Summary of Python tracker Issues

2020-09-18 Thread Python tracker


ACTIVITY SUMMARY (2020-09-11 - 2020-09-18)
Python tracker at https://bugs.python.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open7675 (-22)
  closed 45870 (+67)
  total  53545 (+45)

Open issues with patches: 3122 


Issues opened (29)
==

#41768: unittest.mock spec calls class properties
https://bugs.python.org/issue41768  opened by melwitt

#41769: Positional arguments which use store boolean actions do not be
https://bugs.python.org/issue41769  opened by rjeffman

#41770: Import  module doesn't updated
https://bugs.python.org/issue41770  opened by prasechen

#41771: bdist_wininst doesn't execute postinstall script
https://bugs.python.org/issue41771  opened by mhammond

#41772: Zipfile.testzip considers wrong password as correct
https://bugs.python.org/issue41772  opened by Amir

#41774: While removing element from list using for and remove(), which
https://bugs.python.org/issue41774  opened by sreedevi.ha

#41775: IDLE: change Shell window title
https://bugs.python.org/issue41775  opened by terry.reedy

#41777: When using `python -bb`, `struct.calcsize` raises a warning wh
https://bugs.python.org/issue41777  opened by tadeu

#41779: add BLOB photo to sqlite3 python
https://bugs.python.org/issue41779  opened by alizaerialora

#41781: Typos in typing.py
https://bugs.python.org/issue41781  opened by pxeger

#41784: Promote PyUnicode_AsUTF8AndSize to be available with the limit
https://bugs.python.org/issue41784  opened by alex

#41787: adding PEP references to documentation
https://bugs.python.org/issue41787  opened by cameron

#41790: C-API documentation ignores heap types and says type objects m
https://bugs.python.org/issue41790  opened by koubaa

#41791: mimetypes module does not recognize jp2 type
https://bugs.python.org/issue41791  opened by naro

#41793: Inaccuracy about reflected operands in datamodel docs.
https://bugs.python.org/issue41793  opened by wim.glenn

#41794: Memory leak in asyncio server
https://bugs.python.org/issue41794  opened by EmperorBale

#41796: _ast module state should be made per interpreter
https://bugs.python.org/issue41796  opened by vstinner

#41797: PyModule_GetState doesn't work with LazyLoader
https://bugs.python.org/issue41797  opened by petr.viktorin

#41798: [C API] Revisit usage of the PyCapsule C API with multi-phase 
https://bugs.python.org/issue41798  opened by vstinner

#41799: splunklib.client does not handle Unicode characters
https://bugs.python.org/issue41799  opened by jpatel

#41800: Python installation fails when run under system account if the
https://bugs.python.org/issue41800  opened by Jurko.GospodnetiÄ

#41801: 23 tests failed for 3.9.0b2-64 installed on Windows 10
https://bugs.python.org/issue41801  opened by terry.reedy

#41802: Missing documentation for 'PyDict_DelItem' behavior
https://bugs.python.org/issue41802  opened by ideasman42

#41803: Robots.txt
https://bugs.python.org/issue41803  opened by admin2

#41804: test_epoll fails test_control_and_wait() randomly on aarch64 R
https://bugs.python.org/issue41804  opened by vstinner

#41805: types.GenericAlias and types.Union have no documentation
https://bugs.python.org/issue41805  opened by pxeger

#41806: socket methods with timeout take very slow path on Windows
https://bugs.python.org/issue41806  opened by steve.dower

#41807: Warnings when installing Linter on VS code on Linux and Window
https://bugs.python.org/issue41807  opened by zamunda

#41809: finding file attributes in Windows seems to fail
https://bugs.python.org/issue41809  opened by musiquegraeme



Most recent 15 issues with no replies (15)
==

#41807: Warnings when installing Linter on VS code on Linux and Window
https://bugs.python.org/issue41807

#41806: socket methods with timeout take very slow path on Windows
https://bugs.python.org/issue41806

#41801: 23 tests failed for 3.9.0b2-64 installed on Windows 10
https://bugs.python.org/issue41801

#41793: Inaccuracy about reflected operands in datamodel docs.
https://bugs.python.org/issue41793

#41790: C-API documentation ignores heap types and says type objects m
https://bugs.python.org/issue41790

#41781: Typos in typing.py
https://bugs.python.org/issue41781

#41775: IDLE: change Shell window title
https://bugs.python.org/issue41775

#41771: bdist_wininst doesn't execute postinstall script
https://bugs.python.org/issue41771

#41769: Positional arguments which use store boolean actions do not be
https://bugs.python.org/issue41769

#41768: unittest.mock spec calls class properties
https://bugs.python.org/issue41768

#41761: multiprocessing.Queue prevents program exit when containing a 
https://bugs.python.org/issue41761

#41754: Webbrowser Module Cannot Find xdg-settings on OSX
https://bugs.python.org/issue41754

#41752: Wave shouldn't try to close an open file at all costs
https://bugs.python.org/issue41752

#41747: dataclas

[Python-Dev] Enum and the Standard Library

2020-09-18 Thread Ethan Furman

As you may have noticed, Enums are starting to pop up all over the 
stdlib [1].


To facilitate transforming existing module constants to IntEnums there 
is `IntEnum._convert_`.  In Issue36548 [2] Serhiy modified the __repr__ 
of RegexFlag:


  >>> import re
  >>> re.I
  re.IGNORECASE

I think for converted constants that that looks nice.  For anyone that 
wants the actual value, it is of course available as the `.value` attribute:


  >>> re.I.value
  2

I'm looking for arguments relating to:

- should _convert_ make the default __repr__ be module_name.member_name?

- should _convert_ make the default __str__ be the same, or be the
  numeric value?

Thank you for your time!

--
~Ethan~


[1] I'm working on making their creation faster.  If anyone wanted to 
convert EnumMeta to C I would be grateful.


[2] https://bugs.python.org/issue36548
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/CHQW6THTDYNPPFWQ2KDDTUYSAJDCZFNP/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Enum and the Standard Library

2020-09-18 Thread Guido van Rossum

Okay, let me take a shot at this.

I actually like the status quo for regular enums, when repr() shows the
type, name and value, and str() shows "classname.flagname", so I'd stick to
that for converted flags. Even though this violates the rule of thumb that
repr() should look like a valid expression -- perhaps a stronger rule of
thumb is that repr() should show more than str(). Showing just (the str of)
the value seems unkind, since e.g. showing '4' makes me think it's just an
int. (Then again I can see that for *converted* flags that's not
unreasonable.)

But yeah, backwards compatibility. However, I don't think we got any
complaints about the `re` flags, did we?

On Fri, Sep 18, 2020 at 2:53 PM Ethan Furman  wrote:

> As you may have noticed, Enums are starting to pop up all over the
> stdlib [1].
>
> To facilitate transforming existing module constants to IntEnums there
> is `IntEnum._convert_`.  In Issue36548 [2] Serhiy modified the __repr__
> of RegexFlag:
>
>>>> import re
>>>> re.I
>re.IGNORECASE
>
> I think for converted constants that that looks nice.  For anyone that
> wants the actual value, it is of course available as the `.value`
> attribute:
>
>>>> re.I.value
>2
>
> I'm looking for arguments relating to:
>
> - should _convert_ make the default __repr__ be module_name.member_name?
>
> - should _convert_ make the default __str__ be the same, or be the
>numeric value?
>
> Thank you for your time!
>
> --
> ~Ethan~
>
>
> [1] I'm working on making their creation faster.  If anyone wanted to
> convert EnumMeta to C I would be grateful.
>
> [2] https://bugs.python.org/issue36548
> ___
> Python-Dev mailing list -- python-dev@python.org
> To unsubscribe send an email to python-dev-le...@python.org
> https://mail.python.org/mailman3/lists/python-dev.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-dev@python.org/message/CHQW6THTDYNPPFWQ2KDDTUYSAJDCZFNP/
> Code of Conduct: http://python.org/psf/codeofconduct/
>


-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/ZFM22AQU2B5P7DQR2N5YL7OVFKZON7B6/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Enum and the Standard Library

2020-09-18 Thread Ethan Furman


On 9/18/20 3:12 PM, Guido van Rossum wrote:
> On 9/18/20 2:44 PM, Ethan Furman wrote:

>> I'm looking for arguments relating to:
>>
>> - should _convert_ make the default __repr__ be
>>   module_name.member_name?
>
> I actually like the status quo for regular enums, when repr() shows
> the type, name and value, and str() shows "classname.flagname", so I'd
> stick to that for converted flags. Even though this violates the rule
> of thumb that repr() should look like a valid expression -- perhaps a
> stronger rule of thumb is that repr() should show more than str().

Well, if the repr is re.IGNORECASE and the str is 2, then we've met that 
bar.  ;-)


>> - should _convert_ make the default __str__ be the same, or be the
>>   numeric value?
>
> Showing just (the str of) the value seems unkind, since e.g. showing
> '4'makes me think it's just an int. (Then again I can see that for
> *converted* flags that's not unreasonable.)
>
> But yeah, backwards compatibility. However, I don't think we got any
> complaints about the `re` flags, did we?

The only complaints I'm aware of were before the re constants became an 
Enum, but my social media activity consists almost entirely of 
Stackoverflow.


So at this point, I think the choices are:

Standard Enum
  __repr__   __str__
   RegexFlag.IGNORECASE

and

Modified Converted Constant
  __repr__   __str__
re.IGNORECASE   2


I will admit I fancy the MCC variant more, but we should make a choice 
and then be consistent.


--
~Ethan~
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/5QWMFP3762XINCNK6WUJFLVNVENO5NOV/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: Enum and the Standard Library

2020-09-18 Thread Guido van Rossum

On Fri, Sep 18, 2020 at 6:19 PM Ethan Furman  wrote:

> On 9/18/20 3:12 PM, Guido van Rossum wrote:
>  > On 9/18/20 2:44 PM, Ethan Furman wrote:
>
>  >> I'm looking for arguments relating to:
>  >>
>  >> - should _convert_ make the default __repr__ be
>  >>   module_name.member_name?
>  >
>  > I actually like the status quo for regular enums, when repr() shows
>  > the type, name and value, and str() shows "classname.flagname", so I'd
>  > stick to that for converted flags. Even though this violates the rule
>  > of thumb that repr() should look like a valid expression -- perhaps a
>  > stronger rule of thumb is that repr() should show more than str().
>
> Well, if the repr is re.IGNORECASE and the str is 2, then we've met that
> bar.  ;-)
>
>  >> - should _convert_ make the default __str__ be the same, or be the
>  >>   numeric value?
>  >
>  > Showing just (the str of) the value seems unkind, since e.g. showing
>  > '4' makes me think it's just an int. (Then again I can see that for
>  > *converted* flags that's not unreasonable.)
>  >
>  > But yeah, backwards compatibility. However, I don't think we got any
>  > complaints about the `re` flags, did we?
>
> The only complaints I'm aware of were before the re constants became an
> Enum, but my social media activity consists almost entirely of
> Stackoverflow.
>

:-)

So at this point, I think the choices are:
>
> Standard Enum
>__repr__   __str__
>RegexFlag.IGNORECASE
>
> and
>
> Modified Converted Constant
>__repr__   __str__
> re.IGNORECASE   2
>
>
> I will admit I fancy the MCC variant more, but we should make a choice
> and then be consistent.
>

Hm, there's also what re actually does (tried in 3.8, 3.9 and 3.10):
```
>>> import re
>>> print(str(re.I))
RegexFlag.IGNORECASE
>>> print(repr(re.I))
re.IGNORECASE
>>>
```
I honestly think we've already lost consistency.

Possibly regular enums (Enum, IntEnum, IntFlag) should just all return "
class.name", e.g. 'Color.RED', for both str() and repr(), and "converted"
enums should return "module.name", e.g. 're.IGNORE' for both? It restores
the rule of thumb, and it's not unusual. Maybe it's a new trend -- PEP
585's list[int] returns "list[int]" for both str() and repr(). :-)

At the same time it's as old as Python -- for most builtins other than
strings, repr() and str() are the same, and modeled after repr().
Historically, I only introduced the difference between str() and repr()
because of strings -- I wanted the REPL to clearly show the difference
between the number 42 and the string '42', but at the same time I wanted
both to print as just '42'. Of course numpy took a different fork in that
road...

Another brainstorm (or brainfart): maybe repr() should show the
module/class and the name, and str() should only show the name. We'd then
get
```
>>> # Mock-up!
>>> print(str(re.i))
IGNORE
>>> print(repr(re.i))
re.IGNORE
>>>
```
and similar for Color.RED:
```
>>> # Another mock-up!
>>> print(str(Color.RED))
RED
>>> print(repr(Color.RED))
Color.RED
>>>
```

-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/5CB22SIQQX3EWIOTIIPLWKMNWFZOVSAH/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] The Python documentation is now compatible with Sphinx 3.2 and newer

[Python-Dev] Re: The Python documentation is now compatible with Sphinx 3.2 and newer

[Python-Dev] Summary of Python tracker Issues

[Python-Dev] Enum and the Standard Library

[Python-Dev] Re: Enum and the Standard Library

[Python-Dev] Re: Enum and the Standard Library

[Python-Dev] Re: Enum and the Standard Library

7 matches

Site Navigation

Mail list logo

Footer information