Mailman 3 September 2018 - docs

[issue34487] enum _sunder_ names mix metaclass and enum class attributes
by Gerrit Holl Sept. 10, 2018

Sept. 10, 2018

New submission from Gerrit Holl <gerrit.holl(a)gmail.com>: In the [`enum` module](https://docs.python.org/3/library/enum.html#supported-sunder-names) documentation, some of the `_sunder_` names are on `EnumMeta`, whereas others are on the produced `Enum` class: > 8.13.15.3.2. Supported `_sunder_` names > * `_name_` – name of the member > * `_value_` – value of the member; can be set / modified in __new__ > * `_missing_` – a lookup function used when a value is not found; may be overridden > * `_ignore_` – a list of names, either as a list() or a str(), that will not be transformed into members, and will be removed from the final class > * `_order_` – used in Python 2/3 code to ensure member order is consistent (class attribute, removed during class creation) > * `_generate_next_value_` – used by the Functional API and by auto to get an appropriate value for an enum member; may be overridden Experimentally, it appears `_name_` and `_value_` are on the `Enum` class, whereas the others are all on the `EnumMeta` class: In [272]: class Test(enum.Enum): a = 0 In [273]: Test.a._name_ Out[273]: 'a' In [274]: Test._name --------------------------------------------------------------------------- AttributeError Traceback (most recent call last) <ipython-input-274-8d4f758e0fb7> in <module>() ----> 1 Test._name /group_workspaces/cems2/fiduceo/Users/gholl/anaconda3/envs/FCDR37a/lib/python3.7/enum.py in __getattr__(cls, name) 344 return cls._member_map_[name] 345 except KeyError: --> 346 raise AttributeError(name) from None 347 348 def __getitem__(cls, name): AttributeError: _name In [275]: Test.a._value_ Out[275]: 0 In [276]: Test._value --------------------------------------------------------------------------- AttributeError Traceback (most recent call last) <ipython-input-276-a1cd5032d83d> in <module>() ----> 1 Test._value /group_workspaces/cems2/fiduceo/Users/gholl/anaconda3/envs/FCDR37a/lib/python3.7/enum.py in __getattr__(cls, name) 344 return cls._member_map_[name] 345 except KeyError: --> 346 raise AttributeError(name) from None 347 348 def __getitem__(cls, name): AttributeError: _value In [277]: Test.a._missing_ Out[277]: <bound method Enum._missing_ of <enum 'Test'>> In [278]: Test._missing_ Out[278]: <bound method Enum._missing_ of <enum 'Test'>> This is not clear from the documentation. ---------- assignee: docs@python components: Documentation messages: 324003 nosy: Gerrit.Holl, docs@python priority: normal severity: normal status: open title: enum _sunder_ names mix metaclass and enum class attributes versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34487> _______________________________________

4 4

[issue34580] sqlite doc: clarify the scope of the context manager
by Daniel Jakots Sept. 10, 2018

Sept. 10, 2018

Daniel Jakots <bpo(a)chown.me> added the comment: LGTM ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34580> _______________________________________

1 0

[issue34617] socket.recvfrom(): docs should warn about packet truncation when bufsize is insufficient
by Anees Ahmed Sept. 9, 2018

Sept. 9, 2018

New submission from Anees Ahmed <aneesahmedpro(a)gmail.com>: When one is receiving UDP packets (socket.SOCK_DGRAM) using: socket.recvfrom(bufsize, flags) the UDP packet payload is truncated if it was too big to fit into the buffer (decided by `bufsize` here). This is documented in Linux Docs: All receive operations return only one packet. When the packet is smaller than the passed buffer, only that much data is returned; when it is bigger, the packet is truncated and the MSG_TRUNC flag is set. MSG_WAITALL is not supported. Source: http://man7.org/linux/man-pages/man7/udp.7.html This is also documented in Windows Docs: For message-oriented sockets, data is extracted from the first enqueued message, up to the size of the buffer specified. If the datagram or message is larger than the buffer specified, the buffer is filled with the first part of the datagram, and recvfrom generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost. For UDP if the packet received contains no data (empty), the return value from the recvfrom function function is zero. Source: https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-r… ** PYTHON DOCS DO NOT WARN ABOUT THIS AT ALL !!! ** The relevant portion of Python Docs is here: https://docs.python.org/3.7/library/socket.html#socket.socket.recvfrom I, not knowing this simple fact when I started socket programming today, wasted half an hour finding out what was wrong. This is a very important piece of information that MUST be present in the Python Docs, even though it is present at Linux Docs and Windows Docs. PROPOSED FIX ------------ Include the warning about packet truncation in the docs. NOTE: I have only pointed out socket.recvfrom(), but there are other related functions too, e.g. socket.recvfrom_into(), which require the same warning in their docs. ---------- assignee: docs@python components: Documentation messages: 324901 nosy: Anees Ahmed, docs@python priority: normal severity: normal status: open title: socket.recvfrom(): docs should warn about packet truncation when bufsize is insufficient type: enhancement versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34617> _______________________________________

1 0

[issue34611] some examples in 'itertools' modules docs are inaccuracy.
by Mark Dickinson Sept. 9, 2018

Sept. 9, 2018

New submission from Mark Dickinson <dickinsm(a)gmail.com>: @taketakeyyy: Did you mean to include information about *which* examples are inaccurate? This issue isn't really useful without that information. ---------- nosy: +mark.dickinson _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34611> _______________________________________

4 3

[issue34612] doc Some classes are treated as functions in Built-in Functions
by Andrés Delfino Sept. 9, 2018

Sept. 9, 2018

New submission from Andrés Delfino <adelfino(a)gmail.com>: Beyond other classes documented as functions (classmethod, enumerate, filter, map, reversed, staticmethod, super and zip), the following issues exist: * memoryview, range, and tuple are marked as functions * complex and object treat themselves as functions in their descriptions Attached PR fixes this. ---------- assignee: docs@python components: Documentation messages: 324864 nosy: adelfino, docs@python priority: normal severity: normal status: open title: doc Some classes are treated as functions in Built-in Functions type: enhancement versions: Python 2.7, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34612> _______________________________________

3 5

[issue34580] sqlite doc: clarify the scope of the context manager
by Karthikeyan Singaravelan Sept. 8, 2018

Sept. 8, 2018

Karthikeyan Singaravelan <tir.karthi(a)gmail.com> added the comment: Sounds good to me too since I copy paste from there time to time and also an unclosed connection doesn't seem to trigger a ResourceWarning it seems. I have pushed a commit to the same PR. I have changed it manually for all the include files. I have ran the files after the PR with the below and I couldn't see any breakages. Let me know if I have missed anything in the include files. I guess there are some more examples in sqlite3.rst but I don't know if it needs to be added on all snippets since they are more focused on the particular function unlike the files in the include folder that has full programs. Verified with : $ ls -1 Doc/includes/sqlite3/*py > sample.txt $ cat sample.txt | xargs -n 1 ./python.exe Thanks ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34580> _______________________________________

1 0

[issue34580] sqlite doc: clarify the scope of the context manager
by Daniel Jakots Sept. 8, 2018

Sept. 8, 2018

Daniel Jakots <bpo(a)chown.me> added the comment: Yes, I would totally support this move as it would show users that it's important to close it! ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34580> _______________________________________

1 0

[issue34580] sqlite doc: clarify the scope of the context manager
by Berker Peksag Sept. 8, 2018

Sept. 8, 2018

Berker Peksag <berker.peksag(a)gmail.com> added the comment: PR 9079 looks good to me. I think we can use this as an opportunity to make the rest of the examples in the sqlite3 documentation more consistent and add missing "conn.close()" calls. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34580> _______________________________________

1 0

[issue34580] sqlite doc: clarify the scope of the context manager
by Karthikeyan Singaravelan Sept. 8, 2018

Sept. 8, 2018

Karthikeyan Singaravelan <tir.karthi(a)gmail.com> added the comment: Thanks, I have pushed a change adding `con.close` at the end of the example and also verified that `./python.exe Doc/includes/sqlite3/ctx_manager.py` works as expected. Thanks ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34580> _______________________________________

1 0

[issue34580] sqlite doc: clarify the scope of the context manager
by Berker Peksag Sept. 8, 2018

Sept. 8, 2018

Berker Peksag <berker.peksag(a)gmail.com> added the comment: > Should I remove or change this line as per Daniel's comment "Note that > this does not automatically call :meth:`close` on the connection object." I'd prefer to keep the current wording as-is. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34580> _______________________________________

1 0