Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

__all__ re-exports don't work for CramMD5ClientAuthenticator #184

Open
glyph opened this issue Jan 28, 2020 · 9 comments · May be fixed by #739
Open

__all__ re-exports don't work for CramMD5ClientAuthenticator #184

glyph opened this issue Jan 28, 2020 · 9 comments · May be fixed by #739
Labels
bug

Comments

@glyph
Copy link
Member

glyph commented Jan 28, 2020

CramMD5ClientAuthenticator is documented here:

https://twistedmatrix.com/documents/19.10.0/api/twisted.mail._cred.CramMD5ClientAuthenticator.html

except that should be a private API.

It's re-exported in the __all__ of twisted.mail.imap4 and twisted.mail.smtp, but doesn't show up in either of those places.

I'm not sure what the actual issue is here (it might be that this is kind of a nonsense thing to do?) but we should probably do something more coherent, or at least report an error.
@glyph glyph mentioned this issue Jan 28, 2020
Merged
5 tasks
@tristanlatr
Copy link
Contributor

I think I'm having the same issue with

https://tristanlatr.github.io/wpscan_out_parse/wpscan_out_parse.parser.html#parse_results_from_file which defined in wpscan_out_parse/parser/__init__.py and exported in wpscan_out_parse/__init__.py but it only shows in wpscan_out_parse/parser/__init__.py.

@mthuurne mthuurne mentioned this issue Nov 12, 2020
Merged
@mthuurne
Copy link
Contributor

I think there are actually 3 issues here:

  • CramMD5ClientAuthenticator does not get re-exported at all
  • pydoctor doesn't have a strategy for things that get re-exported more than once
  • the module index doesn't differentiate between public and private modules (package pages do)

I don't know if re-exporting a name in multiple locations is something we should support: it seems confusing to just have the same class documentation at different places in the tree. Maybe one of them could be the official location and the others could link to it? That would be the preferred approach when something is moved and the old location is deprecated but still around for backwards compatibility.

@mthuurne
Copy link
Contributor

@tristanlatr parse_results_from_file() is re-exported when using the latest pydoctor; I think the fixes from #262 have helped here.

@tristanlatr
Copy link
Contributor

@mthuurne Thanks

@mthuurne
Copy link
Contributor

A long-term improvement discussed in #277 was to drop the reparenting of re-exported names and instead build a separate documentation layer on top of the code model. Doing so would allow one name from the code model to be published in more than one location in the documentation.

I'm still not sure whether it's a good idea to have one name published in more than one location though. For example if an exception type is documented in more than one place, it might surprise the user if catching one documented type will also catch a type documented in a different module. But perhaps that decision can be made by the developer on a case by case basis, instead of the tool deciding for them.

@mthuurne mthuurne mentioned this issue Nov 27, 2020
Open
@tristanlatr
Copy link
Contributor

Still true with latest pydoctor (https://pydocbrowser.github.io/twisted/latest/twisted.mail._cred.CramMD5ClientAuthenticator.html).

@tristanlatr
Copy link
Contributor

This problem is likely due to circular imports. Probably we re hitting the re exporting of the CramMD5ClientAuthenticator class before having processed the class itself.

There are several manner to tackle this problem. The more obvious thing to do would be to do all the reparenting in post processing. This would ensure that all objects are processed before moving them around. Unfortunately, for this to work the way it does now, we need to upgrade our understanding of recursive imports aliases, so all names can be resolved at the end.

We could also try to reach a model representation that does not need reparenting at all. That’s much harder right now, but it would be the right thing to do.

@tristanlatr tristanlatr mentioned this issue Jul 13, 2023
Closed
@tristanlatr
Copy link
Contributor

Turns out there is a condition preventing a name to be re-exported when it's listed in the __all__ variable of the origin module.

not moving 'twisted.internet.iocpreactor.reactor.install' into 'twisted.internet.iocpreactor', because install is present in twisted.internet.iocpreactor.reactor.__all__
not moving 'twisted.mail._cred.CramMD5ClientAuthenticator' into 'twisted.mail.imap4', because CramMD5ClientAuthenticator is present in twisted.mail._cred.__all__
not moving 'twisted.mail._cred.LOGINAuthenticator' into 'twisted.mail.imap4', because LOGINAuthenticator is present in twisted.mail._cred.__all__
not moving 'twisted.mail._cred.LOGINCredentials' into 'twisted.mail.imap4', because LOGINCredentials is present in twisted.mail._cred.__all__
not moving 'twisted.mail._cred.PLAINAuthenticator' into 'twisted.mail.imap4', because PLAINAuthenticator is present in twisted.mail._cred.__all__
not moving 'twisted.mail._cred.PLAINCredentials' into 'twisted.mail.imap4', because PLAINCredentials is present in twisted.mail._cred.__all__
not moving 'twisted.mail.interfaces.IAccountIMAP' into 'twisted.mail.imap4', because IAccountIMAP is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IClientAuthentication' into 'twisted.mail.imap4', because IClientAuthentication is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.ICloseableMailboxIMAP' into 'twisted.mail.imap4', because ICloseableMailboxIMAP is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMailboxIMAP' into 'twisted.mail.imap4', because IMailboxIMAP is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMailboxIMAPInfo' into 'twisted.mail.imap4', because IMailboxIMAPInfo is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMailboxIMAPListener' into 'twisted.mail.imap4', because IMailboxIMAPListener is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageIMAP' into 'twisted.mail.imap4', because IMessageIMAP is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageIMAPCopier' into 'twisted.mail.imap4', because IMessageIMAPCopier is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageIMAPFile' into 'twisted.mail.imap4', because IMessageIMAPFile is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageIMAPPart' into 'twisted.mail.imap4', because IMessageIMAPPart is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.INamespacePresenter' into 'twisted.mail.imap4', because INamespacePresenter is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.ISearchableIMAPMailbox' into 'twisted.mail.imap4', because ISearchableIMAPMailbox is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMailboxPOP3' into 'twisted.mail.pop3', because IMailboxPOP3 is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IServerFactoryPOP3' into 'twisted.mail.pop3', because IServerFactoryPOP3 is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail._cred.CramMD5ClientAuthenticator' into 'twisted.mail.smtp', because CramMD5ClientAuthenticator is present in twisted.mail._cred.__all__
not moving 'twisted.mail._cred.LOGINAuthenticator' into 'twisted.mail.smtp', because LOGINAuthenticator is present in twisted.mail._cred.__all__
not moving 'twisted.mail.interfaces.IClientAuthentication' into 'twisted.mail.smtp', because IClientAuthentication is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageDelivery' into 'twisted.mail.smtp', because IMessageDelivery is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageDeliveryFactory' into 'twisted.mail.smtp', because IMessageDeliveryFactory is present in twisted.mail.interfaces.__all__
not moving 'twisted.mail.interfaces.IMessageSMTP' into 'twisted.mail.smtp', because IMessageSMTP is present in twisted.mail.interfaces.__all__
not moving 'twisted.names.error.AuthoritativeDomainError' into 'twisted.names.dns', because AuthoritativeDomainError is present in twisted.names.error.__all__
not moving 'twisted.names.error.DNSQueryTimeoutError' into 'twisted.names.dns', because DNSQueryTimeoutError is present in twisted.names.error.__all__
not moving 'twisted.names.error.DomainError' into 'twisted.names.dns', because DomainError is present in twisted.names.error.__all__
not moving 'twisted.python._tzhelper.UTC' into 'twisted.protocols.amp', because UTC is present in twisted.python._tzhelper.__all__
not moving 'twisted.trial._asyncrunner.TestSuite' into 'twisted.trial.runner', because TestSuite is present in twisted.trial.unittest.__all__

@tristanlatr
Copy link
Contributor

I'm working on a fix

tristanlatr added a commit that referenced this issue Jul 18, 2023
@tristanlatr
Fix issue #184
2c28b00 
(Wip, still a couple of problems)
@tristanlatr tristanlatr mentioned this issue Jul 18, 2023
Closed
@tristanlatr tristanlatr mentioned this issue Sep 30, 2023
Closed
tristanlatr added a commit that referenced this issue Oct 1, 2023
@tristanlatr
Fix issue #184.
8d7b748 
Introduce.
Module.elsewhere_contents
@tristanlatr tristanlatr linked a pull request Oct 1, 2023 that will close this issue
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug
Projects
None yet
Milestone
No milestone
3 participants
@mthuurne @glyph @tristanlatr