Mailman 3 June 2015 - docs

[issue24079] xml.etree.ElementTree.Element.text does not conform to the documentation
by Stefan Behnel June 5, 2015

June 5, 2015

Stefan Behnel added the comment: Looks good to me. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24079> _______________________________________

1 0

[issue23659] csv.register_dialect doc string
by Vladimir Ulupov June 5, 2015

June 5, 2015

New submission from Vladimir Ulupov: I use PyCharm. This IDE checks the signature functions. When I used the extra arguments to the function register_dialect - IDE reported error. This is what has generated IDE for this function. http://dumpz.org/1347592/ Apparently error here https://hg.python.org/cpython/file/44c1c0cbdc06/Modules/_csv.c#l1547 https://hg.python.org/cpython/file/c1abcbcfefab/Modules/_csv.c#l1590 https://docs.python.org/2/library/csv.html?highlight=csv#csv.register_diale… https://docs.python.org/3/library/csv.html?highlight=csv#csv.register_diale… ---------- assignee: docs@python components: Documentation messages: 238035 nosy: Vladimir Ulupov, docs@python priority: normal severity: normal status: open title: csv.register_dialect doc string versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23659> _______________________________________

6 11

[issue24148] 'cum' not a valid sort key for pstats.Stats.sort_stats
by ramiro June 5, 2015

June 5, 2015

New submission from ramiro: On the documentation page "The Python Profilers" https://docs.python.org/3.4/library/profile.html#instant-user-s-manual the following example is given: p.sort_stats('time', 'cum').print_stats(.5, 'init') This raises a KeyError, because 'cum' is not available as a sort key to pstats.Stats.sort_stats. As per the documentation of this method (https://docs.python.org/3.4/library/profile.html#the-stats-class) you can either use 'cumulative' or 'cumtime', which both work as expected. Since 'cumulative' is used a few examples earlier I suggest to use that for consistency. Tested with the following Python version: Python 3.4.3 on Ubuntu 15.04 ---------- assignee: docs@python components: Documentation messages: 242812 nosy: docs@python, ramiro priority: normal severity: normal status: open title: 'cum' not a valid sort key for pstats.Stats.sort_stats type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24148> _______________________________________

4 3

Python tutorial
by Richard Trahan June 3, 2015

June 3, 2015

I am a noob in Python (but not in programming), and am reading the tutorial. Generally it is well-written, but section 6.4 on packages is obscure. "Package" is not actually defined anywhere. The last two paragraphs of this section are unclear. The terms module, submodule, package, subpackage, item, and name are all very confusing. There is no comprehensible explanation of __init__.py and how it affects the search for modules. Missing from the tutorial is a description of the most-used string functions. The ones in the standard library are not the most common. Look at the Java String API to see many functions which are not found in the Python Standard Library in the tutorial. I would like to see a large section on this web site dealing with the issue of why almost nothing works as advertised in what is supposed to be a simple computer language. Getting a Python program to work requires numerous kludges found in countless blogs. For example, even on the first execution of a module, the garbage collection system will wipe out an image object before it is used in the very module in which it is created. I found a blog which says the fix is to save the image object to a widget variable There is no explanation of why this works. There are hundreds of tricks like that all over the Internet, which are not explained in the tutorial or any other official documentation. There are also installation problems. Why does Ubuntu install version 2.7 from its Software Center? If 3.3 is downloaded explicitly, it doesn't work with any version of IDLE or Spyder available on Ubuntu. These types of issues are very annoying to someone just trying to learn the language. There should be a section in the tutorial on all this.

1 0

[issue24079] xml.etree.ElementTree.Element.text does not conform to the documentation
by Martin Panter June 3, 2015

June 3, 2015

Martin Panter added the comment: Okay, here is a version with most of the wording reverted to Jérôme’s suggestion. I only left my itertext() example, and the grouping of text and tail together. If there are any more bits that are incorrect or unclear please identify them. ---------- Added file: http://bugs.python.org/file39606/etree-text.v2.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24079> _______________________________________

1 0

Re: [docs] xml.etree.ElementTree.Element.text does not conform to the documentation (issue 24079)
by vadmium+py＠gmail.com June 3, 2015

June 3, 2015

https://bugs.python.org/review/24079/diff/14986/Doc/library/xml.etree.eleme… File Doc/library/xml.etree.elementtree.rst (right): https://bugs.python.org/review/24079/diff/14986/Doc/library/xml.etree.eleme… Doc/library/xml.etree.elementtree.rst:657: and the next tag. The *tail* attribute holds any text between the On 2015/05/30 07:35:22, scoder wrote: > Not strictly true, e.g. "<tag />abc<next-tag/>" - is "abc" in text or tail here? Tail only, being equivalent to <tag></tag>abc<next-tag/>. Hopefully this is also illustrated by the <d/> tag in Jérôme’s example. > Also, I think the usual wording is "opening" and "closing" tag. Actually, I’m changing it to use “start tag”, but keeping “end tag”. These terms are used in other parts of the page, XML specifications, etc. https://bugs.python.org/review/24079/

1 0

Re: [docs] PEP 484 docs (issue 24272)
by guido＠python.org June 3, 2015

June 3, 2015

Thank you again! I have made a full pass this time. I should mention that I'm going on a long vacation starting this weekend so I may not be available to do another round of review. But I may be able to commit this if you address (most of) my feedback by Friday. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst File Doc/library/typing.rst (right): http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:31: Url = str Maybe use a more complex example, e.g. Vector = List[float] ? (It's okay if that's a forward reference to syntax that hasn't been explained yet.) http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:33: Callable Can you also document the special form Callable[..., <type>]? Here "..." is a literal ellipsis, and the meaning is "don't type-check the args" (it's described in the PEP). http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:59: from typing import Mapping, Set Unfortunately we renamed the ABC Set to AbstractSet, and Set refers to (the generic variant of) the concrete type 'set'. Maybe change the example to use Sequence, which is an ABC? (To clarify, the example with Set[Employee] works, but it isn't using an ABC.) http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:80: A user-defined class can be defined as a generic. "a generic" -> either "generic" or "a generic class". http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:84: from typing import TypeVar, Generic The example should also include "from logging import Logger". http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:103: self.logger.info('{}: {}'.format(self.name message)) Missing comma after self.name. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:118: be constrained:: The mention of "constrained" here dangles a bit -- there's no example immediately following of a constrained type variable. (I think it's different in the PEP.) http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:166: When the type of a value is object, the type checker will reject almost all I'd use `object`. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:173: Version and platform checking Drop this section. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:196: def foo(x: AnyStr, y: AnyStr = ...) -> AnyStr: ... There is no definition of AnyStr, so this dangles a bit. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:204: .. class:: Any(Final, metaclass=AnyMeta, _root=True) Don't mention the base classes. This also applies below. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:208: * Any object is an instance of Any. I'd use `Any` for all places where the word "Any" refers to the special object `Any`. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:229: '''Return a list containing n references to x.''' I strongly prefer """ for docstrings. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:237: of (str, str) -> str and (bytes, bytes) -> bytes. Also note You're slacking on the backticks here. :-) http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:242: issubclass(C, T) is true for any class C, and issubclass(str, A) Actually, issubclass() involving type variables or other special objects will probably start failing too in one of the next betas. Perhaps it's better to say something like "you shouldn't use these". http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:250: Type variables can be introspected. e.g.:: I prefer not to document this for now. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:258: .. class:: Union(Final, metaclass=UnionMeta, _root=True) Again, please don't list the base classes. (Same for every class below). http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:266: * None as an argument is a special case and is replaced by This is not unique to union -- this applies everywhere. So probably move it up ahead. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:285: * When two arguments have a subclass relationship, the least We're on thin ice with this bullet. I'd like to drop it. (The PEP doesn't say this.) http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:294: * Corollary: if Any is present it is the sole survivor, e.g.:: I'd remove "Corollary:" -- this is just another rule. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:298: * Similar for object:: I'd drop this too. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:302: * To cut a tie: `Union[object, Any] == Union[Any, object] == Any`. Drop this too. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:318: Tuple type; Tuple[X, Y] is the cross-product type of X and Y. I'd drop the "cross-product" concept -- it's very type-theoretic. I'd just say this is the type of a tuple of two items with the first item of type X and the second of type Y. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:324: To specify a variable-length tuple of homogeneous type, use `Sequence[T]`. The PEP actually also supports Tuple[t, ...]. (And I'd use a lowercase t because it doesn't have to be a type variable. Maybe use Tuple[int, ...] as an example. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:335: such function types are rarely used as callback types. But do add Callable[..., t] as a way to spell callable of any args returning t. Also note that plain Callable is equivalent to Callable[..., Any]. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:337: .. class:: Generic(metaclass=GenericMeta) This looks (mostly?) redundant with the earlier discussion of Generic. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:352: def lookup_name(mapping: Mapping, key: KT, default: VT) -> VT: Actually we changed our mind about this and you must write Mapping[KT, VT] here (essentially making this the same as the next example). http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:445: .. function:: get_type_hints(obj, globalns=None, localns=None) I prefer not to document globalns/localns at this time. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:453: .. warning:: Just drop this warning. http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newco… Doc/library/typing.rst:469: .. function:: overload(func) Consider leaving this out. http://bugs.python.org/review/24272/

1 0

[issue22725] improve documentation for enumerate() (built-in function)
by Van Ly June 2, 2015

June 2, 2015

New submission from Van Ly: The existing documentation is confusing. — improve wording as follows enumerate(sequence, start=0) Returns pairings of index into sequence[link to glossary.html#term-sequence] with the object at that index in the sequence. — wording as found in v.2.7.5 enumerate(sequence, start=0) Return an enumerate object. sequence must be a sequence, an iterator, or some other object which supports iteration. The next() method of the iterator returned by enumerate() returns a tuple containing a count (from start which defaults to 0) and the values obtained from iterating over sequence: ---------- assignee: docs@python components: Documentation messages: 229979 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: improve documentation for enumerate() (built-in function) type: enhancement versions: Python 2.7, Python 3.3, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22725> _______________________________________

9 31

Can't open IDLE (Python GUI) on Windows 7
by Tiffany Sara June 2, 2015

June 2, 2015

Hi, I downloaded Python 2.7 today on my Windows 7. I am able to open python via command line, but I can't open IDLE Python GUI at all. Whenever I double-click on the program nothing opens. I tried looking online for suggestions but I couldn't find anything applicable to Windows 7 64 bit. I am very new to coding, so I don't know how to solve this problem. Any help would be great. Thanks, Tiffany Saran

2 1

Mac -- Python 2.7.10 still is not using newer OpenSSL on new installs
by Kevin LaTona June 2, 2015

June 2, 2015

The current shipping Mac package for Python 2.7.10 installed on a OS X 10.8.5 machine currently still is reverting back and using Apple's older OpenSSL. I read in the readm.txt file that this problem was patched to load newer version of OpenSSL. I've been trying to compile source and all suggestions I have been able to find on the net of how to add newer openSSL to Python 2.7/x have failed as well. I can get Python to compile but have not been able to link that to newer OpenSSL. I am not sure if the new install is not overwriting some older file or the new linking is not working on the OS X version. Please let me know what I can do to fix this? Thanks -Kevin Last login: Mon Jun 1 21:56:59 on ttys000 $ python Python 2.7.10 (v2.7.10:15c95b7d81dc, May 23 2015, 09:33:12) [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin >>> import ssl >>> print (ssl.OPENSSL_VERSION) OpenSSL 0.9.8y 5 Feb 2013 >>>

1 0