CONTRIBUTING.md

Contributing to blender-python-cookbook

Thank you for your interest in contributing! This project collects practical Blender Python (bpy) recipes that solve real problems.

How to contribute

1. Fork the repository and create a feature branch.
2. Add your recipe in the appropriate recipes/ subdirectory.
3. Follow the TYPE_CHECKING pattern for bpy imports (see existing recipes).
4. Add tests in tests/ that mock bpy — no real Blender installation needed.
5. Run checks before submitting:

   pip install -e ".[dev]"
   ruff check recipes/ utils/ tests/
   pytest tests/ -v

6. Open a pull request with a clear description of what your recipe does and when it is useful.

Code style

• Use type hints on all function signatures.
• Write Google-style docstrings with Args/Returns sections.
• Keep line length under 120 characters (enforced by ruff).
• Use the TYPE_CHECKING guard for import bpy so files are importable outside Blender.

Recipe structure

Each recipe file should:

• Have a module-level docstring explaining the category.
• Contain focused, single-purpose functions.
• Work inside Blender 4.x Python environment.

Reporting issues

Open a GitHub issue with steps to reproduce. Include your Blender version and OS.