Project Architecture & Packages

Project Architecture for Distribution

• Concept: Before a Python package can be built and distributed, the project directory must be strictly organized. Source code, documentation, and the build script must be separated logically.
• Architecture: All actual Python code (packages and sub-packages) is moved into a dedicated source directory (e.g., animals). The build instructions (setup.py) and documentation (README.md) sit at the absolute root of the project.

Architecture:

zoo-example/                 # Project Root
├── setup.py                 # The core build script
├── README.md                # Project documentation
└── animals/                 # The actual Python source code
    ├── __init__.py
    ├── crocodile.py
    ├── monkey.py
    ├── zoo.py               # Contains the main() function
    └── handlers/            # Sub-package
        ├── __init__.py
        ├── walk.py
        └── swim.py

---

The Setup Configuration (setup.py)

• Concept: The center of all build and distribution activity. It uses setuptools to describe the module’s metadata, dependencies, and executable commands to the Python build system.
• Core Mechanisms:
• find_packages(): Automatically scans the directory and returns a list of all valid Python packages (directories with an __init__.py), saving you from listing them manually.
• entry_points: Metadata that exposes functionality to the user’s terminal. Specifically, console_scripts binds a terminal command (like zoo) to a specific function inside your Python code (like main() in animals.zoo).

Program:

# --- File: setup.py ---
from setuptools import setup, find_packages

setup(
    name="zoo-example",             # The official package name
    version="0.1",
    author="Captain Jack",
    author_email="captain_jack@gmail.com",
    description="Example of the test application",
    license="MIT",

    packages=find_packages(),       # Automatically includes the 'animals' directory

    install_requires=[              # External dependencies PIP must install first
        "termcolor==1.1.0",
    ],

    entry_points={
        "console_scripts": [
            # When the user types 'zoo' in the terminal,
            # execute the 'main' function inside 'animals/zoo.py'
            "zoo = animals.zoo:main",
        ],
    }
)

---

Building Distributives

• Concept: Converting your raw code and setup.py instructions into a compressed, installable artifact (like a Wheel or Source Archive).
• Methods (Run from the project root where setup.py lives):
  • $ python setup.py bdist_wheel: Builds a Wheel file (.whl). This is the modern, standard, compiled package format. (Requires running pip install wheel first).
  • $ python setup.py bdist_wheel --universal: Builds a wheel compatible with both Python 2 and Python 3.
  • $ python setup.py sdist: Creates a Source Archive (.tar.gz), containing raw source code rather than compiled binaries.
  • $ python setup.py bdist_egg: Builds an Egg file (Older, legacy format).
  • $ python setup.py --help-commands: Lists all available build commands.

Architecture Output: Executing a build command generates two new directories. dist/ holds the actual installable file, and *.egg-info/ holds the compilation metadata.

zoo-example/
├── dist/
│   └── zoo_example-0.1-py3-none-any.whl   <-- The installable package
└── zoo_example.egg-info/
    ├── PKG-INFO
    ├── SOURCES.txt
    ├── dependency_links.txt
    └── top_level.txt

---

Package Installation & Management (PIP)

• Concept: Using the Python Package Installer (PIP) to globally or locally install your compiled package so it can be imported from anywhere on the system.
• Methods (Targeting your custom package):
  • $ pip install . : Installs the package directly from the current directory by reading setup.py.
  • $ pip install /home/user/zoo-example : Installs from a specific absolute path.
  • $ pip install dist/zoo_example-0.1-py3-none-any.whl : Installs directly from the compiled Wheel file.
  • $ pip uninstall zoo-example : Removes the package from the system.
• Methods (General PIP commands):
  • $ pip install <package_name> : Standard installation from PyPI.
  • $ pip install --upgrade <package_name> : Forces an update to the latest version.
  • $ pip install <package_name>=='version_num' : Strict version installation.
  • $ pip install <package_name> >= 'version_num' : Installs any version matching or exceeding the criteria.
  • $ pip install -U pip : Upgrades the PIP tool itself.
  • $ pip search "query" : Searches the PyPI database.

Execution & Verification: Once installed locally, you can call your entry point directly from the bash terminal, or import the module in Python regardless of your current working directory.

# Executing the console script defined in entry_points
$ zoo
Welcome to the zoo!

# Verifying the import path in the Python REPL
$ python
>>> import animals
>>> animals.__path__
['/home/user/.pyenv/versions/devops/lib/python3.7/site-packages/animals']