Mailman 3 December 2016 - docs

[issue28853] locals() and free variables
by Marco Buttu 03 Dec '16

03 Dec '16

New submission from Marco Buttu: The locals() documentation [1] says that "Free variables are returned by locals() when it is called in function blocks". A free variable inside a function has a global scope, and in fact it is not returned by locals():: >>> x = 33 >>> def foo(): ... print(x) ... print(locals()) ... >>> foo() 33 {} Maybe "function blocks" here means "closure"? Does the doc mean this? >>> def foo(): ... x = 33 ... def moo(): ... print(x) ... print(locals()) ... return moo ... >>> moo = foo() >>> moo() 33 {'x': 33} In that case, I think it is better to write "closures" instead of "function blocks". [1] https://docs.python.org/3/library/functions.html#locals ---------- assignee: docs@python components: Documentation messages: 282200 nosy: docs@python, marco.buttu priority: normal severity: normal status: open title: locals() and free variables type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28853> _______________________________________

6 11

Python Documentation
by Aayush Aishwani 03 Dec '16

03 Dec '16

Hi Sir/Mam, I want to learn Python as i have started my carrier with python programm . Since 6 month i am working in python but i want to build my knowledge up to advance level in python . for that what is good material for learning python. i want python ocumentation is it enough for learning python. Thanks & regards Aayush Aishwani

1 0

[issue17546] Document the circumstances where the locals() dict get updated
by Martin Panter 02 Dec '16

02 Dec '16

Martin Panter added the comment: Some minor tweaks to my earlier patch: * list comprehension → comprehension * time it is called → time of the call ---------- versions: +Python 3.6, Python 3.7 -Python 3.3, Python 3.4 Added file: http://bugs.python.org/file45735/locals_doc.04.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17546> _______________________________________

1 0

__builtins__ propagation is misleading described in exec and eval documentation (issue 26363)
by vadmium+py＠gmail.com 02 Dec '16

02 Dec '16

https://bugs.python.org/review/26363/diff/19291/Doc/library/functions.rst File Doc/library/functions.rst (right): https://bugs.python.org/review/26363/diff/19291/Doc/library/functions.rst#n… Doc/library/functions.rst:399: present and does not contain a value for the key '__builtins__', What was wrong with the original? Your new wording raising questions about whether you can have a key without a value, is None considered a value, etc. https://bugs.python.org/review/26363/

1 0

[issue19795] Formatting of True/False in docs
by Serhiy Storchaka 02 Dec '16

02 Dec '16

New submission from Serhiy Storchaka: The proposed patch improves formatting of True/False in the documentation. "True" becomes "``True``" if it means True constant and "true" if it means true value (in input arguments). See also issue19793 and issue19794. ---------- assignee: docs@python components: Documentation files: doc_truefalse.patch keywords: patch messages: 204463 nosy: docs@python, serhiy.storchaka priority: normal severity: normal stage: patch review status: open title: Formatting of True/False in docs type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file32854/doc_truefalse.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19795> _______________________________________

7 20

Re: [docs] Sync-up docstrings in C version of the the decimal module (issue 27779)
by lisaroach14＠gmail.com 01 Dec '16

01 Dec '16

Thanks Stefan! I added a couple of notes to your comments, I'll upload the new draft in a moment. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… File Modules/_decimal/docstrings.h (left): https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:34: Return a context manager that will set the default context to a copy of ctx\n\ On 2016/10/23 21:39:46, skrah wrote: > This is actually important in the age of asyncio. It returns *and sets* the > thread's default context. > > I prefer the existing wording here. Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:109: the same numeric value but different representations compare unequal\n\ On 2016/10/23 21:39:46, skrah wrote: > I'd leave this in. I tried to give examples only when something unexpected > happens. This is one of the cases. Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… File Modules/_decimal/docstrings.h (right): https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:244: Represents the number as a triple tuple, to show the internals exactly as\n\ On 2016/10/23 21:39:46, skrah wrote: > This is outdated for the Python version and wrong for the C version. For python 3.7 it looks correct to me? >>> Decimal(10).as_tuple() DecimalTuple(sign=0, digits=(1, 0), exponent=0) https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:351: Compares two operands using their abstract representation rather than\n\ On 2016/10/23 21:39:46, skrah wrote: > Everyone has a preferred form. I think Guido prefers the imperative "Compare" > (it may be in a PEP somewhere). Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:405: Returns a copy of the operand with the sign set to 0. This operation is unaffected by\n\ On 2016/10/23 21:59:26, skrah wrote: > I think "sign set to zero" is a bit confusing for the C version. "absolute > value" sounds fine to me. Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:405: Returns a copy of the operand with the sign set to 0. This operation is unaffected by\n\ On 2016/10/23 21:59:26, skrah wrote: > I think "sign set to zero" is a bit confusing for the C version. "absolute > value" sounds fine to me. Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:432: Copies the second operand's sign to the first one.\n\ On 2016/10/23 21:39:46, skrah wrote: > That sounds as if it is a destructive update. Done. https://bugs.python.org/review/27779/diff/18450/Modules/_decimal/docstrings… Modules/_decimal/docstrings.h:739: value of that digit and without limiting the resulting exponent).\n\ On 2016/10/23 21:39:46, skrah wrote: > Personally, I have a hard time understanding this explanation. I agree this is confusing. It is taken directly from the specification, I worry that clarifying the wording could misrepresent the definition, but the C docstring is a lot clearer. I'm not sure which would be better to include. https://bugs.python.org/review/27779/

1 0

[issue28733] Show how to use mock_open in modules other that __main__
by Michał Bultrowicz 01 Dec '16

01 Dec '16

New submission from Michał Bultrowicz: Documentation of mock_open doesn't say how to use it in real-life test situations (when you're probably not mocking in __main__). I've spent some time scratching my head and googling for the way to mock-out the "open" function, want to spare other people the hassle. The thing is that "open" needs to be mocked out from the magical "builtins" module, and not from the place of usage (like when mocking everything that's not built-in). So it's not obvious how to do that, especially that the example with __main__ makes it look like the normal mocking approach should work. I still don't fully understand why mocking "__main__.open" can work from interpreter, but that's a different thing... ---------- assignee: docs@python components: Documentation files: mock_open_doc.patch keywords: patch messages: 281114 nosy: butla, docs@python priority: normal severity: normal status: open title: Show how to use mock_open in modules other that __main__ type: enhancement versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45533/mock_open_doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28733> _______________________________________

3 6

[issue26483] docs unclear on difference between str.isdigit() and str.isdecimal()
by Julien Palard 01 Dec '16

01 Dec '16

Julien Palard added the comment: “digits which do not form decimal radix forms” > “forming a form” seems a long way of saying very little. The difference seems a bit vague > I gather that digits not in the Unicode “decimal digit” category are often (always?) still decimal digits I expected them not to, but they often are representative of a base 10 value: >>> import sys >>> import unicodedata >>> chars = ''.join(map(chr, range(sys.maxunicode+1))) >>> decimals = ''.join(filter(str.isdecimal, chars)) >>> digits = ''.join(filter(str.isdigit, chars)) >>> non_decimal_digits = set(digits) - set(decimals) >>> from collections import Counter >>> Counter([unicodedata.digit(char) for char in non_decimal_digits]) Counter({1: 15, 2: 14, 3: 14, 4: 14, 5: 13, 6: 13, 7: 13, 8: 13, 9: 13, 0: 6}) But, note that there's one more in the range [1,4], it's the [Kharosthi](https://en.wikipedia.org/wiki/Kharosthi) numbers, they do not use base 10 but a notation reminiscent of Roman numerals. So here, clearly, all digits are not an notation for a base 10 value. > but primarily used for a symbolic or typographical meaning more than in a plain number, e.g. superscripts, subscripts and other fonts, added circles and other decorations. Which also can't be used to form a base 10 number. So here is another proposition for isdecimal, probably more human friendly: Return true if all characters in the string are decimal characters and there is at least one character, false otherwise. Decimal characters are those that can be used to form numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a decimal character is a character in the Unicode General Category "Nd". And here is another proposition for isdigit, probably friendlier too: Return true if all characters in the string are digits and there is at least one character, false otherwise. Digits include decimal characters and digits that need special handling, such as the compatibility superscript digits. This covers digits which cannot be used to form numbers in base 10, like the Kharosthi numbers. Formally, a digit is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26483> _______________________________________

1 0

[issue26483] docs unclear on difference between str.isdigit() and str.isdecimal()
by Martin Panter 30 Nov '16

30 Nov '16

Martin Panter added the comment: “digits which do not form decimal radix forms” I see you have taken this from a Unicode document, but “forming a form” seems a long way of saying very little. The difference seems a bit vague, but I gather that digits not in the Unicode “decimal digit” category are often (always?) still decimal digits, but primarily used for a symbolic or typographical meaning more than in a plain number, e.g. superscripts, subscripts and other fonts, added circles and other decorations. ---------- stage: needs patch -> patch review versions: +Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26483> _______________________________________

1 0