Mailman 3 July 2018 - docs

Found a bug in your docs
by Pawel Gieniec 13 Jul '18

13 Jul '18

2 1

[issue33859] Spelling mistakes found using aspell
by Karthikeyan Singaravelan 13 Jul '18

13 Jul '18

New submission from Karthikeyan Singaravelan <tir.karthi(a)gmail.com>: I have found some typos in docs folder using aspell. I have fixed them. The changes are as below : Doc/library/codecs.rst - cypher - cipher Doc/library/email.rst - Protcol - Protocol Doc/library/importlib.rst - abstact - abstract Doc/library/xmlrpc.client.rst - unmarsalling - unmarshalling Doc/license.rst - aheared to - adhered to Doc/using/cmdline.rst - descibed - described Doc/whatsnew/3.3.rst - accumlated - accumulated Doc/whatsnew/3.6.rst - Lollilop - Lollipop Doc/whatsnew/3.7.rst - direcory - directory Find typos - find . -iname '*rst' | xargs -I{} sh -c "aspell --master=en_US --extra-dicts=en_GB --ignore 3 list < {}" | sort | uniq > typos.txt Ignore case tr '[:upper:]' '[:lower:]' < typos.txt | sort | uniq | less This requires manually looking at output of less and then making changes. ---------- assignee: docs@python components: Documentation messages: 319510 nosy: docs@python, xtreak priority: normal severity: normal status: open title: Spelling mistakes found using aspell type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33859> _______________________________________

4 9

Search Improvement Suggestion - Methods
by Kim Ford 13 Jul '18

13 Jul '18

Hi there, I know there might be a way to get what I’m suggesting, but I haven’t found it, so I’m sharing it here. In brief, searching for things like “Dictionary Methods”, “List Methods”, and “String Methods” returns long lists or search results. Searching for any of the above should result in the top search result being a page that contains the methods. Or at least there should be some easy to find links in the docs that point to such things. Sadly, I wind up using Google and usually find myself on a different site than the official Python documentation. While some of these sites are okay, I find the content in the Python documentation to be best. If only I can find it! I hope I don’t come across as sounding like a whiner, but… whaaa whaa whaaa :) Best, Kim To clarify I start my searches from here: file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/index.html# <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/index.html#> This like is provided during Python 3.7 install and I’ve bookmarked it for “easy” reference. An example is when searching for “List Methods”, there are 239 results. In order to actually find List Methods in the docs, I need to do this: 1. Navigate to the General Index page 2. Click L (for List) 3. Search on the page for List (there are 19 matches) 4. Get frustrated as there is not section for Methods to click on list <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/glossary.html#term-list> assignment, target <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-6> comprehensions <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-12> deletion target <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-21> display <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-12> empty <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-12> expression <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-80>, [1] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-1>, [2] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-2> object <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/c-api/list.html#index-0>, [1] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-21>, [2] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-23>, [3] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/datamodel.html#index-23>, [4] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-12>, [5] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-33>, [6] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-35>, [7] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-38>, [8] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-10> target <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/compound_stmts.html#index-6>, [1] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/compound_stmts.html#index-6>, [2] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-5> type, operations on <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-22> list (built-in class) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#list> List (class in typing) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/typing.html#typing.List> list (pdb command) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/pdb.html#pdbcommand-list> list comprehension <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/glossary.html#term-list-comprehension> list() (imaplib.IMAP4 method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/imaplib.html#imaplib.IMAP4.list> (multiprocessing.managers.SyncManager method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/multiprocessing.html#multiprocessing.managers.SyncManager.list> (nntplib.NNTP method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/nntplib.html#nntplib.NNTP.list> (poplib.POP3 method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/poplib.html#poplib.POP3.list> (tarfile.TarFile method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/tarfile.html#tarfile.TarFile.list> LIST_APPEND (opcode) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/dis.html#opcode-LIST_APPEND> list_dialects() (in module csv) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/csv.html#csv.list_dialects> list_folders() (mailbox.Maildir method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/mailbox.html#mailbox.Maildir.list_folders> (mailbox.MH method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/mailbox.html#mailbox.MH.list_folders> At least String has a section called methods: string PyObject_Str (C function) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/c-api/object.html#index-2> __format__() (object method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/datamodel.html#index-74> __str__() (object method) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/datamodel.html#index-72> conversion <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/datamodel.html#index-74>, [1] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/simple_stmts.html#index-3> format() (built-in function) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/functions.html#index-4> formatted literal <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/lexical_analysis.html#index-20> formatting, printf <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-33> immutable sequences <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/datamodel.html#index-18> interpolated literal <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/lexical_analysis.html#index-20> interpolation, printf <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-33> item <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-36> methods <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-30> module <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/locale.html#index-6> object <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-26>, [1] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-35>, [2] <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/reference/expressions.html#index-38> object representation <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/extending/newtypes.html#index-3> str (built-in class) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-28> str() (built-in function) <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/functions.html#index-10> text sequence type <file:///Library/Frameworks/Python.framework/Versions/3.7/Resources/English.lproj/Documentation/library/stdtypes.html#index-26> Sent via Migadu.com, world's easiest email hosting

1 0

[issue34101] PyBuffer_GetPointer() not documented
by Antoine Pitrou 12 Jul '18

12 Jul '18

Change by Antoine Pitrou <pitrou(a)free.fr>: ---------- assignee: docs@python components: Documentation nosy: docs@python, pitrou, skrah priority: normal severity: normal status: open title: PyBuffer_GetPointer() not documented type: behavior versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34101> _______________________________________

1 0

[issue34094] Porting Python 2 to Python 3 example contradicts its own advice
by Bruce Richardson 11 Jul '18

11 Jul '18

New submission from Bruce Richardson <it.is.bruce(a)gmail.com>: https://docs.python.org/3/howto/pyporting.html#use-feature-detection-instea… In this section, the (very good) advice is "It would be better to treat Python 2 as the exceptional case instead of Python 3 and assume that future Python versions will be more compatible with Python 3 than Python 2" However, it then goes on to present the best solution (for dealing with library imports) is this: try: from importlib import abc except ImportError: from importlib2 import abc This is literally treating Python 3 as the exception, completely contradicting the advice given a few lines earlier. Practically, it also has the effect that, as Python 3 adoption spreads, import errors and automatic retries will become *more* common and then universal, adding a small amount of delay and noise to the entire Python estate. And that's not considering the case where both libraries are installed to cope with old code relying on the old library (in which case you surely want new code to default to using the new library) If the example is simply changed to try: from importlib2 import abc except ImportError: from importlib import abc then both the contradiction and the practical problems go away ---------- assignee: docs@python components: Documentation messages: 321436 nosy: Bruce Richardson, brett.cannon, docs@python priority: normal severity: normal status: open title: Porting Python 2 to Python 3 example contradicts its own advice _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34094> _______________________________________

3 3

[issue33729] Hashlib/blake2* missing 'data' keyword argument
by STINNER Victor 11 Jul '18

11 Jul '18

STINNER Victor <vstinner(a)redhat.com> added the comment: > None of the hashlib functions are taking keyword arguments for data: ... So it's just a documentation issue, no? https://docs.python.org/dev/library/hashlib.html#creating-hash-objects Juuso Lehtivarjo: do you want to write a pull request to fix the documentation? ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python, vstinner _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33729> _______________________________________

1 0

[issue34083] Functional Programming HOWTO: Dictionary ordering isn't "essentially random"
by Stig Johan Berggren 11 Jul '18

11 Jul '18

New submission from Stig Johan Berggren <stigjb(a)gmail.com>: The section about iterators in the Functional Programming HOWTO (https://docs.python.org/3/howto/functional.html#data-types-that-support-ite…) states the following about looping over dictionary keys: "Note that the order is essentially random, because it’s based on the hash ordering of the objects in the dictionary." Starting with 3.7, dictionary order is guaranteed to be the same as insertion order. ---------- assignee: docs@python components: Documentation messages: 321375 nosy: Stig Johan Berggren, docs@python priority: normal severity: normal status: open title: Functional Programming HOWTO: Dictionary ordering isn't "essentially random" versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34083> _______________________________________

4 8

[issue34050] Broken links to "OpenSSL cipher list format" in documentation
by Roland Weber 11 Jul '18

11 Jul '18

New submission from Roland Weber <rolweber(a)de.ibm.com>: The docs for SSLContext.set_ciphers [1] in Python 3 and ssl.wrap_socket [2] in Python 2 contain a link for "OpenSSL cipher list format", which points to an empty wiki page at https://wiki.openssl.org/index.php/Manual:Ciphers(1)#CIPHER_LIST_FORMAT The OpenSSL cipher list format is currently documented here instead: https://www.openssl.org/docs/manmaster/man1/ciphers.html [1] https://docs.python.org/3/library/ssl.html#ssl.SSLContext.set_ciphers [2] https://docs.python.org/2/library/ssl.html#ssl.wrap_socket ---------- assignee: docs@python components: Documentation messages: 321085 nosy: docs@python, rolweber priority: normal severity: normal status: open title: Broken links to "OpenSSL cipher list format" in documentation _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34050> _______________________________________

5 11

can python be used by a commercial company on their servers?
by Edger, Lisa A 10 Jul '18

10 Jul '18

Please let me know. I can find a way to contact anyone on this?? Lisa Edger, CSAM Certified Software Asset Manager License Management & Software Compliance Corning Incorporated SP-ZV-01-F3L 21 Lynn Morse Dr. Painted Post, NY 14870 t (607)974-9114 m (607)684-8190 edgerla(a)corning.com<mailto:briggsaa@corning.com> Reach Software Management on Blue Line<https://www.yammer.com/corning.com/#/threads/inGroup?type=in_group&feedId=1…>

2 1

configparser example typo
by Weihe Chen 10 Jul '18

10 Jul '18

To whom it may concern, In the page https://docs.python.org/3/library/configparser.html, under 14.2.1 Quick Start, example 2 with code: >>> import configparser>>> config = configparser.ConfigParser()>>> config['DEFAULT'] = {'ServerAliveInterval': '45',... 'Compression': 'yes',... 'CompressionLevel': '9'}>>> config['bitbucket.org'] = {}>>> config['bitbucket.org']['User'] = 'hg'>>> config['topsecret.server.com'] = {}>>> topsecret = config['topsecret.server.com']>>> topsecret['Port'] = '50022' # mutates the parser>>> topsecret['ForwardX11'] = 'no' # same here>>> config['DEFAULT']['ForwardX11'] = 'yes'>>> with open('example.ini', 'w') as configfile:... config.write(configfile)... Shouldn't the last line be configfile.write(config) ? Weihe

2 1