pyproject-lens 0.1.0__tar.gz

pyproject_lens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam
+
+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.

pyproject_lens-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: pyproject-lens
+Version: 0.1.0
+Summary: A small health scanner for Python projects.
+Author: Sam
+License: MIT
+Project-URL: Homepage, https://github.com/Sam3360/pyproject-lens
+Project-URL: Repository, https://github.com/Sam3360/pyproject-lens
+Project-URL: Issues, https://github.com/Sam3360/pyproject-lens/issues
+Keywords: python,cli,project,pyproject,health
+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 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli; python_version < "3.11"
+Dynamic: license-file
+
+# pyproject-lens
+
+A small, free health scanner for Python projects. Point it at a folder and it checks the basics: packaging metadata, imports versus declared dependencies, Python-version claims, project layout, and Git hygiene.
+
+It is built for the first ten seconds of project review — not to replace Ruff, pytest, Bandit, or a human code review.
+
+## Install
+
+```bash
+pip install pyproject-lens
+```
+
+## Use it
+
+```bash
+pyproject-lens .
+pyproject-lens ./another-project --json report.json
+pyproject-lens . --markdown report.md
+pyproject-lens . --ci --minimum-score 75
+```
+
+You can also use it in Python:
+
+```python
+from pyproject_lens import analyze
+
+report = analyze(".")
+print(report.score)
+print(report.to_json())
+```
+
+## What the score means
+
+Each of the five sections starts at 100. Detected issues reduce only the relevant section, and the project score is the rounded average. The rules are deliberately simple and visible in `src/pyproject_lens/analyzers.py`; it is a conversation starter, not a grade.
+
+## Scope for version 0.1
+
+- Packaging: `pyproject.toml`, project name, Python version, README
+- Dependencies: direct source imports compared with `project.dependencies`
+- Compatibility: detects `match/case` used with a Python claim below 3.10
+- Structure: `src/`, packages, root modules, and tests directory
+- Repository hygiene: `.gitignore` and uncommitted changes
+
+Everything is free and open source under the MIT license.
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+Contributions are welcome. Please keep checks practical, explain what they found, and avoid claiming certainty when static analysis cannot prove something.

pyproject_lens-0.1.0/README.md

@@ -0,0 +1,53 @@
+# pyproject-lens
+
+A small, free health scanner for Python projects. Point it at a folder and it checks the basics: packaging metadata, imports versus declared dependencies, Python-version claims, project layout, and Git hygiene.
+
+It is built for the first ten seconds of project review — not to replace Ruff, pytest, Bandit, or a human code review.
+
+## Install
+
+```bash
+pip install pyproject-lens
+```
+
+## Use it
+
+```bash
+pyproject-lens .
+pyproject-lens ./another-project --json report.json
+pyproject-lens . --markdown report.md
+pyproject-lens . --ci --minimum-score 75
+```
+
+You can also use it in Python:
+
+```python
+from pyproject_lens import analyze
+
+report = analyze(".")
+print(report.score)
+print(report.to_json())
+```
+
+## What the score means
+
+Each of the five sections starts at 100. Detected issues reduce only the relevant section, and the project score is the rounded average. The rules are deliberately simple and visible in `src/pyproject_lens/analyzers.py`; it is a conversation starter, not a grade.
+
+## Scope for version 0.1
+
+- Packaging: `pyproject.toml`, project name, Python version, README
+- Dependencies: direct source imports compared with `project.dependencies`
+- Compatibility: detects `match/case` used with a Python claim below 3.10
+- Structure: `src/`, packages, root modules, and tests directory
+- Repository hygiene: `.gitignore` and uncommitted changes
+
+Everything is free and open source under the MIT license.
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+Contributions are welcome. Please keep checks practical, explain what they found, and avoid claiming certainty when static analysis cannot prove something.

pyproject_lens-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyproject-lens"
+version = "0.1.0"
+description = "A small health scanner for Python projects."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["tomli; python_version < '3.11'"]
+license = {text = "MIT"}
+authors = [{name = "Sam"}]
+keywords = ["python", "cli", "project", "pyproject", "health"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+pyproject-lens = "pyproject_lens.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Sam3360/pyproject-lens"
+Repository = "https://github.com/Sam3360/pyproject-lens"
+Issues = "https://github.com/Sam3360/pyproject-lens/issues"
+
+[tool.pyproject-lens]
+minimum_score = 0
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyproject_lens-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyproject_lens-0.1.0/src/pyproject_lens/__init__.py

@@ -0,0 +1,7 @@
+"""Public API for pyproject-lens."""
+
+from .analyzers import analyze
+from .models import Finding, Report, Section
+
+__all__ = ["analyze", "Finding", "Report", "Section"]
+__version__ = "0.1.0"

pyproject_lens-0.1.0/src/pyproject_lens/analyzers.py

@@ -0,0 +1,163 @@
+"""The intentionally small, dependency-free project checks."""
+
+from __future__ import annotations
+
+import ast
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.9/3.10
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from .models import Report, Section
+
+SKIP_DIRS = {".git", ".venv", "venv", "__pycache__", "build", "dist", ".tox", ".mypy_cache"}
+STDLIB = set(getattr(sys, "stdlib_module_names", ()))
+
+
+def _python_files(root: Path) -> list[Path]:
+    return [path for path in root.rglob("*.py") if not any(part in SKIP_DIRS for part in path.parts)]
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as handle:
+            return tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def _top_level_imports(files: list[Path]) -> set[str]:
+    imports: set[str] = set()
+    for file in files:
+        try:
+            tree = ast.parse(file.read_text(encoding="utf-8"), filename=str(file))
+        except (OSError, UnicodeDecodeError, SyntaxError):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imports.update(name.name.split(".")[0] for name in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+                imports.add(node.module.split(".")[0])
+    return imports
+
+
+def _distribution_name(value: str) -> str:
+    return re.split(r"[<>=!~;[ ]", value, maxsplit=1)[0].lower().replace("_", "-")
+
+
+def _packaging(root: Path, config: dict[str, Any]) -> Section:
+    section = Section("Packaging")
+    pyproject = root / "pyproject.toml"
+    project = config.get("project", {})
+    if not pyproject.exists():
+        section.score = 30
+        section.add("warning", "No pyproject.toml found.", "Add one to describe how your project is built.")
+        return section
+    if not config:
+        section.score = 45
+        section.add("error", "pyproject.toml could not be read.", "Check its TOML syntax.", "pyproject.toml")
+    if not project.get("name"):
+        section.score -= 20
+        section.add("warning", "Project name is missing.", "Set project.name in pyproject.toml.", "pyproject.toml")
+    if not project.get("requires-python"):
+        section.score -= 15
+        section.add("warning", "Supported Python versions are not declared.", "Set project.requires-python.", "pyproject.toml")
+    if not (root / "README.md").exists() and not project.get("readme"):
+        section.score -= 15
+        section.add("warning", "No README was found.", "Add a short README with install and usage instructions.")
+    return section
+
+
+def _dependencies(root: Path, config: dict[str, Any], files: list[Path]) -> Section:
+    section = Section("Dependencies")
+    declared = {_distribution_name(item) for item in config.get("project", {}).get("dependencies", [])}
+    imports = _top_level_imports(files)
+    local = {path.stem for path in files}
+    for file in files:
+        try:
+            relative = file.relative_to(root)
+        except ValueError:
+            continue
+        local.update(part for part in relative.parts[:-1] if part not in {"src", "tests"})
+    missing = sorted(name for name in imports if name not in STDLIB and name not in local and name.replace("_", "-") not in declared)
+    if missing:
+        section.score -= min(45, 10 * len(missing))
+        for name in missing[:8]:
+            section.add("warning", f"'{name}' is imported but not declared.", "Add it to project.dependencies if it is a runtime dependency.")
+    if (root / "requirements.txt").exists() and not declared:
+        section.score -= 10
+        section.add("info", "requirements.txt exists but project.dependencies is empty.", "Consider keeping runtime dependencies in pyproject.toml.")
+    return section
+
+
+def _compatibility(config: dict[str, Any], files: list[Path]) -> Section:
+    section = Section("Python compatibility")
+    requires = config.get("project", {}).get("requires-python", "")
+    uses_match = False
+    for file in files:
+        try:
+            uses_match |= any(isinstance(node, ast.Match) for node in ast.walk(ast.parse(file.read_text(encoding="utf-8"))))
+        except (OSError, UnicodeDecodeError, SyntaxError):
+            continue
+    if uses_match and re.search(r">=3\.(?:[0-9]|10)\b", requires) and not re.search(r">=3\.(?:1[0-9]|[2-9][0-9])\b", requires):
+        section.score = 60
+        section.add("warning", "match/case syntax needs Python 3.10+.", "Raise requires-python to >=3.10 or avoid match/case.")
+    elif not requires:
+        section.score = 80
+        section.add("info", "Compatibility cannot be checked without requires-python.", "Declare supported Python versions in pyproject.toml.")
+    return section
+
+
+def _structure(root: Path, files: list[Path]) -> Section:
+    section = Section("Project structure")
+    source_root = root / "src"
+    packages = [path for path in (source_root if source_root.is_dir() else root).iterdir() if path.is_dir() and (path / "__init__.py").exists()]
+    if source_root.is_dir() and not packages:
+        section.score -= 25
+        section.add("warning", "src/ exists but no package was detected.", "Put your package in src/ with an __init__.py file.", "src")
+    top_level = [path for path in files if path.parent == root and path.name not in {"setup.py", "conftest.py"}]
+    if len(top_level) > 6:
+        section.score -= 15
+        section.add("info", f"{len(top_level)} Python files live at the project root.", "Consider grouping application code into a package.")
+    tests = root / "tests"
+    if not tests.exists():
+        section.score -= 20
+        section.add("warning", "No tests/ directory found.", "Start with a small tests/ directory for important behavior.")
+    return section
+
+
+def _git_health(root: Path) -> Section:
+    section = Section("Repository hygiene")
+    if not (root / ".git").exists():
+        section.score = 80
+        section.add("info", "This directory is not a Git repository.", "Initialize Git before sharing or releasing the project.")
+        return section
+    if not (root / ".gitignore").exists():
+        section.score -= 20
+        section.add("warning", "No .gitignore found.", "Ignore virtual environments, caches, and build output.")
+    try:
+        result = subprocess.run(["git", "status", "--porcelain"], cwd=root, text=True, capture_output=True, timeout=3, check=False)
+        changes = result.stdout.splitlines()
+        if changes:
+            section.score -= min(20, len(changes))
+            section.add("info", f"{len(changes)} uncommitted Git change(s).", "Commit or stash work when you reach a clean checkpoint.")
+    except (OSError, subprocess.TimeoutExpired):
+        section.add("info", "Git status could not be checked.")
+    return section
+
+
+def analyze(path: str | Path = ".") -> Report:
+    """Analyze a project directory and return a report. Never changes the project."""
+    root = Path(path).expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError(f"Not a directory: {root}")
+    files = _python_files(root)
+    config = _read_toml(root / "pyproject.toml")
+    sections = [_packaging(root, config), _dependencies(root, config, files), _compatibility(config, files), _structure(root, files), _git_health(root)]
+    return Report(path=root, sections=sections, files_scanned=len(files))

pyproject_lens-0.1.0/src/pyproject_lens/cli.py

@@ -0,0 +1,69 @@
+"""Command line interface for pyproject-lens."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from .analyzers import analyze
+
+
+def _print_report(report: object) -> None:
+    from .models import Report
+    report = report  # keep the terminal-friendly type narrow below
+    assert isinstance(report, Report)
+    print("pyproject-lens — Project Health Report")
+    print(f"Project: {report.path.name}  |  Python files scanned: {report.files_scanned}")
+    print("=" * 58)
+    for section in report.sections:
+        print(f"\n{section.name.upper()}  {section.score}/100")
+        if not section.findings:
+            print("  OK — nothing obvious found")
+        for finding in section.findings:
+            print(f"  {finding.level.upper()}: {finding.message}")
+            if finding.recommendation:
+                print(f"    Try: {finding.recommendation}")
+    warnings = sum(item.level in {"warning", "error"} for item in report.findings)
+    print(f"\nPROJECT HEALTH: {report.score}/100  |  {warnings} warning(s)")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="A small health scanner for Python projects.")
+    parser.add_argument("path", nargs="?", default=".", help="project directory (default: current directory)")
+    parser.add_argument("--json", metavar="FILE", help="write a JSON report to FILE; use - for stdout")
+    parser.add_argument("--markdown", metavar="FILE", help="write a Markdown report to FILE; use - for stdout")
+    parser.add_argument("--ci", action="store_true", help="return an error if minimum_score is not met")
+    parser.add_argument("--minimum-score", type=int, help="score needed for --ci (overrides pyproject.toml)")
+    args = parser.parse_args(argv)
+    try:
+        report = analyze(args.path)
+    except ValueError as error:
+        parser.error(str(error))
+    if args.json:
+        text = report.to_json(None if args.json == "-" else args.json)
+        if args.json == "-":
+            print(text, end="")
+    elif args.markdown:
+        text = report.to_markdown(None if args.markdown == "-" else args.markdown)
+        if args.markdown == "-":
+            print(text, end="")
+    else:
+        _print_report(report)
+    if args.ci:
+        threshold = args.minimum_score
+        if threshold is None:
+            import tomllib
+            try:
+                with (Path(args.path) / "pyproject.toml").open("rb") as handle:
+                    threshold = tomllib.load(handle).get("tool", {}).get("pyproject-lens", {}).get("minimum_score", 0)
+            except (OSError, tomllib.TOMLDecodeError):
+                threshold = 0
+        if report.score < threshold:
+            print(f"CI FAILED: score {report.score} is below minimum_score {threshold}", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyproject_lens-0.1.0/src/pyproject_lens/models.py

@@ -0,0 +1,74 @@
+"""Small data objects used by the scanner."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+import json
+
+
+@dataclass
+class Finding:
+    level: str
+    message: str
+    recommendation: str | None = None
+    path: str | None = None
+
+
+@dataclass
+class Section:
+    name: str
+    score: int = 100
+    findings: list[Finding] = field(default_factory=list)
+
+    def add(self, level: str, message: str, recommendation: str | None = None, path: str | None = None) -> None:
+        self.findings.append(Finding(level, message, recommendation, path))
+
+
+@dataclass
+class Report:
+    path: Path
+    sections: list[Section]
+    files_scanned: int
+
+    @property
+    def score(self) -> int:
+        if not self.sections:
+            return 100
+        return round(sum(section.score for section in self.sections) / len(self.sections))
+
+    @property
+    def findings(self) -> list[Finding]:
+        return [finding for section in self.sections for finding in section.findings]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": str(self.path),
+            "score": self.score,
+            "files_scanned": self.files_scanned,
+            "sections": [asdict(section) for section in self.sections],
+        }
+
+    def to_json(self, output: str | Path | None = None) -> str:
+        text = json.dumps(self.to_dict(), indent=2) + "\n"
+        if output:
+            Path(output).write_text(text, encoding="utf-8")
+        return text
+
+    def to_markdown(self, output: str | Path | None = None) -> str:
+        lines = [f"# pyproject-lens report", "", f"**Project:** `{self.path.name}`", f"**Health:** {self.score}/100", ""]
+        for section in self.sections:
+            lines.extend([f"## {section.name} — {section.score}/100", ""])
+            if not section.findings:
+                lines.extend(["No issues detected.", ""])
+                continue
+            for finding in section.findings:
+                detail = f" — {finding.recommendation}" if finding.recommendation else ""
+                location = f" (`{finding.path}`)" if finding.path else ""
+                lines.append(f"- **{finding.level.upper()}**{location}: {finding.message}{detail}")
+            lines.append("")
+        text = "\n".join(lines)
+        if output:
+            Path(output).write_text(text, encoding="utf-8")
+        return text

pyproject_lens-0.1.0/src/pyproject_lens.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: pyproject-lens
+Version: 0.1.0
+Summary: A small health scanner for Python projects.
+Author: Sam
+License: MIT
+Project-URL: Homepage, https://github.com/Sam3360/pyproject-lens
+Project-URL: Repository, https://github.com/Sam3360/pyproject-lens
+Project-URL: Issues, https://github.com/Sam3360/pyproject-lens/issues
+Keywords: python,cli,project,pyproject,health
+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 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli; python_version < "3.11"
+Dynamic: license-file
+
+# pyproject-lens
+
+A small, free health scanner for Python projects. Point it at a folder and it checks the basics: packaging metadata, imports versus declared dependencies, Python-version claims, project layout, and Git hygiene.
+
+It is built for the first ten seconds of project review — not to replace Ruff, pytest, Bandit, or a human code review.
+
+## Install
+
+```bash
+pip install pyproject-lens
+```
+
+## Use it
+
+```bash
+pyproject-lens .
+pyproject-lens ./another-project --json report.json
+pyproject-lens . --markdown report.md
+pyproject-lens . --ci --minimum-score 75
+```
+
+You can also use it in Python:
+
+```python
+from pyproject_lens import analyze
+
+report = analyze(".")
+print(report.score)
+print(report.to_json())
+```
+
+## What the score means
+
+Each of the five sections starts at 100. Detected issues reduce only the relevant section, and the project score is the rounded average. The rules are deliberately simple and visible in `src/pyproject_lens/analyzers.py`; it is a conversation starter, not a grade.
+
+## Scope for version 0.1
+
+- Packaging: `pyproject.toml`, project name, Python version, README
+- Dependencies: direct source imports compared with `project.dependencies`
+- Compatibility: detects `match/case` used with a Python claim below 3.10
+- Structure: `src/`, packages, root modules, and tests directory
+- Repository hygiene: `.gitignore` and uncommitted changes
+
+Everything is free and open source under the MIT license.
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+Contributions are welcome. Please keep checks practical, explain what they found, and avoid claiming certainty when static analysis cannot prove something.

pyproject_lens-0.1.0/src/pyproject_lens.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/pyproject_lens/__init__.py
+src/pyproject_lens/analyzers.py
+src/pyproject_lens/cli.py
+src/pyproject_lens/models.py
+src/pyproject_lens.egg-info/PKG-INFO
+src/pyproject_lens.egg-info/SOURCES.txt
+src/pyproject_lens.egg-info/dependency_links.txt
+src/pyproject_lens.egg-info/entry_points.txt
+src/pyproject_lens.egg-info/requires.txt
+src/pyproject_lens.egg-info/top_level.txt
+tests/test_analyze.py

pyproject_lens-0.1.0/src/pyproject_lens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyproject_lens-0.1.0/src/pyproject_lens.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyproject-lens = pyproject_lens.cli:main

pyproject_lens-0.1.0/src/pyproject_lens.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[:python_version < "3.11"]
+tomli

pyproject_lens-0.1.0/src/pyproject_lens.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyproject_lens

pyproject_lens-0.1.0/tests/test_analyze.py

@@ -0,0 +1,23 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from pyproject_lens import analyze
+
+
+class AnalyzeTests(unittest.TestCase):
+    def test_analyze_returns_sections(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            (root / "pyproject.toml").write_text('[project]\nname = "demo"\nrequires-python = ">=3.10"\n')
+            (root / "README.md").write_text("# Demo")
+            (root / "src" / "demo").mkdir(parents=True)
+            (root / "src" / "demo" / "__init__.py").write_text("")
+            report = analyze(root)
+        self.assertLessEqual(report.score, 100)
+        self.assertEqual([section.name for section in report.sections], ["Packaging", "Dependencies", "Python compatibility", "Project structure", "Repository hygiene"])
+
+    def test_json_is_valid(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            report = analyze(temporary)
+        self.assertIn('"score"', report.to_json())