Package

A file modu.py in the directory pack/ is imported with the statement import pack.modu. This statement will look for an __init__.py file in pack, execute all of its top-level statements. Then it will look for a file named pack/modu.py and execute all of its top-level statements. After these operations, any variable, function, or class defined in modu.py  is available in the pack.modu namespace.

A commonly seen issue is to add too much code to __init__.py files. When the project complexity grows, there may be sub-packages and sub-sub-packages in a deep directory structure. In this case, importing a single item from a sub-sub-package will require executing all __init__.py files met while traversing the tree.

This and other issues led to the idea that using stateless functions is a better programming paradigm.

Another way to say the same thing is to suggest using functions and procedures with as few implicit contexts and side-effects as possible. A function’s implicit context is made up of any of the global variables or items in the persistence layer that are accessed from within the function. Side-effects are the changes that a function makes to its implicit context. If a function saves or deletes data in a global variable or in the persistence layer, it is said to have a side-effect.

Pure functions

• Pure functions are deterministic: given a fixed input, the output will always be the same.
• Pure functions are much easier to change or replace if they need to be refactored or optimized.
• Pure functions are easier to test with unit-tests: There is less need for complex context setup and data cleaning afterwards.
• Pure functions are easier to manipulate, decorate, and pass around.

However, it may be a good discipline to avoid assigning to a variable more than once, and it helps in grasping the concept of mutable and immutable types.

• A LICENSE file should always be present and specify the license under which the software is made available to the public.
• A TODO file or a TODO section in README should list the planned development for the code.
• A CHANGELOG file or section in README should compile a short overview of the changes in the code base for the latest versions.
• Project Publication

Depending on the project, your documentation might include some or all of the following components:

• An introduction should show a very short overview of what can be done with the product, using one or two extremely simplified use cases. This is the thirty-second pitch for your project.
• A tutorial should show some primary use cases in more detail. The reader will follow a step-by-step procedure to set-up a working prototype.
• An API reference is typically generated from the code (see docstrings). It will list all publicly available interfaces, parameters, and return values.
• Developer documentation is intended for potential contributors. This can include code convention and general design strategy of the project.

Put tests/, docs/ directory inside the project