Mailman 3 June 2018 - docs

[issue14944] Setup & Usage documentation for pydoc
by Nick Coghlan March 20, 2019

March 20, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: pydoc is installed as a script by Python. It should be documented under http://docs.python.org/dev/using/index.html. ---------- assignee: docs@python components: Documentation messages: 161831 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for pydoc type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14944> _______________________________________

7 13

[issue13231] sys.settrace - document 'some other code blocks' for 'call' event type
by anatoly techtonik March 16, 2019

March 16, 2019

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/sys.html#sys.settrace While writing settrace function you need to know what kind of data is expected and how to get more information about it. Current documentation for sys.settrace doesn't give too much answers. To improve that situation at least with 'call' event: 1. Link 'frame' to the middle of table on inspect module page [1] 2. List all possible 'code blocks' for 'call' event (I know there is module in addition to function) 3. Provide example how to extract popular data for corresponding 'code block' (name for functions, name for modules, name for classes/methods, relative file path, line no, how to detect labmbda function) in a safe manner (inspect page contains some FUD about memory usage) 1. http://docs.python.org/library/inspect#types-and-members ---------- assignee: docs@python components: Documentation messages: 146009 nosy: docs@python, techtonik priority: normal severity: normal status: open title: sys.settrace - document 'some other code blocks' for 'call' event type _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13231> _______________________________________

2 2

[issue13277] tzinfo subclasses information
by Senthil Kumaran March 16, 2019

March 16, 2019

New submission from Senthil Kumaran <senthil(a)uthcode.com>: This was in the docs mailing list, not translated to bug report Paul Koning wrote: Section 8.1.6 of the library manual talks about utcoffset(dt)-dst(dt) as the "standard offset" and says that this should not depend on the date or +time but only on the location. This is not true as there cases were certain locations changed the time offsets as per their convenience. It is either a doc fix to remove that sentence if the datetime.astimezone does not depend upon utcoffset(dt)-dst(dt), or if it does, then it is a code fix. ---------- assignee: docs@python messages: 146501 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: tzinfo subclasses information type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13277> _______________________________________

5 5

[issue13074] Improve documentation of locale encoding functions
by Geoffrey Bache March 15, 2019

March 15, 2019

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: The locale module provides locale.getdefaultlocale and locale.getpreferredencoding. The encodings returned by each are generally subtly different ('ISO8859-1' vs 'ISO-8859-1'), but the difference between these methods is not explained. A comment by Martin von Löwis from 2003 in http://bugs.python.org/issue813449 indicates that "getdefaultlocale should not be used in new code", if this is really the case then this should be in the docs. Anyone reading the docs from the top will currently encounter getdefaultlocale first and believe that this is the way to get the encoding. ---------- assignee: docs@python components: Documentation messages: 144677 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Improve documentation of locale encoding functions versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13074> _______________________________________

5 5

[issue23311] Update PC/example_nt and extending/windows.rst
by Steve Dower March 15, 2019

March 15, 2019

New submission from Steve Dower: The installer for 3.5 will include an option to install debug binaries alongside the release ones, so we should update extending/windows.rst to explain that and generally describe how to build an extension. It should also refer to python3.dll at least once... The example project in PC/example_nt is fairly outdated. It could be updated to automatically find a 3.5 install and use the debug or release binaries/libraries from there. We could also include a 'test' project for PTVS (http://pytools.codeplex.com/) that helps write Python code for testing the extension and also has mixed-mode debugging enabled so people can step between the Python and the C code. (In fact, the PTVS team wants to do a sample project like this anyway, so maybe we can remove PC/example_nt and point to theirs...) ---------- assignee: docs@python components: Documentation, Windows messages: 234624 nosy: docs@python, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Update PC/example_nt and extending/windows.rst versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23311> _______________________________________

2 3

[issue20749] shutil.unpack_archive(): security concerns not documented
by Jakub Wilk March 15, 2019

March 15, 2019

New submission from Jakub Wilk: shutil.unpack_archive() uses tarfile.extractall() under the hood, so it's not suitable for unpacking untrusted archives. But this fact is not documented. Please add a security warning to shutil.unpack_archive() documentation. ---------- assignee: docs@python components: Documentation messages: 212029 nosy: docs@python, jwilk priority: normal severity: normal status: open title: shutil.unpack_archive(): security concerns not documented _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20749> _______________________________________

3 3

[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

[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

[issue30831] Inconsistent or wrong documentation around Asynchronous Context Manager
by Daisuke Miyakawa March 7, 2019

March 7, 2019

New submission from Daisuke Miyakawa: I was reading the following doc and got confused. https://docs.python.org/3.7/reference/datamodel.html#object.__aenter__ According to the API doc itself (and original PEP 492), __aenter__() "is semantically similar to the __enter__(), with only difference that it must return an awaitable." __aexit__() has similar sentence that confuses me too. PEP 492 also implies the (awaitable) object returned from obj.__aenter__() will be awaited immediately. In same manner, the (awaitable) object returned from obj.__aexit__() will be awaited too. (From PEP 492) > async with EXPR as VAR: > BLOCK > > which is semantically equivalent to: > > mgr = (EXPR) > aexit = type(mgr).__aexit__ > aenter = type(mgr).__aenter__(mgr) > exc = True > > VAR = await aenter > try: > BLOCK > except: > if not await aexit(mgr, *sys.exc_info()): > raise > else: > await aexit(mgr, None, None, None) On the other hand, actual CPython implementation won't do that; it won't await the returned objects. Moreover, the example shown in the API doc (AsyncContextManager) does NOT return awaitable as the doc itself suggests, but just await inside __aenter__() (and __aexit__()). > class AsyncContextManager: > async def __aenter__(self): > await log('entering context') > > async def __aexit__(self, exc_type, exc, tb): > await log('exiting context') I'm not sure which is true; the doc saying "__aenter__() must return awaitable" is just incorrect, or CPython implementation has a bug. Actual source implies former. _ContextManagerMixin in asyncio.locks does not return awaitable at all, for example. Anyway, I believe there are inconsistencies around here. ---------- assignee: docs@python components: Documentation messages: 297542 nosy: dmiyakawa, docs@python priority: normal severity: normal status: open title: Inconsistent or wrong documentation around Asynchronous Context Manager versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30831> _______________________________________

3 3

[issue23864] issubclass without registration only works for "one-trick pony" collections ABCs.
by Martijn Pieters Feb. 27, 2019

Feb. 27, 2019

New submission from Martijn Pieters: The collections.abc documentation implies that *any* of the container ABCs can be used in an issubclass test against a class that implements all abstract methods: > These ABCs allow us to ask classes or instances if they provide particular functionality [...] In reality this only applies to the "One Trick Ponies" (term from PEP 3119, things like Container and Iterable, those classes with one or two methods). It fails for the compound container ABCs: >>> from collections.abc import Sequence, Container, Sized >>> class MySequence(object): ... def __contains__(self, item): pass ... def __len__(self): pass ... def __iter__(self): pass ... def __getitem__(self, index): pass ... def __len__(self): pass ... >>> issubclass(MySequence, Container) True >>> issubclass(MySequence, Sized) True >>> issubclass(MySequence, Sequence) False That's because the One Trick Ponies implement a __subclasshook__ method that is locked to the specific class and returns NotImplemented for subclasses; for instance, the Iterable.__subclasshook__ implementation is: @classmethod def __subclasshook__(cls, C): if cls is Iterable: if any("__iter__" in B.__dict__ for B in C.__mro__): return True return NotImplemented The compound container classes build on top of the One Trick Ponies, so the class test will fail, NotImplemented is returned and the normal ABC tests for base classes that have been explicitly registered continues, but this won't include unregistered complete implementations. Either the compound classes need their own __subclasshook__ implementations, or the documentation needs to be updated to make it clear that without explicit registrations the issubclass() (and isinstance()) tests only apply to the One Trick Ponies. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 240060 nosy: docs@python, mjpieters priority: normal severity: normal status: open title: issubclass without registration only works for "one-trick pony" collections ABCs. _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23864> _______________________________________

9 13