Mailman 3 June 2015 - docs

Re: [docs] Feedback for awaitable coroutine documentation (issue 24439)
by vadmium+py＠gmail.com June 24, 2015

June 24, 2015

https://bugs.python.org/review/24439/diff/15143/Doc/library/types.rst File Doc/library/types.rst (right): https://bugs.python.org/review/24439/diff/15143/Doc/library/types.rst#newco… Doc/library/types.rst:293: it may not necessarily implement the :meth:`__await__` method. On 2015/06/23 18:51:10, Yury.Selivanov wrote: > Please take a look at my other patch: > http://bugs.python.org/review/24325/patch/15133/57450 > > Ideally we should combine the two I will include your changes in … [View More]

1 0

[issue12920] Inspect.getsource fails to get source of local classes
by Popa Claudiu June 24, 2015

June 24, 2015

New submission from Popa Claudiu <pcmanticore(a)gmail.com>: inspect.getsource called with a class defined in the same file fails with TypeError: <module '__main__' (built-in)> is a built-in class, although the documentation says that: "The argument may be a module, class, method, function, traceback, frame, or code object. The source code is returned as a single string." I think that should be specified in documentation that this function works only for objects living in a module.… [View More]

5 8

Re: [docs] Feedback for awaitable coroutine documentation (issue 24439)
by vadmium+py＠gmail.com June 23, 2015

June 23, 2015

http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst File Doc/library/asyncio-task.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/library/asyncio-task.rst… Doc/library/asyncio-task.rst:16: :func:`@asyncio.coroutine <asyncio.coroutine>`. This is mainly On 2015/06/23 18:51:10, Yury.Selivanov wrote: > I'd say that it's encouraged to use the decorator on generator-based coroutine > functions for documentation purposes *and* for compatibility … [View More]

1 0

Re: [docs] Feedback for awaitable coroutine documentation (issue 24439)
by yselivanov＠gmail.com June 23, 2015

June 23, 2015

Martin, Thanks for the update! My main concern with this version is about introducing the "native coroutine" terminology. While it was a necessary thing to do in PEP 492, I really doubt that we should use it in Python docs. http://bugs.python.org/review/24439/diff/15143/Doc/glossary.rst File Doc/glossary.rst (right): http://bugs.python.org/review/24439/diff/15143/Doc/glossary.rst#newcode181 Doc/glossary.rst:181: coroutine function` is defined with the :keyword:`async def` statement, … [View More]

1 0

Documentation for PEP 489 (issue 24458)
by ncoghlan＠gmail.com June 23, 2015

June 23, 2015

Sorry for the delay reviewing this - the beta release revealed some aspects of the async/await changes we thought could be deferred to 3.6 really needed to be addressed for 3.5 after all. Back on topic, I really like the revised structure for these docs. Mostly some minor comments regarding typos and formatting, one substantive question, but there's one substantive suggestion about providing some rationale for why we read the module name from the spec by default, and not from the C level … [View More]

1 0

Re: [docs] Feedback for awaitable coroutine documentation (issue 24439)
by vadmium+py＠gmail.com June 23, 2015

June 23, 2015

Reviewers: Yury.Selivanov, https://bugs.python.org/review/24439/diff/15090/Doc/library/asyncio-task.rst File Doc/library/asyncio-task.rst (right): https://bugs.python.org/review/24439/diff/15090/Doc/library/asyncio-task.rs… Doc/library/asyncio-task.rst:11: A :term:`coroutine` is :term:`generator` that follows certain conventions. For On 2015/06/22 20:23:12, Yury.Selivanov wrote: > Again, no need to reference "coroutine" term here. Coroutines in asyncio is a > bit broader thing than '… [View More]async def' coroutine objects defined in the glossary. In my upcoming patch I have reworded this so that the glossary reference is used in the context of native coroutines. > We need a separate sub-section for native coroutines though. So far, I have kept it all in the one section but expanded it to cover both using native Python coroutines and generator-based coroutines. https://bugs.python.org/review/24439/diff/15090/Doc/library/dis.rst File Doc/library/dis.rst (right): https://bugs.python.org/review/24439/diff/15090/Doc/library/dis.rst#newcode… Doc/library/dis.rst:516: returns ``o`` if ``o`` is a native coroutine object, or resolves On 2015/06/22 20:23:12, Yury.Selivanov wrote: > .. if ``o`` is a native or generator-based coroutine object .. Replacing with “native coroutine object or one derived from :func:`types.coroutine` ”, to avoid confusing with PEP 342 and asyncio generator-based coroutines. https://bugs.python.org/review/24439/diff/15090/Doc/library/types.rst File Doc/library/types.rst (right): https://bugs.python.org/review/24439/diff/15090/Doc/library/types.rst#newco… Doc/library/types.rst:283: compatible with native coroutines. On 2015/06/22 20:23:12, Yury.Selivanov wrote: > This bit was also updated, please rebase. I don’t think anything got changed here. Did you have anything in mind? I intend to add that the returned objects are awaitable, but do not implement __await__(). https://bugs.python.org/review/24439/diff/15090/Doc/reference/datamodel.rst File Doc/reference/datamodel.rst (right): https://bugs.python.org/review/24439/diff/15090/Doc/reference/datamodel.rst… Doc/reference/datamodel.rst:629: Native coroutine objects are similar to the objects returned by On 2015/06/22 20:23:12, Yury.Selivanov wrote: > Since we've merged issue 24400, I think we need to briefly document each of > those methods (send, close, throw) with references to generators docs for more > details. I’m thinking of putting a proper full explanation of each method in a new Native Coroutine Objects subsection near the bottom. Please review this at https://bugs.python.org/review/24439/ Affected files: Doc/glossary.rst Doc/howto/functional.rst Doc/library/asyncio-task.rst Doc/library/asyncio.rst Doc/library/collections.abc.rst Doc/library/dis.rst Doc/library/inspect.rst Doc/library/sys.rst Doc/library/types.rst Doc/reference/compound_stmts.rst Doc/reference/datamodel.rst Doc/reference/expressions.rst [View Less]

1 0

Feedback for awaitable coroutine documentation (issue 24439)
by yselivanov＠gmail.com June 22, 2015

June 22, 2015

http://bugs.python.org/review/24439/diff/15090/Doc/howto/functional.rst File Doc/howto/functional.rst (right): http://bugs.python.org/review/24439/diff/15090/Doc/howto/functional.rst#new… Doc/howto/functional.rst:611: a more generalized form of subroutines. I don't think we need a reference to the term here. Coroutines defined in the glossary section are what 'async def' functions return, not a generic definition. http://bugs.python.org/review/24439/diff/15090/Doc/library/asyncio-task.rst … [View More]

1 0

Re: [docs] urlparse() documentation does not account for default scheme (issue 23684)
by vadmium+py＠gmail.com June 21, 2015

June 21, 2015

Reviewers: berkerpeksag, http://bugs.python.org/review/23684/diff/14992/Doc/library/urllib.parse.rst File Doc/library/urllib.parse.rst (right): http://bugs.python.org/review/23684/diff/14992/Doc/library/urllib.parse.rst… Doc/library/urllib.parse.rst:95: | :attr:`scheme` | 0 | URL scheme specifier | *scheme* argument | On 2015/06/22 00:01:42, berkerpeksag wrote: > "argument" looks incorrect to me. Can this be "value of *scheme*", "*scheme* > parameter" or something else? … [View More]Yes “*scheme* parameter” would be good. Originally I though “argument” would be more correct, but I agree it feels strange when we are not talking about a concrete value. Demian suggested “value of *scheme*”, but I though this might sound like the attribute “scheme” defaults to itself. Please review this at http://bugs.python.org/review/23684/ Affected files: Doc/library/urllib.parse.rst Lib/test/test_urlparse.py # HG changeset patch # Parent 04162e06323f369c1468d2009b4d8ba6805a6b0c diff -r 04162e06323f Doc/library/urllib.parse.rst --- a/Doc/library/urllib.parse.rst Sun May 31 09:16:13 2015 +0300 +++ b/Doc/library/urllib.parse.rst Sun May 31 10:15:38 2015 +0000 @@ -76,13 +76,15 @@ ParseResult(scheme='', netloc='', path='help/Python.html', params='', query='', fragment='') - If the *scheme* argument is specified, it gives the default addressing - scheme, to be used only if the URL does not specify one. The default value for - this argument is the empty string. + The *scheme* argument gives the default addressing scheme, to be + used only if the URL does not specify one. It should be the same type + (text or bytes) as *urlstring*, except that the default value ``''`` is + always allowed, and is automatically converted to ``b''`` if appropriate. If the *allow_fragments* argument is false, fragment identifiers are not - recognized and parsed as part of the preceding component. The default value - for this argument is :const:`True`. + recognized. Instead, they are parsed as part of the path, parameters + or query component, and :attr:`fragment` is set to the empty string in + the return value. The return value is actually an instance of a subclass of :class:`tuple`. This class has the following additional read-only convenience attributes: @@ -90,7 +92,7 @@ +------------------+-------+--------------------------+----------------------+ | Attribute | Index | Value | Value if not present | +==================+=======+==========================+======================+ - | :attr:`scheme` | 0 | URL scheme specifier | empty string | + | :attr:`scheme` | 0 | URL scheme specifier | *scheme* argument | +------------------+-------+--------------------------+----------------------+ | :attr:`netloc` | 1 | Network location part | empty string | +------------------+-------+--------------------------+----------------------+ @@ -206,7 +208,7 @@ +------------------+-------+-------------------------+----------------------+ | Attribute | Index | Value | Value if not present | +==================+=======+=========================+======================+ - | :attr:`scheme` | 0 | URL scheme specifier | empty string | + | :attr:`scheme` | 0 | URL scheme specifier | *scheme* argument | +------------------+-------+-------------------------+----------------------+ | :attr:`netloc` | 1 | Network location part | empty string | +------------------+-------+-------------------------+----------------------+ diff -r 04162e06323f Lib/test/test_urlparse.py --- a/Lib/test/test_urlparse.py Sun May 31 09:16:13 2015 +0300 +++ b/Lib/test/test_urlparse.py Sun May 31 10:15:38 2015 +0000 @@ -686,6 +686,47 @@ self.assertEqual(urllib.parse.urlparse(b"x-newscheme://foo.com/stuff?query"), (b'x-newscheme', b'foo.com', b'/stuff', b'', b'query', b'')) + def test_default_scheme(self): + # Exercise the scheme parameter of urlparse() and urlsplit() + for func in (urllib.parse.urlparse, urllib.parse.urlsplit): + with self.subTest(func): + result = func("http://example.net/", "ftp") + self.assertEqual(result.scheme, "http") + result = func(b"http://example.net/", b"ftp") + self.assertEqual(result.scheme, b"http") + self.assertEqual(func("path", "ftp").scheme, "ftp") + self.assertEqual(func("path", scheme="ftp").scheme, "ftp") + self.assertEqual(func(b"path", scheme=b"ftp").scheme, b"ftp") + self.assertEqual(func("path").scheme, "") + self.assertEqual(func(b"path").scheme, b"") + self.assertEqual(func(b"path", "").scheme, b"") + + def test_parse_fragments(self): + # Exercise the allow_fragments parameter of urlparse() and urlsplit() + tests = ( + ("http:#frag", "path"), + ("//example.net#frag", "path"), + ("index.html#frag", "path"), + (";a=b#frag", "params"), + ("?a=b#frag", "query"), + ("#frag", "path"), + ) + for url, attr in tests: + for func in (urllib.parse.urlparse, urllib.parse.urlsplit): + if attr == "params" and func is urllib.parse.urlsplit: + attr = "path" + with self.subTest(url=url, func=func): + result = func(url, allow_fragments=False) + self.assertEqual(result.fragment, "") + self.assertTrue(getattr(result, attr).endswith("#frag")) + self.assertEqual(func(url, "", False).fragment, "") + + result = func(url, allow_fragments=True) + self.assertEqual(result.fragment, "frag") + self.assertFalse(getattr(result, attr).endswith("frag")) + self.assertEqual(func(url, "", True).fragment, "frag") + self.assertEqual(func(url).fragment, "frag") + def test_mixed_types_rejected(self): # Several functions that process either strings or ASCII encoded bytes # accept multiple arguments. Check they reject mixed type input [View Less]

1 0

urlparse() documentation does not account for default scheme (issue 23684)
by berker.peksag＠gmail.com June 21, 2015

June 21, 2015

The patch looks good to me. You don't need to send another patch. I can do the last modifications and apply it. Thanks! http://bugs.python.org/review/23684/diff/14992/Doc/library/urllib.parse.rst File Doc/library/urllib.parse.rst (right): http://bugs.python.org/review/23684/diff/14992/Doc/library/urllib.parse.rst… Doc/library/urllib.parse.rst:95: | :attr:`scheme` | 0 | URL scheme specifier | *scheme* argument | "argument" looks incorrect to me. Can this be "value of *scheme*", … [View More]

1 0