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
make public & private interface more explicit #12246
Comments
I think what you are describing is basically https://doc.rust-lang.org/reference/visibility-and-privacy.html 😄, but an "inversion" (i.e. public by default, instead of private), which is good 👍
I would say that the use of and so I would say maybe i.e. you can't make things private via the the use of For example, this is good: __all__ = ("a", "X", "function")
from .inner import function
def a(): ...
def _b(): ...
class X: ... But this is not good: __all__ = ()
def a(): ...
class X: ... |
not exactly- the use of
actually i think it main use case was originally controlling the behaviour of glob imports. But it's now used also used for defining public interfaces and also explicit re-exports, as you mention
no, i don't think this is right. The point of using
|
by the way, i'm not suggesting my proposal is definitely the way to go- more a straw man to kick off the discussion |
Well formally its still only for
and that is why I feel it would not be practical to expect users to obey this, since it is not enforced (to my knowledge) by any IDEs, linters, etc (By contrast, for exposing inner objects, mypy can enforce that: https://mypy.readthedocs.io/en/stable/config_file.html#confval-implicit_reexport) |
@electric-coder I think you missed the point of what I said; I specifically said you can use |
Not entirely. PEP 8 explicitly states (ref):
However, they also say
As such,
Technically, yes and no. One thing that I can say is that in private modules and their children, everything is considered private, whether there's an underscore or not. I personally am more leaning towards:
Now
Well... I don't want to make the whole code base fool-proof honestly. The main problem with Python is that there is no notion of a protected scope because when you have an I can suggest something that could meet both my expectations and probably yours as well: let's divide the API into private and public modules where in private modules we have public names and those private modules are imported (or we can even import the public names as is because imports should always be considered an implementation detail). |
I would hate for the presence of documentation to indicate the boundary between private and public. Documentation of private modules and objects could be very useful for contributors. Is there an equivalent of rust's |
Err, you can include private members using autodoc with |
it is not totally obvious which methods and types in sphinx are part of the public interface. This makes accidental breaking changes very likely.
I propose the following convention for denoting public/private objects (for discussion). The convention should be adopted incrementally on a best-effort basis:
__all__
to exhaustively list its public API__all__
Alternatives
__all__
listEnforcement
no-explicit-reexport
The text was updated successfully, but these errors were encountered: