Mailman 3 June 2013 - docs

Re: [docs] Code, test, and doc review for PEP-0435 Enum (issue 17947)
by ethan＠stoneleaf.us 10 Jun '13

10 Jun '13

http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst File Doc/library/enum.rst (right): http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode60 Doc/library/enum.rst:60: Enums also have a property that contains just their item name:: Fixed this one and the other further down. http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:314: >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__) Moved, and reworded: Pickling enums created with the functional API can be tricky as frame stack implementation details are used to try and figure out which module the enumeration is being created in (e.g. it will fail if you use a utility function in separate module, and also may not work on IronPython or Jython). The solution is to specify the module name explicitly as follows:: http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:337: A variation of :class:`Enum` is proposed which is also a subclass of Done. http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode4… Doc/library/enum.rst:423: One frequent request is to not have to specify values for enum members:: Major rewrite: Interesting examples ==================== While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of use-cases, they cannot cover them all. Here are recipes for some different types of enumerations that can be used directly, or as examples for creating one's own. AutoNumber ---------- Avoids having to specify the value for each enumeration member:: . . . UniqueEnum ---------- Raises an error if a duplicate member name is found instead of creating an alias:: . . . OrderedEnum ----------- An ordered enumeration that is not based on :class:`IntEnum` and so maintains the normal :class:`Enum` invariants (such as not being comparable to other enumerations):: . . . Planet ------ If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member will be passed to those methods:: http://bugs.python.org/review/17947/diff/8339/Lib/test/test_enum.py File Lib/test/test_enum.py (right): http://bugs.python.org/review/17947/diff/8339/Lib/test/test_enum.py#newcode… Lib/test/test_enum.py:474: _reserved_ = 0 Removed. http://bugs.python.org/review/17947/

1 0

comments in documentation misprint
by Ruslan Baratov 10 Jun '13

10 Jun '13

Hello, I think I've found misprint in this page: http://docs.python.org/3/tutorial/introduction.html >>> word = 'Python' >>>word[0:2] # characters from position 0 (included) to 2 (excluded) 'Py' >>>word[2:5] # characters from position 2 (included) to 4 (excluded) 'tho' I think it should be: >>>word[2:5] # characters from position 2 (included) to 4 (included) 'tho' or >>>word[2:5] # characters from position 2 (included) to 5 (excluded) 'tho'

1 0

Re: [docs] Code, test, and doc review for PEP-0435 Enum (issue 17947)
by zachary.ware＠gmail.com 10 Jun '13

10 Jun '13

A few nitpicks and a suggestion. Everything else looks good to me. http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst File Doc/library/enum.rst (right): http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode60 Doc/library/enum.rst:60: Enums also have a property that contains just their item name:: Conflict with the note on nomenclature above; should be 'Enum members ...'. http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:314: >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__) This bit about pickling should be at the end of this section (just as the 'module' argument is last in the call). http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:337: A variation of :class:`Enum` is proposed which is also a subclass of s/proposed/provided/ http://bugs.python.org/review/17947/diff/8339/Doc/library/enum.rst#newcode4… Doc/library/enum.rst:423: One frequent request is to not have to specify values for enum members:: The obvious thing that comes to mind when reading "One frequent request" or "Some have asked...", etc., is "Then why are these not provided in the module?" I wonder if it might be better to wrap these examples up into a demo file for Tools/demo, and shorten this section to "Some interesting Enum subclasses can be found in the Tools/demo folder of your Python installation or source distribution." Alternately, I'd advise finding a different wording, though I unfortunately can't come up with any myself. http://bugs.python.org/review/17947/diff/8339/Lib/test/test_enum.py File Lib/test/test_enum.py (right): http://bugs.python.org/review/17947/diff/8339/Lib/test/test_enum.py#newcode… Lib/test/test_enum.py:474: _reserved_ = 0 This test is covered by test_invalid_names above. http://bugs.python.org/review/17947/

1 0

bug find in the documention
by aurelien＠replicant.io 10 Jun '13

10 Jun '13

Hi, It seems there is a bug in the documentation search tool bar. It asked me to activate javascript in my web browser, but i don't wish to send information. Please can you respect my privacy ? CC: prism liberty fuckers and nytimes ;-) -- Aurélien DESBRIÈRES Run free! Run GNU.ORG

1 0

Documentation manual suggestion
by Howard Small 09 Jun '13

09 Jun '13

I'm still relatively new to Python, and find myself frequently referring to the documentation manual. Would it be possible to add a bookmark feature so that I don't have repeat searching an item that I might want to reference again? On a larger scope and greater undertaking, it would be nice to see more code snippets in the manual. For a newbee like me the explanation of feature can often be a little too abstract to understand.

1 0

Re: [docs] Code, test, and doc review for PEP-0435 Enum (issue 17947)
by ethan＠stoneleaf.us 09 Jun '13

09 Jun '13

I'll try to have the changes in place later tonight; otherwise it will be tomorrow. http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst File Doc/library/enum.rst (right): http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:240: of *_sunder_* names, *__dunder__* names, and descriptors; methods are Ah, yes. _sunder_names_ are completely forbidden, __dunder_names__ are only forbidden from being enum members. I'll clarify. http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:245: methods. I'll add something. http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:260: But this is allowed:: I'll see what I can dream up. :) http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:280: A variation of :class:`Enum` is proposed which is also a subclass of :class:`int`. Done. http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:331: Other derived enumerations Will do. http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:340: This demonstrates how similar derived enumerations can be defined, for example Done. http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode4… Doc/library/enum.rst:443: ... ) Done. http://bugs.python.org/review/17947/diff/8332/Lib/enum.py File Lib/enum.py (right): http://bugs.python.org/review/17947/diff/8332/Lib/enum.py#newcode42 Lib/enum.py:42: """Returns True if a sunder name, False otherwise.""" Done. http://bugs.python.org/review/17947/

1 0

[issue18126] Update links to NumPy resources in documentation
by Yury V. Zaytsev 09 Jun '13

09 Jun '13

New submission from Yury V. Zaytsev: Hi, The links to NumPy sites and documentation are outdated. I replaced them with www.numpy.org, and also the canonical location for documentation (docs.scipy.org). I removed the explicit mention of the PDF file, because the documentation has been split in several guides, so I think it no longer makes sense, and it's better to link docs.scipy.org instead. Thanks! ---------- assignee: docs@python components: Documentation files: doc-numpy.patch keywords: patch messages: 190543 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, zaytsev priority: normal severity: normal status: open title: Update links to NumPy resources in documentation type: enhancement Added file: http://bugs.python.org/file30455/doc-numpy.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18126> _______________________________________

3 2

Re: [docs] Code, test, and doc review for PEP-0435 Enum (issue 17947)
by eliben＠gmail.com 09 Jun '13

09 Jun '13

http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst File Doc/library/enum.rst (right): http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:240: of *_sunder_* names, *__dunder__* names, and descriptors; methods are The specific rules are not well-enough defined. sunder names are forbidden, dunders are not - is this explained elsewhere? http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:245: methods. This needs some more explanation and/or example, perhaps somewhere in the end in "advanced customization" http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:260: But this is allowed:: Can this have a sensical example? (like, some simple example of where this actually makes sense) http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode2… Doc/library/enum.rst:280: A variation of :class:`Enum` is proposed which is also a subclass of :class:`int`. 80 col http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:331: Other derived enumerations I think this should be merged somehow with the "interesting examples", perhaps in a higher-level header: "Creating custom enumerations" with some dry explanation of the semantics, followed by examples. And this should definitely be the last section of the document :-) http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode3… Doc/library/enum.rst:340: This demonstrates how similar derived enumerations can be defined, for example ; instead of , after "defined" ? http://bugs.python.org/review/17947/diff/8332/Doc/library/enum.rst#newcode4… Doc/library/enum.rst:443: ... ) just append this to the previous line http://bugs.python.org/review/17947/diff/8332/Lib/enum.py File Lib/enum.py (right): http://bugs.python.org/review/17947/diff/8332/Lib/enum.py#newcode42 Lib/enum.py:42: """Returns True if a sunder name, False otherwise.""" Unlike "dunder", "sunder" has no historical meaning for python programmers. I suggest a more consistent documentation then, like: "Returns True if a __dunder__ name, False otherwise" "Returns True if a _sunder_ name, False otherwise" http://bugs.python.org/review/17947/

1 0

minor typo in http://docs.python.org/2/library/gzip.html
by Peter A. H. Peterson 07 Jun '13

07 Jun '13

Hi, Under the class gzip.GzipFile documentation, the text reads: "When fileobj is not None, the filename argument is only used to be included in the gzip file header, which may includes the original filename of the uncompressed file." It says "which may includes the original filename" which should either read: "which may include the original filename" ...or... "which includes the original filename" I would also suggest that "the filename argument is only used to be included in the gzip file header" should be changed to "is only used in the gzip file header" ...or... "is only included in the gzip file header" It seems to me that the implication is that the gzip file header *may* include the filename but is not required to do so. If that is the case, I would suggest that the text read: "When fileobj is not None, the filename argument is only used in the gzip file header, which may include the original filename of the uncompressed file." Thanks for all your hard work, Sincerely, Peter -- Peter A. H. Peterson Graduate Student Researcher Laboratory for Advanced Systems Research University of California, Los Angeles

1 0

[issue18146] Document miss, Stats objects has no method called "print_results"
by hanks 06 Jun '13

06 Jun '13

New submission from hanks: link: http://docs.python.org/2/library/profile.html The example in this page: import cProfile, pstats, io pr = cProfile.Profile() pr.enable() ... do something ... pr.disable() s = io.StringIO() ps = pstats.Stats(pr, stream=s) ps.print_results() # actually Stats objects has no method called "print_results" ---------- assignee: docs@python components: Documentation messages: 190705 nosy: docs@python, hanks priority: normal severity: normal status: open title: Document miss, Stats objects has no method called "print_results" type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18146> _______________________________________

3 3