{"id":34499383,"url":"https://github.com/bobmatnyc/python-project-template","last_synced_at":"2025-12-24T01:58:57.586Z","repository":{"id":329448433,"uuid":"1101585578","full_name":"bobmatnyc/python-project-template","owner":"bobmatnyc","description":"Copier template for Python projects with comprehensive modular Makefile (Ruff, pytest, release automation)","archived":false,"fork":false,"pushed_at":"2025-12-19T16:17:46.000Z","size":29,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T06:47:23.031Z","etag":null,"topics":["copier","copier-template","makefile","project-template","pytest","python","python-template","ruff","template"],"latest_commit_sha":null,"homepage":null,"language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobmatnyc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T22:24:42.000Z","updated_at":"2025-12-19T16:17:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bobmatnyc/python-project-template","commit_stats":null,"previous_names":["bobmatnyc/python-project-template"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bobmatnyc/python-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fpython-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fpython-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fpython-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fpython-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobmatnyc","download_url":"https://codeload.github.com/bobmatnyc/python-project-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobmatnyc%2Fpython-project-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27992995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-23T02:00:07.087Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["copier","copier-template","makefile","project-template","pytest","python","python-template","ruff","template"],"created_at":"2025-12-24T01:58:52.946Z","updated_at":"2025-12-24T01:58:57.581Z","avatar_url":"https://github.com/bobmatnyc.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Project Template\n\nA comprehensive Copier-based template for Python projects with a modular, enterprise-grade Makefile system.\n\n## Overview\n\nThis template generates Python projects with battle-tested build automation, derived from production codebases with 97+ Make targets and 1,200+ lines of proven automation.\n\n### Key Features\n\n- **Modular Makefile Architecture**: 5 specialized modules (common, quality, testing, deps, release)\n- **Ruff-First Quality**: 10-200x faster linting than Black+Flake8+isort\n- **Release Automation**: Semantic versioning with one-command publishing\n- **Environment-Aware**: Automatic dev/staging/prod detection\n- **Dependency Intelligence**: Poetry/uv integration with lockfile management\n\n## Quick Start\n\n### Prerequisites\n\n```bash\n# Install Copier\npip install copier\n# or\npipx install copier\n```\n\n### Generate Project\n\n```bash\n# From GitHub (when published)\ncopier copy gh:YOUR_USERNAME/python-project-template my-project\n\n# From local clone\ncopier copy /path/to/python-project-template my-project\n\n# Follow interactive prompts\ncd my-project\nmake help\n```\n\n### Template Questions\n\nThe template will ask:\n- **project_name**: Human-readable name (e.g., \"My Awesome Project\")\n- **project_slug**: URL/package name (auto-generated from name)\n- **project_description**: One-line summary\n- **python_version**: Minimum Python version (3.10-3.13)\n- **use_testing**: Include pytest/coverage targets (default: yes)\n- **use_release_automation**: Include version bumping/publishing (default: yes)\n- **use_docker**: Include Docker targets (default: no)\n- **github_username**: Your GitHub username/org\n- **author_name**: Your full name\n- **author_email**: Your email address\n\n## Generated Structure\n\n```\nmy-project/\n├── Makefile                    # Main Makefile (includes modules)\n├── .makefiles/\n│   ├── common.mk              # Variables, colors, helpers\n│   ├── quality.mk             # lint, format, type-check\n│   ├── testing.mk             # test, coverage, benchmarks\n│   ├── deps.mk                # install, sync, update deps\n│   └── release.mk             # version bumping, publishing\n├── pyproject.toml             # Python project config\n├── README.md                  # Project README\n├── .gitignore                 # Standard Python ignores\n└── scripts/                   # Project automation scripts\n```\n\n## Makefile Targets\n\n### Development Workflow\n\n```bash\nmake install        # Install in development mode\nmake quality        # Run all quality checks (lint + type-check)\nmake test           # Run test suite with coverage\nmake lint-fix       # Auto-fix linting issues\n```\n\n### Release Management\n\n```bash\nmake patch          # Bump patch version (0.1.0 -\u003e 0.1.1)\nmake minor          # Bump minor version (0.1.0 -\u003e 0.2.0)\nmake major          # Bump major version (0.1.0 -\u003e 1.0.0)\nmake release        # Full release: quality + test + build + publish\n```\n\n### Dependency Management\n\n```bash\nmake deps-install   # Install dependencies\nmake deps-update    # Update dependencies\nmake deps-sync      # Sync lockfile with pyproject.toml\n```\n\n## Customization\n\n### Adding Custom Targets\n\nEdit the generated `Makefile`:\n\n```makefile\n# At the bottom of Makefile\n.PHONY: custom-task\ncustom-task: ## Run custom project task\n\t@echo \"Running custom automation\"\n\t./scripts/my_script.py\n```\n\n### Modifying Module Behavior\n\nEdit `.makefiles/*.mk` files:\n\n```makefile\n# .makefiles/quality.mk\nlint: ## Run linting (customized)\n\truff check src/ tests/ --fix\n\tmypy src/ --strict\n```\n\n### Updating Template\n\nWhen the template receives updates:\n\n```bash\ncd my-project\ncopier update\n```\n\nCopier will:\n- Fetch latest template changes\n- Show diff of proposed changes\n- Allow selective acceptance of updates\n\n## Design Philosophy\n\n### Modular Makefile Architecture\n\nThe template separates concerns into specialized modules:\n\n1. **common.mk**: Shared variables, colors, utility functions\n2. **quality.mk**: Code quality (linting, formatting, type-checking)\n3. **testing.mk**: Test execution, coverage reporting, benchmarks\n4. **deps.mk**: Dependency installation, updates, synchronization\n5. **release.mk**: Version management, changelog, publishing\n\n**Benefits**:\n- **Maintainability**: Each module has single responsibility\n- **Reusability**: Drop-in modules across projects\n- **Extensibility**: Add new modules without touching existing ones\n- **Clarity**: Find targets by category, not by searching 1,200 lines\n\n### Ruff-First Quality Strategy\n\nTraditional Python tooling:\n- Black (formatter) + Flake8 (linter) + isort (imports) + pydocstyle\n- **4 tools**, **4 config files**, **slow execution**\n\nThis template:\n- Ruff (all-in-one)\n- **1 tool**, **1 config section**, **10-200x faster**\n\n### Environment-Aware Builds\n\nThe template detects environment automatically:\n\n```makefile\n# In common.mk\nENV ?= development\nifeq ($(ENV),production)\n    BUILD_FLAGS := --optimized --no-dev\nelse\n    BUILD_FLAGS := --dev\nendif\n```\n\nOverride with: `make build ENV=production`\n\n## Advanced Features\n\n### Parallel Test Execution\n\n```bash\nmake test PYTEST_ARGS=\"-n auto\"  # Auto-detect CPU cores\nmake test PYTEST_ARGS=\"-n 4\"     # Use 4 workers\n```\n\n### Coverage Thresholds\n\n```bash\nmake test                        # Fail if coverage \u003c 85%\nmake test COVERAGE_MIN=90        # Custom threshold\n```\n\n### Release Workflows\n\n```bash\n# Automatic changelog generation\nmake changelog                   # Generate CHANGELOG.md\n\n# Pre-release testing\nmake pre-release                 # quality + test + build (no publish)\n\n# Full release pipeline\nmake release                     # Full workflow with publishing\n```\n\n## Examples\n\n### Generate CLI Tool Project\n\n```bash\ncopier copy gh:YOUR_USERNAME/python-project-template my-cli-tool\n\n# Answer prompts:\n# project_name: My CLI Tool\n# project_slug: my-cli-tool\n# python_version: 3.11\n# use_testing: yes\n# use_release_automation: yes\n# use_docker: no\n\ncd my-cli-tool\nmake install\nmake help\n```\n\n### Generate Library Project\n\n```bash\ncopier copy gh:YOUR_USERNAME/python-project-template my-library\n\n# After generation, add to Makefile:\n.PHONY: docs\ndocs: ## Build documentation\n\tsphinx-build docs/ docs/_build/\n```\n\n## Troubleshooting\n\n### Copier Not Found\n\n```bash\npip install --user copier\n# or\npipx install copier\n```\n\n### Make Targets Not Working\n\nCheck that `.makefiles/*.mk` files are included:\n\n```bash\nls -la .makefiles/\n# Should show: common.mk, quality.mk, testing.mk, deps.mk, release.mk\n```\n\n### Python Version Mismatch\n\nUpdate `pyproject.toml`:\n\n```toml\n[tool.poetry.dependencies]\npython = \"^3.11\"  # Change to your version\n```\n\n## Contributing\n\nImprovements welcome! To contribute:\n\n1. Fork this repository\n2. Create feature branch: `git checkout -b feature/improvement`\n3. Test with: `copier copy . /tmp/test-project`\n4. Submit PR with description of changes\n\n### Testing Template Changes\n\n```bash\n# Test template generation\ncopier copy . /tmp/test-generation\n\n# Verify generated project\ncd /tmp/test-generation\nmake help\nmake quality\nmake test\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Credits\n\nBased on production Makefiles from:\n- **claude-mpm**: 1,205 lines, 97 targets\n- Real-world Python projects with years of refinement\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/YOUR_USERNAME/python-project-template/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/YOUR_USERNAME/python-project-template/discussions)\n- **Documentation**: See `TEMPLATE_README.md` for generated project docs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobmatnyc%2Fpython-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobmatnyc%2Fpython-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobmatnyc%2Fpython-project-template/lists"}