API of a module in python. In __init__.py?

Question

Hi I have written a python module wich consists of several .py files which contain classes and so on. I want to expose it to client using "Facade" pattern. So I don't want clients learn all internal classes but they only need methods exposed by this API interface.

Question is: where do I put this api ? Have I to define a file api.py inside the module of can I put this api in the __init__.py of the module?

I explain better with an example

<my_module>\
     __init__.py
     core.py
     submodule1.py
     submodule2.py
     util.py
     ........

so where do I put the public API of ?

Answer 1

The __init__.py file is an acceptable place to put the public API or a package, with the other modules within it providing the implementation.

Answer 2

The most common choice is to use __init__.py -- it's worth hiving off to a module of its own (or more) only if it's complex enough to warrant it (then it wouldn't be much of a Facade;-) or, more importantly, if you provide alternative APIs (a simplified one with reduced functionality but greater ease of use, and a rich/complex one, for example), in which case using separate modules keeps things better organized.

To communicate to package users that they're not supposed to import other modules directly, be sure to name your "private, internal implementation modules" with a leading underscore: _core.py, not core.py, and so forth. This convention is always used in Python to separate public APIs from internal implementation details and is well worth the (really small) effort for you to implement it!