105

When writing a python module and functions in it, I have some "public" functions that are supposed to be exposed to outsiders, but some other "private" functions that are only supposed to be seen and used locally and internally.

I understand in python there is no absolute private functions. But what is the best, most neat, or most used style to distinguish "public" functions and "private" functions?

I list some of the styles I know:

  1. use __all__ in module file to indicate its "public" functions (What's the python __all__ module level variable for?)
  2. use underscore at the beginning of name of "private" functions

Is there any other idea or convention that people use?

Thank you very much!

user
  • 1,220
  • 1
  • 12
  • 31
Kaifei
  • 1,568
  • 2
  • 13
  • 16
  • I have the same question and answer here is not for me. I know about `_` for private functions, but i have functions, that is used outside it's local namespace (is not private), but only internally in my module and is not supposed for public API. Is there any recommended way? – Daniel Malachov Dec 19 '21 at 19:00

1 Answers1

137

From Python's Class module documentation:

Private” instance variables that cannot be accessed except from inside an object don’t exist in Python. However, there is a convention that is followed by most Python code: a name prefixed with an underscore (e.g. _spam) should be treated as a non-public part of the API (whether it is a function, a method or a data member). It should be considered an implementation detail and subject to change without notice.

Since there is a valid use-case for class-private members (namely to avoid name clashes of names with names defined by subclasses), there is limited support for such a mechanism, called name mangling. Any identifier of the form __spam (at least two leading underscores, at most one trailing underscore) is textually replaced with _classname__spam, where classname is the current class name with leading underscore(s) stripped. This mangling is done without regard to the syntactic position of the identifier, as long as it occurs within the definition of a class.

Casimir et Hippolyte
  • 88,009
  • 5
  • 94
  • 125
Eric Hydrick
  • 3,467
  • 2
  • 28
  • 41
  • 4
    Thank you! So generally people will just use a leading underscore to distinguish between "public" and "private" functions in module? – Kaifei Feb 26 '13 at 00:30
  • 16
    Mostly. Like the documentation says, it's a convention, you can still access the functions like they're public, but the "correct" way to do things is to pretend they're not really there. – Eric Hydrick Feb 26 '13 at 00:51
  • 2
    Does this convention apply to functions that are not class based? – radtek Apr 21 '17 at 08:43
  • 4
    @radtek I would say it should apply for any function you don't want to be considered part of a public contract for that script. – Eric Hydrick Apr 21 '17 at 13:45
  • This is not a good answer. The question was about functions in modules not methods in classes and there is a serious issue with using `__` as a prefix for private (internal) functions. If we define an internal function `__foo()` in a module and call it from within a class `A` in this module, we will get the error `NameError: name '_A__foo' is not defined`. – Number47 Dec 15 '22 at 20:25
  • Python 3 docs still say the same thing: https://docs.python.org/3/tutorial/classes.html#tut-private – dijonkitchen May 22 '23 at 18:06