Python Topics : Best Practices for Code Structuring
What are Python Packages?
a package is essentially a directory which contains Python modules and a special file named __init__.py
the purpose of a package is to organize related modules under a common namespace
makes it easier to develop complex projects by compartmentalizing different parts of the application

the __init__.py file serves as the initializer for our package
in previous versions of Python this file was necessary to designate a folder as a package
since version Python 3.5 now allows for implicit packages
eliminates the need to add empty __init__.py files
now inclusion is optional

__init__.py file can be beneficial for

  • streamlining imports from subpackages
  • loading platform-specific modules
  • executing package-specific initialization tasks, such as configuration and validation
Creating a Python Package
StepDescription
1 - create a directory directory will be the package
name it according to the package's purpose.
2 - add modules place .py files (modules) inside the directory
each module can contain functions, classes, or variables
3 - include __init__.py create an __init__.py file within the directory
use this file to
  • initialize the package environment
  • define the package's public interface
  • perform any package-level initializations
Structuring the Package
a well-structured package is key to maintainability and reusability
structure for a hypothetical package named mypackage 
mypackage/
│-- __init__.py
│-- module1.py
│-- module2.py
└───subpackage1/
│   │-- __init__.py
│   │-- submodule1.py
└───subpackage2/
    │-- __init__.py
    │-- submodule2.py
mypackage contains two modules, module1.py and module2.py and two subpackages, subpackage1 and subpackage2
each subpackage, like the main package, contains its own __init__.py file and submodules
Utilizing Packages
importing from the package simplifies accessing its modules and functions
from the main.py file to import module1 from mypackage use 
import mypackage.module1
to import a specific function from a submodule use 
from mypackage.subpackage1.submodule1 import my_function
utilizing the __init__.py file can also enable easier access to key functions, classes, or variables by importing them into the package's namespace
users of your package can import directly from the package instead of navigating through its module structure
Best Practices for Package Development
PracticeDescription
consistency in naming use clear and consistent naming conventions for packages, modules, and subpackages to enhance readability and ease of use
by convention this should be in snake_case
another common convention is naming based on the domain such as client.py or request_handlers.py.
structure code logically try to define a clear tree structure with minimal coupling especially across packages
when there is a need to couple packages consider hoisting them up the tree so the coupling occurs in parent packages
prefer dependency injection where possible
important to avoid structures that create cyclic imports
simplify imports use __init__.py to manage your package's namespace
import key functions or classes in __init__.py to allow users to access them directly from the package
documentation document packages, modules, and functions thoroughly
good documentation is essential for maintaining and scaling the project
documentation facilitates the packages use by others
index