pythaw 0.1.0__tar.gz

pythaw-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: pythaw
+Version: 0.1.0
+Summary: A Python static analysis tool that detects heavy initialization inside AWS Lambda handlers that should be moved to module scope for faster warm starts.
+Keywords: aws,lambda,static-analysis,boto3,linter
+Author: MiuraToya
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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-Dist: rich>=14.0.0
+Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/MiuraToya/pythaw
+Description-Content-Type: text/markdown
+
+# pythaw
+
+[日本語ドキュメント](README.ja.md)
+
+A Python static analysis tool that detects heavy initialization inside AWS Lambda handlers that should be moved to module scope for faster warm starts.
+
+Recursively follows function calls—including across imported files—to catch indirect violations.
+
+## Requirements
+
+Python 3.10 - 3.14 — matching the actively supported AWS Lambda Python runtimes.
+
+## Install
+
+```bash
+# pip
+pip install pythaw
+
+# uv
+uv add pythaw
+```
+
+## Quick Start
+
+```python
+# handler.py
+
+def lambda_handler(event, context):
+    # BAD: Creating a boto3 client inside the handler
+    #      runs initialization on every invocation,
+    #      losing the benefit of warm starts.
+    client = boto3.client("s3")
+    return client.get_object(Bucket="my-bucket", Key=event["key"])
+```
+
+```
+$ pythaw check handler.py
+infra/aws.py:7:15: PW001 boto3.client() should be called at module scope
+  → handler.py:5:11 process()
+    → service.py:5:13 S3Provider.get_client()
+
+Found 1 violation in 1 file.
+```
+
+Move the client to module scope so Lambda container reuse skips the initialization:
+
+```python
+# handler.py (fixed)
+
+client = boto3.client("s3")
+
+def lambda_handler(event, context):
+    return client.get_object(Bucket="my-bucket", Key=event["key"])
+```
+
+```
+$ pythaw check handler.py
+All checks passed!
+```
+
+## Usage
+
+```bash
+pythaw check <path>                    # Check a file or directory
+pythaw check . --format json           # JSON output
+pythaw check . --format github         # GitHub Actions annotation format
+pythaw check . --format sarif          # SARIF format (Code Scanning integration)
+pythaw check . --select PW001,PW002    # Enable only specific rules
+pythaw check . --ignore PW003          # Disable specific rules
+pythaw check . --exit-zero             # Always exit with code 0
+pythaw check . --statistics            # Show per-rule violation counts
+pythaw rules                           # List built-in rules
+pythaw rule PW001                      # Show rule details
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No violations found |
+| 1 | Violations found |
+| 2 | Tool error (invalid config, etc.) |
+
+## Rules
+
+| ID    | Detects |
+|-------|---------|
+| PW001 | `boto3.client()` |
+| PW002 | `boto3.resource()` |
+| PW003 | `boto3.Session()` |
+| PW004 | `pymysql.connect()` |
+| PW005 | `psycopg2.connect()` |
+| PW006 | `redis.Redis()` |
+| PW007 | `redis.StrictRedis()` |
+| PW008 | `httpx.Client()` |
+| PW009 | `requests.Session()` |
+
+## Call Graph Traversal
+
+pythaw recursively follows local function calls and imported modules from the handler, detecting indirect violations across files.
+
+### Supported patterns
+
+| Pattern | Example |
+|---------|---------|
+| Same-file function call | `helper()` |
+| Module-qualified function call | `infra.get_client()` |
+| Class method call | `AwsProvider.get_client()` |
+| Class instantiation (`__init__`) | `S3Client()` |
+| Cross-file import tracking | `from infra import get_client` |
+
+> **Note:** Instance method calls via variables (e.g. `obj = Cls(); obj.method()`) are not tracked — this would require data-flow analysis beyond the current scope.
+
+```
+infra/aws.py:4:15: PW001 boto3.client() should be called at module scope
+  → handler.py:2:10 get_client()
+
+Found 1 violation in 1 file.
+```
+
+## Suppression
+
+### Inline suppression
+
+Append `# nopw: <code>` to a line to suppress that violation. Multiple codes can be comma-separated.
+
+```python
+client = boto3.client("s3")  # nopw: PW001
+```
+
+### File-level suppression
+
+Add `# pythaw: nocheck` in the leading comment block to skip the entire file.
+
+```python
+# pythaw: nocheck
+import boto3
+
+def handler(event, context):
+    boto3.client("s3")  # not checked
+```
+
+## Configuration
+
+Configure via the `[tool.pythaw]` section in `pyproject.toml`.
+
+```toml
+[tool.pythaw]
+# Function name patterns recognized as handlers (fnmatch syntax)
+handler_patterns = ["handler", "lambda_handler", "*_handler"]
+
+# Patterns to exclude from scanning
+exclude = [".venv", "tests"]
+
+# Disable specific rules per file pattern
+[tool.pythaw.per-file-ignores]
+"tests/*" = ["PW001", "PW002"]
+"scripts/*" = ["PW001"]
+```
+
+## License
+
+[MIT](LICENSE)

pythaw-0.1.0/README.md

@@ -0,0 +1,163 @@
+# pythaw
+
+[日本語ドキュメント](README.ja.md)
+
+A Python static analysis tool that detects heavy initialization inside AWS Lambda handlers that should be moved to module scope for faster warm starts.
+
+Recursively follows function calls—including across imported files—to catch indirect violations.
+
+## Requirements
+
+Python 3.10 - 3.14 — matching the actively supported AWS Lambda Python runtimes.
+
+## Install
+
+```bash
+# pip
+pip install pythaw
+
+# uv
+uv add pythaw
+```
+
+## Quick Start
+
+```python
+# handler.py
+
+def lambda_handler(event, context):
+    # BAD: Creating a boto3 client inside the handler
+    #      runs initialization on every invocation,
+    #      losing the benefit of warm starts.
+    client = boto3.client("s3")
+    return client.get_object(Bucket="my-bucket", Key=event["key"])
+```
+
+```
+$ pythaw check handler.py
+infra/aws.py:7:15: PW001 boto3.client() should be called at module scope
+  → handler.py:5:11 process()
+    → service.py:5:13 S3Provider.get_client()
+
+Found 1 violation in 1 file.
+```
+
+Move the client to module scope so Lambda container reuse skips the initialization:
+
+```python
+# handler.py (fixed)
+
+client = boto3.client("s3")
+
+def lambda_handler(event, context):
+    return client.get_object(Bucket="my-bucket", Key=event["key"])
+```
+
+```
+$ pythaw check handler.py
+All checks passed!
+```
+
+## Usage
+
+```bash
+pythaw check <path>                    # Check a file or directory
+pythaw check . --format json           # JSON output
+pythaw check . --format github         # GitHub Actions annotation format
+pythaw check . --format sarif          # SARIF format (Code Scanning integration)
+pythaw check . --select PW001,PW002    # Enable only specific rules
+pythaw check . --ignore PW003          # Disable specific rules
+pythaw check . --exit-zero             # Always exit with code 0
+pythaw check . --statistics            # Show per-rule violation counts
+pythaw rules                           # List built-in rules
+pythaw rule PW001                      # Show rule details
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No violations found |
+| 1 | Violations found |
+| 2 | Tool error (invalid config, etc.) |
+
+## Rules
+
+| ID    | Detects |
+|-------|---------|
+| PW001 | `boto3.client()` |
+| PW002 | `boto3.resource()` |
+| PW003 | `boto3.Session()` |
+| PW004 | `pymysql.connect()` |
+| PW005 | `psycopg2.connect()` |
+| PW006 | `redis.Redis()` |
+| PW007 | `redis.StrictRedis()` |
+| PW008 | `httpx.Client()` |
+| PW009 | `requests.Session()` |
+
+## Call Graph Traversal
+
+pythaw recursively follows local function calls and imported modules from the handler, detecting indirect violations across files.
+
+### Supported patterns
+
+| Pattern | Example |
+|---------|---------|
+| Same-file function call | `helper()` |
+| Module-qualified function call | `infra.get_client()` |
+| Class method call | `AwsProvider.get_client()` |
+| Class instantiation (`__init__`) | `S3Client()` |
+| Cross-file import tracking | `from infra import get_client` |
+
+> **Note:** Instance method calls via variables (e.g. `obj = Cls(); obj.method()`) are not tracked — this would require data-flow analysis beyond the current scope.
+
+```
+infra/aws.py:4:15: PW001 boto3.client() should be called at module scope
+  → handler.py:2:10 get_client()
+
+Found 1 violation in 1 file.
+```
+
+## Suppression
+
+### Inline suppression
+
+Append `# nopw: <code>` to a line to suppress that violation. Multiple codes can be comma-separated.
+
+```python
+client = boto3.client("s3")  # nopw: PW001
+```
+
+### File-level suppression
+
+Add `# pythaw: nocheck` in the leading comment block to skip the entire file.
+
+```python
+# pythaw: nocheck
+import boto3
+
+def handler(event, context):
+    boto3.client("s3")  # not checked
+```
+
+## Configuration
+
+Configure via the `[tool.pythaw]` section in `pyproject.toml`.
+
+```toml
+[tool.pythaw]
+# Function name patterns recognized as handlers (fnmatch syntax)
+handler_patterns = ["handler", "lambda_handler", "*_handler"]
+
+# Patterns to exclude from scanning
+exclude = [".venv", "tests"]
+
+# Disable specific rules per file pattern
+[tool.pythaw.per-file-ignores]
+"tests/*" = ["PW001", "PW002"]
+"scripts/*" = ["PW001"]
+```
+
+## License
+
+[MIT](LICENSE)

pythaw-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "pythaw"
+version = "0.1.0"
+description = "A Python static analysis tool that detects heavy initialization inside AWS Lambda handlers that should be moved to module scope for faster warm starts."
+readme = "README.md"
+authors = [
+    { name = "MiuraToya" }
+]
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["aws", "lambda", "static-analysis", "boto3", "linter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "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 = [
+    "rich>=14.0.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[project.urls]
+Repository = "https://github.com/MiuraToya/pythaw"
+
+[project.scripts]
+pythaw = "pythaw.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=6.2.1",
+
+    "ruff>=0.15.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "."
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.ruff]
+target-version = "py310"
+extend-exclude = ["tests/e2e/scenarios", "tests/scenarios"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D",       # pydocstyle — ドキュメント規約は別途決める
+    "ANN",     # flake8-annotations — mypy strict でカバー
+    "COM812",  # trailing comma — formatter と競合
+    "ISC001",  # implicit string concat — formatter と競合
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "PLR2004"]  # assert・マジックナンバーの使用を許可
+"pythaw/cli.py" = ["T201", "TC003"]  # CLI は print で出力し、Path を実行時に使用する
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pythaw-0.1.0/pythaw/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from pythaw.cli import main
+
+main()

pythaw-0.1.0/pythaw/checker.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import ast
+import os
+import re
+from fnmatch import fnmatch
+from typing import TYPE_CHECKING, TypeAlias
+
+from pythaw.finder import find_files
+from pythaw.resolver import Resolver
+from pythaw.rules import get_all_rules
+from pythaw.violation import CallSite, Violation
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from pythaw.config import Config
+    from pythaw.rules._base import Rule
+
+FunctionNode: TypeAlias = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+def check(
+    path: Path,
+    config: Config,
+    *,
+    select: frozenset[str] = frozenset(),
+    ignore: frozenset[str] = frozenset(),
+) -> list[Violation]:
+    """Run all rules against handler functions found under *path*.
+
+    Args:
+        path: File or directory to check.
+        config: Project configuration (handler patterns, excludes, etc.).
+        select: If non-empty, only run rules whose codes are in this set.
+        ignore: Rule codes to skip.
+
+    Returns:
+        A list of violations found across all handler functions.
+    """
+    files = find_files(path, config)
+    rules = _filter_rules(get_all_rules(), select=select, ignore=ignore)
+    violations: list[Violation] = []
+
+    base = path if path.is_dir() else path.parent
+    resolver = Resolver(base)
+    for file in files:
+        source = _read_source(file)
+        if source is None:
+            continue
+        if _has_nocheck(source):
+            continue
+        tree = _parse_source(source, file)
+        if tree is None:
+            continue
+        file_rules = _apply_per_file_ignores(rules, file, base, config.per_file_ignores)
+        suppressed = _parse_nopw_comments(source)
+        for func_node in _extract_handlers(tree, config.handler_patterns):
+            violations.extend(
+                _check_function(
+                    file,
+                    func_node,
+                    file_rules,
+                    suppressed,
+                    resolver,
+                )
+            )
+
+    return violations
+
+
+def _apply_per_file_ignores(
+    rules: tuple[Rule, ...],
+    file: Path,
+    base: Path,
+    per_file_ignores: tuple[tuple[str, tuple[str, ...]], ...],
+) -> tuple[Rule, ...]:
+    """Remove rules that match per-file-ignores patterns for *file*."""
+    if not per_file_ignores:
+        return rules
+    ignored_codes: set[str] = set()
+    try:
+        rel = str(file.resolve().relative_to(base.resolve()))
+    except ValueError:
+        rel = os.path.relpath(file)
+    for pattern, codes in per_file_ignores:
+        if fnmatch(rel, pattern):
+            ignored_codes.update(codes)
+    if not ignored_codes:
+        return rules
+    return tuple(r for r in rules if r.code not in ignored_codes)
+
+
+def _filter_rules(
+    rules: tuple[Rule, ...],
+    *,
+    select: frozenset[str],
+    ignore: frozenset[str],
+) -> tuple[Rule, ...]:
+    """Filter rules by *select* and *ignore* code sets."""
+    filtered = rules
+    if select:
+        filtered = tuple(r for r in filtered if r.code in select)
+    if ignore:
+        filtered = tuple(r for r in filtered if r.code not in ignore)
+    return filtered
+
+
+_NOPW_RE = re.compile(r"#\s*nopw:\s*(PW\d+(?:\s*,\s*PW\d+)*)")
+_NOCHECK_RE = re.compile(r"^\s*#\s*pythaw:\s*nocheck\b")
+
+
+def _read_source(file: Path) -> str | None:
+    """Read *file* and return its contents, or ``None`` on failure."""
+    try:
+        return file.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return None
+
+
+def _parse_source(source: str, file: Path) -> ast.Module | None:
+    """Parse *source* and return the AST, or ``None`` on failure."""
+    try:
+        return ast.parse(source, filename=str(file))
+    except SyntaxError:
+        return None
+
+
+def _has_nocheck(source: str) -> bool:
+    """Return ``True`` if *source* contains a ``# pythaw: nocheck`` directive."""
+    for line in source.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            if _NOCHECK_RE.match(stripped):
+                return True
+            continue
+        break
+    return False
+
+
+def _parse_nopw_comments(source: str) -> dict[int, frozenset[str]]:
+    """Extract per-line ``# nopw: PWXXX`` suppression directives.
+
+    Returns a mapping of line number to the set of suppressed rule codes.
+    """
+    suppressed: dict[int, frozenset[str]] = {}
+    for lineno, line in enumerate(source.splitlines(), start=1):
+        m = _NOPW_RE.search(line)
+        if m:
+            codes = frozenset(c.strip() for c in m.group(1).split(","))
+            suppressed[lineno] = codes
+    return suppressed
+
+
+def _extract_handlers(
+    tree: ast.Module,
+    patterns: tuple[str, ...],
+) -> list[FunctionNode]:
+    """Return top-level function nodes whose name matches *patterns*."""
+    # Only inspect top-level nodes (iter_child_nodes does not recurse)
+    # so that nested functions and class methods are excluded.
+    return [
+        node
+        for node in ast.iter_child_nodes(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and any(fnmatch(node.name, p) for p in patterns)
+    ]
+
+
+def _check_function(  # noqa: PLR0913
+    file: Path,
+    func_node: FunctionNode,
+    rules: tuple[Rule, ...],
+    suppressed: dict[int, frozenset[str]],
+    resolver: Resolver,
+    *,
+    chain: tuple[CallSite, ...] = (),
+    visited: set[tuple[str, str]] | None = None,
+) -> list[Violation]:
+    """Walk *func_node* and return violations, following local calls."""
+    if visited is None:
+        visited = set()
+
+    violations: list[Violation] = []
+    for node in ast.walk(func_node):
+        if not isinstance(node, ast.Call):
+            continue
+
+        # Check rule violations
+        suppressed_codes = suppressed.get(node.lineno, frozenset())
+        violations.extend(
+            Violation(
+                file=os.path.relpath(file),
+                line=node.lineno,
+                col=node.col_offset,
+                code=rule.code,
+                message=rule.message,
+                call_chain=chain,
+            )
+            for rule in rules
+            if rule.check(node) and rule.code not in suppressed_codes
+        )
+
+        # Follow resolved local calls
+        _follow_call(
+            file,
+            node,
+            rules,
+            resolver,
+            chain,
+            visited,
+            violations,
+        )
+
+    return violations
+
+
+def _follow_call(  # noqa: PLR0913
+    file: Path,
+    node: ast.Call,
+    rules: tuple[Rule, ...],
+    resolver: Resolver,
+    chain: tuple[CallSite, ...],
+    visited: set[tuple[str, str]],
+    violations: list[Violation],
+) -> None:
+    """Resolve *node* and recursively check the target definition."""
+    target = resolver.resolve_call(file, node)
+    if target is None:
+        return
+    target_file, target_defn = target
+
+    walkable: FunctionNode | None
+    if isinstance(target_defn, ast.ClassDef):
+        walkable = resolver.get_init(target_defn)
+    else:
+        walkable = target_defn
+    if walkable is None:
+        return
+
+    key = (str(target_file.resolve()), target_defn.name)
+    if key in visited:
+        return
+    visited.add(key)
+
+    site = CallSite(
+        file=os.path.relpath(file),
+        line=node.lineno,
+        col=node.col_offset,
+        name=resolver.call_display_name(node),
+    )
+    target_source = resolver.read_source(target_file)
+    target_suppressed = _parse_nopw_comments(target_source) if target_source else {}
+    violations.extend(
+        _check_function(
+            target_file,
+            walkable,
+            rules,
+            target_suppressed,
+            resolver,
+            chain=(*chain, site),
+            visited=visited,
+        )
+    )