dlen 0.1.0__py3-none-any.whl

dlen/__init__.py

@@ -0,0 +1,13 @@
+"""dlen — check how long your functions and classes are."""
+
+from .core import Code, Finding, Level, Limits, check_file, check_paths, check_source
+
+__all__ = [
+    "Code",
+    "Finding",
+    "Level",
+    "Limits",
+    "check_file",
+    "check_paths",
+    "check_source",
+]

dlen/cli.py

@@ -0,0 +1,89 @@
+"""The command line: parses arguments, renders findings, picks the exit code.
+
+This is the only module that prints or reads argv. The core stays a pure function
+of its inputs, which is what makes it usable from another program.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from .core import Finding, Level, Limits, check_paths
+
+DEFAULTS = Limits()
+
+
+def format_full(findings: Sequence[Finding]) -> str:
+    """One line per finding, the shape editors and CI logs already know how to parse."""
+    return "\n".join(f"{f.path}:{f.line}:{f.column}: {f.code.value} {f.message}" for f in findings)
+
+
+def format_github(findings: Sequence[Finding]) -> str:
+    """Workflow commands, so the findings land on the PR diff instead of in a log."""
+    return "\n".join(
+        f"::{f.level.value} file={f.path},line={f.line},col={f.column},"
+        f"title={f.code.value}::{f.message}"
+        for f in findings
+    )
+
+
+def _as_dict(finding: Finding) -> dict[str, str | int]:
+    return {
+        "path": str(finding.path),
+        "line": finding.line,
+        "column": finding.column,
+        "code": finding.code.value,
+        "level": finding.level.value,
+        "message": finding.message,
+    }
+
+
+def format_json(findings: Sequence[Finding]) -> str:
+    return json.dumps([_as_dict(f) for f in findings], indent=2)
+
+
+FORMATTERS = {"full": format_full, "github": format_github, "json": format_json}
+
+
+def _add_limit(parser: argparse.ArgumentParser, flag: str, default: int, verb: str) -> None:
+    parser.add_argument(
+        flag,
+        type=int,
+        default=default,
+        metavar="N",
+        help=f"{verb} above N lines (default: {default})",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dlen", description="Check how long your functions and classes are."
+    )
+    parser.add_argument("paths", nargs="+", type=Path, metavar="PATH", help="files or directories")
+    _add_limit(parser, "--warn-function", DEFAULTS.warn_function, "warn")
+    _add_limit(parser, "--max-function", DEFAULTS.max_function, "fail")
+    _add_limit(parser, "--max-class", DEFAULTS.max_class, "fail")
+    parser.add_argument(
+        "--output-format", choices=sorted(FORMATTERS), default="full", metavar="FORMAT"
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Returns the exit code: 1 when anything is over a max, 0 otherwise."""
+    args = build_parser().parse_args(argv)
+    limits = Limits(args.warn_function, args.max_function, args.max_class)
+
+    findings = check_paths(args.paths, limits)
+    if findings:
+        print(FORMATTERS[args.output_format](findings))
+
+    return 1 if any(f.level is Level.ERROR for f in findings) else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

dlen/core.py

@@ -0,0 +1,130 @@
+"""Measuring how long a function or a class is, and deciding whether that is too long.
+
+Everything here returns data. Nothing prints, nothing reads argv, nothing keeps state
+between calls — so a second run can never inherit the first one's findings.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class Level(str, Enum):
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class Code(str, Enum):
+    FUNCTION_TOO_LONG = "DL001"
+    CLASS_TOO_LONG = "DL002"
+    SYNTAX_ERROR = "DL900"
+
+
+@dataclass(frozen=True, slots=True)
+class Limits:
+    """The three thresholds, defaulting to the ones dlen has used since 2017."""
+
+    warn_function: int = 12
+    max_function: int = 20
+    max_class: int = 500
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    path: Path
+    line: int
+    column: int
+    code: Code
+    level: Level
+    message: str
+
+
+Definition = ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef
+Function = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+def _span(node: Definition) -> int:
+    """Lines the node covers, decorators included — they are part of what you read."""
+    start = min([node.lineno, *(d.lineno for d in node.decorator_list)])
+    end = node.end_lineno if node.end_lineno is not None else node.lineno
+    return end - start + 1
+
+
+def _finding(node: Definition, path: Path, code: Code, level: Level, text: str) -> Finding:
+    return Finding(path, node.lineno, node.col_offset + 1, code, level, text)
+
+
+def _describe(kind: str, name: str, length: int, limit: int, level: Level) -> str:
+    threshold = "max" if level is Level.ERROR else "warn"
+    return f"{kind} {name!r} is {length} lines ({threshold} {limit})"
+
+
+def _check_function(node: Function, path: Path, limits: Limits) -> Finding | None:
+    length = _span(node)
+    if length > limits.max_function:
+        level, limit = Level.ERROR, limits.max_function
+    elif length > limits.warn_function:
+        level, limit = Level.WARNING, limits.warn_function
+    else:
+        return None
+    text = _describe("function", node.name, length, limit, level)
+    return _finding(node, path, Code.FUNCTION_TOO_LONG, level, text)
+
+
+def _check_class(node: ast.ClassDef, path: Path, limits: Limits) -> Finding | None:
+    length = _span(node)
+    if length <= limits.max_class:
+        return None
+    text = _describe("class", node.name, length, limits.max_class, Level.ERROR)
+    return _finding(node, path, Code.CLASS_TOO_LONG, Level.ERROR, text)
+
+
+def _syntax_finding(exc: SyntaxError, path: Path) -> Finding:
+    line, column = exc.lineno or 1, exc.offset or 1
+    message = f"cannot parse: {exc.msg}"
+    return Finding(path, line, column, Code.SYNTAX_ERROR, Level.ERROR, message)
+
+
+def check_source(source: str, path: Path, limits: Limits) -> list[Finding]:
+    """Findings for one piece of source, in the order they appear in the file."""
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        return [_syntax_finding(exc, path)]
+
+    findings = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            found = _check_class(node, path, limits)
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            found = _check_function(node, path, limits)
+        else:
+            continue
+        if found is not None:
+            findings.append(found)
+
+    return sorted(findings, key=lambda f: (f.line, f.column))
+
+
+def check_file(path: Path, limits: Limits) -> list[Finding]:
+    """Findings for one file. An unreadable file is a finding, not a crash."""
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return [Finding(path, 1, 1, Code.SYNTAX_ERROR, Level.ERROR, f"cannot read: {exc}")]
+    return check_source(source, path, limits)
+
+
+def iter_python_files(paths: list[Path]) -> list[Path]:
+    """Every .py under the given paths, deduplicated and in a stable order."""
+    found: list[Path] = []
+    for path in paths:
+        found.extend(sorted(path.rglob("*.py")) if path.is_dir() else [path])
+    return list(dict.fromkeys(found))
+
+
+def check_paths(paths: list[Path], limits: Limits) -> list[Finding]:
+    return [finding for path in iter_python_files(paths) for finding in check_file(path, limits)]

dlen-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: dlen
+Version: 0.1.0
+Summary: Check how long your functions and classes are
+Project-URL: Homepage, https://github.com/Endika/dlen
+Project-URL: Repository, https://github.com/Endika/dlen
+Project-URL: Issues, https://github.com/Endika/dlen/issues
+Project-URL: Changelog, https://github.com/Endika/dlen/blob/main/CHANGELOG.md
+Author-email: Endika Iglesias <endika2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code-quality,complexity,linter,refactoring,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# dlen
+
+Check how long your functions and classes are.
+
+A long function is the cheapest smell to detect and the most reliable one to act on.
+`dlen` tells you which ones crossed the line, and where.
+
+```console
+$ dlen src/
+src/importer.py:42:1: DL001 function 'process_batch' is 34 lines (max 20)
+src/importer.py:88:5: DL001 function 'validate' is 14 lines (warn 12)
+src/models.py:7:1: DL002 class 'LegacyRecord' is 812 lines (max 500)
+```
+
+## Install
+
+```console
+uv tool install dlen     # or: pipx install dlen, pip install dlen
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Use
+
+```console
+dlen src/ tests/                 # files, directories, or both
+dlen . --max-function 30         # your project, your thresholds
+dlen . --output-format=json      # for other tools
+```
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--warn-function N` | 12 | report a function above N lines, without failing |
+| `--max-function N` | 20 | fail on a function above N lines |
+| `--max-class N` | 500 | fail on a class above N lines |
+| `--output-format` | `full` | `full`, `github` or `json` |
+
+A function's length includes its decorators — they are part of what you read before
+you understand it.
+
+### Exit codes
+
+| Code | When |
+| --- | --- |
+| `0` | nothing found, or only warnings |
+| `1` | something was over a `max`, or a file could not be parsed |
+| `2` | bad arguments |
+
+Warnings never fail the build. That is the point of having two thresholds: one to
+nudge, one to stop.
+
+### Rules
+
+| Code | Rule |
+| --- | --- |
+| `DL001` | function is too long |
+| `DL002` | class is too long |
+| `DL900` | file could not be read or parsed |
+
+## In CI
+
+`--output-format=github` puts each finding on the diff of the pull request instead
+of burying it in a log:
+
+```yaml
+- run: uvx dlen src --output-format=github
+```
+
+## As a library
+
+The core returns data and prints nothing, so you can build your own reporting on it:
+
+```python
+from pathlib import Path
+from dlen import Limits, check_paths
+
+findings = check_paths([Path("src")], Limits(max_function=30))
+for finding in findings:
+    print(finding.code, finding.path, finding.line, finding.message)
+```
+
+Every call returns a fresh list. Two runs never see each other's findings.
+
+## How it measures
+
+`dlen` parses your code with Python's own `ast` module, so it agrees with Python
+about what a function is. It sees `async def`, decorators, nested functions and
+methods, and it is not fooled by the word `def` inside a string or a comment.
+
+> Versions before 0.1.0 matched text with regular expressions and had been broken on
+> Python 3 since 2017. 0.1.0 is a rewrite: the counts are now correct rather than
+> compatible, and the output carries file, line and column.
+
+## Licence
+
+MIT.

dlen-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dlen/__init__.py,sha256=3RSReGaLufqvd_kqrOc_59eDXLTVk-O1uE5uHVLkVOc,275
+dlen/cli.py,sha256=SpWR8lbrCO1SwhXTzn0wW-MT6DT49ZkkekeDuX0-6UE,2891
+dlen/core.py,sha256=c4VQjt4zVpmDIKGiIUW-eOyWF0V1x4ZsDjv_K-THgj8,4350
+dlen/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dlen-0.1.0.dist-info/METADATA,sha256=Fp5YQxsg3kq5Y7SkKGzpLgybOiDIYiAM9XOqy22ZYcQ,3832
+dlen-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+dlen-0.1.0.dist-info/entry_points.txt,sha256=nZ54_Po3rqunCEk8IwyJJdsl0sYzSOMg5inEQMYkFvI,39
+dlen-0.1.0.dist-info/licenses/LICENSE,sha256=kDv_kGy0hM0TIgTJeWx0FzVESJ3AX2StwGMx6QW1hs4,1072
+dlen-0.1.0.dist-info/RECORD,,

dlen-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dlen-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dlen = dlen.cli:main

dlen-0.1.0.dist-info/licenses/LICENSE

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