pycmdcheck 0.1.0__tar.gz

pycmdcheck-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,17 @@
+# Python version: 3, 3.10, 3.11, 3.12, ... 
+# https://hub.docker.com/_/microsoft-devcontainers-python
+ARG VARIANT="3.12"
+FROM mcr.microsoft.com/devcontainers/python:${VARIANT}
+
+# Setup devcontainer user
+ARG USERNAME=vscode
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+
+# Update pip
+RUN pip install --upgrade pip
+
+# Install pkg dev dependencies
+COPY requirements-dev.txt /tmp/requirements-dev.txt
+RUN pip install -r /tmp/requirements-dev.txt && \
+    rm /tmp/requirements-dev.txt

pycmdcheck-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,61 @@
+// For format details, see https://aka.ms/devcontainer.json.
+{
+    "name": "Python 3",
+    "build": {
+        // More info: https://containers.dev/guide/dockerfile
+        "dockerfile": "Dockerfile",
+        // Change VARIANT to pick different Python version: 3, 3.10, 3.11, 3.12, ...
+        "args": {
+            "VARIANT": "3.12"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                // Python
+                "ms-python.python",
+                "ms-python.black-formatter",
+                "ms-toolsai.jupyter",
+                "ms-toolsai.jupyter-renderers",
+                "ms-python.vscode-pylance",
+                // Docker
+                "ms-azuretools.vscode-docker",
+                // Documentation
+                "njpwerner.autodocstring",
+                // Format
+                "stkb.rewrap",
+                // Lint
+                "charliermarsh.ruff",
+                // Gen AI
+                "GitHub.copilot"
+            ],
+            "settings": {
+                // Editor
+                "editor.formatOnSave": true,
+                // Files
+                "files.insertFinalNewline": true,
+                "files.trimTrailingWhitespace": true,
+                // Testing
+                "python.testing.pytestArgs": [
+                    "."
+                ],
+                "python.testing.unittestEnabled": false,
+                "python.testing.pytestEnabled": true,
+                "python.testing.autoTestDiscoverOnSaveEnabled": true,
+                // Formatting
+                "python.formatting.provider": "black",
+                "python.formatting.blackArgs": [
+                    "--no-color"
+                ],
+                // Linting
+                "python.linting.mypyEnabled": true,
+                "python.linting.enabled": true
+            },
+            "git.branchProtection": [
+                "main",
+                "master"
+            ]
+        }
+    },
+    "remoteUser": "vscode"
+}

pycmdcheck-0.1.0/.devcontainer/requirements-dev.txt

@@ -0,0 +1,5 @@
+cookiecutter>=2.6.0
+pytest>=8.2.0
+ruff>=0.4.4
+black>=24.4.2
+mypy>=1.10

pycmdcheck-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          # 3.10 matches [tool.mypy] python_version and installs tomli
+          # (a conditional dependency) so mypy can resolve the tomllib fallback.
+          python-version: "3.10"
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev --extra linting --extra typing-mypy
+      - name: Ruff (lint)
+        run: uv run ruff check src/ tests/
+      - name: Ruff (format)
+        run: uv run ruff format --check src/ tests/
+      - name: Mypy
+        run: uv run mypy src/pycmdcheck
+
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests
+        run: uv run pytest -q

pycmdcheck-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Test & build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests (gate the release on green)
+        run: uv run pytest -q
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment can be configured on GitHub to require manual approval
+    # before a release is published.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycmdcheck
+    permissions:
+      id-token: write  # OIDC: required for PyPI Trusted Publishing (no token)
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pycmdcheck-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# OS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Plans (keep locally, don't track)
+docs/plans/

pycmdcheck-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to pycmdcheck will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- 7 additional built-in checks (bringing the total to **20**):
+  - `community` - Checks for CONTRIBUTING and CODE_OF_CONDUCT files
+  - `ci` - Checks for CI configuration
+  - `changelog` - Checks for a CHANGELOG/NEWS/HISTORY file
+  - `citation` - Checks for a CITATION file
+  - `python_versions` - Checks `requires-python` excludes EOL Python versions
+  - `urls` - Validates project URLs are reachable
+  - `doctests` - Runs doctests via `pytest --doctest-modules`
+- Profile system with built-in profiles `minimal`, `triage`, `default`,
+  `pyopensci`, and `strict`, plus `--profile` and `--list-profiles` CLI options.
+  The new `triage` profile runs only the static, no-install/no-network checks —
+  intended for CI triage of arbitrary (un-installed) repositories.
+- Support for legacy Poetry projects (`[tool.poetry]` with no PEP 621
+  `[project]` table) across the metadata, version, python_versions, and
+  dependencies checks.
+- `structure` now recognizes PEP 420 implicit namespace packages, single-file
+  modules, and native-extension build backends (maturin/scikit-build/setuptools-rust).
+- GitHub Actions workflows: CI (lint + type-check + pytest matrix on 3.10–3.13)
+  and a tag-triggered PyPI release using Trusted Publishing (OIDC).
+- `packaging` added as a runtime dependency (accurate PEP 440 version handling).
+
+### Changed
+
+- The `formatting` check now defaults to `tool = "auto"`: it detects ruff vs
+  black from `[tool.ruff]`/`ruff.toml`/`[tool.black]` and is **skipped** when no
+  formatter is configured (previously hard-coded to ruff).
+- Many checks were made more lenient to eliminate false positives on legitimate
+  real-world packages: PEP 621 `dynamic` metadata fields, dual-license/suffixed
+  license filenames, RST/plain-text README section detection, community files in
+  `.github/`/`docs/`, single-module/re-exported `__version__`, dependency extras,
+  `pytest` "no tests collected" (exit 5) in doctests, and ruff/mypy
+  tool/config-error handling.
+
+### Fixed
+
+- `metadata` no longer reports a false ERROR for packages whose version is
+  supplied dynamically (PEP 621 `dynamic = ["version"]`, e.g. setuptools_scm /
+  hatch-vcs / uv-dynamic-versioning) or declared under legacy `[tool.poetry]`.
+
+## [0.1.0] - 2024-12-31
+
+### Added
+
+- Initial release of pycmdcheck
+- Core `check()` function for programmatic package checking
+- CLI with `pycmdcheck` command
+- 13 built-in checks:
+  - `build` - Verifies package builds (wheel/sdist)
+  - `dependencies` - Audits declared vs. actual imports
+  - `docs` - Checks for README and docstrings
+  - `formatting` - Checks code formatting (ruff format/black)
+  - `imports` - Validates imports
+  - `license` - Checks for LICENSE file
+  - `linting` - Runs ruff/flake8/pylint
+  - `metadata` - Validates pyproject.toml
+  - `py_typed` - Checks for PEP 561 py.typed marker
+  - `structure` - Validates package structure
+  - `tests` - Runs pytest/unittest
+  - `typing` - Runs mypy/pyright
+  - `version` - Verifies version consistency
+- Configuration via `[tool.pycmdcheck]` in pyproject.toml
+- Plugin system via entry points for custom checks
+- Parallel check execution
+- Rich terminal output with colors and tables
+- JSON output format for CI integration
+- `CheckResult`, `CheckStatus`, and `Report` classes
+- `BaseCheck` abstract class for custom check development

pycmdcheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pycmdcheck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycmdcheck-0.1.0/PKG-INFO

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: pycmdcheck
+Version: 0.1.0
+Summary: Python package quality checker inspired by R CMD check
+Project-URL: Homepage, https://github.com/pycmdcheck/pycmdcheck
+Project-URL: Repository, https://github.com/pycmdcheck/pycmdcheck
+Project-URL: Issues, https://github.com/pycmdcheck/pycmdcheck/issues
+Author: pycmdcheck contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: check,lint,package,quality,test
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: mypy>=1.0; extra == 'all'
+Requires-Dist: pyright>=1.1; extra == 'all'
+Requires-Dist: ruff>=0.1; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: quartodoc>=0.7; extra == 'docs'
+Provides-Extra: linting
+Requires-Dist: ruff>=0.1; extra == 'linting'
+Provides-Extra: typing-mypy
+Requires-Dist: mypy>=1.0; extra == 'typing-mypy'
+Provides-Extra: typing-pyright
+Requires-Dist: pyright>=1.1; extra == 'typing-pyright'
+Description-Content-Type: text/markdown
+
+# pycmdcheck
+
+A Python package quality checker inspired by R's `R CMD check`.
+
+## Installation
+
+> **Note:** pycmdcheck is not yet published to PyPI. Install it directly from
+> GitHub for now. Once it is released, `pip install pycmdcheck` will work too.
+
+```bash
+pip install git+https://github.com/coatless-py-pkg/pycmdcheck
+```
+
+Or with uv:
+
+```bash
+uv pip install git+https://github.com/coatless-py-pkg/pycmdcheck
+```
+
+To pin a specific branch, tag, or commit, append `@<ref>` to the URL — for
+example `git+https://github.com/coatless-py-pkg/pycmdcheck@main`.
+
+### Optional dependencies
+
+pycmdcheck can use external tools for linting and type checking. Request the
+matching extra in the install command. For a GitHub install, the extra goes in
+the PEP 508 `pycmdcheck[extra] @ <url>` form:
+
+```bash
+# For mypy type checking
+pip install "pycmdcheck[typing-mypy] @ git+https://github.com/coatless-py-pkg/pycmdcheck"
+
+# For pyright type checking
+pip install "pycmdcheck[typing-pyright] @ git+https://github.com/coatless-py-pkg/pycmdcheck"
+
+# For ruff linting
+pip install "pycmdcheck[linting] @ git+https://github.com/coatless-py-pkg/pycmdcheck"
+
+# All optional dependencies
+pip install "pycmdcheck[all] @ git+https://github.com/coatless-py-pkg/pycmdcheck"
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Check current directory
+pycmdcheck
+
+# Check a specific directory
+pycmdcheck /path/to/package
+
+# Run only specific checks
+pycmdcheck -c metadata -c tests
+
+# Skip specific checks
+pycmdcheck -s typing -s linting
+
+# Fail on warnings too
+pycmdcheck --fail-on error --fail-on warning
+
+# List available checks
+pycmdcheck --list
+
+# JSON output
+pycmdcheck --json
+
+# Stop after first error (fail fast)
+pycmdcheck -x
+pycmdcheck --fail-fast
+
+# Verbose output with details
+pycmdcheck -v
+
+# Use a check profile
+pycmdcheck --profile pyopensci
+pycmdcheck --profile minimal
+pycmdcheck --profile strict
+
+# List available profiles
+pycmdcheck --list-profiles
+```
+
+### With uv
+
+```bash
+uv run pycmdcheck
+uv run pycmdcheck -c tests -c linting
+```
+
+### Python API
+
+```python
+from pycmdcheck import check, CheckStatus
+
+# Check current directory
+report = check(".")
+
+# Check specific directory
+report = check("/path/to/package")
+
+# Run only specific checks
+report = check(".", checks=["metadata", "tests"])
+
+# Skip specific checks
+report = check(".", skip=["linting", "typing"])
+
+# Check results
+if report.passed:
+    print("All checks passed!")
+else:
+    for result in report.results:
+        print(f"{result.status}: {result.name} - {result.message}")
+
+# Get counts by status
+counts = report.count_by_status()
+print(f"OK: {counts[CheckStatus.OK]}, Errors: {counts[CheckStatus.ERROR]}")
+
+# JSON output
+import json
+print(json.dumps(report.to_dict(), indent=2))
+```
+
+## Built-in Checks
+
+### Core checks
+
+| Check | Description |
+|-------|-------------|
+| `build` | Verifies the package builds successfully (wheel/sdist) |
+| `dependencies` | Audits declared vs. actual imports, warns on unbounded versions |
+| `docs` | Checks for README (content sections, word count) and docstrings |
+| `formatting` | Checks code formatting (ruff format/black) |
+| `imports` | Validates all imports can be resolved |
+| `license` | Checks for LICENSE file and OSI-approved license validation |
+| `linting` | Runs ruff, flake8, or pylint |
+| `metadata` | Validates pyproject.toml fields (required, recommended, extended) |
+| `py_typed` | Checks for PEP 561 py.typed marker |
+| `structure` | Checks package directory structure (src or flat layout) |
+| `tests` | Runs pytest or unittest and reports results |
+| `typing` | Runs mypy or pyright type checker |
+| `version` | Verifies version consistency between pyproject.toml and code |
+
+### pyOpenSci / community checks
+
+| Check | Description |
+|-------|-------------|
+| `changelog` | Checks for CHANGELOG, NEWS, or HISTORY file |
+| `ci` | Checks for CI configuration (GitHub Actions, CircleCI, etc.) |
+| `citation` | Checks for CITATION.cff or CITATION.bib file |
+| `community` | Checks for CONTRIBUTING.md and CODE_OF_CONDUCT.md |
+| `doctests` | Runs doctests via pytest --doctest-modules |
+| `python_versions` | Checks requires-python excludes EOL Python versions |
+| `urls` | Validates project URLs in metadata are reachable |
+
+## Profiles
+
+Profiles bundle checks for common use cases:
+
+| Profile | Description | Checks |
+|---------|-------------|--------|
+| `minimal` | Quick sanity checks | metadata, structure, license |
+| `triage` | Static checks only — no install, external tools, or network (for CI triage of arbitrary repos) | All static checks (excludes tests, imports, dependencies, build, linting, typing, formatting, doctests, urls) |
+| `default` | Standard quality checks | All 13 core checks |
+| `pyopensci` | pyOpenSci onboarding | All 20 checks with stricter docs settings |
+| `strict` | Maximum strictness | All 20 checks with strict typing |
+
+```bash
+# Run pyOpenSci onboarding checks
+pycmdcheck --profile pyopensci
+
+# Static-only triage (safe to run on an un-installed repo in CI)
+pycmdcheck --profile triage
+
+# Quick check before committing
+pycmdcheck --profile minimal
+```
+
+Profiles can be combined with `--skip` to exclude specific checks:
+
+```bash
+pycmdcheck --profile pyopensci -s urls -s doctests
+```
+
+## Configuration
+
+Configure pycmdcheck in your `pyproject.toml`:
+
+```toml
+[tool.pycmdcheck]
+# Fail on these statuses (default: ["error"])
+fail_on = ["error", "warning"]
+
+[tool.pycmdcheck.checks]
+# Enable/disable checks with boolean
+metadata = true
+structure = true
+imports = true
+license = true
+
+# Configure checks with options
+tests = { enabled = true, runner = "pytest" }
+linting = { enabled = true, tool = "ruff" }
+typing = { enabled = true, tool = "mypy", strict = false }
+# formatting "tool" defaults to "auto": detects ruff vs black from
+# [tool.ruff]/ruff.toml or [tool.black]; skips if neither is configured.
+formatting = { enabled = true, tool = "auto" }
+docs = { enabled = true, require_readme = true, check_docstrings = false, check_readme_sections = false }
+
+# New checks (disabled by default in "default" profile)
+community = true
+ci = true
+changelog = true
+citation = true
+python_versions = true
+urls = { enabled = true, timeout = 10 }
+doctests = true
+```
+
+### Linting tools
+
+Supported linting tools:
+- `ruff` (default, recommended)
+- `flake8`
+- `pylint`
+
+```toml
+[tool.pycmdcheck.checks.linting]
+tool = "ruff"
+args = ["--select=E,F,W"]
+```
+
+### Build options
+
+```toml
+[tool.pycmdcheck.checks.build]
+timeout = 300  # seconds (default: 120)
+args = ["--wheel"]
+```
+
+### Type checking tools
+
+Supported type checkers:
+- `mypy` (default)
+- `pyright`
+
+```toml
+[tool.pycmdcheck.checks.typing]
+tool = "pyright"
+strict = true
+```
+
+## Custom Checks
+
+Create custom checks by implementing the `Check` protocol:
+
+```python
+from pathlib import Path
+from typing import Any
+from pycmdcheck.checks.base import BaseCheck
+from pycmdcheck.results import CheckResult, CheckStatus
+
+class MyCustomCheck(BaseCheck):
+    name = "my_custom_check"
+    description = "My custom quality check"
+
+    def run(self, package_path: Path, config: dict[str, Any]) -> CheckResult:
+        # Your check logic here
+        issues = []  # ... populate with any issues found
+        if not issues:
+            return CheckResult(
+                name=self.name,
+                status=CheckStatus.OK,
+                message="All good!",
+            )
+        return CheckResult(
+            name=self.name,
+            status=CheckStatus.ERROR,
+            message="Something is wrong",
+            details=issues,
+        )
+```
+
+Register your check via entry points in `pyproject.toml`:
+
+```toml
+[project.entry-points."pycmdcheck.checks"]
+my_custom_check = "my_package.checks:MyCustomCheck"
+```
+
+## Check Statuses
+
+| Status | Symbol | Description |
+|--------|--------|-------------|
+| OK | ✓ | Check passed |
+| NOTE | ℹ | Minor observation, not a problem |
+| WARNING | ⚠ | Potential issue, should be reviewed |
+| ERROR | ✗ | Check failed |
+| SKIPPED | ○ | Check was skipped (e.g., tool not installed) |
+
+## License
+
+MIT