Opened 9 years ago
Last modified 9 years ago
#6249 defect new
twisted.mail.pop3client.__all__ should be empty, so API docs list those objects in correct module
Reported by: | Itamar Turner-Trauring | Owned by: | Michael Hudson-Doyle |
---|---|---|---|
Priority: | normal | Milestone: | |
Component: | Keywords: | ||
Cc: | Branch: | ||
Author: |
Description
https://twistedmatrix.com/documents/current/api/twisted.mail.pop3.html doesn't list AdvancedPOP3Client
. This is wrong. The reason is that pydoctor wants objects to only be in one module's __all__
, and it already appears in pop3client
; the same is true of the exception classes there.
pop3client
is basically an implementation module of pop3
, and should probably be private, so its __all__
should be empty.
Attachments (1)
Change History (5)
Changed 9 years ago by
Attachment: | my-twisted-patch-6249.patch added |
---|
comment:1 Changed 9 years ago by
Keywords: | review added |
---|
comment:2 Changed 9 years ago by
Keywords: | review removed |
---|---|
Owner: | set to Michael Hudson-Doyle |
Unfortunately, doing this changes the public api of twisted.mail.pop3client
, which is a backwards incompatible change.
However, it should be possible to tell pydoctor that nothing should be documented here, without changing the api. Perhaps something like
__hidden_all__ = ['some', 'stuff'] __all__ = __hidden_all__'
Assigning to mwhudson, as the pydoctor expert.
In any case, a ticket should be filed to deprecate pop3client, and move everything in it to a private module. (Perhaps moving things to a private module and just importing them in t.m.pop3client
is enough to get the documentation in the right place.
comment:3 Changed 9 years ago by
This sounds like a gross hack.
The contents of __all__
don't actually matter to most programs. Supporting "from ... import *" where "..." is a Twisted module should explicitly be documented as not supported, if it is not already, because it is already likely to result in things breaking when new names are introduced.
So, I don't think these extra hoops are necessary. If we want to remove everything from __all__
we can do that.
comment:4 Changed 9 years ago by
Keywords: | easy removed |
---|
all = []
all is empty. Too simple?