- ⚙️ Setup Instructions
- 🛠️ Tools and Configurations
- 🔜 Future Package Manager Support
- 🤝 How to Contribute
- 📝 License
This template provides a modern setup for Python projects with an emphasis on code quality, security, testing, and automated workflows. It integrates a range of tools to streamline the development process.
- 📦 Poetry: Dependency management and packaging.
- 🔧 Taskipy: Task automation and management.
- 🖋️ Pre-commit hooks: Automate linting, formatting, and checks before commits.
- 🧪 Pytest: Testing framework for Python.
- 📊 Coverage: Measure and track test coverage.
- 🛡️ Bandit: Security analysis of Python code.
- 🗑️ Vulture: Detect unused code (dead code).
- 🔐 Safety: Check for vulnerabilities in dependencies.
Ensure you have Python 3.13 or higher installed. Additionally, you'll need Poetry to manage dependencies and environments.
To install Poetry, follow the instructions here: Poetry Installation Guide
To generate a new project using this template with Cookiecutter, run:
cookiecutter https://github.com/robert-nogueira/awesome-py-project-templateYou will be prompted to customize your project setup, with options to choose:
- ✅ Linters (e.g.,
ruff,flake8,pylint). - ✅ Formatters (e.g.,
black,ruff). - ✅ Type Checkers (e.g.,
mypy,pyright). - ✅ Additional tools (e.g., isort).
The cookiecutter template will automatically configure the necessary tools based on your selections.
[!TIP] You can set default values at you user config file
After generating the project, Cookiecutter will run a post-generation script (post_gen_project.sh) that:
- Installs and updates dependencies via Poetry.
- Sets up pre-commit hooks.
- Customizes configurations based on your choices during project setup (e.g., linters, formatters, and other tools).
The script is executed automatically after running cookiecutter. If you need to run it manually, use:
./post_gen_project.shPre-commit is configured to run hooks automatically before each commit. The post-generation script will install pre-commit and set up hooks as defined in .pre-commit-config.yaml.
All dependencies and environment settings are managed by Poetry, and the pyproject.toml file contains both runtime and development dependencies.
The .pre-commit-config.yaml file defines the hooks that run before each commit, including linters, formatters, and checks for common issues.
Taskipy is configured to help you automate project tasks. You can define and run any task you need, including running tests, code analysis, and more. Tasks are defined in the tasks.py file.
Pytest is the recommended framework for testing in this template. It supports fixtures, plugins, and extensive test case setups.
The coverage tool integrates with pytest to measure how much of your code is tested. The reports can be viewed in the terminal or as an HTML file.
- Bandit checks for common security flaws in Python code.
- Vulture identifies dead code that should be removed.
- Safety checks for known security vulnerabilities in the project’s dependencies.
This project follows the Conventional Commits specification, ensuring that commit messages are standardized and easily understood. Additionally, Gitmoji is used to add emojis to commit messages, providing a more visual and expressive way of representing changes.
Example commit messages:
- 🎉 feat(api): add new user authentication feature
- 🐛 fix(security): resolve issue with password hashing
- 📦 chore: update dependencies
- 📝 docs: improve README.md with new setup instructions
For more details on Conventional Commits and Gitmoji, check these resources:
We plan to add support for other package managers in the future, such as UV and Hatch, to provide more flexibility and compatibility with various environments.
- Fork the repository.
- Create a new branch.
- Make your changes.
- Run all tests, linters, and static analysis tools.
- Submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.