pytecode 0.0.1__py3-none-any.whl

pytecode/constants.py

@@ -0,0 +1,208 @@
+"""Constants for JVM class file parsing (JVMS §4)."""
+
+from enum import Enum, IntEnum, IntFlag
+
+__all__ = [
+    "ClassAccessFlag",
+    "FieldAccessFlag",
+    "MAGIC",
+    "MethodAccessFlag",
+    "MethodParameterAccessFlag",
+    "ModuleAccessFlag",
+    "ModuleExportsAccessFlag",
+    "ModuleOpensAccessFlag",
+    "ModuleRequiresAccessFlag",
+    "NestedClassAccessFlag",
+    "TargetInfoType",
+    "TargetType",
+    "TypePathKind",
+    "VerificationType",
+]
+
+MAGIC = 0xCAFEBABE
+"""The magic number identifying a valid Java class file (§4.1)."""
+
+
+class ModuleAccessFlag(IntFlag):
+    """Access flags for modules (§4.7.25, Table 4.7.25-A)."""
+
+    OPEN = 0x0020
+    SYNTHETIC = 0x1000
+    MANDATED = 0x8000
+
+
+class ModuleRequiresAccessFlag(IntFlag):
+    """Access flags for module requires directives (§4.7.25, Table 4.7.25-B)."""
+
+    TRANSITIVE = 0x0020
+    STATIC_PHASE = 0x0040
+    SYNTHETIC = 0x1000
+    MANDATED = 0x8000
+
+
+class ModuleExportsAccessFlag(IntFlag):
+    """Access flags for module exports directives (§4.7.25, Table 4.7.25-C)."""
+
+    SYNTHETIC = 0x1000
+    MANDATED = 0x8000
+
+
+class ModuleOpensAccessFlag(IntFlag):
+    """Access flags for module opens directives (§4.7.25, Table 4.7.25-D)."""
+
+    SYNTHETIC = 0x1000
+    MANDATED = 0x8000
+
+
+class ClassAccessFlag(IntFlag):
+    """Access flags for classes (§4.1, Table 4.1-B)."""
+
+    PUBLIC = 0x0001
+    FINAL = 0x0010
+    SUPER = 0x0020
+    INTERFACE = 0x0200
+    ABSTRACT = 0x0400
+    SYNTHETIC = 0x1000
+    ANNOTATION = 0x2000
+    ENUM = 0x4000
+    MODULE = 0x8000
+
+
+class NestedClassAccessFlag(IntFlag):
+    """Access flags for nested classes (§4.7.6, Table 4.7.6-A)."""
+
+    PUBLIC = 0x0001
+    PRIVATE = 0x0002
+    PROTECTED = 0x0004
+    STATIC = 0x0008
+    FINAL = 0x0010
+    INTERFACE = 0x0200
+    ABSTRACT = 0x0400
+    SYNTHETIC = 0x1000
+    ANNOTATION = 0x2000
+    ENUM = 0x4000
+
+
+class MethodAccessFlag(IntFlag):
+    """Access flags for methods (§4.6, Table 4.6-A)."""
+
+    PUBLIC = 0x0001
+    PRIVATE = 0x0002
+    PROTECTED = 0x0004
+    STATIC = 0x0008
+    FINAL = 0x0010
+    SYNCHRONIZED = 0x0020
+    BRIDGE = 0x0040
+    VARARGS = 0x0080
+    NATIVE = 0x0100
+    ABSTRACT = 0x0400
+    STRICT = 0x0800
+    SYNTHETIC = 0x1000
+
+
+class MethodParameterAccessFlag(IntFlag):
+    """Access flags for method parameters (§4.7.24, Table 4.7.24-A)."""
+
+    FINAL = 0x0010
+    SYNTHETIC = 0x1000
+    MANDATED = 0x8000
+
+
+class FieldAccessFlag(IntFlag):
+    """Access flags for fields (§4.5, Table 4.5-A)."""
+
+    PUBLIC = 0x0001
+    PRIVATE = 0x0002
+    PROTECTED = 0x0004
+    STATIC = 0x0008
+    FINAL = 0x0010
+    VOLATILE = 0x0040
+    TRANSIENT = 0x0080
+    SYNTHETIC = 0x1000
+    ENUM = 0x4000
+
+
+class TargetType(IntEnum):
+    """Target type values for type annotations (§4.7.20, Table 4.7.20-A/B)."""
+
+    TYPE_PARAMETER_GENERIC_CLASS_OR_INTERFACE = 0x00
+    TYPE_PARAMETER_GENERIC_METHOD_OR_CONSTRUCTOR = 0x01
+    SUPERTYPE = 0x10
+    TYPE_PARAMETER_BOUND_GENERIC_CLASS_OR_INTERFACE = 0x11
+    TYPE_PARAMETER_BOUND_GENERIC_METHOD_OR_CONSTRUCTOR = 0x12
+    TYPE_IN_FIELD_OR_RECORD = 0x13
+    RETURN_OR_OBJECT_TYPE = 0x14
+    RECEIVER_TYPE_METHOD_OR_CONSTRUCTOR = 0x15
+    FORMAL_PARAMETER_METHOD_CONSTRUCTOR_OR_LAMBDA = 0x16
+    TYPE_THROWS = 0x17
+    TYPE_LOCAL_VARIABLE = 0x40
+    TYPE_RESOURCE_VARIABLE = 0x41
+    TYPE_EXCEPTION_PARAMETER = 0x42
+    TYPE_INSTANCEOF = 0x43
+    TYPE_NEW = 0x44
+    TYPE_METHOD_NEW = 0x45
+    TYPE_METHOD_IDENTIFIER = 0x46
+    TYPE_CAST = 0x47
+    TYPE_GENERIC_CONSTRUCTOR = 0x48
+    TYPE_GENERIC_METHOD = 0x49
+    TYPE_GENERIC_CONSTRUCTOR_NEW = 0x4A
+    TYPE_GENERIC_METHOD_IDENTIFIER = 0x4B
+
+
+class TargetInfoType(Enum):
+    """Mapping from target_info union discriminants to target types (§4.7.20.1)."""
+
+    TYPE_PARAMETER = (
+        TargetType.TYPE_PARAMETER_GENERIC_CLASS_OR_INTERFACE,
+        TargetType.TYPE_PARAMETER_GENERIC_METHOD_OR_CONSTRUCTOR,
+    )
+    SUPERTYPE = (TargetType.SUPERTYPE,)
+    TYPE_PARAMETER_BOUND = (
+        TargetType.TYPE_PARAMETER_BOUND_GENERIC_CLASS_OR_INTERFACE,
+        TargetType.TYPE_PARAMETER_BOUND_GENERIC_METHOD_OR_CONSTRUCTOR,
+    )
+    EMPTY = (
+        TargetType.TYPE_IN_FIELD_OR_RECORD,
+        TargetType.RETURN_OR_OBJECT_TYPE,
+        TargetType.RECEIVER_TYPE_METHOD_OR_CONSTRUCTOR,
+    )
+    FORMAL_PARAMETER = (TargetType.FORMAL_PARAMETER_METHOD_CONSTRUCTOR_OR_LAMBDA,)
+    THROWS = (TargetType.TYPE_THROWS,)
+    LOCALVAR = (TargetType.TYPE_LOCAL_VARIABLE, TargetType.TYPE_RESOURCE_VARIABLE)
+    CATCH = (TargetType.TYPE_EXCEPTION_PARAMETER,)
+    OFFSET = (
+        TargetType.TYPE_INSTANCEOF,
+        TargetType.TYPE_NEW,
+        TargetType.TYPE_METHOD_NEW,
+        TargetType.TYPE_METHOD_IDENTIFIER,
+    )
+    TYPE_ARGUMENT = (
+        TargetType.TYPE_CAST,
+        TargetType.TYPE_GENERIC_CONSTRUCTOR,
+        TargetType.TYPE_GENERIC_METHOD,
+        TargetType.TYPE_GENERIC_CONSTRUCTOR_NEW,
+        TargetType.TYPE_GENERIC_METHOD_IDENTIFIER,
+    )
+
+
+class TypePathKind(IntEnum):
+    """Kind values for type_path entries in type annotations (§4.7.20.2, Table 4.7.20.2-A)."""
+
+    ARRAY_TYPE = 0
+    NESTED_TYPE = 1
+    WILDCARD_TYPE = 2
+    PARAMETERIZED_TYPE = 3
+
+
+class VerificationType(IntEnum):
+    """Verification type info tags for StackMapTable entries (§4.7.4, Table 4.7.4-A)."""
+
+    TOP = 0
+    INTEGER = 1
+    FLOAT = 2
+    DOUBLE = 3
+    LONG = 4
+    NULL = 5
+    UNINITIALIZED_THIS = 6
+    OBJECT = 7
+    UNINITIALIZED = 8

pytecode/debug_info.py

@@ -0,0 +1,319 @@
+"""Utilities for managing JVM debug information in class files.
+
+Provides policies, state tracking, and stripping helpers for debug
+attributes such as line numbers, local variables, and source file
+references.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, overload
+
+from .attributes import AttributeInfo, MethodParametersAttr, SourceDebugExtensionAttr, SourceFileAttr
+
+if TYPE_CHECKING:
+    from .model import ClassModel, CodeModel, MethodModel
+
+__all__ = [
+    "DebugInfoPolicy",
+    "DebugInfoState",
+    "apply_debug_info_policy",
+    "has_class_debug_info",
+    "has_code_debug_info",
+    "is_class_debug_info_stale",
+    "is_code_debug_info_stale",
+    "mark_class_debug_info_stale",
+    "mark_code_debug_info_stale",
+    "normalize_debug_info_policy",
+    "skip_debug_method_attributes",
+    "strip_class_debug_attributes",
+    "strip_debug_info",
+]
+
+
+class DebugInfoPolicy(Enum):
+    """Policy controlling how debug information is handled.
+
+    Attributes:
+        PRESERVE: Keep existing debug information unchanged.
+        STRIP: Remove all debug information from the target.
+    """
+
+    PRESERVE = "preserve"
+    STRIP = "strip"
+
+
+class DebugInfoState(Enum):
+    """Staleness state of debug information on a model.
+
+    Attributes:
+        FRESH: Debug information is up to date.
+        STALE: Debug information may be outdated due to bytecode changes.
+    """
+
+    FRESH = "fresh"
+    STALE = "stale"
+
+
+def normalize_debug_info_policy(policy: DebugInfoPolicy | str) -> DebugInfoPolicy:
+    """Coerce a string or enum value into a ``DebugInfoPolicy``.
+
+    Args:
+        policy: A ``DebugInfoPolicy`` member or its string value.
+
+    Returns:
+        The corresponding ``DebugInfoPolicy`` member.
+
+    Raises:
+        ValueError: If the string does not match any policy value.
+    """
+    if isinstance(policy, DebugInfoPolicy):
+        return policy
+    try:
+        return DebugInfoPolicy(policy)
+    except ValueError as exc:
+        expected = ", ".join(member.value for member in DebugInfoPolicy)
+        raise ValueError(f"debug_info must be one of: {expected}") from exc
+
+
+def strip_class_debug_attributes(attributes: list[AttributeInfo]) -> list[AttributeInfo]:
+    """Filter out class-level debug attributes from a list.
+
+    Removes ``SourceFileAttr`` and ``SourceDebugExtensionAttr`` entries,
+    returning only the non-debug attributes.
+
+    Args:
+        attributes: The attribute list to filter.
+
+    Returns:
+        A new list with class-level debug attributes removed.
+    """
+    return [
+        attribute for attribute in attributes if not isinstance(attribute, (SourceFileAttr, SourceDebugExtensionAttr))
+    ]
+
+
+def skip_debug_method_attributes(attributes: list[AttributeInfo]) -> list[AttributeInfo]:
+    """Filter out method-level debug attributes from a list.
+
+    Removes ``MethodParametersAttr`` entries, returning only the
+    remaining attributes.
+
+    Args:
+        attributes: The attribute list to filter.
+
+    Returns:
+        A new list with method-level debug attributes removed.
+    """
+    return [attribute for attribute in attributes if not isinstance(attribute, MethodParametersAttr)]
+
+
+def has_class_debug_info(target: ClassModel) -> bool:
+    """Check whether a class model contains class-level debug attributes.
+
+    Args:
+        target: The class model to inspect.
+
+    Returns:
+        ``True`` if the class has ``SourceFileAttr`` or
+        ``SourceDebugExtensionAttr`` attributes.
+    """
+    return any(isinstance(attribute, (SourceFileAttr, SourceDebugExtensionAttr)) for attribute in target.attributes)
+
+
+def has_code_debug_info(target: CodeModel) -> bool:
+    """Check whether a code model contains code-level debug information.
+
+    Args:
+        target: The code model to inspect.
+
+    Returns:
+        ``True`` if the code has line numbers, local variables, or local
+        variable type entries.
+    """
+    return bool(target.line_numbers or target.local_variables or target.local_variable_types)
+
+
+def is_class_debug_info_stale(target: ClassModel) -> bool:
+    """Check whether a class model has stale class-level debug info.
+
+    Args:
+        target: The class model to inspect.
+
+    Returns:
+        ``True`` if the debug state is stale and debug attributes are present.
+    """
+    return target.debug_info_state is DebugInfoState.STALE and has_class_debug_info(target)
+
+
+def is_code_debug_info_stale(target: CodeModel) -> bool:
+    """Check whether a code model has stale code-level debug info.
+
+    Args:
+        target: The code model to inspect.
+
+    Returns:
+        ``True`` if the debug state is stale and debug information is present.
+    """
+    return target.debug_info_state is DebugInfoState.STALE and has_code_debug_info(target)
+
+
+def mark_class_debug_info_stale(target: ClassModel) -> ClassModel:
+    """Mark a class model's debug information as stale.
+
+    If the class has debug attributes, sets its debug state to
+    ``DebugInfoState.STALE``.
+
+    Args:
+        target: The class model to mark.
+
+    Returns:
+        The same class model, possibly with updated debug state.
+    """
+    if has_class_debug_info(target):
+        target.debug_info_state = DebugInfoState.STALE
+    return target
+
+
+@overload
+def mark_code_debug_info_stale(target: CodeModel) -> CodeModel: ...
+
+
+@overload
+def mark_code_debug_info_stale(target: MethodModel) -> MethodModel: ...
+
+
+@overload
+def mark_code_debug_info_stale(target: ClassModel) -> ClassModel: ...
+
+
+def mark_code_debug_info_stale(target: object) -> object:
+    """Mark code-level debug information as stale.
+
+    Accepts a ``CodeModel``, ``MethodModel``, or ``ClassModel``. For a
+    ``CodeModel``, sets its state to stale if it has debug info. For a
+    ``MethodModel``, delegates to its code attribute. For a ``ClassModel``,
+    recursively marks all methods.
+
+    Args:
+        target: The model whose code debug info should be marked stale.
+
+    Returns:
+        The same model, possibly with updated debug state.
+
+    Raises:
+        TypeError: If *target* is not a supported model type.
+    """
+    from .model import ClassModel, CodeModel, MethodModel
+
+    if isinstance(target, CodeModel):
+        if has_code_debug_info(target):
+            target.debug_info_state = DebugInfoState.STALE
+        return target
+    if isinstance(target, MethodModel):
+        if target.code is not None:
+            mark_code_debug_info_stale(target.code)
+        return target
+    if isinstance(target, ClassModel):
+        for method in target.methods:
+            mark_code_debug_info_stale(method)
+        return target
+    raise TypeError("code-debug helper expects a CodeModel, MethodModel, or ClassModel")
+
+
+@overload
+def apply_debug_info_policy(target: CodeModel, policy: DebugInfoPolicy | str) -> CodeModel: ...
+
+
+@overload
+def apply_debug_info_policy(target: MethodModel, policy: DebugInfoPolicy | str) -> MethodModel: ...
+
+
+@overload
+def apply_debug_info_policy(target: ClassModel, policy: DebugInfoPolicy | str) -> ClassModel: ...
+
+
+def apply_debug_info_policy(target: object, policy: DebugInfoPolicy | str) -> object:
+    """Apply a debug information policy to a model.
+
+    When the policy is ``STRIP``, removes all debug information from the
+    target. When the policy is ``PRESERVE``, leaves the target unchanged.
+
+    Args:
+        target: The model to apply the policy to.
+        policy: The policy to apply, as an enum member or string.
+
+    Returns:
+        The same model, with debug information stripped if requested.
+
+    Raises:
+        TypeError: If *target* is not a supported model type.
+        ValueError: If *policy* is an invalid string.
+    """
+    from .model import ClassModel, CodeModel, MethodModel
+
+    debug_policy = normalize_debug_info_policy(policy)
+    if isinstance(target, CodeModel):
+        if debug_policy is DebugInfoPolicy.STRIP:
+            strip_debug_info(target)
+        return target
+    if isinstance(target, MethodModel):
+        if debug_policy is DebugInfoPolicy.STRIP:
+            strip_debug_info(target)
+        return target
+    if isinstance(target, ClassModel):
+        if debug_policy is DebugInfoPolicy.STRIP:
+            strip_debug_info(target)
+        return target
+    raise TypeError("debug-info helpers expect a CodeModel, MethodModel, or ClassModel")
+
+
+@overload
+def strip_debug_info(target: CodeModel) -> CodeModel: ...
+
+
+@overload
+def strip_debug_info(target: MethodModel) -> MethodModel: ...
+
+
+@overload
+def strip_debug_info(target: ClassModel) -> ClassModel: ...
+
+
+def strip_debug_info(target: object) -> object:
+    """Remove all debug information from a model.
+
+    For a ``CodeModel``, clears line numbers, local variables, and local
+    variable types. For a ``MethodModel``, delegates to its code attribute.
+    For a ``ClassModel``, strips class-level debug attributes and recurses
+    into all methods.
+
+    Args:
+        target: The model to strip debug information from.
+
+    Returns:
+        The same model with debug information removed and state set to fresh.
+
+    Raises:
+        TypeError: If *target* is not a supported model type.
+    """
+    from .model import ClassModel, CodeModel, MethodModel
+
+    if isinstance(target, CodeModel):
+        target.line_numbers.clear()
+        target.local_variables.clear()
+        target.local_variable_types.clear()
+        target.debug_info_state = DebugInfoState.FRESH
+        return target
+    if isinstance(target, MethodModel):
+        if target.code is not None:
+            strip_debug_info(target.code)
+        return target
+    if isinstance(target, ClassModel):
+        target.attributes[:] = strip_class_debug_attributes(target.attributes)
+        target.debug_info_state = DebugInfoState.FRESH
+        for method in target.methods:
+            strip_debug_info(method)
+        return target
+    raise TypeError("debug-info helpers expect a CodeModel, MethodModel, or ClassModel")