In his review of PR#4911, Antoine points to the documentation of two type definitions in importlib.resources, Package and Resource.
https://github.com/python/cpython/pull/4911/files#diff-2a479c407f7177f3d7cb876f244e47bcR804 One question is what markup to use for type definitions. I’m using class:: because that’s what’s used in typing and there doesn’t seem to be any better alternative. More to the point, Antoine questions whether these two types should be documented at all: https://github.com/python/cpython/pull/4911#discussion_r158801065 "What I mean is that a class is supposed to specify concrete behaviour, but being a type, Package doesn't have any methods or attributes of its own. So I don't see the point of mentioning it in the docs.” I suggest that they are worth documenting because they help to organize the discussion about what API is expected from the arguments to the functions, without having to duplicate that information in every function description. I also think that since you’ll see those types in the code, they are worth documenting. I don’t think you *lose* anything by including their documentation. But Antoine makes a good point that we probably don’t have a lot of precedence here, so suggests we discuss it on python-dev to come up with some useful conventions. I haven’t kept up on the dataclasses discussion, but given that types are important in that API too, have the same issues come up there and if so, how are they being handled? Cheers, -Barry
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
