pylon-analyzer 0.1.1__py3-none-any.whl

pylon_analyzer/ai/explain.py

@@ -0,0 +1,29 @@
+# explain.py receives a response regardless of the LLM provider of choice
+from pylon_analyzer.ai.providers.base import LLMProvider
+from pylon_analyzer.rules.base import Finding
+
+def explain_finding(finding: Finding, source_snippet: str, provider: LLMProvider) -> str:
+    """Explain a finding using an LLM and return its response, runnning Prompt V1"""
+    # provide finding in destructured form, specifically finding.rule_id and finding.message
+    # provide source_snippet in python markdown
+    # respond in 2-3 sentences at most
+    # dont be overly confident
+    # indicate the finding line is the one starting with '---->' from get_snippet
+    prompt = f"""
+    You operate as a key part of a static Python analyzer tool that employs an LLM to explain various findings:
+    structured patterned rule violations. You receive the following crucial information about a finding:
+        Rule id: {finding.rule_id},
+        Line number: {finding.line},
+        Message: "{finding.message}",
+    and a file with the source code where the violating line is indicated '---->' and the rest is surrounding context:
+    
+    ```python
+    {source_snippet}
+    ```
+    
+    You must now explain to the user of the Python analyzer, in no more than 2-3 sentences, exactly the nature of the
+    finding and just as importantly, whether or not this is likely a real issue or potentially a false positive by the static 
+    analyzer. Do not be overconfident and do not hesitate. Be incredibly concise, and shorten some sentences like
+    'there is a high likelihood that this is a false positive because...' to 'likely a false positive as....'."""
+        
+    return provider.complete(prompt)

pylon_analyzer/ai/providers/__init__.py

@@ -0,0 +1,30 @@
+from pylon_analyzer.ai.providers.base import LLMProvider
+import importlib
+# from pylon_analyzer.ai.providers.anthropic_provider import AnthropicProvider
+# from pylon_analyzer.ai.providers.ollama_provider import OllamaProvider
+# from pylon_analyzer.ai.providers.openai_provider import OpenAIProvider
+# from pylon_analyzer.ai.providers.google_provider import GoogleProvider
+
+# converstion from explicit calls to a dict string-matching
+_ALL_PROVIDERS = {
+    "ollama": ("ollama_provider", "OllamaProvider", "ollama"),
+    "anthropic": ("anthropic_provider", "AnthropicProvider", "anthropic"),
+    "openai": ("openai_provider", "OpenAIProvider", "openai"),
+    "google": ("google_provider", "GoogleProvider", "google-genai")
+}
+
+def get_provider(name: str) -> LLMProvider:
+    
+    if name not in _ALL_PROVIDERS:
+        raise ValueError(f"Unknown LLM provider: {name}. Choose from: {list(_ALL_PROVIDERS)}")
+    
+    module_name, class_name, extra = _ALL_PROVIDERS[name]
+    try:
+        module = importlib.import_module(f"pylon_analyzer.ai.providers.{module_name}")
+    except ImportError as e:
+        raise ImportError(
+            f"The '{name}' provider requires installation of an optional dependency. Do you need to install it? "
+            f'Install with: pip install "pylon-analyzer[{extra}]"'
+        ) from e
+    
+    return getattr(module, class_name)() # callable

pylon_analyzer/ai/providers/anthropic_provider.py

@@ -0,0 +1,15 @@
+import anthropic
+from pylon_analyzer.ai.providers.base import LLMProvider
+
+class AnthropicProvider(LLMProvider):
+    def __init__(self, model: str = "claude-sonnet-5"): # maybe opus is better?
+        self.client = anthropic.Anthropic()
+        self.model = model
+    
+    def complete(self, prompt: str) -> str:
+        response = self.client.messages.create(
+            model = self.model,
+            max_tokens = 500, # limit size since claude drones on
+            messages = [{"role": "user", "content": prompt}]
+        )
+        return response.content[0].text

pylon_analyzer/ai/providers/base.py

@@ -0,0 +1,8 @@
+# ABC = abstract base class, much like a java interface
+# subclasses must implement complete(), much like subclasses of interfaces abstract methods
+from abc import ABC, abstractmethod
+
+class LLMProvider(ABC):
+    @abstractmethod
+    def complete(self, prompt: str) -> str:
+            """Send a prompt and return the model's response"""

pylon_analyzer/ai/providers/google_provider.py

@@ -0,0 +1,14 @@
+from google import genai
+from pylon_analyzer.ai.providers.base import LLMProvider
+
+class GoogleProvider(LLMProvider):
+    def __init__(self, model: str = "gemini-3.6-flash"):
+        self.client = genai.Client()
+        self.model = model
+    
+    def complete(self, prompt: str) -> str:
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=prompt
+        )
+        return response.text

pylon_analyzer/ai/providers/ollama_provider.py

@@ -0,0 +1,14 @@
+import requests
+from pylon_analyzer.ai.providers.base import LLMProvider
+
+class OllamaProvider(LLMProvider):
+    def __init__(self, model: str = "qwen2.5-coder:7b"):
+        self.model = model
+    
+    def complete(self, prompt):
+        response = requests.post(
+            "http://localhost:11434/api/generate", # post api endpoint
+            json={"model": self.model, "prompt": prompt, "stream": False} # dont stream since we want it to return one chunk
+        )
+        response.raise_for_status() # raises http error if one occurred
+        return response.json()["response"]

pylon_analyzer/ai/providers/openai_provider.py

@@ -0,0 +1,15 @@
+from openai import OpenAI
+from pylon_analyzer.ai.providers.base import LLMProvider
+
+class OpenAIProvider(LLMProvider):
+    def __init__(self, model: str = "gpt-5.5"):
+        self.client = OpenAI()
+        self.model = model
+        
+    def complete(self, prompt: str) -> str:
+        response = self.client.chat.completions.create(
+            model = self.model,
+            stream = False,
+            messages = [{"role": "user", "content": prompt}]
+        )
+        return response.choices[0].message.content

pylon_analyzer/cli.py

@@ -0,0 +1,82 @@
+# https://click.palletsprojects.com/en/stable/
+import click
+from pathlib import Path
+from pylon_analyzer.rules.registry import ALL_RULES
+from pylon_analyzer.ai.providers import get_provider
+from pylon_analyzer.ai.explain import explain_finding
+from dotenv import load_dotenv, find_dotenv
+load_dotenv(find_dotenv(usecwd=True)) # use cwd to find envs
+
+def find_python_files(filepath: str) -> list[Path]:
+    """Find all python files in a directory and return as list[Path]"""
+    p = Path(filepath)
+    # check if path is valid
+    if not p.exists():
+        click.echo(f"{filepath} is not a valid directory.")
+        return []
+
+    if p.is_file() and p.suffix == ".py":
+        return [p]  # singleton file to append
+    if p.is_file():
+        return []   # not a python file
+
+    return list(p.rglob("*.py")) # recursively search the directory
+
+
+def get_snippet(filepath: Path, finding_line, margin = 25) -> str:
+    """Receive a file and line number for a known finding, grab surrounding `margin` lines of code, and return the snippet as a surrounding context"""
+    with open(filepath) as f:
+        all_lines = f.readlines()
+        
+    first = max(0, finding_line - margin - 1) # -1 for from-zero indexing
+    last = min(len(all_lines), finding_line + margin)
+    
+    snippet_lines = []
+    for i in range(first, last):
+        line_num = i + 1
+        prefix = "----> " if line_num == finding_line else "    "
+        snippet_lines.append(f"{prefix}{line_num}: {all_lines[i]}")
+    
+    return "".join(snippet_lines) # concatenate lines from first to last and return as a new string
+
+@click.command()
+@click.argument("filepath")
+@click.option("--explain", is_flag=True, help="Generate LLM explanations for each finding, using surrounding context.") # explain flag calls LLM layer
+@click.option("--provider", default="ollama", help="LLM provider for --explain: ollama (local, included), anthropic (requires [anthropic] extra), openai (requires [openai] extra), google (requires [google-genai] extra)")
+def check(filepath, explain, provider):
+    """Run all Pylon validation rules on the specified Python file or directory and print findings with LLM insight if explaining."""
+    files = find_python_files(filepath)
+    click.echo(f"Validating {len(files)} file(s)...")
+    
+    try:
+        llm = get_provider(provider) if explain else None # dont fill if not explaining. here rather than in 'if explain' so it isnt recomputed
+    except (ValueError, ImportError) as e:
+        raise click.ClickException(str(e)) # carry raise as a click exception
+    
+    all_findings = []
+    for file in files:
+        for rule in ALL_RULES:
+            # need source file as well as the finding
+            findings = rule(str(file))
+            for finding in findings:
+                all_findings.append((file, finding)) # returning a zipped tuple for later report
+            
+
+    if not all_findings: # if all_findings == []
+        click.echo("No issues found! :)")
+        return
+    
+    else: # all_findings != []
+        for file, finding in sorted(all_findings, key=lambda pair: pair[1].line): # sorts by file by line number, with (file, _) used
+            click.echo(f"{file}:{finding.line}: [{finding.rule_id}] {finding.message}")
+            
+            if explain: # employ the LLM layer!
+                source_snippet = get_snippet(file, finding.line) # helper
+            
+                explanation = explain_finding(finding, source_snippet, llm)
+                click.echo(f"   --> {explanation}")
+        
+    raise SystemExit(1)
+
+if __name__ == "__main__":
+    check()

pylon_analyzer/rules/bare_excepts.py

@@ -0,0 +1,24 @@
+from pylon_analyzer.rules.base import Finding
+import ast
+
+def find_bare_excepts(filepath: str) -> list[Finding]:
+    """given a python file path, return a list of Findings where try-catch uses a bare except"""
+    with open(filepath) as f:
+        src = f.read()
+    tree = ast.parse(src)
+    
+    result = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ExceptHandler) and node.type is None:
+            last_statement = node.body[-1] if node.body else None # [-1] gives the tail of the list every time regardless of size
+            if isinstance(last_statement, ast.Raise) and last_statement.exc is None:
+                continue # skip, as this is a catch-and-re-raise scenario
+            result.append(Finding(
+                rule_id="bare-except",
+                message="Bare except clause found in try block",
+                line=node.lineno
+            ))
+    
+    # notice: i dont want through and find tries and then match tries with exception handlers
+    # the tree walk finds ALL nodes, recursively, so it will find exception handlers anyway.
+    return result

pylon_analyzer/rules/base.py

@@ -0,0 +1,21 @@
+# defining a standard structure for rules to output
+from dataclasses import dataclass
+import hashlib
+
+@dataclass  # basically a python shortcut for a class with no manual __init__
+class Finding:
+    rule_id: str    # an identifier ex. "unused-imports", "mutable-default-args"
+    message: str
+    line: int
+    
+    @property # property attribute class
+    def id(self) -> str:
+        # give each instance Finding a unique id stable across runs, 
+        # so the same file-line-finding gives the same ID every time (without a database)
+        # IDs needed for user flagging and metric collection
+        raw_id = f"{self.rule_id}:{self.line}:{self.message}" # combo of fields
+        encoded = hashlib.sha256(raw_id.encode()).hexdigest() # 64 digit encode
+        return encoded[:8] 
+    # return the first 8 digits like a commit ID, since 64 is way too many
+    # 2^8 = worst case 256 incredibly similarly hashed issues. very unlikely
+        

pylon_analyzer/rules/improper_compare_keyword_const.py

@@ -0,0 +1,32 @@
+from pylon_analyzer.rules.base import Finding
+import ast
+
+def find_improper_compares(filepath: str) -> list[Finding]:
+    """given a python file path, return a list of Findings for improper comparisons using '==' rather than 'is' with keyword constants"""
+    with open(filepath) as f:
+        src = f.read()
+    tree = ast.parse(src)
+
+    result = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Compare):
+            compare_node_left = node.left
+            compare_node_ops = node.ops[0]
+            compare_node_right = node.comparators[0]
+            if isValidConst(compare_node_right) or isValidConst(compare_node_left):
+                if isinstance(compare_node_ops, (ast.Eq, ast.NotEq)):
+                    result.append(Finding(
+                        rule_id="improper-compares",
+                        message=f"Improper comparison using operator '{'!=' if isinstance(compare_node_ops, ast.NotEq) else '=='}' with keyword constant in line {node.lineno}",
+                        line=node.lineno
+                    ))
+
+    return result
+
+def isValidConst(node):
+    if isinstance(node, ast.Constant):
+        val = node.value
+        if isinstance(val, bool) or val is None:
+            return True
+    else:
+        return False

pylon_analyzer/rules/mutable_default_args.py

@@ -0,0 +1,40 @@
+# def add_item(item, items=[]):
+#     items.append(item)
+#     return items
+# "if no list is passed, start with an empty list."
+# but in python, the same list is shared every time the function is called
+# this means the default list grows as it accumulates new items
+# avoid with ast detection!
+from pylon_analyzer.rules.base import Finding
+import ast
+
+def find_mutable_defaults(filepath: str) -> list[Finding]:
+    """given a python file path, return a list of Findings for functions with mutable default arguments"""
+    with open(filepath) as f:
+        src = f.read()
+    tree = ast.parse(src)
+    
+    result = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            for default in node.args.defaults:
+                # args is an argument node
+                # args.defaults is a list of default values passed positionally
+                # check if default is a mutable literal  
+                if is_mutable(default):
+                    result.append(Finding(
+                        rule_id="mutable-default",
+                        message=f"Mutable default argument in function def '{node.name}'",
+                        line=node.lineno
+                    ))
+    return result
+
+def is_mutable(node):
+    if isinstance(node, (ast.List, ast.Dict, ast.Set)):
+        # if its a direct object of one of our mutable types
+        return True
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+        # if its a call to a function with id belonging to one of our mutable types
+        # i.e. set(), which is an initialization returning an empty set
+        return node.func.id in ("list", "dict", "set")
+    return False

pylon_analyzer/rules/registry.py

@@ -0,0 +1,17 @@
+from pylon_analyzer.rules.bare_excepts import find_bare_excepts
+from pylon_analyzer.rules.unused_imports import find_unused_imports
+from pylon_analyzer.rules.mutable_default_args import find_mutable_defaults
+from pylon_analyzer.rules.wildcard_imports import find_wildcard_imports
+from pylon_analyzer.rules.improper_compare_keyword_const import find_improper_compares
+from pylon_analyzer.rules.shadowed_functions import find_shadowed_functions
+from pylon_analyzer.rules.shadowed_builtins import find_shadowed_builtins
+
+ALL_RULES = [
+    find_bare_excepts,
+    find_unused_imports,
+    find_mutable_defaults,
+    find_wildcard_imports,
+    find_improper_compares,
+    find_shadowed_functions,
+    find_shadowed_builtins
+]

pylon_analyzer/rules/shadowed_builtins.py

@@ -0,0 +1,38 @@
+import ast
+import builtins
+
+from pylon_analyzer.rules.base import Finding
+
+
+BUILTIN_NAMES = frozenset(name for name in dir(builtins) if not name.startswith('_'))
+
+
+def find_shadowed_builtins(filepath: str) -> list[Finding]:
+    """Find bindings that shadow Python builtins."""
+    with open(filepath) as f:
+        tree = ast.parse(f.read())
+
+    result = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.arg):
+            name = node.arg
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            name = node.id
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            name = node.name
+        elif isinstance(node, ast.alias):
+            name = node.asname or node.name.split(".")[0]
+        elif isinstance(node, ast.ExceptHandler):
+            name = node.name
+        else:
+            continue
+
+        if name in BUILTIN_NAMES:
+            result.append(Finding(
+                rule_id='shadowed-builtin',
+                message=f"'{name}' shadows a Python builtin",
+                line=node.lineno,
+            ))
+
+    result.sort(key=lambda finding: finding.line)
+    return result

pylon_analyzer/rules/shadowed_functions.py

@@ -0,0 +1,80 @@
+from pylon_analyzer.rules.base import Finding
+import ast
+
+KIND = {
+    ast.FunctionDef: "function",
+    ast.AsyncFunctionDef: "async function",
+    ast.ClassDef: "class"
+}
+DEFS = tuple(KIND)
+
+def find_shadowed_functions(filepath: str) -> list[Finding]:
+    """Given a python file path, return a list of Findings where functions have been redefined, silently shadowing. This includes `def`, `async def`, and `class`"""
+    with open(filepath) as f:
+        src = f.read()
+    tree = ast.parse(src)
+    
+    # return
+    # 'test_create' redefined; the definition on line 12 is unreachable
+    result = []
+    seen = {} # dict[str, ast.AST]
+    for node in ast.walk(tree):
+        # per-scope
+        for field in ("body", "orelse", "finalbody"):
+            stmts = getattr(node, field, None) # get field if it has one, equiv to node.field
+            if isinstance(stmts, list):
+                # lambda / if exp have a non-list 'body' field
+                _scan_statements(stmts, result)
+                
+    result.sort(key=lambda f: f.line) # sort by line since it wont match walk order
+    return result
+
+def _scan_statements(stmts: list[ast.stmt], result: list[Finding]) -> None:
+    seen: dict[str, ast.AST] = {}
+    for stmt in stmts:
+        if isinstance(stmt, DEFS):
+            first_seen = seen.get(stmt.name)
+            if first_seen is not None and not _exempt(first_seen, stmt):
+                result.append(Finding(
+                    rule_id="shadowed-function",
+                    message=(f"'{stmt.name}' redefined; the {KIND[type(first_seen)]} "
+                             f"on line {first_seen.lineno} is shadowed"), # "myFunc redefined; the function on line 2 is shadowed"
+                    line=stmt.lineno
+                ))
+            seen[stmt.name] = stmt
+
+def _exempt(first, second) -> bool:
+    # overload stubs, exempt if either first or second is marked as overloaded
+    if _has_decorator(first, "overload") or _has_decorator(second, "overload"):
+        return True
+    # single dispatch: 'singledispatch' creates a generic function and '@x.register' registers special variants of it
+    # property accessors (getters, setters) and @x.register on function named x
+    if _is_attribute_of_self(second):
+        return True
+    # singledispatch convention matching repeated 'def _'s
+    return second.name == "_"
+    
+def _has_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef, name: str) -> bool:
+    """Is true for @name, @mod.name, @name(...), @mod.name(...), false otherwise"""
+    for deco in node.decorator_list:
+        deco = deco.func if isinstance(deco, ast.Call) else deco # unwrap it if its a function call
+        
+        # ast.Name matching name
+        if isinstance(deco, ast.Name) and deco.id == name:
+            return True 
+        # ast.Attribute matching name
+        if isinstance(deco, ast.Attribute) and deco.attr == name:
+            return True
+        
+    return False
+
+def _is_attribute_of_self(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> bool:
+    """Is true for @x.setter, @x.getter, @x.deleter, @x.register on 'def x' or any 'def foo'"""
+    for deco in node.decorator_list:
+        deco = deco.func if isinstance(deco, ast.Call) else deco # unwrap it if its a function call
+        
+        # if its an attribute, it has a Name label and the name matches the function def x / foo
+        if isinstance(deco, ast.Attribute) and isinstance(deco.value, ast.Name) and deco.value.id == node.name:
+            return True
+        
+    return False

pylon_analyzer/rules/unused_imports.py

@@ -0,0 +1,59 @@
+from pylon_analyzer.rules.base import Finding
+import ast
+
+def all_string_literals(value_node):
+    """Pull string literals out of a list/tuple AST node — used for __all__ = [...]"""
+    names = set()
+    if isinstance(value_node, (ast.List, ast.Tuple)):
+        for elt in value_node.elts:
+            if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                names.add(elt.value)
+    return names
+
+def find_unused_imports(filepath: str) -> list[Finding]:
+    """Given a Python file path, return a list of Findings, import names that are never used"""
+    # get tree
+    with open(filepath) as f:
+        source = f.read() # string
+    tree = ast.parse(source)
+    
+    # get list of imports
+    imported = {}
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            for name in node.names:
+                # check if .name or .asname (import os || import os as opersys)
+                if name.asname is not None and name.asname == name.name:
+                    continue # skip for deliberate pattern "import X as "
+                imported[name.asname or name.name] = node.lineno
+    
+    # every time code references a name: os.path.join(), path.exists(),... parser creates ast.Name with .id attribute
+    used_names = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            used_names.add(node.id)
+
+        # __all__ = list of strings
+        # names listed in __all__ = [...] or __all__ += [...] count as "used"
+        # this catches the re-export-via-__all__ idiom (e.g. in numpy's __init__.py),
+        # since those names never appear as an ast.Name, and only as string literals
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and target.id == "__all__":
+                    used_names |= all_string_literals(node.value) # union
+        if isinstance(node, ast.AugAssign):
+            if isinstance(node.target, ast.Name) and node.target.id == "__all__":
+                used_names |= all_string_literals(node.value)
+    
+    # compare
+    result = []
+    for name,lineno in imported.items():
+        if name not in used_names:
+            # unused import: create a Finding
+            result.append(Finding(
+                rule_id="unused-import",
+                message=f"Unused import from '{name}'",
+                line=lineno
+            ))
+    
+    return result

pylon_analyzer/rules/wildcard_imports.py

@@ -0,0 +1,22 @@
+from pylon_analyzer.rules.base import Finding
+import ast
+
+def find_wildcard_imports(filepath: str) -> list[Finding]:
+    """given a python file path, return a list Findings of wilcard imports"""
+    with open(filepath) as f:
+        src = f.read()
+    tree = ast.parse(src)
+    
+    result = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            for name in node.names:
+                if name.name == "*":
+                    result.append(Finding(
+                        rule_id="wildcard-import",
+                        message=f"Wildcard import from '{node.module}'",
+                        line=node.lineno
+                    ))
+                # deliberately not using aliased names as these will always be '*'
+    
+    return result

pylon_analyzer-0.1.1.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: pylon-analyzer
+Version: 0.1.1
+Summary: A static analysis CLI for Python scripts with various enhancements and an LLM layer
+Author: Ethan Gat
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Anonymoose725/Pylon
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Provides-Extra: ollama
+Requires-Dist: anthropic; extra == "ollama"
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+Provides-Extra: google-genai
+Requires-Dist: google-genai; extra == "google-genai"
+Provides-Extra: llm-all
+Requires-Dist: anthropic; extra == "llm-all"
+Requires-Dist: openai; extra == "llm-all"
+Requires-Dist: google-genai; extra == "llm-all"
+Dynamic: license-file
+
+## Pylon
+
+Pylon is a static analysis CLI for Python that flags real issues in your code and, on request, explains them and suggests fixes using an LLM.
+
+Pylon mostly utilises Python's included [ast module](https://docs.python.org/3/library/ast.html) to traverse source code.
+
+Built in collaboration with [Soham200613](https://github.com/Soham200613) and [GraydenDonaldson](https://github.com/GraydenDonaldson)
+
+## Implemented rules
+
+- **Unused imports**: imports that are never referenced. Correctly handles Python's re-export idioms (`from .app import Flask as Flask`, `__all__ = [...]`) so it doesn't flag deliberate public re-exports as dead code.
+- **Mutable default arguments**: `def f(x=[])` shares the same object across every call, a classic source of hard-to-trace bugs. Catches both literal syntax (`[]`, `{}`) and constructor calls (`list()`, `dict()`, `set()`).
+- **Bare `except:` clauses**: catching all exceptions, including `KeyboardInterrupt` and `SystemExit`, silently swallows bugs. Recognizes and skips the deliberate catch-and-reraise pattern (`except: ... raise`), rather than flagging every bare except indiscriminately.
+- **Wildcard imports**: `from module import *` pollutes the namespace and makes it impossible to tell where a name came from.
+- **Comparing with `==` instead of `is` for `None`/`True`/`False`** — non-idiomatic and can misbehave with custom `__eq__`. Check `ast.Compare` nodes where one side is an `ast.Constant` with value `None`/`True`/`False` and the operator is `Eq`/`NotEq`.
+- **Shadowed funcions/methods/class definitions**: functions later shadowed without an @overload stub and other exceptions are silently shadowed by python
+
+- **Shadowed builtins**: parameters and variable bindings named `list`, `dict`, `id`, `type`, etc. hide Python's builtins. Attribute names and ordinary builtin references are not flagged.
+
+## Rules yet to be implemented
+
+- **Excessive function arguments**: functions with too many parameters are hard to maintain and often signal the function is doing too much.
+- **Unused function arguments**: parameters never referenced in the function body, often signaling incomplete refactoring. Same "walk and collect `ast.Name` usages" pattern as unused imports, applied per-function.
+- **Global variable mutation inside functions**: using `global` to mutate outer-scope state is a common source of hard-to-trace bugs. Check for `ast.Global` nodes within functions.
+- **Deeply nested code (high cyclomatic complexity)**: functions with many nested `if`/`for`/`while`/`try` blocks are hard to read and test. Requires tracking nesting depth/branch count while walking, rather than matching a single node type.
+- **Redefining function in same scope**: functions that are later redefined in the same scope silently shadow, hinting to dead code
+- **Format-string arg count mismatch**: `%` operator and `logging` calls with a mismatch in the number of format requests and args supplied
+
+## LLM layer
+
+Passing `--explain` sends each finding, along with its surrounding source code, to an LLM for a short, specific judgment on whether it's a genuine issue or a likely false positive. This is deliberately kept separate from the deterministic rule engine: rules encode patterns worth hard-coding that have few special deliberate cases, while the LLM layer handles judgment calls that don't generalize cleanly into a fixed rule. For example, correctly identifying that an unused `from __future__ import annotations` import is not actually dead code, despite never appearing as a referenced name in its respective file.
+
+Supports multiple providers behind a shared interface — local models via [ollama](https://ollama.com) for fast, free iteration, or Anthropic/OpenAI for production-quality explanations:
+
+```bash
+pylon path/to/file.py --explain --provider ollama   # default
+pylon path/to/file.py --explain --provider anthropic
+pylon path/to/file.py --explain --provider openai
+pylon path/to/file.py --explain # will use default ollama qwen2.5:7b-coder
+```
+
+Note that users of OpenAI/Anthropic models should configure their API keys by following the [Configuration section](#-configuration-set-up-environment-variables) above.
+
+## Installation, as PyPI package
+
+
+Plain installation without external provider support ie. Ollama only
+```bash
+pip install pylon-analyzer
+```
+
+To install specific or all providers, 
+```bash
+# Just Anthropic
+pip install "pylon-analyzer[anthropic]"
+# Just OpenAI
+pip install "pylon-analyzer[openai]"
+# Just Google
+pip install "pylon-analyzer[google]"
+# Full provider support
+pip install "pylon-analyzer[llm-all]"
+```
+
+## Installation, from source
+
+```bash
+git clone https://github.com/Anonymoose725/pylon.git
+cd pylon
+python3 -m venv .venv
+source .venv/bin/activate # for linux/mac, or .venv\Scripts\activate on Windows
+pip install -r requirements.txt
+```
+
+### Minimal install (Ollama only, no API keys required)
+```bash
+pip install -e ".[ollama]"
+```
+
+### Full install with all LLM providers
+```bash
+pip install -e ".[llm-all]"
+```
+
+### Or install specific providers
+```bash
+# Just OpenAI
+pip install -e ".[openai]"
+# Just Anthropic  
+pip install -e ".[anthropic]"
+```
+
+## Configuration: Set Up Environment Variables
+
+**After installation**, you'll need to configure environment variables for LLM API access:
+
+1. **Copy the example file**: Rename `.env.example` to `.env.local` first to review the template, then rename it to `.env`:
+   ```bash
+   cp .env.example .env.local  # Review what needs to be set
+   mv .env.local .env          # Now you can edit it safely
+   ```
+
+2. **Edit `.env`**: Add your API keys to the `.env` file:
+   ```bash
+   nano .env  # or use your preferred editor
+   ```
+
+3. **Load environment variables** (if your shell doesn't auto-source):
+   ```bash
+   source .env  # Linux/mac, or .venv\Scripts\activate.ps1 for Windows
+   ```
+
+## Detailed setup, for contributors
+
+Clone the repo:
+```bash
+git clone https://github.com/Anonymoose725/pylon.git
+cd pylon
+```
+
+Create and activate a virtual environment:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install dependencies from requirements.txt:
+```bash
+pip install -r requirements.txt
+```
+
+Run the test suite to confirm everything works:
+```bash
+pytest testing/ -v
+```
+
+**Optional**: Configure LLM API keys by following the [Configuration section](#-configuration-set-up-environment-variables). The tests will run with Ollama by default (no API keys needed) unless you've installed other providers and set up `.env`.
+
+## Milestones & metrics
+
+Validated against 5 actively maintained production codebases to confirm the tool works at real scale and to catch genuine false-positive patterns before they'd be found by an actual user.
+
+| Repo | Files | Lines | Findings |
+|---|---|---|---|
+| Flask | 24 | 9,513 | 32 |
+| Requests | 19 | 6,394 | 56 |
+| Click | 17 | 12,821 | 19 |
+| Django | 907 | 165,529 | 198 |
+| NumPy | 428 | 260,868 | 764 |
+| **Total** | **1,395** | **455,125** | **1,069** |
+
+- **Reduced false-positive unused-import findings by 34%** (1,479 → 976) by diagnosing and fixing two Python re-export idioms (`from x import Y as Y` and `__all__` re-exports) that the AST-based detector initially misread as dead code
+- **Correctly identified a genuine bare-except anti-pattern** in Flask's core WSGI dispatch logic (`app.py`), then refined the rule to distinguish safe catch-and-reraise handlers from true error suppression via AST-level exception analysis
+- **Processes ~365 files/sec** (Django) and remains performant on dense, large codebases (~83 files/sec on NumPy's 260K-line source tree due to larger file sizes)
+- Every rule is covered by positive *and* negative test cases (`pytest`) — proving each rule catches real issues without false-flagging safe, idiomatic code
+- Uploaded to PyPI, where now users can 'pip install pylon-analyzer' on any system!
+
+## Roadmap
+
+1. Implement the roadmap rules listed above!
+2. Implement a --fat flag that assumes a user is testing on a large number of files/repos, compacting the large list of findings into a more digestible (and collapsible?) format, potentially outside the CLI
+3. Add a false-positive flagging mechanism to the CLI, so users can mark findings as false positives, with and without having seen an `--explain` explanation first. This is the basis for measuring whether the LLM layer's context genuinely reduces false-positive flags in practice

pylon_analyzer-0.1.1.dist-info/RECORD

@@ -0,0 +1,26 @@
+pylon_analyzer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylon_analyzer/cli.py,sha256=MzFwtbQFRznV1laXJjr1_TOll6Byv7mAGsvVEF3NVME,3591
+pylon_analyzer/ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylon_analyzer/ai/explain.py,sha256=zgBgBSMaP_1aLiXJSdeKoPExGwtk1754NeLi__iZTUE,1682
+pylon_analyzer/ai/providers/__init__.py,sha256=tcjUtr8AMXWNEjCLxN3XrZkgt2YDKp3K8Kgw_Wy3yqA,1372
+pylon_analyzer/ai/providers/anthropic_provider.py,sha256=uD8aaDOod4Vq3ys4bYoVen-NKRpFKPdreuzxIIYY558,569
+pylon_analyzer/ai/providers/base.py,sha256=hMOBSl3XOUdVuw6c3PXka0znQzYs0rhQX_C7YPQbFoM,336
+pylon_analyzer/ai/providers/google_provider.py,sha256=EnCmMXQddlLgkeWFX2-jCDJr0pX8khZps6P8mvo3SBs,441
+pylon_analyzer/ai/providers/ollama_provider.py,sha256=cGuhtJ2EdDoA4cr_5PoKTo6Gq76tN7K6lqa5MENNFPo,584
+pylon_analyzer/ai/providers/openai_provider.py,sha256=ohPA3XxO0ZXaGOn-AbZQSloWBBX5HE9iYVDBmUUjcww,515
+pylon_analyzer/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylon_analyzer/rules/bare_excepts.py,sha256=iyjmpwO-YJDewWxT-0Kecy0-JQdLlzk26ckgEBIjdu0,1097
+pylon_analyzer/rules/base.py,sha256=nfXUAMnO72ToE_YnlBMy0s-l5RLXD87IYC2qtN3hh2I,947
+pylon_analyzer/rules/improper_compare_keyword_const.py,sha256=zbU_3zmWDK77GRBycCv5n8eWtYGABGNpOsO4dMcOZLE,1266
+pylon_analyzer/rules/mutable_default_args.py,sha256=9NhPR9NDScjOf6iLWWyT63z_yqnBs1MrIlJnE8OQ0ak,1690
+pylon_analyzer/rules/registry.py,sha256=i6EHbspIAIpgrfHdc-Vk0h6T2AabZDoc9JIQotvd9kY,719
+pylon_analyzer/rules/shadowed_builtins.py,sha256=pxmbqL7En42Ln3KD-u4QZi5GO870UIMPUw8PZTx8XYg,1184
+pylon_analyzer/rules/shadowed_functions.py,sha256=GcZjPitmk_D44WSNH8dNJucrPFMNhiw3-ZVL2nTEkOo,3556
+pylon_analyzer/rules/unused_imports.py,sha256=ZiqFe-0lFrbxQQP6r0X__dsQ7qk7OB_iRGT7GXckjCM,2466
+pylon_analyzer/rules/wildcard_imports.py,sha256=PLJJzRpivc1U7A2JJRK63nY807e-GEWZX8ifgVYJ6Pg,781
+pylon_analyzer-0.1.1.dist-info/licenses/LICENSE,sha256=YONk9sVULP0hmIoHkHCxIphaZVoVKmqwf76zwz_ovJo,1065
+pylon_analyzer-0.1.1.dist-info/METADATA,sha256=co5kNd8FQ7WYBY4_utW-uXvY2MwRJcyzvvXE9CGSFfA,9394
+pylon_analyzer-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pylon_analyzer-0.1.1.dist-info/entry_points.txt,sha256=tRbMe4id8FlNUktJm7JzeD6O58xmN_CbhVacJvDEd7Q,51
+pylon_analyzer-0.1.1.dist-info/top_level.txt,sha256=mODmLSxRAiAI0jzC9nQMWD04A7WXWZiPo9Mj9_T_rZM,15
+pylon_analyzer-0.1.1.dist-info/RECORD,,

pylon_analyzer-0.1.1.dist-info/WHEEL

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

pylon_analyzer-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pylon = pylon_analyzer.cli:check

pylon_analyzer-0.1.1.dist-info/licenses/LICENSE

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

pylon_analyzer-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pylon_analyzer