Mailman 3 March 2019 - docs

[issue28124] Rework SSL module documentation
by Christian Heimes March 11, 2019

March 11, 2019

New submission from Christian Heimes: The documentation of the SSL module needs a rework. It's confusing and hard to understand even for experienced developers. The documentation should start with basic use cases and easy-to-reuse best practices. * The module starts with move ssl.wrap_socket() but it's no longer best practice. The section should be moved down and favor of a quick introduction of SSLContext. * ssl.create_default_context() is the best way to create a SSLContext. Mention that purpose flags and that Purpose.SERVER_AUTH is the correct setting on the client side. It means: "Create a context to authenticate the certs of a TLS server." (correct also for ftp, imap, ldap, smtp and so on). * The protocol table is confusing and does not mention the meaning of PROTOCOL_SSLv23 (aka PROTOCOL_TLS). It's auto-negotiation of the highest TLS protocol version and takes OP_NO_* SSLContext.options into account. PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER are the recommended options nowadays. * Don't confront users with CERT_OPTIONAL in the first section. It's a super special mode for client cert authentication on the server side. On the client side, CERT_REQUIRED is the right mode with CERT_NONE as workaround. On the server side CERT_NONE (default) is usually the right setting. * check_hostname is a client-side option that should be enabled all the time. * Explain that users can load the public key of a self-signed certificate like a CA cert to have cert validation even for self-signed certs. ---------- assignee: docs@python components: Documentation messages: 276238 nosy: christian.heimes, docs@python priority: high severity: normal stage: needs patch status: open title: Rework SSL module documentation type: enhancement versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28124> _______________________________________

4 8

Problem: Order of operations with a list
by MrSiuol Siuol March 11, 2019

March 11, 2019

There is a problem with: [0]*4/2 "Traceback (most recent call last): File "<pyshell#5>", line 1, in <module> [0]*4/2 TypeError: unsupported operand type(s) for /: 'list' and 'int'" Solution: prioritize calcul without list, before duplicate list

2 1

Section 5 of Python 2.7.16 documentation errors
by Bud Maddock March 11, 2019

March 11, 2019

Most notable, section 5. Expressions def f(a,b): print a,b # raises an error and should read print(a,b) Section 5.4 Raising a negative number to a fractional power does not return an error as stated in the documentation but appears to functioning correctly. Section 5.9 <> returns a syntax error and is no longer usable to replace != Bud

2 1

[issue36240] Definitions of time
by Robert Billing March 11, 2019

March 11, 2019

New submission from Robert Billing <robertthebilling(a)googlemail.com>: https://docs.python.org/3.7/library/time.html contains the text "UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or GMT)". This is not strictly true. Referring to https://en.wikipedia.org/wiki/Coordinated_Universal_Time the definition of UTC is in terms of frequency standards, GMT in terms of astronomy. Hence with GMT each minute has exactly 60 seconds, but the length of the second may vary slightly to account for changes in the Earth's rotation. With UTC each second is the same length, but "leap seconds" can be inserted or removed giving 59 and 61 second minutes. The leap seconds keep the two systems in sync to less than one second. This of course only matters for the most critical applications, but it would be worth documenting correctly. ---------- assignee: docs@python components: Documentation messages: 337482 nosy: Robert Billing, docs@python priority: normal severity: normal status: open title: Definitions of time type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36240> _______________________________________

5 4

回复:Re: example error--port inconsistent
by 程念 March 11, 2019

March 11, 2019

Hi, very good! --------------原始邮件-------------- 发件人："Julien Palard "<julien(a)palard.fr>; 发送时间：2019年3月11日(星期一) 下午5:58 收件人："程念" <chengnian(a)zkfurong.com>; 抄送："docs(a)python.org "<docs(a)python.org>; 主题：Re: [docs] example error--port inconsistent ----------------------------------- Hi! Thanks for reporting, I'm fixing this here: https://github.com/python/cpython/pull/12273 does it looks OK to you? Bests, -- Julien Palard https://mdk.fr

1 0

example error--port inconsistent
by 程念 March 11, 2019

March 11, 2019

docs url: https://docs.python.org/3/library/multiprocessing.html describe：The connection ports are inconsistent

2 1

[issue36258] Incorrect docstring of the ssl module
by Ofek Lev March 10, 2019

March 10, 2019

New submission from Ofek Lev <ofekmeister(a)gmail.com>: The docstring refers to the function `fetch_server_certificate` that no longer exists. Context from https://github.com/python/cpython/pull/12168#issuecomment-469488585: """ In the commit on 8/28/2007, the ssl.py module was first added and it contained the fetch_server_certificate() function. That function was removed with commit r57680 on 8/30/2007. The function get_server_certificate() was added in commit r58164 on 9/18/2007. ... Additionally, there are more than just 2 functions now, so it seems to me that the entire module docstring should be reviewed and updated to reflect the current state of the module or else it should be removed since it hasn't been kept in sync. """ ---------- assignee: docs@python components: Documentation messages: 337639 nosy: Ofekmeister, cheryl.sabella, docs@python priority: normal severity: normal status: open title: Incorrect docstring of the ssl module type: behavior versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36258> _______________________________________

1 0

[issue26018] documentation of ZipFile file name encoding
by Martin von Gagern March 10, 2019

March 10, 2019

New submission from Martin von Gagern: https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile.write writes: “Note: There is no official file name encoding for ZIP files. If you have unicode file names, you must convert them to byte strings in your desired encoding before passing them to write(). WinZip interprets all file names as encoded in CP437, also known as DOS Latin.” I think this is wrong in many ways. Firstly, APPNOTE.TXT used to explicitely define CP437 as the standard, and it's still the standard in the absence of general purpose bit 11 and a more specific description using the 0x0008 Extra Field. On the other hand, we do have that general purpose bit these days, so there are now not just one but two well-defined file name encodings. And thirdly, encoding the string to bytes as suggested will in fact lead to a run time error, since ZipInfo expects to do this conversion itself. See work towards issue1734346, starting at commit 8e33f316ce14, for details on when this was addressed in the source code. ---------- assignee: docs@python components: Documentation messages: 257567 nosy: docs@python, gagern priority: normal severity: normal status: open title: documentation of ZipFile file name encoding type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26018> _______________________________________

4 5

[issue36248] document about `or`, `and` operator.
by Windson Yang March 9, 2019

March 9, 2019

New submission from Windson Yang <wiwindson(a)outlook.com>: I think we should document the behavior as below, (maybe at https://docs.python.org/3/reference/expressions.html#operator-precedence) >>> 1 or 0 and 3 1 >>> 0 or 1 and 3 3 Please correct me if we already document it. ---------- assignee: docs@python components: Documentation messages: 337555 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: document about `or`, `and` operator. type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36248> _______________________________________

4 6

[issue35830] building multiple (binary) packages from a single project
by Stefan Seefeld March 9, 2019

March 9, 2019

New submission from Stefan Seefeld <stefan(a)seefeld.name>: I'm working on a project that I'd like to split into multiple separately installable components. The main component is a command-line tool without any external dependencies. Another component is a GUI frontend that adds some third-party dependencies. Therefore, I'd like to distribute the code in a single source package, but separate binary packages (so users can install only what they actually need). I couldn't find any obvious way to support such a scenario with either `distutils` nor `setuptools`. Is there an easy solution to this ? (I'm currently thinking of adding two `setup()` calls to my `setup.py` script. That would then call all commands twice, so I'd need to override the `sdist` command to only build a single (joint) source package. Is there a better way to achieve what I want ? ---------- assignee: docs@python components: Distutils, Documentation messages: 334381 nosy: docs@python, dstufft, eric.araujo, stefan priority: normal severity: normal status: open title: building multiple (binary) packages from a single project type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35830> _______________________________________

3 4