shakeout 0.1.0__py3-none-any.whl

shakeout/__init__.py

@@ -0,0 +1,3 @@
+"""shakeout: a static, tree-shaking bundler for Python."""
+
+__version__ = "0.1.0"

shakeout/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m shakeout``."""
+
+from shakeout.cli import main
+
+raise SystemExit(main())

shakeout/_compat.py

@@ -0,0 +1,19 @@
+"""Small shims for older supported Python versions (no extra runtime dependencies)."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+if sys.version_info >= (3, 12):
+    from typing import override
+elif TYPE_CHECKING:  # type checkers understand typing_extensions; nothing is imported at runtime
+    from typing_extensions import override
+else:  # pragma: no cover - exercised on 3.10/3.11 only
+
+    def override(func, /):  # noqa: ANN001, ANN202 - typed via typing_extensions above
+        """Mark a method as overriding its base (typing.override before 3.12)."""
+        return func
+
+
+__all__ = ["override"]

shakeout/analysis/__init__.py

@@ -0,0 +1 @@
+"""Per-statement analysis: scopes, bindings and side effects."""

shakeout/analysis/classes.py

@@ -0,0 +1,115 @@
+"""Side effects of class definitions that come from their bases.
+
+Subclassing runs ``__init_subclass__`` and metaclass code of every base, which is how plugin
+registries work. A class is *registering* if it defines ``__init_subclass__``, has a metaclass,
+or inherits from a registering class; defining a subclass of a registering class is a side effect.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+from shakeout.analysis.effects import EffectRules
+from shakeout.analysis.registry import PURE_BASE_MODULES, PURE_BASES
+from shakeout.analysis.scopes import attribute_chain
+from shakeout.model import NameTarget
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from shakeout.graph import Resolver, StmtKey
+    from shakeout.model import Module
+
+Verdict = tuple[str | None, bool]  # (impurity reason from bases, is registering)
+
+
+class ClassEffects:
+    """Classifies class statements by what their bases do when subclassed."""
+
+    def __init__(
+        self,
+        modules: dict[str, Module],
+        resolver: Resolver,
+        qualify: Callable[[Module, ast.expr], str | None],
+        *,
+        pure_calls: frozenset[str],
+        assume_pure_bases: bool,
+    ) -> None:
+        """Create an analyzer over ``modules``; ``qualify`` names expressions per module."""
+        self.modules = modules
+        self.resolver = resolver
+        self.qualify = qualify
+        self.pure_calls = pure_calls
+        self.assume_pure_bases = assume_pure_bases
+        self._memo: dict[StmtKey, Verdict] = {}
+
+    def classify_all(self) -> None:
+        """Set ``impure`` on every class statement whose bases make defining it observable."""
+        for mod in self.modules.values():
+            for st in mod.statements:
+                if st.kind == "class" and not st.impure:
+                    st.impure, _ = self.verdict((mod.name, st.index), frozenset())
+
+    def verdict(self, key: StmtKey, active: frozenset[StmtKey]) -> Verdict:
+        """Impurity reason and registering flag for the class statement ``key``."""
+        if key in self._memo:
+            return self._memo[key]
+        if key in active:
+            return ("cyclic class hierarchy", True)
+        mod = self.modules[key[0]]
+        node = mod.statements[key[1]].nodes[0]
+        if not isinstance(node, ast.ClassDef):  # pragma: no cover - callers check kind
+            return (None, False)
+        registering = _declares_registration(node)
+        impure: str | None = None
+        for base in node.bases:
+            reason = self._base_reason(mod, base, active | {key})
+            if reason:
+                impure = impure or reason
+                registering = True
+        self._memo[key] = (impure, registering)
+        return self._memo[key]
+
+    def _base_reason(self, mod: Module, base: ast.expr, active: frozenset[StmtKey]) -> str | None:
+        text = ast.unparse(base)
+        expr = base.value if isinstance(base, ast.Subscript) else base
+        chain = attribute_chain(expr)
+        if chain is None:
+            rules = EffectRules(lambda e: self.qualify(mod, e), self.pure_calls)
+            return None if rules.pure_expr(base) else f"base {text!r} may have side effects"
+        qualified = self.qualify(mod, expr)
+        if qualified is not None and self._is_external(qualified):
+            return self._external_base_reason(qualified, text)
+        res = self.resolver.resolve(mod.name, NameTarget(chain[0]), chain[1])
+        if not res.terminal:
+            return None if self.assume_pure_bases else f"base {text!r} cannot be resolved"
+        for tkey in sorted(res.terminal):
+            tst = self.modules[tkey[0]].statements[tkey[1]]
+            if tst.kind == "class" and isinstance(tst.nodes[0], ast.ClassDef):
+                if self.verdict(tkey, active)[1]:
+                    return f"base {text!r} registers subclasses (__init_subclass__/metaclass)"
+            elif not self.assume_pure_bases:
+                return f"base {text!r} is not a plain class definition"
+        return None
+
+    def _external_base_reason(self, qualified: str, text: str) -> str | None:
+        known_pure = (
+            qualified.startswith("builtins.")
+            or qualified in PURE_BASES
+            or qualified.rpartition(".")[0] in PURE_BASE_MODULES
+        )
+        if known_pure or self.assume_pure_bases:
+            return None
+        return f"base {text!r} comes from outside the bundle and may register subclasses"
+
+    def _is_external(self, qualified: str) -> bool:
+        parts = qualified.split(".")
+        return not any(".".join(parts[:i]) in self.modules for i in range(len(parts), 0, -1))
+
+
+def _declares_registration(node: ast.ClassDef) -> bool:
+    return any(k.arg == "metaclass" for k in node.keywords) or any(
+        isinstance(b, (ast.FunctionDef, ast.AsyncFunctionDef)) and b.name == "__init_subclass__"
+        for b in node.body
+    )

shakeout/analysis/effects.py

@@ -0,0 +1,168 @@
+"""Side-effect classification of top-level statements.
+
+A statement is *pure* when executing it only creates bindings in its own module: it cannot print,
+mutate shared state, register anything, or fail in a way that matters. Pure statements may be
+removed when nothing references what they bind. Everything else is impure and always kept.
+
+The rules are deliberately conservative. Known assumptions (documented in docs/PLAN.md):
+operators, attribute reads and subscripts on module-level values do not call user code with side
+effects, and the listed pure callables do not call back into user code.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, cast
+
+from shakeout.analysis.registry import PURE_CALLABLES, PURE_IF_CHILDREN_PURE
+from shakeout.model import ImportTarget, ModuleTarget
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class EffectRules:
+    """Purity rules for one module. ``qualify`` maps an expression to a dotted external name."""
+
+    def __init__(
+        self,
+        qualify: Callable[[ast.expr], str | None],
+        extra_pure: frozenset[str] = frozenset(),
+    ) -> None:
+        self.qualify = qualify
+        self.pure_callables = PURE_CALLABLES | extra_pure
+
+    # -- expressions -------------------------------------------------------------------------
+    def pure_callable(self, func: ast.expr) -> bool:
+        """Whether calling ``func`` is known to have no side effects."""
+        q = self.qualify(func)
+        return q is not None and q in self.pure_callables
+
+    def pure_expr(self, node: ast.expr | None) -> bool:
+        """Whether evaluating ``node`` at module level has no observable side effects."""
+        if node is None or isinstance(node, (ast.Constant, ast.Name, ast.Lambda)):
+            return True
+        if isinstance(node, ast.Call):
+            return (
+                self.pure_callable(node.func)
+                and all(self.pure_expr(a) for a in node.args)
+                and all(self.pure_expr(k.value) for k in node.keywords)
+            )
+        children = PURE_IF_CHILDREN_PURE.get(type(node))
+        # Anything else (comprehensions may call user __iter__, walrus binds, await...) is impure.
+        return children is not None and all(self.pure_expr(c) for c in children(node))
+
+    def pure_decorator(self, node: ast.expr) -> bool:
+        """Whether applying the decorator ``node`` has no side effects."""
+        if isinstance(node, ast.Call):
+            return self.pure_expr(node)
+        return self.pure_callable(node)
+
+    # -- statements --------------------------------------------------------------------------
+    def function_effect(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> str | None:
+        """Why defining the function has side effects (decorators, defaults), or None."""
+        for deco in node.decorator_list:
+            if not self.pure_decorator(deco):
+                return f"decorator {ast.unparse(deco)!r} may have side effects"
+        for default in (*node.args.defaults, *node.args.kw_defaults):
+            if not self.pure_expr(default):
+                return "default argument value may have side effects"
+        return None
+
+    def class_shell_effect(self, node: ast.ClassDef) -> str | None:
+        """Effects from decorators, keywords and body; bases are checked by the linker."""
+        for deco in node.decorator_list:
+            if not self.pure_decorator(deco):
+                return f"class decorator {ast.unparse(deco)!r} may have side effects"
+        for kw in node.keywords:
+            return f"class keyword {kw.arg or '**'!s}= is passed to the metaclass/__init_subclass__"
+        for base in node.bases:
+            if isinstance(base, ast.Starred):
+                return "starred class bases"
+        for stmt in node.body:
+            reason = self.class_body_effect(stmt)
+            if reason:
+                return reason
+        return None
+
+    def class_body_effect(self, stmt: ast.stmt) -> str | None:
+        """Why executing ``stmt`` inside a class body has side effects, or None."""
+        match stmt:
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                return self.function_effect(stmt)
+            case ast.ClassDef():
+                return self.class_shell_effect(stmt) or (
+                    None if all(self.pure_expr(b) for b in stmt.bases) else "nested class base"
+                )
+            case ast.Assign(targets=targets, value=value):
+                if all(isinstance(t, ast.Name) for t in targets) and self.pure_expr(value):
+                    return None
+                return "class attribute initializer may have side effects"
+            case ast.AnnAssign(target=ast.Name(), value=value):
+                return (
+                    None
+                    if self.pure_expr(value)
+                    else "class attribute initializer may have side effects"
+                )
+            case ast.Expr(value=ast.Constant()) | ast.Pass():
+                return None
+            case _:
+                return f"class body contains {type(stmt).__name__}"
+
+    def assignment_effect(self, stmt: ast.Assign | ast.AnnAssign) -> str | None:
+        """Why a module-level assignment has side effects, or None."""
+        value: ast.expr | None
+        if isinstance(stmt, ast.Assign):
+            targets: list[ast.expr] = list(stmt.targets)
+            value = stmt.value
+        else:
+            if stmt.value is None and isinstance(stmt.target, ast.Name):
+                return None
+            targets, value = [cast("ast.expr", stmt.target)], stmt.value
+        for t in targets:
+            for sub in ast.walk(t):
+                if isinstance(sub, (ast.Attribute, ast.Subscript)):
+                    return "assignment stores into an attribute or item"
+        if not self.pure_expr(value):
+            return f"initializer {_short(value)} may have side effects"
+        return None
+
+
+_SHORT = 40
+
+
+def _short(node: ast.expr | None) -> str:
+    if node is None:
+        return "''"
+    text = ast.unparse(node)
+    return repr(text if len(text) <= _SHORT else text[: _SHORT - 3] + "...")
+
+
+def is_main_guard(node: ast.stmt) -> bool:
+    """Whether ``node`` is ``if __name__ == '__main__':``."""
+    if not isinstance(node, ast.If):
+        return False
+    test = node.test
+    if isinstance(test, ast.Compare) and len(test.ops) == 1 and isinstance(test.ops[0], ast.Eq):
+        sides = [test.left, test.comparators[0]]
+        names = [s for s in sides if isinstance(s, ast.Name) and s.id == "__name__"]
+        consts = [s for s in sides if isinstance(s, ast.Constant) and s.value == "__main__"]
+        return bool(names and consts)
+    return False
+
+
+def is_type_checking_guard(node: ast.stmt, qualify: Callable[[ast.expr], str | None]) -> bool:
+    """Whether ``node`` is ``if TYPE_CHECKING:`` without an ``else``."""
+    if not isinstance(node, ast.If) or node.orelse:
+        return False
+    q = qualify(node.test)
+    if q in {"typing.TYPE_CHECKING", "typing_extensions.TYPE_CHECKING"}:
+        return True
+    return isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING"
+
+
+def qualify_target(target: ImportTarget, attrs: tuple[str, ...]) -> str:
+    """Dotted name of ``attrs`` reached through an import target."""
+    if isinstance(target, ModuleTarget):
+        return ".".join((target.module, *attrs))
+    return ".".join((target.module, target.attr, *attrs))

shakeout/analysis/registry.py

@@ -0,0 +1,220 @@
+"""Static knowledge used by the effects rules.
+
+Known-pure callables, safe base classes, and which expressions are pure when their parts are.
+Pure data built once at import, so it is kept out of mutation testing (mutants of import-time
+code can never be observed).
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_TYPING = ("typing", "typing_extensions")
+
+
+def _qualified(*names: str) -> frozenset[str]:
+    return frozenset(names)
+
+
+PURE_CALLABLES = _qualified(
+    # builtins that construct values and never call user callbacks
+    *(
+        f"builtins.{n}"
+        for n in (
+            "object",
+            "int",
+            "float",
+            "complex",
+            "str",
+            "bytes",
+            "bytearray",
+            "bool",
+            "tuple",
+            "list",
+            "dict",
+            "set",
+            "frozenset",
+            "range",
+            "slice",
+            "len",
+            "repr",
+            "ord",
+            "chr",
+            "hex",
+            "oct",
+            "bin",
+            "abs",
+            "round",
+            "property",
+            "staticmethod",
+            "classmethod",
+            "isinstance",
+            "issubclass",
+            "callable",
+            "id",
+            "memoryview",
+        )
+    ),
+    *(
+        f"{m}.{n}"
+        for m in _TYPING
+        for n in (
+            "TypeVar",
+            "NewType",
+            "ParamSpec",
+            "TypeVarTuple",
+            "NamedTuple",
+            "TypedDict",
+            "cast",
+            "overload",
+            "final",
+            "runtime_checkable",
+            "no_type_check",
+            "dataclass_transform",
+            "override",
+            "TypeAliasType",
+            "get_type_hints",
+            "deprecated",
+        )
+    ),
+    "collections.namedtuple",
+    "collections.OrderedDict",
+    "collections.defaultdict",
+    "collections.deque",
+    "collections.Counter",
+    "collections.ChainMap",
+    "re.compile",
+    "dataclasses.field",
+    "dataclasses.dataclass",
+    "dataclasses.make_dataclass",
+    "functools.partial",
+    "functools.lru_cache",
+    "functools.cache",
+    "functools.wraps",
+    "functools.cached_property",
+    "functools.total_ordering",
+    "functools.singledispatch",
+    "functools.singledispatchmethod",
+    "functools.partialmethod",
+    "contextlib.contextmanager",
+    "contextlib.asynccontextmanager",
+    "abc.abstractmethod",
+    "abc.abstractproperty",
+    "abc.abstractclassmethod",
+    "abc.abstractstaticmethod",
+    "enum.auto",
+    "enum.unique",
+    "enum.verify",
+    "enum.member",
+    "enum.nonmember",
+    "logging.getLogger",
+    "operator.itemgetter",
+    "operator.attrgetter",
+    "operator.methodcaller",
+    "pathlib.Path",
+    "pathlib.PurePath",
+    "pathlib.PurePosixPath",
+    "pathlib.PureWindowsPath",
+    "decimal.Decimal",
+    "fractions.Fraction",
+    "datetime.timedelta",
+    "datetime.date",
+    "datetime.datetime",
+    "datetime.time",
+    "datetime.timezone",
+    "types.MappingProxyType",
+    "types.SimpleNamespace",
+    "struct.Struct",
+    "string.Template",
+    "threading.Lock",
+    "threading.RLock",
+    "threading.local",
+    "threading.Event",
+    "weakref.WeakValueDictionary",
+    "weakref.WeakKeyDictionary",
+    "weakref.WeakSet",
+    "weakref.ref",
+    "contextvars.ContextVar",
+    "uuid.UUID",
+    "ipaddress.ip_address",
+    "ipaddress.ip_network",
+)
+
+# Bases whose subclassing has no global side effects.
+PURE_BASES = _qualified(
+    *(
+        f"{m}.{n}"
+        for m in _TYPING
+        for n in (
+            "NamedTuple",
+            "TypedDict",
+            "Protocol",
+            "Generic",
+            "Any",
+        )
+    ),
+    "abc.ABC",
+    "enum.Enum",
+    "enum.IntEnum",
+    "enum.Flag",
+    "enum.IntFlag",
+    "enum.StrEnum",
+    "enum.ReprEnum",
+    "collections.OrderedDict",
+    "collections.defaultdict",
+    "collections.UserDict",
+    "collections.UserList",
+    "collections.UserString",
+    "collections.namedtuple",
+    "threading.Thread",
+    "threading.local",
+    "json.JSONEncoder",
+    "json.JSONDecoder",
+    "argparse.Action",
+    "argparse.ArgumentParser",
+    "string.Formatter",
+    "io.StringIO",
+    "io.BytesIO",
+    "contextlib.AbstractContextManager",
+    "contextlib.ContextDecorator",
+    "html.parser.HTMLParser",
+)
+PURE_BASE_MODULES = frozenset({"collections.abc", "numbers", "typing", "typing_extensions"})
+
+
+def _children(*fields: str) -> Callable[[ast.AST], list[ast.expr | None]]:
+    def get(node: ast.AST) -> list[ast.expr | None]:
+        out: list[ast.expr | None] = []
+        for name in fields:
+            value: object = getattr(node, name)
+            if isinstance(value, list):
+                out.extend(cast("list[ast.expr | None]", value))
+            else:
+                out.append(cast("ast.expr | None", value))
+        return out
+
+    return get
+
+
+# Expressions that are pure exactly when all of their sub-expressions are pure.
+PURE_IF_CHILDREN_PURE: dict[type[ast.AST], Callable[[ast.AST], list[ast.expr | None]]] = {
+    ast.Attribute: _children("value"),
+    ast.Subscript: _children("value", "slice"),
+    ast.Tuple: _children("elts"),
+    ast.List: _children("elts"),
+    ast.Set: _children("elts"),
+    ast.Starred: _children("value"),
+    ast.Dict: _children("keys", "values"),
+    ast.BinOp: _children("left", "right"),
+    ast.UnaryOp: _children("operand"),
+    ast.BoolOp: _children("values"),
+    ast.Compare: _children("left", "comparators"),
+    ast.IfExp: _children("test", "body", "orelse"),
+    ast.JoinedStr: _children("values"),
+    ast.FormattedValue: _children("value", "format_spec"),
+    ast.Slice: _children("lower", "upper", "step"),
+}