init.py

Overview

This [__init__.py](/projects/286/67254) file serves as the top-level API entry point for a Python inspection and code generation package. It consolidates and exposes key classes and functions from internal submodules (`code` and `source`), providing a clean and organized interface for users of the package. The main focus of this package is to facilitate introspection of Python code objects, handling of tracebacks and frames, and retrieval of raw source code for dynamic analysis or generation tasks.

By importing this module, users gain access to essential abstractions and utilities for working with Python's runtime code structures and exceptions in a structured and Pythonic manner.

Exported Classes and Functions

Classes

Functions

Detailed Descriptions

Class: Code

**Module:** `.code`

A wrapper around Python's native code objects (`types.CodeType`) that provides enhanced inspection and code generation methods. This class abstracts complexities of Python bytecode structures, enabling:

• Inspection of code attributes (e.g., filename, first line number, constants).

• Generation or modification of code objects for dynamic execution.

**Usage Example:**

from package import Code

code_obj = some_function.__code__
wrapped_code = Code(code_obj)
print(wrapped_code.filename)
print(wrapped_code.firstlineno)

Class: ExceptionInfo

**Module:** `.code`

Encapsulates detailed information about an exception instance, including:

• The exception type and value.

• The associated traceback.

• Methods to extract or format this information for logging or display.

**Usage Example:**

from package import ExceptionInfo

try:
    risky_operation()
except Exception:
    exc_info = ExceptionInfo.from_current_exception()
    print(exc_info.traceback)

Class: Frame

**Module:** `.code`

Represents a single execution frame within the Python call stack. This abstraction provides access to:

• Local and global variables in the frame.

• The code object that the frame is executing.

• The ability to navigate frame chains for stack inspection.

**Usage Example:**

from package import Frame
import sys

current_frame = Frame(sys._getframe())
print(current_frame.locals)

Class: Traceback

**Module:** `.code`

Wraps a Python traceback object to facilitate inspection of the call stack at the point an exception was raised. Enables filtering and traversal of traceback entries.

Class: TracebackEntry

**Module:** `.code`

Represents an individual call frame within a `Traceback`. Provides access to the frame, filename, line number, and code context.

Class: Source

**Module:** `.source`

Represents the raw source code associated with a code object or frame. Provides methods to retrieve and manipulate source text, useful for code analysis and transformations.

Function: filter_traceback

**Module:** `.code`

Filters a given traceback object, removing frames that are considered irrelevant or internal to the library. This helps present cleaner tracebacks to end-users.

**Parameters:**

• traceback: The original traceback object.

**Returns:**

• A filtered traceback object.

Function: getfslineno

**Module:** `.code`

Retrieves the filename and line number corresponding to a given frame or code object, providing contextual location information.

**Parameters:**

• frame_or_code: A Frame instance or code object.

**Returns:**

• Tuple (filename: str, lineno: int)

Function: getrawcode

**Module:** `.source`

Retrieves the raw code object from a source abstraction, allowing lower-level inspection or recompilation.

Important Implementation Details

• The package uses lazy imports and re-exports from two internal submodules, .code and .source, to organize related functionality.

• The __all__ list explicitly defines the public API, ensuring only intended classes and functions are exposed.

• The design emphasizes separation between code object manipulation (code submodule) and source code handling (source submodule).

• The usage of future annotations (from __future__ import annotations) enables postponed evaluation of type annotations for forward references and cleaner typing.

Interaction with Other System Components

• This module acts as the public interface of the inspection/code generation package, making it a dependency for higher-level modules that perform dynamic code analysis, debugging, or runtime code generation.

• The classes and functions here likely integrate with an exception handling system, debugging tools, or a code transformation pipeline within the larger project.

• Other components import this module to gain access to consistent and well-structured abstractions over Python's internal code and traceback objects.

Visual Diagram

The following Mermaid class diagram shows the relationships of the main classes and functions exported by this module, grouped by their origin submodule.

classDiagram
    direction LR

    class Code {
        +<properties and methods>
    }
    class ExceptionInfo {
        +from_current_exception()
        +traceback
    }
    class Frame {
        +locals
        +globals
        +code
    }
    class Traceback {
        +filter()
        +entries
    }
    class TracebackEntry {
        +frame
        +filename
        +lineno
    }
    class Source {
        +raw_code
        +get_source_text()
    }

    class filter_traceback {
        +(traceback)
    }
    class getfslineno {
        +(frame_or_code)
    }
    class getrawcode {
        +(source)
    }

    %% Grouping by modules
    Code --> ExceptionInfo : uses
    ExceptionInfo --> Traceback : contains
    Traceback --> TracebackEntry : composed of
    TracebackEntry --> Frame : references
    Frame --> Code : wraps
    Source --> getrawcode : provides
    filter_traceback ..> Traceback : filters
    getfslineno ..> Frame : queries

Summary

This [__init__.py](/projects/286/67254) file is the centralized public API for the Python inspection and code generation package. It re-exports key classes and functions from internal modules, facilitating easy access to powerful abstractions for introspecting Python code objects, stack frames, tracebacks, and source code. This makes it an essential module for any component in the system that requires deep runtime code analysis, debugging, or dynamic code manipulation.