Opened 5 years ago

Last modified 4 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: mail 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)

my-twisted-patch-6249.patch (506 bytes) - added by esacteksab 4 years ago.

Download all attachments as: .zip

Change History (5)

Changed 4 years ago by esacteksab

Attachment: my-twisted-patch-6249.patch added

comment:1 Changed 4 years ago by esacteksab

Keywords: review added

all = []

all is empty. Too simple?

comment:2 Changed 4 years ago by Tom Prince

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 4 years ago by Jean-Paul Calderone

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 4 years ago by Itamar Turner-Trauring

Keywords: easy removed
Note: See TracTickets for help on using tickets.