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.

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

feature: Support conventions to mark objects as public #282

Closed
pawamoy opened this issue May 31, 2024 · 2 comments
Closed

feature: Support conventions to mark objects as public #282

pawamoy opened this issue May 31, 2024 · 2 comments
Assignees
Labels
feature New feature or request insiders Candidate for Insiders

Comments

@pawamoy
Copy link
Member

pawamoy commented May 31, 2024

Is your feature request related to a problem? Please describe.

In the ecosystem, we have common conventions to mark objects as public:

  • redundant imports: import x as x
  • redundant from-imports: from a import x as x
  • wildcard imports: from a import *

Users rely on those, but Griffe currently does not support them. This affects both our API checker and mkdocstrings-python: some objects might be wrongly considered private instead of public, or the opposite.

Describe the solution you'd like

Support these conventions.

A few solution ideas:

  • Use the public attribute? When visiting modules, set public = True on objects imported like that. Later, if we find __all__ is defined, set them back to None. Not sure I like using public like that, internally.
  • Write extensions. I think this would require adding a hook like on_alias? Extensions do not run during wildcard expansion though.
  • Add metadata to objects? This metadata ²would then be used by the "public" logic?

Describe alternatives you've considered

/

Additional context

See mkdocstrings/python#39.

@pawamoy pawamoy added the feature New feature or request label May 31, 2024
@pawamoy pawamoy self-assigned this May 31, 2024
@pawamoy pawamoy added this to the 1.0.0 milestone Jun 8, 2024
@pawamoy
Copy link
Member Author

pawamoy commented Aug 13, 2024

Since we don't recommend relying on these conventions in our docs, we should probably implement this as (insiders) extensions. For this we'll probably need new hooks:

  • on_alias: we could name it on_import, but during inspection we're not sure it's actually an import. Since we create an Alias, that follows the existing naming pattern (on module, on function, etc.).
  • on_wildcard_expansion? or maybe we can combine it in on_alias by passing relevant info?

@pawamoy pawamoy removed this from the 1.0.0 milestone Aug 14, 2024
@pawamoy pawamoy added the insiders Candidate for Insiders label Aug 15, 2024
pawamoy added a commit that referenced this issue Aug 17, 2024
pawamoy added a commit that referenced this issue Aug 17, 2024
@pawamoy
Copy link
Member Author

pawamoy commented Aug 18, 2024

@pawamoy pawamoy closed this as completed Aug 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature New feature or request insiders Candidate for Insiders
Projects
None yet
Development

No branches or pull requests

1 participant