Mailman 3 September 2013 - docs

[issue18933] Add link to source code in logging documentation
by Jonathan Frere 05 Sep '13

05 Sep '13

New submission from Jonathan Frere: The logging module documentation is probably best accompanied by the source that it is meant to be documenting. Could a link to either the package directory (http://hg.python.org/cpython/file/2.7/Lib/logging/) or the __init__.py file in that directory (http://hg.python.org/cpython/file/2.7/Lib/logging/__init__.py), I'd argue the __init__.py file. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 197000 nosy: Johz, docs@python, vinay.sajip priority: normal severity: normal status: open title: Add link to source code in logging documentation type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18933> _______________________________________

3 3

[issue18912] Intendation issue in example code in itertools.count documentation
by Jeroen Van Goey 05 Sep '13

05 Sep '13

New submission from Jeroen Van Goey: The sample code in the itertools.count documentation should be indented by 4 spaces. For 2.7.4: lines 3429 till 3432 in http://hg.python.org/releasing/2.7.4/file/026ee0057e2d/Modules/itertoolsmod… For 3.4.0a1: lines 3981 till 3984 in http://hg.python.org/releasing/py3.4.0a1/file/edc668a667ad/Modules/itertool… Also, the example code uses the arguments 'firstval' and 'step' whereas the documentation of the function itself uses the arguments 'start' and 'step'. Maybe better be consistent and use as first argument 'start' in both cases? ---------- assignee: docs@python components: Documentation hgrepos: 207 messages: 196826 nosy: docs@python, jeroen-vangoey priority: normal severity: normal status: open title: Intendation issue in example code in itertools.count documentation type: enhancement versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18912> _______________________________________

5 8

[issue18928] Remove misleading documentation for random.shuffle
by David Benbennick 05 Sep '13

05 Sep '13

New submission from David Benbennick: Since Python 2.1 [1], when random.shuffle was added, the documentation has said: """Note that for even rather small len(x), the total number of permutations of x is larger than the period of most random number generators; this implies that most permutations of a long sequence can never be generated.""" This comment is incorrect and misleading. In fact, I claim that shuffle can produce "all" permutations for any representable sequence. To shuffle a sequence of length N requires log(N!) ~ N * log(N/e) bits of randomness [2]. The random module provides a generator with "a period of 2**19937-1", meaning you can get 2**19937 bits of randomness out of it before it starts repeating. All of which is to say that any representable sequence, say N < 2**50, will need no more than 2**60 bits of randomness to shuffle. That is well within the period of the random number generator. Attached is a patch that deletes the comment. An illustration of this misconception is at [3]. 1: http://docs.python.org/release/2.1/lib/module-random.html 2: https://en.wikipedia.org/wiki/Factorial#Rate_of_growth_and_approximations_f… 3: http://stackoverflow.com/questions/3062741/maximal-length-of-list-to-shuffl… ---------- assignee: docs@python components: Documentation files: mywork.patch keywords: patch messages: 196971 nosy: dbenbenn, docs@python priority: normal severity: normal status: open title: Remove misleading documentation for random.shuffle Added file: http://bugs.python.org/file31593/mywork.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18928> _______________________________________

3 5

[issue18914] Python docs link to terrible outsi
by Brian Mingus 03 Sep '13

03 Sep '13

New submission from Brian Mingus: The python documentation links to an outside website for info and examples on http basic auth. This documentation is terrible and confusing. The link should be removed, and user's should be advised to use the Requests library. # this example is from http://www.voidspace.org.uk/python/articles/authentication.shtml # which is linked to by the official python docs http://docs.python.org/2/howto/urllib2.html import urllib2 theurl = 'http://www.someserver.com/toplevelurl/somepage.htm' username = 'johnny' password = 'XXXXXX' # a great password passman = urllib2.HTTPPasswordMgrWithDefaultRealm() # this creates a password manager passman.add_password(None, theurl, username, password) # because we have put None at the start it will always # use this username/password combination for urls # for which `theurl` is a super-url authhandler = urllib2.HTTPBasicAuthHandler(passman) # create the AuthHandler opener = urllib2.build_opener(authhandler) urllib2.install_opener(opener) # All calls to urllib2.urlopen will now use our handler # Make sure not to include the protocol in with the URL, or # HTTPPasswordMgrWithDefaultRealm will be very confused. # You must (of course) use it when fetching the page though. pagehandle = urllib2.urlopen(theurl) # authentication is now handled automatically for us ---------- assignee: docs@python components: Documentation messages: 196854 nosy: docs@python, mingus priority: normal severity: normal status: open title: Python docs link to terrible outsi versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________

5 7

Cpython sys.version parser in platform.py bug and resolution?
by Zerbe, Brandon 03 Sep '13

03 Sep '13

To whom this may concern; I am contacting you in the hope that I may provide help to others by addressing a possible, very small bug (assuming I diagnosed and solved the issue correctly). No need to contact me since I consider my solution as sufficient. I ran into an exception today from a program running plaftorm.py using python version 2.7.5. Here is the code in platform.py that produced the exception (line 1454) match = _sys_version_parser.match(sys_version) if match is None: raise ValueError( 'failed to parse CPython sys.version: %s' % repr(sys_version)) This results from the following regular expression: _sys_version_parser = re.compile( r'([\w.+]+)\s*' '\|[^|]*\|\s*' # version extra '\(#?([^,]+),\s*([\w ]+),\s*([\w :]+)\)\s*' '\[([^\]]+)\]?') At least on my computer, CPython does not have "version extra". So I simply removed the second part of the regular expression and put it into a new object: _cpython_sys_version_parser = re.compile( r'([\w.+]+)\s*' '\(#?([^,]+),\s*([\w ]+),\s*([\w :]+)\)\s*' '\[([^\]]+)\]?') I then called this object for cpython, and it appears to have worked (fingers crossed). Thanks, Brandon Zerbe

1 0

Newcomer to document maintenance - regarding @staticmethod
by bob gailer 03 Sep '13

03 Sep '13

I'd like a stab at submitting a fix. The process seems daunting, and I seek some hand-holding. < Problem: Chapter 2 Built-in Functions - staticmethod() "The @staticmethod form is a function /decorator/ <../glossary.html#term-decorator> – see the description of function definitions in /Function definitions/ <../reference/compound_stmts.html#function> for details." < Clearer: Example of applying staticmethod() using the decorator idiom: existing code example See description of /decorator /in Function definitions. <../reference/compound_stmts.html#function> < link /decorator / to the paragraph starting A function definition may be wrapped by one or more /decorator/ <../glossary.html#term-decorator> expressions". < Precede that paragraph with *Decorators*. < I also question the value of /decorator/ <../glossary.html#term-decorator> expressions linking to the glossary, as the glossary entry does not add to the explanation. -- Bob Gailer 919-636-4239 Chapel Hill NC

1 0

socket.sethostname() error type mistake
by Simeon S 03 Sep '13

03 Sep '13

Hi, I believe there is a mistake in the type of error raised by socket.sethostname(). The documentation says the error returned is OSError. Here is what I get (3.3.2): [16:39:sys] % python3 Python 3.3.2 (default, Aug 5 2013, 11:52:10) [GCC 4.5.3] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import socket as s >>> s.sethostname('bla') Traceback (most recent call last): File "<stdin>", line 1, in <module> PermissionError: [Errno 1] Operation not permitted Simeon

2 1

defaults redirects bit confusing
by Luca Sbardella 03 Sep '13

03 Sep '13

Hi, just noticed that http://docs.python.org/ redirect to http://docs.python.org/3/ good but http://docs.python.org/library/ redirect to http://docs.python.org/2/library/ not good if not confusing am I missing something? Regards

2 1

[issue18553] os.isatty() is not Unix only
by Andrew Svetlov 03 Sep '13

03 Sep '13

Andrew Svetlov added the comment: Agree ---------- nosy: +asvetlov _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18553> _______________________________________

1 0

A more concise example for OrederedEnum
by אלעזר 03 Sep '13

03 Sep '13

Instead of implementing 4 comparison methods, I suggest using total_ordering: >>> from functools import total_ordering >>> @total_ordering ... class OrderedEnum(Enum): ... def __gt__(self, other): ... if self.__class__ is other.__class__: ... return self.value > other.value ... return NotImplemented ... I believe the reader needn't be famiiar with total_ordering() to understand what's going on here. elazar

1 0