ABC documentation needs more details on usage

[cdorsman]

I am trying to use Abstract Base Classes. But I find the documentation lacking on several points that makes the matter too 'abstract'.

For example. There is no explanation on making abstract objects mandatory by using exceptions

Or how to implement Iterable abstract bsse class that can be inherited from and still be usable.

Can someone shed more light onto this so that the documentation is more accessible?

[willingc]

Could you provide a bit more detail on what areas of the docs you are looking at?

• https://docs.python.org/3/library/abc.html#module-abc
• https://docs.python.org/3/library/collections.abc.html#module-collections.abc

For example. There is no explanation on making abstract objects mandatory by using exceptions

I'm sorry but I'm not clear on what you are asking here.

Or how to implement Iterable abstract bsse class that can be inherited from and still be usable.

I'm sorry but I'm not clear on what you are asking here.

[cdorsman]

Could you provide a bit more detail on what areas of the docs you are looking at?

• https://docs.python.org/3/library/abc.html#module-abc

• https://docs.python.org/3/library/collections.abc.html#module-collections.abc

I am looking at the module: https://docs.python.org/3/library/abc.html#module-abc

For example. There is no explanation on making abstract objects mandatory by using exceptions

I'm sorry but I'm not clear on what you are asking here.

It is apparently possible to make methods and attributes mandatory by using the NotInplemented exception, but there are no examples. The user has to be aware of this possibility.

Or how to implement Iterable abstract bsse class that can be inherited from and still be usable.

I'm sorry but I'm not clear on what you are asking here.

If a Iterator is being used in an Abstract Base Class, the Iterator is not passed down to the child class. What should the user do to make the Iterator work?

These are just random two examples. But what I am generally asking if someone can look at the documentation and write more practical examples/instructions so that it makes more sense on the why and how to use the module for the more "advanced" usage, because the source code itself is not giving any information what is and isn't possible.

[Mariatta]

It is apparently possible to make methods and attributes mandatory by using the NotInplemented exception, but there are no examples

Hmm you should use decorate the function with @abstractmethod which will raise exception if the child class doesn't implement it.

However I agree that we need to provide clearer explanation and instructions overall.

If a Iterator is being used in an Abstract Base Class, the Iterator is not passed down to the child class. What should the user do to make the Iterator work?

Sorry I still don't fully understand this. Do you perhaps have code snippet of how you defined the iterator on your ABC and the child class?

[cdorsman]

“Hmm you should use decorate the function with @AbstractMethod which will raise exception if the child class doesn't implement it.” But what if I have a series of variables. Some are mandatory and the others aren’t. How should I then define them? I would like to see these possibilities in the documentation. “Sorry I still don't fully understand this. Do you perhaps have code snippet of how you defined the iterator on your ABC and the child class?” Here you can find a full working test code: https://github.com/cdorsman/snippets/blob/e401c5a1da9eebfb5aa3ad2ff9c329f13fc8191d/mvc/mvc.py I had to define ABC Iterator like so to iterate and get the values because the childclasses cannot not inherit the Iterator from the Abstract Base Class. class Model(ABC, Iterable): _instances = [] @AbstractMethod def __iter__(self): return iter(getattr(self, '_instances', [])) While I expected that the Iterator would be passed downstream.

…

________________________________ From: Mariatta ***@***.***> Sent: Monday, September 16, 2024 5:04 PM To: python/docs-community ***@***.***> Cc: Chris Dorsman ***@***.***>; Author ***@***.***> Subject: Re: [python/docs-community] ABC documentation needs more details on usage (Issue #132) It is apparently possible to make methods and attributes mandatory by using the NotInplemented exception, but there are no examples Hmm you should use decorate the function with @AbstractMethod which will raise exception if the child class doesn't implement it. However I agree that we need to provide clearer explanation and instructions overall. If a Iterator is being used in an Abstract Base Class, the Iterator is not passed down to the child class. What should the user do to make the Iterator work? Sorry I still don't fully understand this. Do you perhaps have code snippet of how you defined the iterator on your ABC and the child class? — Reply to this email directly, view it on GitHub<#132 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AJMU4APL44GWNI4Q7KMJ4CDZW3XPJAVCNFSM6AAAAABOEU4H6KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNJTGE4DGOJVGY>. You are receiving this because you authored the thread.Message ID: ***@***.***>