Mailman 3 April 2019 - docs

[issue36538] _thread.interrupt_main() no longer interrupts Lock.wait
by Gregory P. Smith April 6, 2019

April 6, 2019

New submission from Gregory P. Smith <greg(a)krypto.org>: In Python 2.7 our threading implementation was so poor that a thread join ultimately called our lock wait implementation that busy looped polling and sleeping to check for a lock acquisition success. calling thread.interrupt_main() which is just PyErr_SetInterrupt() C API in disguise successfully broke out of that lock wait loop. In Python 3 with our drastically improved threading implementation, a lock wait is a pthreads sem_timedwait() or sem_trywait() API call, blocking within the pthreads library or OS kernel. PyErr_SetInterrupt() obviously has no effect on that. Only an actual signal arriving can interrupt that. Thus instead of code using _thread.interrupt_main() - in 2and3 compatible applications, six.moves._thread.interrupt_main() - they should instead write: os.kill(os.getpid(), signal.SIGINT) Given that _thread is a private module making _thread.interrupt_main() a private API, do we need to keep it? If we do, we should at least document this behavior and recommend actually sending the signal. It is less capable of actually interrupting the main thread from some common blocking operations today. Sending the signal seems like it would always be better. ---------- assignee: docs@python components: Documentation, Extension Modules, Library (Lib) messages: 339518 nosy: docs@python, gregory.p.smith priority: normal severity: normal stage: needs patch status: open title: _thread.interrupt_main() no longer interrupts Lock.wait type: behavior versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36538> _______________________________________

2 1

[issue36532] Example of logging.formatter with new str.format style
by spaceman_spiff April 6, 2019

April 6, 2019

New submission from spaceman_spiff <accounts(a)sgerber.de>: It was not quite clear how to use the logging library with the new str.format style so I added an example in the logging cookbook ---------- assignee: docs@python components: Documentation messages: 339470 nosy: docs@python, spaceman_spiff priority: normal severity: normal status: open title: Example of logging.formatter with new str.format style versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36532> _______________________________________

5 7

[issue36486] Bugs and inconsistencies in unicodedata
by David Corbett April 5, 2019

April 5, 2019

New submission from David Corbett <corbett.dav(a)husky.neu.edu>: In `unicodedata`, the functions `lookup` and `name` have some bugs and inconsistencies. `lookup` matches case-insensitively, except for the algorithmic names of Hangul syllables and CJK unified ideographs, which must be in all caps. The documentation does not explain how character names are fuzzily matched. `lookup` accepts names like “CJK UNIFIED IDEOGRAPH-04E00”, where the code point has a leading zero. `lookup` and `name` don’t implement rule NR2, defined in chapter 4 of Unicode, for Tangut ideographs’ names. ---------- assignee: docs@python components: Documentation, Unicode messages: 339203 nosy: docs@python, dscorbett, ezio.melotti, vstinner priority: normal severity: normal status: open title: Bugs and inconsistencies in unicodedata type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36486> _______________________________________

3 2

Python documentation well designed to confuse newbies
by YK April 5, 2019

April 5, 2019

I'm getting quite frustrated with this poorly designed documentation. Info about a specific topic I'm interested in is usually split between 2 places, if not 3. Which forces me to search the whole documentation for locations where they were, which location had that specific part which I seek. Why can't each topic simply be in one place? Documentation is so fragmented. Any love for newbies? Whole documentation is a huge wreck, it should be done over, with better details, explanations, examples and without excess jumping. Have you seen how neat and tidy *w3schools* is? Today I stepped on another landmine in Python's documentation. Was checking out "*secrets — Generate secure random numbers for managing secrets*". At some point of writing code, I wondered to myself, gee, why doesn't secrets module simply have a shuffling function to shuffle object contents. So instead I wrote a manual thing that picked items randomly into a new list. Few days later, I accidentally stumbled upon a code piece on the internet: " *secrets.SystemRandom().shuffle(obj)*". I again opened up secrets topic in documentation. I could not see anything directly as that. Instead I have not much telling info about a class and then "*See random.SystemRandom for additional details.*". Alright, I'll click that. And again, info about a class and nothing related to "*secrets.SystemRandom().shuffle(obj)*". But that expression works. How? Why? No idea. Great. Checking in *Wing IDE*, I noticed that it points to "*random.shuffle()*" instead. How, why are they related? I have no idea. How am I, as a non-expert to Python, supposed to know and understand this feature? Documentation is poorly designed, I will soon have a hole in my front of my head from rubbing out of frustration. Is the documentation designed so on purpose? Do I have to hand out a 3 digit figure of cash to go to Python school? Python is free, so why can't proper education about Python be free too...

2 1

[issue36530] Document codecs decode_encode() and encode_decode() APIs
by Gregory P. Smith April 5, 2019

April 5, 2019

New submission from Gregory P. Smith <greg(a)krypto.org>: The codecs module has public decode_encode() and encode_decode() functions. They have never been documented, but are recommended for some uses such as: https://stackoverflow.com/questions/14820429/how-do-i-decodestring-escape-i… As public APIs, we should document them. ---------- assignee: docs@python components: Documentation messages: 339467 nosy: docs@python, gregory.p.smith, njs priority: normal severity: normal stage: needs patch status: open title: Document codecs decode_encode() and encode_decode() APIs versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36530> _______________________________________

1 2

Translation of documentation
by Davi Px April 4, 2019

April 4, 2019

Hello! I want to contribute by translating the python documentation from english to portuguese - brazil. Where i can find the tools to help? Thanks!

3 2

[issue32413] Document that locals() may return globals()
by Steven D'Aprano April 2, 2019

April 2, 2019

New submission from Steven D'Aprano <steve+python(a)pearwood.info>: The obvious documentation for locals() fails to mention that when called from the top level of a module (outside of a function or class body) it returns the same dict as globals(). https://docs.python.org/2/library/functions.html#locals ---------- assignee: docs@python components: Documentation messages: 308947 nosy: docs@python, steven.daprano priority: normal severity: normal status: open title: Document that locals() may return globals() type: enhancement 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/issue32413> _______________________________________

6 9

[issue36364] errors in multiprocessing.shared_memory examples
by Pierre Glaser April 2, 2019

April 2, 2019

New submission from Pierre Glaser <pierreglaser(a)msn.com>: The examples of the new shared_memory module using SharedMemoryManager try to import the class from multiprocessing.shared_memory instead of multiprocessing.managers, making them fail. ---------- assignee: docs@python components: Documentation files: 0001-DOC-fix-SharedMemoryManager-examples.patch keywords: patch messages: 338360 nosy: docs@python, pierreglaser priority: normal severity: normal status: open title: errors in multiprocessing.shared_memory examples versions: Python 3.8 Added file: https://bugs.python.org/file48221/0001-DOC-fix-SharedMemoryManager-examples… _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36364> _______________________________________

5 6

[issue36377] Python 'datastructures.html' docs page needs improvement because of ambiguity
by parkito April 2, 2019

April 2, 2019

New submission from parkito <shoark7(a)gmail.com>: Hi, I have lots of interests in python data structures and their inheritance relationships so I often look around in python collections and collections.abc module. ``` https://docs.python.org/3/tutorial/datastructures.html#comparing-sequences-… ``` Please see the last section of the page. I know all Python users are well aware of Sequence comparisons like in tuples and list. This page also mentions that 'Sequence objects may be compared to other objects with the same sequence type' in the very first line of the page. However, we have to know that 'range' is also a subclass of 'Sequence' but 'range' objects are not comparable to each other. I tested 'range(1, 3) < 'range(3)' in my interpreter. If it compares correctly as both are same Sequence types, result would be 'False'. Instead, TypeError was raised. It's because comparision methods(__gt__, __lte__, etc) are not impleneted here. I thought range objects would compare the values with peeking. But they don't. So, I recommend you to implement 5.8 section in this page as follows: -> Please specify that 'not all' Sequence subclass are comparable to the same classes: typically, 'range'. 'range' is a good example because every Python user uses 'range' in for loop. ---------- assignee: docs@python components: Documentation hgrepos: 382 messages: 338433 nosy: docs@python, shoark7 priority: normal severity: normal status: open title: Python 'datastructures.html' docs page needs improvement because of ambiguity type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36377> _______________________________________

4 5

[issue30661] Support tarfile.PAX_FORMAT in shutil.make_archive
by C.A.M. Gerlach April 1, 2019

April 1, 2019

C.A.M. Gerlach <CAM.Gerlach(a)Gerlach.CAM> added the comment: Thanks for the confirmation! ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue30661> _______________________________________

1 0