summaryrefslogtreecommitdiff
path: root/python
diff options
context:
space:
mode:
Diffstat (limited to 'python')
-rw-r--r--python/__init__.py6
-rw-r--r--python/basicblock.py1
-rw-r--r--python/binaryview.py22
-rw-r--r--python/debuginfo.py47
-rw-r--r--python/decorators.py16
-rw-r--r--python/function.py16
-rw-r--r--python/highlevelil.py4
-rw-r--r--python/interaction.py9
-rw-r--r--python/types.py8
-rw-r--r--python/websocketprovider.py2
10 files changed, 81 insertions, 50 deletions
diff --git a/python/__init__.py b/python/__init__.py
index b81b6089..a230dec4 100644
--- a/python/__init__.py
+++ b/python/__init__.py
@@ -333,8 +333,7 @@ def connect_pycharm_debugger(port=5678):
"""
Connect to PyCharm (Professional Edition) for debugging.
- .. note:: See https://docs.binary.ninja/dev/plugins.html#remote-debugging-with-intellij-pycharm
- for step-by-step instructions on how to set up Python debugging.
+ .. note:: See https://docs.binary.ninja/dev/plugins.html#remote-debugging-with-intellij-pycharm for step-by-step instructions on how to set up Python debugging.
:param port: Port number for connecting to the debugger.
"""
@@ -350,8 +349,7 @@ def connect_vscode_debugger(port=5678):
Connect to Visual Studio Code for debugging. This function blocks until the debugger
is connected! Not recommended for use in startup.py
- .. note:: See https://docs.binary.ninja/dev/plugins.html#remote-debugging-with-vscode
- for step-by-step instructions on how to set up Python debugging.
+ .. note:: See https://docs.binary.ninja/dev/plugins.html#remote-debugging-with-vscode for step-by-step instructions on how to set up Python debugging.
:param port: Port number for connecting to the debugger.
"""
diff --git a/python/basicblock.py b/python/basicblock.py
index 208ab9e7..65069f6c 100644
--- a/python/basicblock.py
+++ b/python/basicblock.py
@@ -383,6 +383,7 @@ class BasicBlock:
def disassembly_text(self) -> List['_function.DisassemblyTextLine']:
"""
``disassembly_text`` property which returns a list of function.DisassemblyTextLine objects for the current basic block.
+
:Example:
>>> current_basic_block.disassembly_text
diff --git a/python/binaryview.py b/python/binaryview.py
index 20201835..882b9e7c 100644
--- a/python/binaryview.py
+++ b/python/binaryview.py
@@ -37,6 +37,7 @@ from collections import defaultdict, OrderedDict, deque
# Binary Ninja components
import binaryninja
from . import _binaryninjacore as core
+from . import decorators
from .enums import (
AnalysisState, SymbolType, Endianness, ModificationStatus, StringType, SegmentFlag, SectionSemantics, FindFlag,
TypeClass, BinaryViewEventType, FunctionGraphType, TagReferenceType, TagTypeType, RegisterValueType, LogLevel
@@ -1831,6 +1832,7 @@ class BinaryView:
return f"<BinaryView: '{filename}', {size}>"
return f"<BinaryView: {size}>"
+ @decorators.deprecated
def __len__(self):
# deprecated - Python does allow the returning of integers >= 0x8000000000000000
# please use .length instead
@@ -2306,10 +2308,10 @@ class BinaryView:
return _function.Function(self, func)
@property
+ @decorators.deprecated
def symbols(self) -> SymbolMapping:
"""
- Deprecated: Dict of symbols (read-only)
- This API is deprecated and will be removed in future versions.
+ Dict of symbols (read-only)
.. warning:: This method **should not** be used in any applications where speed is important as it \
copies all symbols from the binaryview each time it is invoked.
@@ -2786,6 +2788,7 @@ class BinaryView:
def get_disassembly(self, addr: int, arch: Optional['architecture.Architecture'] = None) -> Optional[str]:
"""
``get_disassembly`` simple helper function for printing disassembly of a given address
+
:param int addr: virtual address of instruction
:param Architecture arch: optional Architecture, ``self.arch`` is used if this parameter is None
:return: a str representation of the instruction at virtual address ``addr`` or None
@@ -3070,6 +3073,7 @@ class BinaryView:
:param SaveSettings settings: optional argument for special save options.
:return: true on success, false on failure
:rtype: bool
+
:Example:
>>> settings = SaveSettings()
>>> bv.create_database(f"{bv.file.filename}.bndb", None, settings)
@@ -8194,11 +8198,9 @@ class BinaryWriter:
core.BNSeekBinaryWriterRelative(self._handle, offset)
+@decorators.deprecated
@dataclass
class StructuredDataValue(object):
- """
- DEPRECATED use: TypedDataAccessor instead.
- """
type: '_types.Type'
address: int
value: bytes
@@ -8239,22 +8241,24 @@ class StructuredDataValue(object):
return int(self)
+@decorators.deprecated
class StructuredDataView(object):
"""
- DEPRECATED use: TypedDataAccessor instead.
-
``class StructuredDataView`` is a convenience class for reading structured binary data.
- StructuredDataView can be instantiated as follows:
+
+ StructuredDataView can be instantiated as follows::
>>> from binaryninja import *
>>> bv = BinaryViewType.get_view_of_file("/bin/ls")
>>> structure = "Elf64_Header"
>>> address = bv.start
>>> elf = StructuredDataView(bv, structure, address)
>>>
- Once instantiated, members can be accessed:
+
+ Once instantiated, members can be accessed::
>>> print("{:x}".format(elf.machine))
003e
>>>
+
"""
def __init__(self, bv: 'BinaryView', structure_name: '_types.QualifiedNameType', address: int):
self._bv = bv
diff --git a/python/debuginfo.py b/python/debuginfo.py
index 37d0c3d6..46f9e959 100644
--- a/python/debuginfo.py
+++ b/python/debuginfo.py
@@ -145,42 +145,41 @@ class _DebugInfoParserMetaClass(type):
class DebugInfoParser(object, metaclass=_DebugInfoParserMetaClass):
"""
- ``DebugInfoParser``s represent the registered parsers and providers of debug information to Binary Ninja.
+ :py:class:`DebugInfoParser` represents the registered parsers and providers of debug information to Binary Ninja.
The debug information is used by Binary Ninja as ground-truth information about the attributes of functions,
types, and variables that Binary Ninja's analysis pipeline would otherwise work to deduce. By providing
debug info, Binary Ninja's output can be generated quicker, more accurately, and more completely.
A DebugInfoParser consists of:
- 1. A name
- 2. An ``is_valid`` function which takes a BV and returns a bool
- 3. A ``parse`` function which takes a ``DebugInfo`` object and uses the member functions ``add_type``, ``add_function``, and ``add_data_variable`` to populate all the info it can.
- And finally calling ``bn.debuginfo.DebugInfoParser.register`` to register it with the core.
- Here's a minimal, complete example boilerplate-plugin:
- ```
- import binaryninja as bn
+ 1. A name
+ 2. An ``is_valid`` function which takes a BV and returns a bool
+ 3. A ``parse`` function which takes a :py:class:`DebugInfo` object and uses the member functions :py:meth:`DebugInfo.add_type`, :py:meth:`DebugInfo.add_function`, and :py:meth:`DebugInfo.add_data_variable` to populate all the info it can.
- def is_valid(bv: bn.binaryview.BinaryView) -> bool:
- return bv.view_type == "Raw"
+ And finally calling :py:meth:`DebugInfoParser.register` to register it with the core.
- def parse_info(debug_info: bn.debuginfo.DebugInfo, bv: bn.binaryview.BinaryView) -> None:
- debug_info.add_type("name", bn.types.Type.int(4, True))
- debug_info.add_data_variable(0x1234, bn.types.Type.int(4, True), "name")
+ A working example::
- function_info = bn.debuginfo.DebugFunctionInfo(0xdead1337, "short_name", "full_name", "raw_name", bn.types.Type.int(4, False), [])
- debug_info.add_function(function_info)
+ import binaryninja as bn
- bn.debuginfo.DebugInfoParser.register("debug info parser", is_valid, parse_info)
- ```
+ def is_valid(bv: bn.binaryview.BinaryView) -> bool:
+ return bv.view_type == "Raw"
- ``DebugInfo`` can then be automatically applied to valid binary views (via the "Parse and Apply Debug Info" setting), or manually fetched/applied as bellow:
- ```
- valid_parsers = bn.debuginfo.DebugInfoParser.get_parsers_for_view(bv)
- parser = valid_parsers[0]
- debug_info = parser.parse_debug_info(bv)
- bv.apply_debug_info(debug_info)
- ```
+ def parse_info(debug_info: bn.debuginfo.DebugInfo, bv: bn.binaryview.BinaryView) -> None:
+ debug_info.add_type("name", bn.types.Type.int(4, True))
+ debug_info.add_data_variable(0x1234, bn.types.Type.int(4, True), "name")
+ function_info = bn.debuginfo.DebugFunctionInfo(0xdead1337, "short_name", "full_name", "raw_name", bn.types.Type.int(4, False), [])
+ debug_info.add_function(function_info)
+
+ bn.debuginfo.DebugInfoParser.register("debug info parser", is_valid, parse_info)
+
+ :py:class:`DebugInfo` can then be automatically applied to valid binary views (via the "Parse and Apply Debug Info" setting), or manually fetched/applied as bellow::
+
+ valid_parsers = bn.debuginfo.DebugInfoParser.get_parsers_for_view(bv)
+ parser = valid_parsers[0]
+ debug_info = parser.parse_debug_info(bv)
+ bv.apply_debug_info(debug_info)
Multiple debug-info parsers can manually contribute debug info for a binary view by simply calling ``parse_debug_info`` with the
``DebugInfo`` object just returned. This is automatic when opening a binary view with multiple valid debug info parsers. If you
diff --git a/python/decorators.py b/python/decorators.py
index e02829f8..7c7025e3 100644
--- a/python/decorators.py
+++ b/python/decorators.py
@@ -1,6 +1,6 @@
def passive(cls):
passive_note = '''
-
+
.. note:: This object is a "passive" object. Any changes you make to it will not be reflected in the core and vice-versa. If you wish to update a core version of this object you should use the appropriate API.
'''
@@ -10,3 +10,17 @@ def passive(cls):
cls.__doc__ = passive_note
return cls
+
+
+def deprecated(cls):
+ deprecated_note = '''
+ .. warning:: This object is deprecated. Please migrate code away from using this class or method.
+
+'''
+
+ if hasattr(cls, "__doc__") and cls.__doc__:
+ cls.__doc__ = deprecated_note + cls.__doc__
+ else:
+ cls.__doc__ = deprecated_note
+
+ return cls \ No newline at end of file
diff --git a/python/function.py b/python/function.py
index 40b9901d..fc9ec860 100644
--- a/python/function.py
+++ b/python/function.py
@@ -59,6 +59,7 @@ from .variable import (
Variable, LookupTableEntry, RegisterValue, ValueRange, PossibleValueSet, StackVariableReference, ConstantReference,
IndirectBranchInfo, ParameterVariables, AddressRange
)
+from . import decorators
from .enums import RegisterValueType
ExpressionIndex = int
@@ -1291,14 +1292,20 @@ class Function:
yield i[0], start
start += i[1]
+ @decorators.deprecated
@property
def llil_instructions(self) -> Generator['lowlevelil.LowLevelILInstruction', None, None]:
- """Deprecated method provided for compatibility. Use llil.instructions instead. Was: A generator of llil instructions of the current function"""
+ """
+ .. note:: Use :py:meth:`LowLevelIlFunction.instructions` instead.
+ """
return self.llil.instructions
+ @decorators.deprecated
@property
def mlil_instructions(self) -> Generator['mediumlevelil.MediumLevelILInstruction', None, None]:
- """Deprecated method provided for compatibility. Use mlil.instructions instead. Was: A generator of mlil instructions of the current function"""
+ """
+ .. note:: Use :py:meth:`MediumLevelIlFunction.instructions` instead.
+ """
return self.mlil.instructions
@property
@@ -1346,8 +1353,11 @@ class Function:
def get_comment_at(self, addr: int) -> str:
return core.BNGetCommentForAddress(self.handle, addr)
+ @decorators.deprecated
def set_comment(self, addr: int, comment: str) -> None:
- """Deprecated method provided for compatibility. Use set_comment_at instead."""
+ """
+ .. note:: Use :py:meth:`set_comment_at` instead.
+ """
core.BNSetCommentForAddress(self.handle, addr, comment)
def set_comment_at(self, addr: int, comment: str) -> None:
diff --git a/python/highlevelil.py b/python/highlevelil.py
index 4ea2aa8f..da055cd4 100644
--- a/python/highlevelil.py
+++ b/python/highlevelil.py
@@ -27,6 +27,7 @@ from enum import Enum
# Binary Ninja components
from . import _binaryninjacore as core
from .enums import HighLevelILOperation, DataFlowQueryOption, FunctionGraphType
+from . import decorators
from . import function
from . import binaryview
from . import architecture
@@ -2046,11 +2047,12 @@ ILInstruction = {
}
+@decorators.deprecated
class HighLevelILExpr:
"""
``class HighLevelILExpr`` hold the index of IL Expressions.
- .. note:: Deprecated. Use ExpressionIndex instead
+ .. note:: Use ExpressionIndex instead
"""
def __init__(self, index: ExpressionIndex):
self._index = index
diff --git a/python/interaction.py b/python/interaction.py
index 978de6b2..ba9da5a3 100644
--- a/python/interaction.py
+++ b/python/interaction.py
@@ -1056,12 +1056,9 @@ def show_markdown_report(title, contents, plaintext=""):
def show_html_report(title, contents, plaintext=""):
"""
``show_html_report`` displays the HTML contents in UI applications and plaintext in command-line \
- applications. This API doesn't support hyperlinking into the BinaryView, use the :py:math:`BinaryView.show_html_report` \
+ applications. This API doesn't support hyperlinking into the BinaryView, use the :py:meth:`BinaryView.show_html_report` \
API if hyperlinking is needed.
- .. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
- a simple text prompt is used.
-
:param str contents: HTML contents to display
:param str plaintext: Plain text version to display (used on the command-line)
:rtype: None
@@ -1201,12 +1198,12 @@ def get_open_filename_input(prompt: str, ext: str = "") -> Optional[str]:
"""
``get_open_filename_input`` prompts the user for a file name to open
- .. note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
+ .. note:: This API functions differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \
a simple text prompt is used. The UI uses the native window pop-up for file selection.
Multiple file selection groups can be included if separated by two semicolons. Multiple file wildcards may be specified by using a space within the parenthesis.
- Also, a simple selector of "*.extension" by itself may also be used instead of specifying the description.
+ Also, a simple selector of "\*.extension" by itself may also be used instead of specifying the description.
:param str prompt: Prompt to display.
:param str ext: Optional, file extension
diff --git a/python/types.py b/python/types.py
index 3d1dc73e..65f58192 100644
--- a/python/types.py
+++ b/python/types.py
@@ -1617,6 +1617,7 @@ class Type:
) -> str:
"""
Get string representation for this type
+
:param TokenEscapingType escaping: How to escape non-parsable strings in types
:return: String for type
:rtype: str
@@ -1634,6 +1635,7 @@ class Type:
) -> str:
"""
Get the string to be printed before this type's name in a representation of it
+
:param TokenEscapingType escaping: How to escape non-parsable strings in types
:return: String for type representation before the name
:rtype: str
@@ -1652,7 +1654,8 @@ class Type:
self, escaping: TokenEscapingType = TokenEscapingType.NoTokenEscapingType
) -> str:
"""
- Get the string to be printed after this type's name in a representation of it
+ Get the string to be printed after this type's name in a representation
+
:param TokenEscapingType escaping: How to escape non-parsable strings in types
:return: String for type representation after the name
:rtype: str
@@ -1678,6 +1681,7 @@ class Type:
) -> List['_function.InstructionTextToken']:
"""
Get a list of tokens for the definition of a type
+
:param int base_confidence: Confidence of this type
:param TokenEscapingType escaping: How to escape non-parsable strings in types
:return: List of tokens
@@ -1705,6 +1709,7 @@ class Type:
) -> List['_function.InstructionTextToken']:
"""
Get a list of tokens for the definition of a type that are placed before the type name
+
:param int base_confidence: Confidence of this type
:param TokenEscapingType escaping: How to escape non-parsable strings in types
:return: List of tokens
@@ -1735,6 +1740,7 @@ class Type:
) -> List['_function.InstructionTextToken']:
"""
Get a list of tokens for the definition of a type that are placed after the type name
+
:param int base_confidence: Confidence of this type
:param TokenEscapingType escaping: How to escape non-parsable strings in types
:return: List of tokens
diff --git a/python/websocketprovider.py b/python/websocketprovider.py
index 0a143562..c87cc384 100644
--- a/python/websocketprovider.py
+++ b/python/websocketprovider.py
@@ -141,7 +141,7 @@ class WebsocketClient(object):
def connect(self, url, headers=None, on_connected=nop, on_disconnected=nop, on_error=nop, on_data=nop):
"""
Connect to a given url, asynchronously. The connection will be run in a separate thread managed by the websocket provider.
- Client callbacks are set according to whichever on_ callback parameters you pass.
+ Client callbacks are set according to whichever on\_ callback parameters you pass.
Callbacks will be called **on the thread of the connection**, so be sure to execute_on_main_thread any long-running
or gui operations in the callbacks.