Skip to content

Commit 6069b9d

Browse files
zznopzznop
committed
Update type hints/docs for Python IL API changes
1 parent 709149e commit 6069b9d

1 file changed

Lines changed: 84 additions & 36 deletions

File tree

‎python/function.py‎

Lines changed: 84 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -979,21 +979,27 @@ def remove_auto_function_tags_of_type(self, tag_type: str):
979979
core.BNRemoveAutoFunctionTagsOfType(self.handle, tag_type.handle)
980980

981981
@property
982-
def low_level_il(self) -> 'lowlevelil.LowLevelILFunction':
982+
def low_level_il(self) -> Optional['lowlevelil.LowLevelILFunction']:
983983
"""
984-
returns LowLevelILFunction used to represent Function low level IL (read-only)
984+
returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL
985+
(read-only)
986+
985987
986-
:rtype: lowlevelil.LowLevelILFunction
988+
.. note::
989+
This function causes low level IL to be generated if it has not been already. It is recommended to generate
990+
IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
987991
"""
988992
return self.llil
989993

990994
@property
991-
def llil(self) -> 'lowlevelil.LowLevelILFunction':
995+
def llil(self) -> Optional['lowlevelil.LowLevelILFunction']:
992996
"""
993-
returns LowLevelILFunction used to represent Function low level IL, or None if an error occurs while loading
994-
the IL (read-only)
997+
returns LowLevelILFunction used to represent low level IL, or None if an error occurs while loading the IL
998+
(read-only)
995999
996-
:rtype: lowlevelil.LowLevelILFunction
1000+
.. note::
1001+
This function causes low level IL to be generated if it has not been already. It is recommended to generate
1002+
IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
9971003
"""
9981004
result = core.BNGetFunctionLowLevelIL(self.handle)
9991005
if not result:
@@ -1002,19 +1008,26 @@ def llil(self) -> 'lowlevelil.LowLevelILFunction':
10021008

10031009
@property
10041010
def llil_if_available(self) -> Optional['lowlevelil.LowLevelILFunction']:
1005-
"""returns LowLevelILFunction used to represent Function low level IL, or None if not loaded (read-only)"""
1011+
"""
1012+
returns LowLevelILFunction used to represent low level IL, or None if not loaded or it cannot be generated
1013+
(read-only)
1014+
1015+
.. note:: This function can be used to check if low level IL is available without generating it.
1016+
"""
10061017
result = core.BNGetFunctionLowLevelILIfAvailable(self.handle)
10071018
if not result:
10081019
return None
10091020
return lowlevelil.LowLevelILFunction(self.arch, result, self)
10101021

10111022
@property
1012-
def lifted_il(self) -> 'lowlevelil.LowLevelILFunction':
1023+
def lifted_il(self) -> Optional['lowlevelil.LowLevelILFunction']:
10131024
"""
1014-
returns LowLevelILFunction used to represent Function lifted IL, or None if an error occurs while loading the IL
1025+
returns LowLevelILFunction used to represent lifted IL, or None if an error occurs while loading the IL
10151026
(read-only)
10161027
1017-
:rtype: lowlevelil.LowLevelILFunction
1028+
.. note::
1029+
This function causes lifted IL to be generated if it has not been already. It is recommended to generate IL
1030+
on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
10181031
"""
10191032
result = core.BNGetFunctionLiftedIL(self.handle)
10201033
if not result:
@@ -1023,28 +1036,38 @@ def lifted_il(self) -> 'lowlevelil.LowLevelILFunction':
10231036

10241037
@property
10251038
def lifted_il_if_available(self) -> Optional['lowlevelil.LowLevelILFunction']:
1026-
"""returns LowLevelILFunction used to represent lifted IL, or None if not loaded (read-only)"""
1039+
"""
1040+
returns LowLevelILFunction used to represent lifted IL, or None if not loaded or it cannot be generated
1041+
(read-only)
1042+
1043+
.. note:: This function can be used to check if lifted IL is available without generating it.
1044+
"""
10271045
result = core.BNGetFunctionLiftedILIfAvailable(self.handle)
10281046
if not result:
10291047
return None
10301048
return lowlevelil.LowLevelILFunction(self.arch, result, self)
10311049

10321050
@property
1033-
def medium_level_il(self) -> 'mediumlevelil.MediumLevelILFunction':
1051+
def medium_level_il(self) -> Optional['mediumlevelil.MediumLevelILFunction']:
10341052
"""
1035-
returns MediumLevelILFunction used to represent Function medium level IL (read-only)
1053+
returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL
1054+
(read-only)
10361055
1037-
:rtype: mediumlevelil.MediumLevelILFunction
1056+
.. note::
1057+
This function causes medium level IL to be generated if it has not been already. It is recommended to
1058+
generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
10381059
"""
10391060
return self.mlil
10401061

10411062
@property
1042-
def mlil(self) -> 'mediumlevelil.MediumLevelILFunction':
1063+
def mlil(self) -> Optional['mediumlevelil.MediumLevelILFunction']:
10431064
"""
1044-
returns MediumLevelILFunction used to represent Function medium level IL, or None if an error occurs while
1045-
loading the IL (read-only)
1065+
returns MediumLevelILFunction used to represent medium level IL, or None if an error occurs while loading the IL
1066+
(read-only)
10461067
1047-
:rtype: mediumlevelil.MediumLevelILFunction
1068+
.. note::
1069+
This function causes medium level IL to be generated if it has not been already. It is recommended to
1070+
generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
10481071
"""
10491072
result = core.BNGetFunctionMediumLevelIL(self.handle)
10501073
if not result:
@@ -1053,58 +1076,78 @@ def mlil(self) -> 'mediumlevelil.MediumLevelILFunction':
10531076

10541077
@property
10551078
def mlil_if_available(self) -> Optional['mediumlevelil.MediumLevelILFunction']:
1056-
"""Function medium level IL, or None if not loaded (read-only)"""
1079+
"""
1080+
returns MediumLevelILFunction used to represent medium level IL, or None if not loaded or it cannot be generated
1081+
(read-only)
1082+
1083+
.. note:: This function can be used to check if medium level IL is available without generating it.
1084+
"""
10571085
result = core.BNGetFunctionMediumLevelILIfAvailable(self.handle)
10581086
if not result:
10591087
return None
10601088
return mediumlevelil.MediumLevelILFunction(self.arch, result, self)
10611089

10621090
@property
1063-
def mmlil(self) -> 'mediumlevelil.MediumLevelILFunction':
1091+
def mmlil(self) -> Optional['mediumlevelil.MediumLevelILFunction']:
10641092
"""
1065-
returns MediumLevelILFunction used to represent Function mapped medium level IL, or None if an error occurs
1066-
while loading the IL (read-only)
1093+
returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading
1094+
the IL (read-only)
10671095
1068-
:rtype: mediumlevelil.MediumLevelILFunction
1096+
.. note::
1097+
This function causes mapped medium level IL to be generated if it has not been already. It is recommended to
1098+
generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
10691099
"""
10701100
result = core.BNGetFunctionMappedMediumLevelIL(self.handle)
10711101
if not result:
10721102
return None
10731103
return mediumlevelil.MediumLevelILFunction(self.arch, result, self)
10741104

10751105
@property
1076-
def mapped_medium_level_il(self) -> 'mediumlevelil.MediumLevelILFunction':
1106+
def mapped_medium_level_il(self) -> Optional['mediumlevelil.MediumLevelILFunction']:
10771107
"""
1078-
returns MediumLevelILFunction used to represent Function mapped medium level IL (read-only)
1108+
returns MediumLevelILFunction used to represent mapped medium level IL, or None if an error occurs while loading
1109+
the IL (read-only)
10791110
1080-
:rtype: mediumlevelil.MediumLevelILFunction
1111+
.. note::
1112+
This function causes mapped medium level IL to be generated if it has not been already. It is recommended to
1113+
generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
10811114
"""
10821115
return self.mmlil
10831116

10841117
@property
10851118
def mmlil_if_available(self) -> Optional['mediumlevelil.MediumLevelILFunction']:
1086-
"""Function mapped medium level IL, or None if not loaded (read-only)"""
1119+
"""
1120+
returns MediumLevelILFunction used to represent mapped medium level IL, or None if not loaded or it cannot be
1121+
generated (read-only)
1122+
1123+
.. note:: This function can be used to check if mapped medium level IL is available without generating it.
1124+
"""
10871125
result = core.BNGetFunctionMappedMediumLevelILIfAvailable(self.handle)
10881126
if not result:
10891127
return None
10901128
return mediumlevelil.MediumLevelILFunction(self.arch, result, self)
10911129

10921130
@property
1093-
def high_level_il(self) -> 'highlevelil.HighLevelILFunction':
1131+
def high_level_il(self) -> Optional['highlevelil.HighLevelILFunction']:
10941132
"""
1095-
returns HighLevelILFunction used to represent Function high level IL (read-only)
1133+
returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL
1134+
(read-only)
10961135
1097-
:rtype: highlevelil.HighLevelILFunction
1136+
.. note::
1137+
This function causes high level IL to be generated if it has not been already. It is recommended to
1138+
generate IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
10981139
"""
10991140
return self.hlil
11001141

11011142
@property
1102-
def hlil(self) -> 'highlevelil.HighLevelILFunction':
1143+
def hlil(self) -> Optional['highlevelil.HighLevelILFunction']:
11031144
"""
1104-
returns HighLevelILFunction used to represent Function high level IL, or None if an error occurs while loading
1105-
the IL (read-only)
1145+
returns HighLevelILFunction used to represent high level IL, or None if an error occurs while loading the IL
1146+
(read-only)
11061147
1107-
:rtype: highlevelil.HighLevelILFunction
1148+
.. note::
1149+
This function causes high level IL to be generated if it has not been already. It is recommended to generate
1150+
IL on-demand to avoid excessive memory usage instead of generating IL for all functions at once.
11081151
"""
11091152
result = core.BNGetFunctionHighLevelIL(self.handle)
11101153
if not result:
@@ -1113,7 +1156,12 @@ def hlil(self) -> 'highlevelil.HighLevelILFunction':
11131156

11141157
@property
11151158
def hlil_if_available(self) -> Optional['highlevelil.HighLevelILFunction']:
1116-
"""Function high level IL, or None if not loaded (read-only)"""
1159+
"""
1160+
returns HighLevelILFunction used to represent high level IL, or None if not loaded or it cannot be generated
1161+
(read-only)
1162+
1163+
.. note:: This function can be used to check if high level IL is available without generating it.
1164+
"""
11171165
result = core.BNGetFunctionHighLevelILIfAvailable(self.handle)
11181166
if not result:
11191167
return None

0 commit comments

Comments
 (0)