lldb/bindings/python/python.swig

/*
   lldb.swig

   This is the input file for SWIG, to create the appropriate C++ wrappers and
   functions for various scripting languages, to enable them to call the
   liblldb Script Bridge functions.
*/

/* Define our module docstring. */
%define DOCSTRING
"The lldb module contains the public APIs for Python binding.

Some of the important classes are described here:

* :py:class:`SBTarget`: Represents the target program running under the debugger.
* :py:class:`SBProcess`: Represents the process associated with the target program.
* :py:class:`SBThread`: Represents a thread of execution. :py:class:`SBProcess` contains SBThreads.
* :py:class:`SBFrame`: Represents one of the stack frames associated with a thread. :py:class:`SBThread`
  contains SBFrame(s).
* :py:class:`SBSymbolContext`: A container that stores various debugger related info.
* :py:class:`SBValue`: Represents the value of a variable, a register, or an expression.
* :py:class:`SBModule`: Represents an executable image and its associated object and symbol
  files.  :py:class:`SBTarget` contains SBModule.
* :py:class:`SBBreakpoint`: Represents a logical breakpoint and its associated settings.
  :py:class:`SBTarget` contains SBBreakpoints.
* :py:class:`SBSymbol`: Represents the symbol possibly associated with a stack frame.
* :py:class:`SBCompileUnit`: Represents a compilation unit, or compiled source file.
* :py:class:`SBFunction`: Represents a generic function, which can be inlined or not.
* :py:class:`SBBlock`: Represents a lexical block. :py:class:`SBFunction` contains SBBlocks.
* :py:class:`SBLineEntry`: Specifies an association with a contiguous range of instructions
  and a source file location. :py:class:`SBCompileUnit` contains SBLineEntry.

The different enums in the `lldb` module are described in :doc:`python_api_enums`.

"
%enddef

/*
Since version 3.0.9, swig's logic for importing the native module has changed in
a way that is incompatible with our usage of the python module as __init__.py
(See swig bug #769).  Fortunately, since version 3.0.11, swig provides a way for
us to override the module import logic to suit our needs. This does that.

Older swig versions will simply ignore this setting.
*/
%define MODULEIMPORT
"try:
    # Try an absolute import first.  If we're being loaded from lldb,
    # _lldb should be a built-in module.
    import $module
except ImportError:
    # Relative import should work if we are being loaded by Python.
    # The cpython module built by swig is pushed one level down into
    # the native submodule, because at this point the interpreter
    # is still constructing the lldb module itself.
    # Simply importing anything using `from . import` constitutes
    # a cyclic importing.
    from .native import $module"
%enddef

// The name of the module to be created.
%module(docstring=DOCSTRING, moduleimport=MODULEIMPORT) lldb

// Parameter types will be used in the autodoc string.
%feature("autodoc", "1");

#if SWIG_VERSION >= 0x040500
%feature("python:annotations", "typing");

// The default pytyping entry maps to `typing.Any`. Use the proxy names here.
// They might generate incorrect annotations (`SWIGTYPE_*`) in more complex scenarios.
%typemap(pytyping) SWIGTYPE      "$&pytypename";
%typemap(pytyping) SWIGTYPE []   "typing.Optional[$pytypename]";
%typemap(pytyping) SWIGTYPE *    "typing.Optional[$pytypename]";
%typemap(pytyping) SWIGTYPE &    "$pytypename";
%typemap(pytyping) SWIGTYPE &&   "$pytypename";
%typemap(pytyping) enum SWIGTYPE "int";

// Exclude operator==/!=. They generate `__eq__(self, rhs: T) -> bool`.
// However, `rhs` should be `object`.
%feature("python:annotations", "0") operator==;
%feature("python:annotations", "0") operator!=;

// OUTPUT/INOUT is not supported by the typing annotations right now.
%feature("python:annotations", "0") lldb::SBDebugger::GetProgressFromEvent;
%feature("python:annotations", "0") lldb::SBDebugger::RunCommandInterpreter;
%feature("python:annotations", "0") lldb::SBFile::Read;
%feature("python:annotations", "0") lldb::SBFile::Write;
#else
// Make sure `typing` is imported in all cases (Swig < 4.5.0).
%pythoncode %{
import typing
%}
#endif // SWIG_VERSION >= 0x040500

// Include lldb-python first as it sets Py_LIMITED_API.
%begin %{
#include "../source/Plugins/ScriptInterpreter/Python/lldb-python.h"
%}

%pythoncode%{
import uuid
import re
import os
%}

// Include the version of swig that was used to generate this interface.
%define EMBED_VERSION(VERSION)
%pythoncode%{
# SWIG_VERSION is written as a single hex number, but the components of it are
# meant to be interpreted in decimal. So, 0x030012 is swig 3.0.12, and not
# 3.0.18.
def _to_int(hex):
    return hex // 0x10 % 0x10 * 10 + hex % 0x10
swig_version = (_to_int(VERSION // 0x10000), _to_int(VERSION // 0x100), _to_int(VERSION))
del _to_int
%}
%enddef
EMBED_VERSION(SWIG_VERSION)

%include <std_string.i>
%include "python-typemaps.swig"
%include "macros.swig"
%include "headers.swig"

%{
#include "../source/Plugins/ScriptInterpreter/Python/PythonDataObjects.h"
#include "../source/Plugins/ScriptInterpreter/Python/SWIGPythonBridge.h"
#include "../bindings/python/python-swigsafecast.swig"
using namespace lldb_private;
using namespace lldb_private::python;
using namespace lldb;
%}

%include "interfaces.swig"
%include "python-extensions.swig"
%include "python-wrapper.swig"

%pythoncode%{
debugger_unique_id = 0
SBDebugger.Initialize()
debugger = None
target = None
process = None
thread = None
frame = None
%}