{"id":46573376,"url":"https://github.com/thoughtparametersllc/python-linting","last_synced_at":"2026-03-07T09:04:31.353Z","repository":{"id":321650091,"uuid":"1084447828","full_name":"thoughtparametersllc/python-linting","owner":"thoughtparametersllc","description":"🐍 A comprehensive Python quality gate that automatically runs Black for formatting, Pylint for code analysis, and MyPy for static type checking to keep your codebase clean and bug-free.","archived":false,"fork":false,"pushed_at":"2025-12-19T16:16:00.000Z","size":155,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T00:50:55.583Z","etag":null,"topics":["black","github-actions","linting","mypy","pylint","python3"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thoughtparametersllc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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-10-27T17:35:05.000Z","updated_at":"2025-12-19T16:16:01.000Z","dependencies_parsed_at":"2025-10-30T20:27:56.665Z","dependency_job_id":"d1983cda-5e83-42e4-8463-905dc3df5723","html_url":"https://github.com/thoughtparametersllc/python-linting","commit_stats":null,"previous_names":["thoughtparametersllc/python-linting"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/thoughtparametersllc/python-linting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtparametersllc%2Fpython-linting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtparametersllc%2Fpython-linting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtparametersllc%2Fpython-linting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtparametersllc%2Fpython-linting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thoughtparametersllc","download_url":"https://codeload.github.com/thoughtparametersllc/python-linting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtparametersllc%2Fpython-linting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30210385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["black","github-actions","linting","mypy","pylint","python3"],"created_at":"2026-03-07T09:04:30.702Z","updated_at":"2026-03-07T09:04:31.339Z","avatar_url":"https://github.com/thoughtparametersllc.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# python-linting\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Python%20Linting-blue.svg?colorA=24292e\u0026colorB=0366d6\u0026style=flat\u0026longCache=true\u0026logo=github)](https://github.com/marketplace/actions/python-linting)\n\nA comprehensive GitHub Action for Python code quality enforcement. Runs **Pylint**, **Black**, and **MyPy** with automatic badge generation and detailed reporting.\n\n## Features\n\n- 🐍 **Flexible Python version support** - Specify any Python version using `actions/setup-python`\n- 📦 **Custom requirements** - Install additional dependencies from a requirements file\n- 🔍 **Comprehensive linting** - Run Pylint, Black, and MyPy in a single action\n- 📊 **Detailed reporting** - View results in GitHub Actions summary\n- 🏅 **Automatic badge generation** - Creates and commits SVG badges for each linter\n- ⚙️ **Highly configurable** - Customize options for each linting tool\n\n## Prerequisites\n\n- Your repository must contain Python code\n- For badge commits: the workflow needs `contents: write` permission\n\n## Usage\n\n### Basic Example\n\n```yaml\nname: Python Linting\non: [push, pull_request]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write  # Required for badge commits\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Python Linting\n        uses: thoughtparametersllc/python-linting@v1\n```\n\n### Advanced Example with Custom Options\n\n```yaml\nname: Python Linting\non: [push, pull_request]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Python Linting\n        uses: thoughtparametersllc/python-linting@v1\n        with:\n          python-version: '3.11'\n          requirements-file: 'requirements.txt'\n          pylint-options: '--max-line-length=120 --disable=C0111'\n          black-options: '--line-length=120'\n          mypy-options: '--strict --ignore-missing-imports'\n          commit-badges: 'true'\n          badge-directory: '.github/badges'\n```\n\n### Example without Badge Commits\n\n```yaml\n- name: Python Linting\n  uses: thoughtparametersllc/python-linting@v1\n  with:\n    python-version: '3.10'  # Always quote version numbers\n    commit-badges: 'false'  # Disable automatic badge commits\n```\n\n### Example with Multiple Python Versions\n\n```yaml\nname: Python Linting\non: [push, pull_request]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        python-version: ['3.9', '3.10', '3.11', '3.12']\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Python Linting\n        uses: thoughtparametersllc/python-linting@v1\n        with:\n          python-version: ${{ matrix.python-version }}\n          commit-badges: ${{ matrix.python-version == '3.11' \u0026\u0026 'true' || 'false' }}  # Only the Python 3.11 job commits badges\n```\n\n## Inputs\n\n| Input | Description | Required | Default |\n|-------|-------------|----------|---------|\n| `python-version` | Python version to use for linting | No | `3.x` |\n| `requirements-file` | Path to requirements file for additional dependencies | No | `requirements.txt` |\n| `pylint-options` | Additional options to pass to pylint | No | `''` |\n| `black-options` | Additional options to pass to black | No | `''` |\n| `mypy-options` | Additional options to pass to mypy | No | `''` |\n| `commit-badges` | Whether to commit generated SVG badges back to the repository | No | `true` |\n| `badge-directory` | Directory to save the generated SVG badges | No | `.github/badges` |\n\n## Outputs\n\nThis action does not produce any outputs. Results are displayed in the GitHub Actions summary and as SVG badges (if enabled).\n\n## Badges\n\nWhen `commit-badges` is set to `true` (default), the action automatically generates and commits three SVG badge files to your repository:\n\n- `{badge-directory}/pylint.svg` - Pylint status badge\n- `{badge-directory}/black.svg` - Black status badge\n- `{badge-directory}/mypy.svg` - MyPy status badge\n\n### Displaying Badges in README\n\nAdd these badges to your README.md to show linting status:\n\n```markdown\n![Pylint](.github/badges/pylint.svg)\n![Black](.github/badges/black.svg)\n![MyPy](.github/badges/mypy.svg)\n```\n\n### Badge Colors\n\n- 🟢 Green (`success`) - No issues found\n- 🔴 Red (`failure`) - Issues detected\n\n## Permissions\n\nThis action requires the following permissions:\n\n```yaml\npermissions:\n  contents: write  # Required only if commit-badges is 'true'\n```\n\nIf you set `commit-badges: 'false'`, you can use:\n\n```yaml\npermissions:\n  contents: read\n```\n\n## Troubleshooting\n\n### Badge Commits Failing\n\n**Issue**: The action fails to commit badges back to the repository.\n\n**Solutions**:\n- Ensure `contents: write` permission is set in your workflow\n- Verify that branch protection rules allow the `github-actions[bot]` to push\n- Check that the badge directory exists or can be created\n\n### Linting Tools Not Found\n\n**Issue**: Pylint, Black, or MyPy commands fail with \"command not found\".\n\n**Solutions**:\n- Ensure Python is properly set up (the action handles this automatically)\n- Check that the Python version you specified is available\n- Review the \"Install Linting Tools\" step logs for errors\n\n### Requirements Installation Fails\n\n**Issue**: Additional requirements cannot be installed.\n\n**Solutions**:\n- Verify the `requirements-file` path is correct relative to repository root\n- Ensure the requirements file exists and is readable\n- Check for syntax errors in the requirements file\n- Review dependency conflicts in the workflow logs\n\n### False Positive Linting Errors\n\n**Issue**: Linters report issues that you want to ignore.\n\n**Solutions**:\n- Use linter-specific options to customize behavior:\n  - Pylint: `pylint-options: '--disable=C0111,W0212'`\n  - Black: `black-options: '--line-length=120'`\n  - MyPy: `mypy-options: '--ignore-missing-imports'`\n- Create configuration files (`.pylintrc`, `pyproject.toml`) in your repository\n\n### Action Fails on Pull Requests from Forks\n\n**Issue**: Badge commits fail on pull requests from forked repositories.\n\n**Solution**: This is expected behavior for security reasons. Forks don't have write access. Consider:\n- Setting `commit-badges: 'false'` for PRs from forks\n- Using a conditional in your workflow:\n  ```yaml\n  commit-badges: ${{ github.event.pull_request.head.repo.full_name == github.repository \u0026\u0026 'true' || 'false' }}\n  ```\n\n## How It Works\n\n1. **Setup Python**: Installs specified Python version\n2. **Install Tools**: Installs Pylint, Black, and MyPy\n3. **Install Requirements**: (Optional) Installs dependencies from your requirements file\n4. **Run Linters**: Executes all three linting tools sequentially\n5. **Generate Badges**: Creates SVG badges showing pass/fail status\n6. **Commit Badges**: (Optional) Commits badges back to your repository\n7. **Generate Summary**: Creates detailed GitHub Actions summary with results\n\n## Best Practices\n\n### When to Use This Action\n\n✅ **Good use cases:**\n- CI/CD pipelines for Python projects\n- Pre-merge checks on pull requests\n- Automated code quality enforcement\n- Ensuring consistent code style across teams\n\n❌ **Not recommended for:**\n- Local development (use pre-commit hooks instead)\n- Projects with custom linting workflows requiring specific tool versions\n- Repositories with complex multi-language setups\n\n### Recommended Workflow Configuration\n\n```yaml\nname: Code Quality\non:\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Python Linting\n        uses: thoughtparametersllc/python-linting@v1\n        with:\n          python-version: '3.11'\n          requirements-file: 'requirements.txt'\n```\n\n### Configuration Files\n\nYou can customize linter behavior using configuration files in your repository:\n\n- **Pylint**: `.pylintrc` or `pyproject.toml`\n- **Black**: `pyproject.toml`\n- **MyPy**: `mypy.ini` or `pyproject.toml`\n\nExample `pyproject.toml`:\n\n```toml\n[tool.black]\nline-length = 120\ntarget-version = ['py311']\n\n[tool.mypy]\npython_version = \"3.11\"\nwarn_return_any = true\nwarn_unused_configs = true\n\n[tool.pylint.format]\nmax-line-length = 120\n\n[tool.pylint.messages_control]\ndisable = [\"C0111\", \"C0103\"]\n```\n\n## Examples\n\n### Example: Python Package with Tests\n\n```yaml\nname: Test and Lint\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n      - run: pip install -r requirements.txt\n      - run: pytest\n\n  lint:\n    runs-on: ubuntu-latest\n    needs: test  # Run after tests pass\n    permissions:\n      contents: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: thoughtparametersllc/python-linting@v1\n        with:\n          requirements-file: 'requirements.txt'\n```\n\n### Example: Monorepo with Python Subdirectory\n\n```yaml\nname: Lint Python Code\non: [push]\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n    steps:\n      - uses: actions/checkout@v4\n      \n      # Note: The action runs from repository root regardless of working-directory settings\n      # Specify full paths from root for requirements-file and Python code location\n      - name: Python Linting\n        uses: thoughtparametersllc/python-linting@v1\n        with:\n          requirements-file: './python-service/requirements.txt'\n```\n\n### Example: Read-Only Mode (No Badge Commits)\n\n```yaml\nname: PR Linting Check\non: pull_request\n\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read  # Read-only for PR checks\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Python Linting\n        uses: thoughtparametersllc/python-linting@v1\n        with:\n          commit-badges: 'false'\n```\n\n## Development\n\nThis repository includes comprehensive GitHub workflows for CI/CD:\n\n- **Test Action**: Validates all action features across multiple Python versions\n- **Lint \u0026 Test**: Ensures code quality with Pylint, Black, MyPy, and Flake8\n- **Changelog Check**: Requires changelog updates for substantive changes\n- **Release \u0026 Marketplace**: Automated semantic versioning and tagging\n\nFor detailed workflow documentation, see [.github/WORKFLOWS.md](.github/WORKFLOWS.md).\n\n### Quick Start for Contributors\n\nSee [.github/WORKFLOW_QUICK_START.md](.github/WORKFLOW_QUICK_START.md) for a quick reference guide.\n\n### Releasing\n\nThe release workflow supports both automatic semantic versioning and manual version specification:\n\n**Automatic Release** (when changes are merged to main):\n\n- Automatically detects version bump from CHANGELOG.md\n- Creates release with extracted changelog notes\n- Updates major version tag (e.g., v1)\n\n**Manual Release** (for specific versions):\n\n1. Go to Actions → Release and Marketplace → Run workflow\n2. Enter version as `1.0.0` or `v1.0.0` (for specific version) or `major`/`minor`/`patch` (for semantic bump)\n3. The workflow will create the release and update tags\n\n### Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n**Quick steps:**\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Update CHANGELOG.md under the `[Unreleased]` section\n5. Ensure all tests pass\n6. Submit a pull request\n\n## Support\n\n- 📚 [Documentation](.github/WORKFLOWS.md)\n- 🐛 [Report a Bug](https://github.com/thoughtparametersllc/python-linting/issues/new?template=bug_report.yml)\n- 💡 [Request a Feature](https://github.com/thoughtparametersllc/python-linting/issues/new?template=feature_request.yml)\n- 🔒 [Security Policy](SECURITY.md)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nBuilt with:\n- [Pylint](https://pylint.pycqa.org/) - Python code analysis\n- [Black](https://github.com/psf/black) - Python code formatter\n- [MyPy](https://mypy-lang.org/) - Static type checker\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoughtparametersllc%2Fpython-linting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthoughtparametersllc%2Fpython-linting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoughtparametersllc%2Fpython-linting/lists"}