Mailman 3 January 2019 - docs

[issue35732] Typo in library/warnings documentation
by Antoine Wecxsteen Jan. 14, 2019

Jan. 14, 2019

New submission from Antoine Wecxsteen <antoine(a)wecxsteen.net>: Hello, I believe there's a mistake in the documentation of library/warnings. https://docs.python.org/3.8/library/warnings.html#warnings.warn "This function raises an exception if the particular warning issued is changed into an error by the warnings filter see above." I think "see above" should be enclosed in brackets (or maybe completely removed as there is already a "(see above)" in the same text block). Regards. ---------- assignee: docs@python components: Documentation messages: 333574 nosy: awecx, docs@python, eric.araujo, ezio.melotti, mdk, willingc priority: normal severity: normal status: open title: Typo in library/warnings documentation 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/issue35732> _______________________________________

3 9

[issue34512] Document platform-specific strftime() behavior for non-ASCII format strings
by Alexey Izbyshev Jan. 14, 2019

Jan. 14, 2019

New submission from Alexey Izbyshev <izbyshev(a)ispras.ru>: If a format string contains code points outside of ASCII range, time.strftime() can behave in four different ways depending on the platform, the current locale and the code points: * raise a UnicodeEncodeError * return an empty string * for surrogates in \uDC80-\uDCFF range, replace them with different code points in the output (potentially mangling nearby parts of the output as well) * round-trip them correctly Some examples: * Linux (glibc 2.27): Python 3.6.4 (default, Jan 03 2018, 13:52:55) [GCC] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import time, locale >>> locale.getlocale() ('en_US', 'UTF-8') >>> time.strftime('\x80') '\x80' >>> time.strftime('\u044f') 'я' # '\u044f' >>> time.strftime('\ud800') '\ud800' >>> time.strftime('\udcff') '\udcff' >>> locale.setlocale(locale.LC_CTYPE, 'C') 'C' >>> time.strftime('\x80') '\x80' >>> time.strftime('\u044f') 'я' # '\u044f' >>> time.strftime('\ud800') '\ud800' >>> time.strftime('\udcff') '\udcff' * macOS 10.13.6 and FreeBSD 11.1: Python 3.7.0 (default, Jul 23 2018, 20:22:55) [Clang 9.1.0 (clang-902.0.39.2)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import time, locale >>> locale.getlocale() ('en_US', 'UTF-8') >>> time.strftime('\x80') '\x80' >>> time.strftime('\u044f') 'я' # '\u044f' >>> time.strftime('\ud800') '' >>> time.strftime('\udcff') '' >>> locale.setlocale(locale.LC_CTYPE, 'C') 'C' >>> time.strftime('\x80') '\x80' >>> time.strftime('\u044f') '' >>> time.strftime('\ud800') '' >>> time.strftime('\udcff') '' * Windows 8.1: Python 3.7.0 (v3.7.0:1bf9cc5093, Jun 27 2018, 04:59:51) [MSC v.1914 64 bit (AMD64)] on win32 >>> import time, locale >>> locale.getlocale() (None, None) >>> time.strftime('\x80') '\x80' >>> time.strftime('\u044f') Traceback (most recent call last): File "<stdin>", line 1, in <module> UnicodeEncodeError: 'locale' codec can't encode character '\u044f' in position 0: encoding error >>> time.strftime('\ud800') Traceback (most recent call last): File "<stdin>", line 1, in <module> UnicodeEncodeError: 'locale' codec can't encode character '\ud800' in position 0: encoding error >>> time.strftime('\udcff') 'y' # '\xff' >>> locale.setlocale(locale.LC_CTYPE, '') 'Russian_Russia.1251' >>> time.strftime('\x80') Traceback (most recent call last): File "<stdin>", line 1, in <module> UnicodeEncodeError: 'locale' codec can't encode character '\x80' in position 0: encoding error >>> time.strftime('\u044f') 'я' # '\u044f' >>> time.strftime('\ud800') Traceback (most recent call last): File "<stdin>", line 1, in <module> UnicodeEncodeError: 'locale' codec can't encode character '\ud800' in position 0: encoding error >>> time.strftime('\udcff') 'я' # '\u044f' The reasons of such differences are the following: * Reliance on either wcsftime() or strftime() from the C library depending on the platform. * For strftime(), the input is encoded into the charset of the current locale with 'surrogateescape' error handler, and the output is decoded back in the same way. * Different handling of code points which are unrepresentable in the charset of the current locale by glibc and macOS/FreeBSD. I suggest to at least document that the format string, despite being an 'str', requires special care if it contains non-ASCII code points. The 'datetime' module docs warn about the locale-dependent output, but only with regard to particular format specifiers [1]. I'll submit a draft PR. Suggestions are welcome. [1] https://docs.python.org/3.7/library/datetime.html#strftime-and-strptime-beh… ---------- assignee: docs@python components: Documentation messages: 324136 nosy: belopolsky, docs@python, izbyshev, p-ganssle, taleinat priority: normal severity: normal status: open title: Document platform-specific strftime() behavior for non-ASCII format strings type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34512> _______________________________________

5 17

[issue33039] int() and math.trunc don't accept objects that only define __index__
by Nick Coghlan Jan. 12, 2019

Jan. 12, 2019

Nick Coghlan <ncoghlan(a)gmail.com> added the comment: @Rémi Aye, filling out derived slots is one of the things PyType_Ready does. This would need a discussion on python-dev before going ahead and doing it though, as the closest equivalent we have to this right now is the "negative" derivation, where overriding __eq__ without overriding __hash__ implicitly marks the derived class as unhashable (look for "type->tp_hash = PyObject_HashNotImplemented;"). ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33039> _______________________________________

1 0

Report bugs on the leaps year
by #CHUAH SHEOU SHUANG# Jan. 12, 2019

Jan. 12, 2019

Dear Sir/Madam, [cid:image002.png@01D4AA81.1B676110] I accidentally found out that for years 1700, 1800, and 1900, they should be leaps year but then it shows that it has 28 days on February. Best Regards, Sheou Shuang. Sent from Mail<https://go.microsoft.com/fwlink/?LinkId=550986> for Windows 10

2 2

[issue35716] CLOCK_MONOTONIC_RAW available on macOS
by Ricardo Fraile Jan. 11, 2019

Jan. 11, 2019

New submission from Ricardo Fraile <rfraile(a)rfraile.eu>: Add macOS to CLOCK_MONOTONIC_RAW description because it is already available since 10.12. ---------- assignee: docs@python components: Documentation files: 001.patch keywords: patch messages: 333445 nosy: docs@python, rfrail3, vstinner priority: normal severity: normal status: open title: CLOCK_MONOTONIC_RAW available on macOS type: enhancement Added file: https://bugs.python.org/file48041/001.patch _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35716> _______________________________________

5 16

[issue35156] Consider revising documentation on Python Builds from source
by Jorge Ramos Jan. 10, 2019

Jan. 10, 2019

New submission from Jorge Ramos <neyuru(a)gmail.com>: I want to build from source a 3.6 Python, using PGO for windows. Followed instructions at https://devguide.python.org/setup/ (the original search from google was "build python from source windows"). From a newbie perspective there are several problems: 1) it is suggested that you should build first a "debug" python (header 1.3) but they don't tell you how. 2) it is suggested that you should first build via "PCBuild\build.bat" but they don't tell you that this builds a win32 platform. What if I want to build a x64 version? (lost much time here figuring out how) 3) I ran into problems when building with "PCBuild\build.bat" (header 1.3.2) because the dependencies where not all downloaded in the first pass (but this is a bug I could fill later). Lost much time here figuring why the build did not succeed. 4) in (1.3.2) it is suggested you keep reading in a readme file: https://github.com/python/cpython/blob/master/PCbuild/readme.txt This is the first time an optimization is mentioned (other than simply compiling from your machine. I did not know that using PGO was mandatory for real speedups compared to the downloadable “general” binaries). 5) In this very same readme, it says that there are other "subprojects" that you need to consider building with Python. Lost much time here trying to figure out that these subprojects are downloaded via "get_externals.bat" in the "Getting External Sources" section. Why not simply put the "Getting External Sources" section first and avoid worrying the newcomer of potential projects that are "not included with python"? 6) They tell you that PGO is automated via a "build_pgo.bat" file. But this does not exist. 7) They tell you that first, you have to run the PGInstrument option in the build, but it is not clear what should be run next: PCBuild\build.bat -c PGUpdate -p x64" or "PCBuild\build.bat --pgo -p x64" 8) After 2 days of trying to build (and learn in the process by trial and error) I stumble upon YET ANOTHER WAY TO BUILD: the one found in "cpython\Tools\msi" NOT the first one: "cpython\PCbuild" And this is the one I was interested in the first place: building an installable version of python (yet I have to figure out how to pack all cab files and such into one exe), not a developer’s python for testing. And after now 3 days with this, I noticed that all previous testing and building techniques are indeed reachable from "cpython\Tools\msi\buildrelease.bat -x64" which tries to build a python in x64 version AND using GPO (by default -in the x64 but not in the win32-, which is not mentioned in the documentation, by the way) also generating the dependencies required (I could have avoided losing some time if knowing this from the very beginning- see point 5) As you can see, I lost few hours here, few there. And because I am not a developer (my intention is to have an optimized python for my PC for AI research) I lost much time trying to figure out things that are not explicitly said in the documentation: I managed to learn from other sources (googling around), by careful observation of the compilation results, and digging into the help section of each of the files used. Hope I successfully communicated Python’s lack of proper documentation (just for the case of building from source!) ---------- assignee: docs@python components: Documentation messages: 329211 nosy: docs@python, neyuru priority: normal severity: normal status: open title: Consider revising documentation on Python Builds from source type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35156> _______________________________________

3 7

EPUB Version is too big.
by Michał Listowski Jan. 10, 2019

Jan. 10, 2019

Hello I believe that you should cut epub file in parts like PDF. This one file is almost unreadable for most of readers like Pocketbook or Kindle (after convert to mobi). When i open on PocketBook Inkpad 3 it shows me that file have 5500+ pages, even start to change pages is really difficuld for device. I think on tablets it's not a big problem because CPU in them are faster. Thanks a lot for your work and response Michał Listowski

1 0

Feedback on the error page
by 张相恩 Jan. 10, 2019

Jan. 10, 2019

I am a Python enthusiast from China. I have been studying this manual recently, but I found a problem and hope to solve it as soon as possible. The problem bothering me. I believe it will also plague other beginners. This is url ： https://docs.python.org/zh-cn/3.7/archives/python-3.7.2-docs-pdf-a4.zip wrong description： 404 Not Found

2 1

[issue35374] Windows doc build does not find autodetected hhc.exe
by Christian Ullrich Jan. 7, 2019

Jan. 7, 2019

New submission from Christian Ullrich <chris(a)chrullrich.net>: If hhc.exe is on the PATH when HTML Help is being built, the build fails because make.bat does not correctly remember the fact. The set command is very finicky with trailing spaces, leading to this: '"hhc "' is not recognized as an internal or external command, operable program or batch file. I suppose the "official" build does not rely on autodetection. In that case, a better fix would be to require setting HTMLHELP explicitly. PR (for the single-character fix) incoming. ---------- assignee: docs@python components: Documentation messages: 330872 nosy: chrullrich, docs@python priority: normal severity: normal status: open title: Windows doc build does not find autodetected hhc.exe type: compile error _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35374> _______________________________________

5 9

[issue35681] urllib.request.HTTPPasswordMgr.add_password requires more information for HTTPPasswordMgrWithDefaultRealm
by Tatz Sekine Jan. 7, 2019

Jan. 7, 2019

New submission from Tatz Sekine <tsekine(a)google.com>: TL;DR HTTPPasswordMgrWithDefaultRealm.add_password() doesn't have proper documentation. All known version of urllib.request (or urllib2 in Python 2.x) documentaion have the same issue. Details: HTTPPasswordMgrWithDefaultRealm object doesn't have its own documentation. Instead of that, HTTPPasswordMgr's doc have information for those 2 objects: https://docs.python.org/3.8/library/urllib.request.html?highlight=httppassw… Both objects have just 2 functions: add_password() and find_user_password(). The doc for find_user_password() has explanation how different between those 2 objects, while the one for add_password() doesn't. One of the missing explanation for HTTPPasswordMgrWithDefaultRealm.add_passowrd() is the value of realm. The document has now "realm, user and passwd must be strings.", but realm could be None for HTTPPasswordMgrWithDefaultRealm, to set default realm-less password. That's typical use case of HTTPPasswordMgrWithDefaultRealm.add_password(), or, that's exactly urllib howto doc mentions in https://docs.python.org/3.8/howto/urllib2.html?highlight=httppasswordmgrwit… Conclusion: So, documentation of HTTPPasswordMgr.add_passoword() should have additional explanation for realm which could be None for HTTPPasswordMgrWithDefaultRealm. Or, HTTPPasswordMgrWithDefaultRealm objects could have independent section from HTTPPasswordMgr, to clarify its usage. Why is this matter? Typeshed (https://github.com/python/typeshed) depends on the doc. I (or somebody else in the company) will report it separately. ---------- assignee: docs@python components: Documentation messages: 333189 nosy: docs@python, tsekine priority: normal severity: normal status: open title: urllib.request.HTTPPasswordMgr.add_password requires more information for HTTPPasswordMgrWithDefaultRealm 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/issue35681> _______________________________________

1 0