title: How to design a library public api avoiding to expose internals?
body: <p>I am studying python. I am trying to understand how to design a library that exposes a public api. I want avoid to expose internal methods that could change in future. I am looking for a simple and pythonic way to do it.
  I have a library that contains a bunch of classes. Some methods of those classes are used internally among classes. I don't want to expose those methods to the client code.</p>
  
  <p>Suppose that my library (f.e. <code>mylib</code>) contains a class <code>C</code> with two methods a <code>C.public()</code> method thought to be used from client code and <code>C.internal()</code> method used to do some work into the library code.
  I want to commit myself to the public api (<code>C.public()</code>) but I am expecting to change the <code>C.internal()</code> method in future, for example adding or removing parameters.</p>
  
  <p>The following code illustrates my question:</p>
  
  <p><code>mylib/c.py</code>:</p>
  
  <pre><code>class C:
      def public(self):
          pass
  
      def internal(self):
          pass
  </code></pre>
  
  <p><code>mylib/f.py</code>:</p>
  
  <pre><code>class F:
      def build():
          c = C()
          c.internal()
          return c
  </code></pre>
  
  <p><code>mylib/__init__.py</code>:</p>
  
  <pre><code>from mylib.c import C
  from mylib.f import F
  </code></pre>
  
  <p><code>client/client.py</code>:</p>
  
  <pre><code>import mylib
  f = mylib.F()
  c = f.build()
  c.public()
  c.internal()  # I wish to hide this from client code
  </code></pre>
  
  <p>I have thought the following solutions:</p>
  
  <ul>
  <li><p>document only public api, warning user in documentation to don't use private library api. Live in peace hoping that clients will use only public api. If the next library version breaks client code is the client fault:). </p></li>
  <li><p>use some form of naming convention, f.e. prefix each method with "_", (it is reserved for protected methods and raises a warning into ide), perhaps I can use other prefixes.</p></li>
  <li><p>use objects composition to hide internal methods.
  For example the library could return to the clients only <code>PC</code> object that
  embeds <code>C</code> objects. </p></li>
  </ul>
  
  <p><code>mylib/pc.py</code>:</p>
  
  <pre><code>class PC:
      def __init__(self, c):
          self.__c__
  
      def public(self):
          self.__cc__.public()
  </code></pre>
  
  <p>But this looks a little contrived.</p>
  
  <p>Any suggestion is appreciated :-)</p>
  
  <p><strong>Update</strong></p>
  
  <p>It was suggested that this question is duplicated of <a href="https://stackoverflow.com/questions/1641219/does-python-have-private-variables-in-classes">Does Python have “private” variables in classes?</a></p>
  
  <p>It is similar question but I is a bit different about scope. My scope is a library not a single class. I am wondering if there is some convention about marking (or forcing) which are the public methods/classes/functions of a library. For example I use the <code>__init__.py</code> to export the public classes or functions. I am wondering if there is some convention about exporting class methods or if i can rely only on documentation. 
  I know I can use "_" prefix for marking protected methods. As best as I know protected method are method that can be used in class hierarchy.</p>
  
  <p>I have found a question about marking public method with a decorator <code>@api</code> <a href="https://stackoverflow.com/questions/10343998/sphinx-public-api-documentation">Sphinx Public API documentation</a> but it was about 3 years ago. There is commonly accepted solution, so if someone are reading my code understand what are methods intended to be library public api, and methods intended to be used internally in the library?
  Hope I have clarified my questions.
  Thanks all!</p>