Mailman 3 December 2016 - docs

[issue28917] Docs: Add missing protocol to pickle
by Anand Reddy Pandikunta Dec. 9, 2016

Dec. 9, 2016

New submission from Anand Reddy Pandikunta: In Python 2.7, it is documented. It is missing in Python 3 documentation. ---------- assignee: docs@python components: Documentation files: docs_pickle_add_missing_protocol.patch keywords: patch messages: 282764 nosy: ChillarAnand, abz64, docs@python, r.david.murray priority: normal severity: normal status: open title: Docs: Add missing protocol to pickle type: enhancement versions: Python 3.7 Added file: http://bugs.python.org/file45810/docs_pickle_add_missing_protocol.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28917> _______________________________________

2 2

Re: [docs] UUID docs should say how to get "standard form" (issue 26267)
by ammar＠ammaraskar.com Dec. 9, 2016

Dec. 9, 2016

On 2016/09/11 09:12:18, berkerpeksag wrote: > https://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst > File Doc/library/uuid.rst (right): > > https://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst#newcod… > Doc/library/uuid.rst:56: .. describe:: uuid1 == uuid2 > On 2016/08/06 05:20:17, ammar2 wrote: > > On 2016/08/03 10:09:25, berkerpeksag wrote: > > > Same as above. See datetime or decimal documentations for an example of how > to > > > document comparison operations. > > > > So datetime takes the approach of documenting operators in a table (presumably > > because it has a lot of ops) > > https://docs.python.org/3/library/datetime.html#datetime.date.day > > > > decimal seems to do it in this way > > https://docs.python.org/3/library/decimal.html#decimal.Decimal.compare > > > > The style I used here is from > > https://docs.python.org/3/library/stdtypes.html#set but now that I look at it, > > within the stdtypes there's also the datetime style operator documentation for > > numbers. > > > https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-com… > > > > Is there a preferred style for documenting operators? Which one should I use > > here? > > > > (apparently I forgot to click the publish button on Rietveld, I wrote this day > > before yesterday) > > Sorry, I wasn't very clear in my earlier message. I was referring to the > following paragraph in datetime documentation: > > Comparisons of timedelta objects are supported with the timedelta object > representing the smaller duration considered to be the smaller timedelta. In > order to stop mixed-type comparisons from falling back to the default comparison > by object address, when a timedelta object is compared to an object of a > different type, TypeError is raised unless the comparison is == or !=. The > latter cases return False or True, respectively. > > https://docs.python.org/3/library/datetime.html#timedelta-objects > > In other words, instead of using too much markup, it would be nice to document > that it supports comparison operators in prose. I've updated it so the comparison operators are explain in prose but there's still markup for the str() operator. http://bugs.python.org/review/26267/

1 0

[issue26483] docs unclear on difference between str.isdigit() and str.isdecimal()
by Julien Palard Dec. 7, 2016

Dec. 7, 2016

Changes by Julien Palard <julien+python(a)palard.fr>: Added file: http://bugs.python.org/file45793/issue26483.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26483> _______________________________________

1 0

[issue28860] Fixed all the doctest failures in Doc/library/configparser.rst
by Marco Buttu Dec. 7, 2016

Dec. 7, 2016

New submission from Marco Buttu: With Python 3.7.0a0 and sphinx-build 1.4.9, this was the result before applying the patch: Doctest summary =============== 80 tests 8 failures in tests 0 failures in setup code 0 failures in cleanup code build finished with problems, 139 warnings. After applaying the patch there are 0 failures in 84 tests. All the doctests also pass with Python 3.6 and 3.5. I skipped three tests (doctest: +SKIP) because their output is random (iterating over dictionary keys). ---------- assignee: docs@python components: Documentation files: configparser.patch keywords: patch messages: 282258 nosy: docs@python, marco.buttu priority: normal severity: normal status: open title: Fixed all the doctest failures in Doc/library/configparser.rst type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45733/configparser.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28860> _______________________________________

4 7

[issue28863] Doc/includes/*.py files and doctests
by Marco Buttu Dec. 7, 2016

Dec. 7, 2016

New submission from Marco Buttu: In the Doc/includes directory, some of the *.py file names have a dash character. For instance: Doc/includes/tzinfo-examples.py. I am trying to make all of the code examples pass the doctests, and I usually need to import from these files some code. Importing from these modules also allow us to test them, and I think that is important because their code is included in the documentation. There are two problems: 1) I can not directly import them, because of the - character, so I have to use __import__('file-name') and write other ugly tricks. I can import them in the setuptests, so the reader will not see these imports, but it is still ugly, and in addition the code examples will be not complete, and the reader will not be able to try the code 2) the dash in the file names is un-pythonic. As the PEP 0008 says, the preferred way is to use underscores: "Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability." In conclusion, I propose to change the Doc/includes/*.py file names, replacing the dash character with an underscore. If you agree, I will do it step by step: I will change each file name only when I will work with the related documentation and code examples. PS. To include these files in the code examples, I also need to add the Doc/includes directory to the sys.path (in conf.py). ---------- assignee: docs@python components: Documentation messages: 282307 nosy: docs@python, marco.buttu priority: normal severity: normal status: open title: Doc/includes/*.py files and doctests type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28863> _______________________________________

1 2

[issue28895] Two suggestions for windows.html
by Mark Summerfield Dec. 7, 2016

Dec. 7, 2016

New submission from Mark Summerfield: This document is v. useful for Windows Python users: https://docs.python.org/dev/using/windows.html However, I think it could be improved as follows: (1) Explain which Python installer to get (since there are so many)! Even a "get the Windows x86 executable installer if you just want it now!". Alternatively, the https://www.python.org/downloads/windows/ page could begine with a brief explanation of the differences. (2) Explain the trade-offs between Admin & User install & the effect this has on using pip (e.g., an Admin install may require pip to be used in an Admin console or to be used with the --user option). ---------- assignee: docs@python components: Documentation messages: 282625 nosy: docs@python, mark priority: normal severity: normal status: open title: Two suggestions for windows.html type: enhancement versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28895> _______________________________________

2 1

[issue28886] Move deprecated abc module decorators to separate section in docs
by Serhiy Storchaka Dec. 7, 2016

Dec. 7, 2016

Changes by Serhiy Storchaka <storchaka+cpython(a)gmail.com>: ---------- nosy: -serhiy.storchaka _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28886> _______________________________________

1 0

[issue28886] Move deprecated abc module decorators to separate section in docs
by Nick Coghlan Dec. 7, 2016

Dec. 7, 2016

Nick Coghlan added the comment: Right, these are in the "Don't use them in new code, but we have absolutely no plans to actually remove them" documentation-only category of deprecation warning. However, I'm converting this to a documentation enhancement request, as the documentation could make that status clearer by moving them to a separate "Legacy builtin decorator subclasses" section at the end of https://docs.python.org/3/library/abc.html Then that section can *start* with the information on simply applying the builtin decorators on top of the abc.abstractproperty() decorator, before moving on to document the available subclasses. ---------- assignee: -> docs@python components: +Documentation -Library (Lib) nosy: +docs@python stage: -> needs patch title: Deprecated abstract base class (abc) decorators do not raise DeprecationWarning -> Move deprecated abc module decorators to separate section in docs type: behavior -> enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28886> _______________________________________

1 0

[issue28890] logging.handlers: Document that QueueListener is a daemon thread
by Julien Castiaux Dec. 6, 2016

Dec. 6, 2016

Changes by Julien Castiaux <julien.castiaux(a)gmail.com>: ---------- assignee: docs@python components: Documentation nosy: Julien Castiaux, docs@python priority: normal severity: normal status: open title: logging.handlers: Document that QueueListener is a daemon thread type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28890> _______________________________________

1 0

confusing docs for plistlib - how to use 'dump()'
by Mark Dec. 6, 2016

Dec. 6, 2016

Hi there - This regards the page for plistlib: https://docs.python.org/dev/library/plistlib.html#plistlib.dumps <https://docs.python.org/dev/library/plistlib.html#plistlib.dumps> I ran in to this problem described here: http://technology.siprep.org/how-to-read-from-and-write-to-plist-files-usin… <http://technology.siprep.org/how-to-read-from-and-write-to-plist-files-usin…> It’s just not clear in the docs how to use ‘dump’ - and the only way I could get a plist to be created is to use the deprecated plistlib.writePlist function. Does it have to be imported from some other module? Mark

2 1