Makefile Documentation¶

This document provides an overview of the Makefile used to support the development process for Python applications. It describes each target, its purpose, and the tools involved.

Makefile Functionalities¶

General Information¶

MODULE: The name of the main application module, here set as iotemplateapp.
PYTHONPATH: Specifies the paths included in the Python environment, covering docs, scripts, and tests.
ARCH and OS: Set up to detect the operating system and architecture to configure DOCKER2EXE settings.
ENV_FOR_DYNACONF: Set to test for the Dynaconf environment.
LANG: Language encoding set to en_US.UTF-8.

Available Targets¶

Each target in the Makefile is documented below:

Development and CI¶

help: Lists available targets and their descriptions.
dev: Runs code formatting, linting, and tests.
docs: Generates documentation with Sphinx.
everything: Runs dev and docs targets for pre-checkin verification.
final: A full workflow, running code formatting, linting, documentation generation, and tests.
pre-push: Prepares code for pushing by formatting, linting, running tests, incrementing version, and building documentation.

Code Formatting and Linting¶

format: Formats code using Black and docformatter.
lint: Runs a suite of linters, including ruff, Bandit, Vulture, Pylint, and Mypy.
black: Formats Python code for consistency.
docformatter: Formats docstrings to comply with PEP 257.
ruff: Runs an optimized linter and formatter.

Testing¶

tests: Runs all tests with pytest.
pytest-ci: Installs pytest dependencies, then runs tests.
pytest-first-issue: Runs pytest but stops at the first failure.
pytest-ignore-mark: Runs all tests excluding those marked with no_ci.
pytest-issue: Runs only tests marked with issue.
pytest-module: Runs tests on a specific module.

Static Analysis and Security¶

bandit: Checks for common security issues.
vulture: Detects unused code.
mypy: Performs static type checking.
mypy-stubgen: Generates stub files for type hinting.

Environment and Version Management¶

conda-dev: Sets up a development Conda environment.
conda-prod: Sets up a production Conda environment.
next-version: Increments the project’s version.
version: Displays versions of installed dependencies.

Documentation¶

sphinx: Generates HTML and PDF documentation with Sphinx.

Docker¶

docker: Builds a Docker image and prepares executables using docker2exe.

How to Use the Makefile¶

Install Dependencies: Make sure all tools required by the Makefile are installed in your environment.
Common Commands:
- make dev: Runs the development workflow, including formatting, linting, and testing.
- make docs: Generates and verifies the documentation.
- make everything: Runs a comprehensive check (development and documentation).
- make pre-push: Prepares code for committing to the repository by ensuring code quality and documentation.
- make conda-dev or make conda-prod: Creates Conda environments for development or production.
Testing Specifics:
- make tests: Runs all tests.
- make pytest-module TEST-MODULE=<module>: Runs tests for a specific module by setting the TEST-MODULE variable.

Tool Analysis¶

Summary of Tools Used¶

Each tool and its relevance to the development process is explained below:

Act (nektos/act): Allows GitHub Actions to run locally, facilitating CI/CD testing without needing GitHub’s infrastructure. This can be helpful for testing workflows before pushing code to remote repositories.
Bandit: Focuses on identifying security issues in Python code. This tool is essential for ensuring the security of the application.
Black: A widely-used code formatter that enforces a consistent coding style, improving readability and reducing merge conflicts.
Compileall: Byte-compiles all Python scripts, which can help with performance optimization and testing compiled code for syntax validity.
Conda: Manages isolated environments with different dependencies, ensuring compatibility across development, testing, and production setups.
Coveralls: Reports test coverage to coveralls.io, which is essential for understanding code coverage metrics in CI/CD pipelines.
Docformatter: Formats docstrings to comply with PEP 257, enhancing readability and consistency in documentation.
Docker and docker2exe: Docker is essential for containerizing applications. docker2exe helps create executables from Docker images, which is useful for building standalone applications.
Mypy: Provides static type checking, reducing runtime errors and improving code clarity.
Pylint: Performs a comprehensive linting process, identifying code smells and enforcing PEP 8 compliance.
Pytest: Runs tests in an organized manner, and various configurations allow different testing scopes, from unit tests to CI-oriented tests.
Ruff: A fast Python linter with a broad range of checks, offering a high-performance alternative to other linters.
Sphinx: Generates documentation from docstrings and reStructuredText, providing an essential resource for developers and end-users.
Vulture: Detects unused code, which helps keep the codebase clean and optimized.

Necessity and Redundancy¶

Necessary Tools: All tools involved contribute to either code quality, security, testing, or documentation, making them generally valuable for a robust development environment.
Potential Redundancies:
- Both ruff and pylint serve similar linting purposes. If speed is a concern, ruff alone might be sufficient for linting.
- Compileall may be optional unless there’s a specific need for bytecode testing or distribution.

Recommendations¶

Consolidate Linting: Depending on project requirements, you might choose ruff over pylint to streamline the linting process.
Assess Docker Usage: Ensure that docker2exe is necessary for the application’s deployment process, as it may add complexity to Docker builds.

This Makefile provides a comprehensive setup for Python application development, encompassing formatting, linting, testing, security analysis, documentation, and deployment. Each target streamlines common tasks, aiding both local development and CI/CD workflows.