Mailing List Archive

[issue40994] Very confusing documenation for abc.Collections
Irit Katriel <iritkatriel@yahoo.com> added the comment:

Can you be more specific about what you found confusing? What is the documentation bug? What do you mean by "this point in the documentation"?

Even better, can you suggest how to rewrite the documentation to make it clearer?

----------
nosy: +iritkatriel

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Sydney Pemberton <spemberton@auntbertha.com> added the comment:

If you look at the Jupyter notebook it should be fairly clear but to
summarize here is the issue:

class collections.abc.Container
class collections.abc.Hashable
class collections.abc.Sized
class collections.abc.Callable
ABCs for classes that provide respectively the
methods __contains__(), __hash__(), __len__(), and __call__().

This should become

class collections.abc.Container
ABC for classes that provide the method __contains__().
class collections.abc.Hashable
ABC for classes that provide the method __hash__().
class collections.abc.Sized
ABC for classes that provide the method __len()__.
class collections.abc.Callable
ABC for classes that provide the method __call__().

----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Srinivas Reddy Thatiparthy(?????????? ?????? ?????????) <thatiparthysreenivas@gmail.com> added the comment:

English is my second language and I am familiar with the expression “respectively” since it is used very often in high school mathematics.

----------
nosy: +thatiparthy

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Irit Katriel <iritkatriel@yahoo.com> added the comment:

Sydney, is the issue related to how Jupyter notebook displays the documentation?

----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Sydney Pemberton <spemberton@auntbertha.com> added the comment:

Nothing to do with Jupyter itself.
When I'm reading the documentation I don't necessarily think that a sibling
"node" in the document structure is going to have anything to do with my
current section.
So it was weird to see the section entirely empty.

Also, I'm not saying that all non-native speakers are going to be
unfamiliar with the construction, but it is certainly more widely
understandable if the definitions are kept separate.

On Thu, Aug 13, 2020 at 12:54 PM Irit Katriel <report@bugs.python.org>
wrote:

>
> Irit Katriel <iritkatriel@yahoo.com> added the comment:
>
> Sydney, is the issue related to how Jupyter notebook displays the
> documentation?
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue40994>
> _______________________________________
>

--

Sydney Pemberton

Software Engineer

512.740.6591

spemberton@auntbertha.com
Aunt Bertha <https://company.auntbertha.com/> | The Social Care Network

----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Georg Brandl <georg@python.org> added the comment:

FWIW, I think Sydney's right. Shared entries should only be used for closely related, or interdependent, APIs, which those here are not.

----------
nosy: +georg.brandl

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Irit Katriel <iritkatriel@yahoo.com> added the comment:

Looks like this is not the first time this has come up: https://stackoverflow.com/questions/39789876/why-collections-callable-provides-contains-hash-len-and-ca

The link directly to the #collections.abc.Callable section is what makes it confusing:

https://python.readthedocs.io/en/latest/library/collections.abc.html#collections.abc.Callable

----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Irit Katriel <iritkatriel@yahoo.com> added the comment:

Sydney, do you want to create a PR for this? I'm happy to if you don't.

----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Sydney Pemberton <spemberton@auntbertha.com> added the comment:

Yes, that would be great. I will figure out how to do that shortly.

On Fri, Aug 14, 2020 at 3:23 AM Irit Katriel <report@bugs.python.org> wrote:

>
> Irit Katriel <iritkatriel@yahoo.com> added the comment:
>
> Sydney, do you want to create a PR for this? I'm happy to if you don't.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue40994>
> _______________________________________
>

--

Sydney Pemberton

Software Engineer

512.740.6591

spemberton@auntbertha.com
Aunt Bertha <https://company.auntbertha.com/> | The Social Care Network

----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Change by Roundup Robot <devnull@psf.upfronthosting.co.za>:


----------
keywords: +patch
nosy: +python-dev
nosy_count: 6.0 -> 7.0
pull_requests: +21004
stage: -> patch review
pull_request: https://github.com/python/cpython/pull/21880

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Change by Irit Katriel <iritkatriel@yahoo.com>:


----------
versions: +Python 3.10, Python 3.9

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment:


New changeset 2ce39631f679e14132a54dc90ce764259d26e166 by Sydney Pemberton in branch 'master':
bpo-40994: Ungroup items in collections.abc documentation for improved clarity (GH-21880)
https://github.com/python/cpython/commit/2ce39631f679e14132a54dc90ce764259d26e166


----------
nosy: +miss-islington

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>:


----------
pull_requests: +21039
pull_request: https://github.com/python/cpython/pull/21926

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>:


----------
pull_requests: +21040
pull_request: https://github.com/python/cpython/pull/21927

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment:

@Sydney Pemberton, thank you for the bug report and for the PR!

----------
nosy: +cheryl.sabella
resolution: -> fixed
stage: patch review -> resolved
status: open -> closed
type: -> enhancement

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment:


New changeset 0694b82381ff27e10bb15172da0832a7e65aaa2d by Miss Islington (bot) in branch '3.8':
bpo-40994: Ungroup items in collections.abc documentation for improved clarity (GH-21880) (#21927)
https://github.com/python/cpython/commit/0694b82381ff27e10bb15172da0832a7e65aaa2d


----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com
[issue40994] Very confusing documenation for abc.Collections [ In reply to ]
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment:


New changeset f497bbeed08e5a7f83adecf330b61fb88e9c3fa6 by Miss Islington (bot) in branch '3.9':
bpo-40994: Ungroup items in collections.abc documentation for improved clarity (GH-21880) (#21926)
https://github.com/python/cpython/commit/f497bbeed08e5a7f83adecf330b61fb88e9c3fa6


----------

_______________________________________
Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40994>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com