dlen 0.0.2__tar.gz → 0.2.0__tar.gz

dlen-0.2.0/.gitignore

@@ -0,0 +1,101 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/

dlen-0.2.0/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.

dlen-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: dlen
+Version: 0.2.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` | 30 | report a function above N lines, without failing |
+| `--max-function N` | 50 | 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.
+
+### Where the defaults come from
+
+They were measured, not chosen. Across 29,000 functions in the Python standard library,
+numpy, Pillow, rich, pytest, httpx, mypy and coverage:
+
+| | median | p75 | p90 | over 20 lines |
+| --- | --- | --- | --- | --- |
+| Python standard library | 7 | 14 | 30 | 16% |
+| mypy | 7 | 17 | 37 | 21% |
+| pytest | 9 | 18 | 34 | 22% |
+| httpx | 9 | 19 | 34 | 23% |
+| rich | 10 | 22 | 41 | 27% |
+| Pillow | 10 | 23 | 51 | 27% |
+| numpy | 14 | 46 | 82 | 43% |
+
+The median function out there is 7 to 14 lines, which is reassuring and remarkably stable
+across eight independent codebases. The tail is what a default has to answer to: a limit
+of 20 flags a sixth of the standard library and a quarter of rich. That is not a warning,
+it is a wall — and a tool that fires on a quarter of your code gets uninstalled on the
+first day.
+
+At 50 — the number `pylint` and `ruff` already use for statements — you flag around 5%.
+That is a list you can work through on a Tuesday.
+
+The class limit is a different story: 500 fires on about 1% of standard library classes,
+and when it fires it is right. It stays where it was.
+
+If you want the stricter Clean Code reading, it is one flag away:
+
+```console
+dlen src/ --warn-function 12 --max-function 20
+```
+
+Versions before 0.2.0 shipped 12 and 20 as the defaults.
+
+### 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.2.0/README.md

@@ -0,0 +1,131 @@
+# 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` | 30 | report a function above N lines, without failing |
+| `--max-function N` | 50 | 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.
+
+### Where the defaults come from
+
+They were measured, not chosen. Across 29,000 functions in the Python standard library,
+numpy, Pillow, rich, pytest, httpx, mypy and coverage:
+
+| | median | p75 | p90 | over 20 lines |
+| --- | --- | --- | --- | --- |
+| Python standard library | 7 | 14 | 30 | 16% |
+| mypy | 7 | 17 | 37 | 21% |
+| pytest | 9 | 18 | 34 | 22% |
+| httpx | 9 | 19 | 34 | 23% |
+| rich | 10 | 22 | 41 | 27% |
+| Pillow | 10 | 23 | 51 | 27% |
+| numpy | 14 | 46 | 82 | 43% |
+
+The median function out there is 7 to 14 lines, which is reassuring and remarkably stable
+across eight independent codebases. The tail is what a default has to answer to: a limit
+of 20 flags a sixth of the standard library and a quarter of rich. That is not a warning,
+it is a wall — and a tool that fires on a quarter of your code gets uninstalled on the
+first day.
+
+At 50 — the number `pylint` and `ruff` already use for statements — you flag around 5%.
+That is a list you can work through on a Tuesday.
+
+The class limit is a different story: 500 fires on about 1% of standard library classes,
+and when it fires it is right. It stays where it was.
+
+If you want the stricter Clean Code reading, it is one flag away:
+
+```console
+dlen src/ --warn-function 12 --max-function 20
+```
+
+Versions before 0.2.0 shipped 12 and 20 as the defaults.
+
+### 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.2.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dlen"
+version = "0.2.0"
+description = "Check how long your functions and classes are"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Endika Iglesias", email = "endika2@gmail.com" }]
+keywords = ["linter", "refactoring", "code-quality", "static-analysis", "complexity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Endika/dlen"
+Repository = "https://github.com/Endika/dlen"
+Issues = "https://github.com/Endika/dlen/issues"
+Changelog = "https://github.com/Endika/dlen/blob/main/CHANGELOG.md"
+
+[project.scripts]
+dlen = "dlen.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dlen"]
+artifacts = ["src/dlen/py.typed"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/dlen", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # import sorting
+    "UP",        # pyupgrade
+    "B",         # bugbear
+    "SIM",       # simplify
+    "C4",        # comprehensions
+    "RET",       # returns
+    "PTH",       # use pathlib
+    "ARG",       # unused arguments
+    "TID",       # tidy imports
+    "RUF",
+]
+
+[tool.mypy]
+# No python_version pin: it only ever makes mypy parse modern stubs with older rules.
+# The 3.10 floor is proven by the CI test matrix instead.
+strict = true
+warn_unreachable = true
+show_error_codes = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --strict-markers --strict-config"
+
+[tool.coverage.run]
+source = ["dlen"]
+
+[tool.coverage.report]
+exclude_also = ["if __name__ == .__main__.:"]

dlen-0.2.0/src/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-0.2.0/src/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())