pydry-cli 0.0.3__py3-none-any.whl

pydry/normalize.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import ast
+import keyword
+
+
+class LocalNameNormalizer(ast.NodeTransformer):
+    def __init__(self, preserve_self_cls: bool = True) -> None:
+        self.name_map: dict[str, str] = {}
+        self.counter = 0
+        self.preserve_self_cls = preserve_self_cls
+
+    def _preserve(self, name: str) -> bool:
+        if keyword.iskeyword(name) or name in {"True", "False", "None"}:
+            return True
+        return self.preserve_self_cls and name in {"self", "cls"}
+
+    def _tok(self, name: str) -> str:
+        if name not in self.name_map:
+            self.name_map[name] = f"v{self.counter}"
+            self.counter += 1
+        return self.name_map[name]
+
+    def visit_Name(self, node: ast.Name) -> ast.Name:
+        if self._preserve(node.id):
+            return node
+        return ast.copy_location(ast.Name(id=self._tok(node.id), ctx=node.ctx), node)
+
+    def visit_arg(self, node: ast.arg) -> ast.arg:
+        if not self._preserve(node.arg):
+            node.arg = self._tok(node.arg)
+        return node
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> ast.ExceptHandler:
+        self.generic_visit(node)
+        if node.name and not self._preserve(node.name):
+            node.name = self._tok(node.name)
+        return node
+
+    def visit_Global(self, node: ast.Global) -> ast.Global:  # preserve semantics
+        return node
+
+    def visit_Nonlocal(self, node: ast.Nonlocal) -> ast.Nonlocal:  # preserve semantics
+        return node
+
+
+class ConstantNormalizer(ast.NodeTransformer):
+    def visit_Constant(self, node: ast.Constant) -> ast.Constant:
+        v = node.value
+        rep: str | bytes | bool | int | float | complex | None
+        if isinstance(v, str):
+            rep = "__str__"
+        elif isinstance(v, bytes):
+            rep = b"__bytes__"
+        elif isinstance(v, bool) or v is None:
+            rep = v
+        elif isinstance(v, int):
+            rep = 0
+        elif isinstance(v, float):
+            rep = 0.0
+        elif isinstance(v, complex):
+            rep = 0j
+        else:
+            rep = "__const__"
+        return ast.copy_location(ast.Constant(value=rep), node)
+
+
+class FunctionNormalizer(ast.NodeTransformer):
+    def __init__(
+        self,
+        *,
+        strip_docstrings: bool = True,
+        strip_decorators: bool = True,
+        normalize_arg_names: bool = True,
+        strip_annotations: bool = True,
+        normalize_local_names: bool = False,
+        normalize_constants: bool = False,
+        preserve_function_name: bool = False,
+    ) -> None:
+        self.strip_docstrings = strip_docstrings
+        self.strip_decorators = strip_decorators
+        self.normalize_arg_names = normalize_arg_names
+        self.strip_annotations = strip_annotations
+        self.normalize_local_names = normalize_local_names
+        self.normalize_constants = normalize_constants
+        self.preserve_function_name = preserve_function_name
+
+    def visit_FunctionDef(
+        self, node: ast.FunctionDef
+    ) -> ast.FunctionDef | ast.AsyncFunctionDef:
+        return self._normalize(node)
+
+    def visit_AsyncFunctionDef(
+        self, node: ast.AsyncFunctionDef
+    ) -> ast.FunctionDef | ast.AsyncFunctionDef:
+        return self._normalize(node)
+
+    def _normalize(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> ast.FunctionDef | ast.AsyncFunctionDef:
+        node = self.generic_visit(node)  # type: ignore[assignment]
+
+        if self.strip_docstrings and node.body:
+            first = node.body[0]
+            if (
+                isinstance(first, ast.Expr)
+                and isinstance(first.value, ast.Constant)
+                and isinstance(first.value.value, str)
+            ):
+                node.body = node.body[1:]
+
+        if not self.preserve_function_name:
+            node.name = "__func__"
+
+        if self.strip_decorators:
+            node.decorator_list = []
+
+        if self.strip_annotations:
+            node.returns = None
+            node.type_comment = None
+
+        ordered_args = (
+            list(node.args.posonlyargs)
+            + list(node.args.args)
+            + list(node.args.kwonlyargs)
+        )
+        if self.normalize_arg_names:
+            for i, arg in enumerate(ordered_args):
+                arg.arg = f"arg{i}"
+            if node.args.vararg:
+                node.args.vararg.arg = "vararg"
+            if node.args.kwarg:
+                node.args.kwarg.arg = "kwarg"
+
+        if self.strip_annotations:
+            for arg in ordered_args:
+                arg.annotation = None
+                arg.type_comment = None
+            if node.args.vararg:
+                node.args.vararg.annotation = None
+                node.args.vararg.type_comment = None
+            if node.args.kwarg:
+                node.args.kwarg.annotation = None
+                node.args.kwarg.type_comment = None
+
+        if self.normalize_local_names:
+            node = LocalNameNormalizer().visit(node)
+            node = ast.fix_missing_locations(node)
+
+        if self.normalize_constants:
+            node = ConstantNormalizer().visit(node)
+            node = ast.fix_missing_locations(node)
+
+        return node

pydry/plugins.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TypeVar
+
+
+@dataclass
+class PluginContext:
+    occurrence: Any
+    node: Any
+    features: dict[str, Any]
+
+
+@dataclass
+class PairContext:
+    a: PluginContext
+    b: PluginContext
+    evidence: Any
+
+
+@dataclass
+class PairPluginResult:
+    pattern_labels: list[str] = field(default_factory=list)
+    key_differences: list[str] = field(default_factory=list)
+    risk_flags: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    suggested_refactor_kind: str | None = None
+    refactorability_delta: float = 0.0
+    abstract_template: str | None = None
+
+
+class PairPlugin(Protocol):
+    name: str
+
+    def analyze_pair(self, ctx: PairContext) -> PairPluginResult: ...
+
+
+class PluginRegistry:
+    def __init__(self) -> None:
+        self._pair_plugins: list[PairPlugin] = []
+
+    def register_pair(self, plugin: PairPlugin) -> None:
+        self._pair_plugins.append(plugin)
+
+    @property
+    def pair_plugins(self) -> list[PairPlugin]:
+        return list(self._pair_plugins)
+
+
+registry = PluginRegistry()
+
+
+_T = TypeVar("_T")
+
+
+def register_pair_plugin(plugin: _T) -> _T:
+    obj: PairPlugin = plugin() if isinstance(plugin, type) else plugin  # type: ignore[assignment]
+    registry.register_pair(obj)
+    return plugin
+
+
+def _uniq(items: list[str]) -> list[str]:
+    seen = set()
+    out = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            out.append(item)
+    return out
+
+
+def apply_pair_plugins(
+    ctx: PairContext, *, plugin_errors: list[str] | None = None
+) -> PairPluginResult:
+    merged = PairPluginResult()
+    pair_errors: list[str] = []
+    for plugin in registry.pair_plugins:
+        try:
+            result = plugin.analyze_pair(ctx)
+        except Exception as exc:
+            msg = f"{plugin.name}: {type(exc).__name__}: {exc}"
+            pair_errors.append(msg)
+            if plugin_errors is not None:
+                plugin_errors.append(msg)
+            continue
+        if result is None:
+            continue
+        merged.pattern_labels.extend(result.pattern_labels)
+        merged.key_differences.extend(result.key_differences)
+        merged.risk_flags.extend(result.risk_flags)
+        merged.metadata[plugin.name] = result.metadata
+        merged.refactorability_delta += result.refactorability_delta
+        if (
+            result.suggested_refactor_kind is not None
+            and merged.suggested_refactor_kind is None
+        ):
+            merged.suggested_refactor_kind = result.suggested_refactor_kind
+        if result.abstract_template is not None and merged.abstract_template is None:
+            merged.abstract_template = result.abstract_template
+    merged.pattern_labels = _uniq(merged.pattern_labels)
+    merged.key_differences = _uniq(merged.key_differences)
+    merged.risk_flags = _uniq(merged.risk_flags)
+    if pair_errors:
+        merged.metadata["_plugin_errors"] = pair_errors
+    return merged

pydry_cli-0.0.3.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: pydry-cli
+Version: 0.0.3
+Summary: AST-based duplicate and structural similarity detector for Python
+Author: Really Him
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hesreallyhim/pydry
+Project-URL: Repository, https://github.com/hesreallyhim/pydry
+Project-URL: Issues, https://github.com/hesreallyhim/pydry/issues
+Keywords: ast,cli,code-analysis,duplicates,refactoring
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: mypy>=1.14; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# pydry
+
+`pydry` is a small Python CLI for finding exact duplicate functions and structurally similar functions in Python code.
+
+## Features
+
+- Finds exact duplicate functions using AST normalization.
+- Ranks near matches by structural similarity and refactorability.
+- Flags likely abstraction candidates and common risk signals.
+- Emits text output for quick inspection and JSON output for automation.
+- Runs without third-party runtime dependencies.
+
+## Installation
+
+```bash
+python -m pip install pydry-cli
+```
+
+For local development from a checkout:
+
+```bash
+make venv
+source venv/bin/activate
+make install
+make check
+```
+
+## Quick start
+
+Run a compact summary for the current directory:
+
+```bash
+pydry showcase
+```
+
+Find exact duplicates:
+
+```bash
+pydry exact ./src --normalize-local-names --normalize-constants
+```
+
+Find near matches:
+
+```bash
+pydry near ./src --threshold 0.85 --top-k 25
+```
+
+Write a full JSON report:
+
+```bash
+pydry report ./src --output reports/pydry-report.json
+```
+
+## Commands
+
+### `pydry exact`
+
+Find exact duplicate functions after AST normalization.
+
+```bash
+pydry exact ./src
+pydry exact ./src --min-count 3
+pydry exact ./src --normalize-local-names --normalize-constants
+pydry exact ./src --format json
+```
+
+Useful options:
+
+- `--min-count`: minimum group size, default `2`.
+- `--top-level-only`: ignore nested functions and methods.
+- `--normalize-local-names`: treat local variable renames as equivalent.
+- `--normalize-constants`: treat many literal value changes as equivalent.
+- `--include-canonical`: include canonical AST dumps in JSON output.
+- `--strict`: fail on files that cannot be read or parsed.
+
+### `pydry near`
+
+Rank structurally similar function pairs.
+
+```bash
+pydry near ./src
+pydry near ./src --threshold 0.85 --top-k 25
+pydry near ./src --format json --output reports/near.json
+```
+
+Useful options:
+
+- `--threshold`: similarity threshold from `0` to `1`, default `0.8`.
+- `--top-k`: cap the number of returned pairs.
+- `--top-level-only`: ignore nested functions and methods.
+- `--strict`: fail on files that cannot be read or parsed.
+
+### `pydry abstract`
+
+Filter near matches to pairs that look like plausible refactor candidates.
+
+```bash
+pydry abstract ./src
+pydry abstract ./src --threshold 0.86 --format json
+```
+
+### `pydry report`
+
+Generate one JSON document with exact, near, and abstract sections.
+
+```bash
+pydry report ./src
+pydry report ./src --threshold 0.82 --top-k 250 --output reports/pydry-report.json
+```
+
+### `pydry showcase` and `pydry simulate`
+
+Run a compact terminal summary. Both commands use the same analysis pipeline. With no path, they scan the current directory.
+
+```bash
+pydry showcase
+pydry showcase ./src --top-k 10 --threshold 0.8
+pydry showcase ./src --format json
+pydry simulate ./src
+```
+
+## JSON output
+
+JSON-capable commands return an envelope:
+
+```json
+{
+  "results": [],
+  "diagnostics": {
+    "scan_errors_count": 0,
+    "scan_error_samples": [],
+    "plugin_errors_count": 0,
+    "plugin_error_samples": []
+  }
+}
+```
+
+Near and abstract entries include:
+
+- `similarity_score`
+- `refactorability_score`
+- `pattern_labels`
+- `shared_structure_summary`
+- `key_differences`
+- `risk_flags`
+- `suggested_refactor_kind`
+- `evidence`
+
+## Python API
+
+The CLI is the primary interface, but the core functions are importable:
+
+```python
+from pathlib import Path
+
+from pydry.engine import exact_groups, near_matches
+
+groups = exact_groups(
+    Path("src"),
+    normalize_local_names=True,
+    normalize_constants=True,
+)
+rows = near_matches(Path("src"), threshold=0.85, top_k=25)
+```
+
+## Limitations
+
+- Similarity is heuristic. It does not prove semantic equivalence.
+- Cross-file import resolution is not attempted.
+- Generated abstraction templates are suggestions, not executable patches.
+
+## Development
+
+```bash
+make check
+make coverage
+make check-dist
+```
+
+The package supports Python 3.11 and newer.
+
+## License
+
+`pydry` is released under the MIT License. See [LICENSE](LICENSE).

pydry_cli-0.0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+pydry/__init__.py,sha256=PTpHrEPXX0XD3mrDKdheFqUx5YwwouTDlmzQldP7Jzk,80
+pydry/__main__.py,sha256=fOlwIdXXr9knJszM70QIFZbOxw41ZpVFpvCdGZ1VsxA,84
+pydry/analyze.py,sha256=_j0rvUHflZwzmagbPLN39ScauKG3hfQ0uzPXHQuW4w4,9114
+pydry/builtin_plugins.py,sha256=U0MivLXCmcyoMKB18IyNBndB-QWpuAYF_Kt2qhUT6Qs,7071
+pydry/cli.py,sha256=4geaO-fRMEdqYD_ykOztc5lHChInHPeZRDznJDFbL1M,22280
+pydry/engine.py,sha256=itI_0vmRuV1pwuf_Q8YPG6G0z9dKpbwhoh9R5cYZjuc,17112
+pydry/models.py,sha256=rs6gpsQkJiIMc5qxldPwKtm9BRxA2A6I23zT9TbCvII,1089
+pydry/normalize.py,sha256=_HxA9QcEGjhhCUdJB3LjTJT-MTqOi0zeOc4kB9ICw9Q,5192
+pydry/plugins.py,sha256=0kVE-4-dUE_X3UGPP99SuIKJZGIywMHoX2NnDudAnoM,3055
+pydry_cli-0.0.3.dist-info/licenses/LICENSE,sha256=4A4mEaxxz9M3y3bLvO5ZpNZTTaKrGrE0bBI7Sa1JX3A,1068
+pydry_cli-0.0.3.dist-info/METADATA,sha256=h3WKDx1rOEHp-x5KPHYgpI3zY_MPpbuVKrf22GvSq74,5244
+pydry_cli-0.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pydry_cli-0.0.3.dist-info/entry_points.txt,sha256=I0YdAv3mqkz-xEf-1YvyWt2v9w2OG2_XNEUcdcFbY0M,41
+pydry_cli-0.0.3.dist-info/top_level.txt,sha256=9C__-pSPfs_qwX4JUoB8I5Gv28FLqc2tpRaVFuXE4vo,6
+pydry_cli-0.0.3.dist-info/RECORD,,

pydry_cli-0.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pydry_cli-0.0.3.dist-info/entry_points.txt

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

pydry_cli-0.0.3.dist-info/licenses/LICENSE

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

pydry_cli-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+pydry