retdec package¶
Subpackages¶
Submodules¶
retdec.analysis module¶
A representation of fileinfo analyses.
-
class
retdec.analysis.
Analysis
(id, conn)[source]¶ Bases:
retdec.resource.Resource
A representation of a fileinfo analysis.
-
wait_until_finished
(on_failure=<class 'retdec.exceptions.AnalysisFailedError'>)[source]¶ Waits until the analysis is finished.
Parameters: on_failure (callable) – What should be done when the analysis fails? If on_failure is
None
, nothing is done when the analysis fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.
-
retdec.conn module¶
API connection.
-
class
retdec.conn.
APIConnection
(base_url, api_key)[source]¶ Bases:
object
Connection to the API.
Parameters: - base_url (str) – Base URL from which all subsequent URLs are constructed.
- api_key (str) – API key to be used for authentication.
The methods of this class may raise the following exceptions:
ConnectionError
: When there is a connection error.AuthenticationError
: When the authentication fails.UnknownAPIError
: When there is an API error other than failed authentication.
-
send_get_request
(path='', params=None)[source]¶ Sends a GET request to the given path with the given parameters.
Parameters: - path (str) – Path to which the request should be sent.
- params (dict) – Request parameters.
Returns: Response from the API (parsed JSON).
If path is the empty string, it sends the request to the base URL from which the connection was initialized.
-
send_post_request
(path='', params=None, files=None)[source]¶ Sends a POST request to the given path with the given parameters.
Parameters: - path (str) – Path to which the request should be sent.
- params (dict) – Request parameters.
- files (dict) – Request files.
Returns: Response from the API (parsed JSON).
If path is the empty string, it sends the request to the base URL from which the connection was initialized.
-
get_file
(path='', params=None)[source]¶ GETs a file from the given path with the given parameters.
Parameters: - path (str) – Path to which the request should be sent.
- params (dict) – Request parameters.
Returns: File from path (
File
).If path is the empty string, it sends the request to the base URL from which the connection was initialized.
retdec.decompilation module¶
A representation of decompilations.
-
class
retdec.decompilation.
DecompilationPhase
(name, part, description, completion, warnings)[source]¶ Bases:
object
Phase of a decompilation.
Parameters: - name (str) – Name of the phase.
- part (str) – Part into which the phase belongs.
- description (str) – Description of the phase.
- completion (int) – What percentage of the decompilation has been completed?
- warnings (list) – A list of warnings that were produced by the decompiler in the phase. Each warning is a string.
part may be
None
if the phase does not belong to any part.-
name
¶ Name of the phase (str).
-
part
¶ Part to which the phase belongs (str).
May be
None
if the phase does not belong to any part.
-
description
¶ Description of the phase (str).
-
completion
¶ Completion (in percentages,
0-100
).
-
warnings
¶ A list of warnings that were produced by the decompiler in the phase.
Each warning is a string.
-
class
retdec.decompilation.
Decompilation
(id, conn)[source]¶ Bases:
retdec.resource.Resource
A representation of a decompilation.
-
get_completion
()[source]¶ How much of the decompilation has been completed (in percentage)?
It is an
int
between 0 and 100.
-
get_phases
()[source]¶ Obtains and returns the list of phases (
DecompilationPhase
).
-
wait_until_finished
(callback=None, on_failure=<class 'retdec.exceptions.DecompilationFailedError'>)[source]¶ Waits until the decompilation is finished.
Parameters: - callback (callable) – Function to be called when the status of the decompilation is changed or when it finishes.
- on_failure (callable) – What should be done when the decompilation fails?
If callback is not
None
, it is called with the decompilation as its argument when the status of the decompilation is changed or when it finishes.If on_failure is
None
, nothing is done when the decompilation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.
-
save_hll_code
(directory=None)[source]¶ Saves the decompiled code in the high-level language to the given directory.
Parameters: directory (str) – Path to a directory in which the decompiled code will be stored. Returns: Path to the saved file (str). If directory is
None
, the current working directory is used.
-
get_dsm_code
()[source]¶ Obtains and returns the disassembled input file in assembly-like syntax (str).
-
save_dsm_code
(directory=None)[source]¶ Saves the disassembled input file in assembly-like syntax to the given directory.
Parameters: directory (str) – Path to a directory in which the file will be stored. Returns: Path to the saved file (str). If directory is
None
, the current working directory is used.
-
cg_generation_has_finished
()[source]¶ Checks if the call-graph generation has finished.
Raises: OutputNotRequestedError – When the call graph was not requested to be generated.
-
cg_generation_has_succeeded
()[source]¶ Checks if the call-graph generation has succeeded.
Raises: OutputNotRequestedError – When the call graph was not requested to be generated.
-
cg_generation_has_failed
()[source]¶ Checks if the call graph has failed to generate.
Raises: OutputNotRequestedError – When the call graph was not requested to be generated.
-
get_cg_generation_error
()[source]¶ Returns the reason why the call graph failed to generate.
Raises: OutputNotRequestedError – When the call graph was not requested to be generated. If the call-graph generation has not failed, it returns
None
.
-
wait_until_cg_is_generated
(on_failure=<class 'retdec.exceptions.CGGenerationFailedError'>)[source]¶ Waits until the call graph is generated.
Parameters: on_failure (callable) – What should be done when the generation fails? Raises: OutputNotRequestedError – When the call graph was not requested to be generated. If on_failure is
None
, nothing is done when the generation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.
-
save_cg
(directory=None)[source]¶ Saves the call graph to the given directory.
Parameters: directory (str) – Path to a directory in which the file will be stored. Returns: Path to the saved file (str). If directory is
None
, the current working directory is used.
-
funcs_with_cfg
¶ A list of names of functions having a control-flow graph.
The returned list does not depend on the control-flow-graph-generation status. It always returns the same function names, disregarding whether their control-flow graph has or has not been generated.
The returned list is ordered by function names.
Raises: OutputNotRequestedError – When control-flow graphs were not requested to be generated.
-
cfg_generation_has_finished
(func)[source]¶ Checks if the generation of a control-flow graph for the given function has finished.
Parameters: func (str) – Name of the function.
Raises: - OutputNotRequestedError – When control-flow graphs were not requested to be generated.
- NoSuchCFGError – When there is no control-flow graph for the given function.
-
cfg_generation_has_succeeded
(func)[source]¶ Checks if the generation of a control-flow graph for the given function has succeeded.
Parameters: func (str) – Name of the function.
Raises: - OutputNotRequestedError – When control-flow graphs were not requested to be generated.
- NoSuchCFGError – When there is no control-flow graph for the given function.
-
cfg_generation_has_failed
(func)[source]¶ Checks if the generation of a control-flow graph for the given function has failed.
Parameters: func (str) – Name of the function.
Raises: - OutputNotRequestedError – When control-flow graphs were not requested to be generated.
- NoSuchCFGError – When there is no control-flow graph for the given function.
-
get_cfg_generation_error
(func)[source]¶ Returns the reason why the control-flow graph for the given function failed to generate.
Parameters: func (str) – Name of the function.
Raises: - OutputNotRequestedError – When control-flow graphs were not requested to be generated.
- NoSuchCFGError – When there is no control-flow graph for the given function.
If the control-flow-graph generation has not failed, it returns
None
.
-
wait_until_cfg_is_generated
(func, on_failure=<class 'retdec.exceptions.CFGGenerationFailedError'>)[source]¶ Waits until the control-flow graph for the given function is generated.
Parameters: - func (str) – Name of the function.
- on_failure (callable) – What should be done when the generation fails?
Raises: - OutputNotRequestedError – When control-flow graphs were not requested to be generated.
- NoSuchCFGError – When there is no control-flow graph for the given function.
If on_failure is
None
, nothing is done when the generation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.
-
save_cfg
(func, directory=None)[source]¶ Saves the control-flow graph for the given function to the given directory.
Parameters: - func (str) – Name of the function.
- directory (str) – Path to a directory in which the file will be stored.
Returns: Path to the saved file (str).
If directory is
None
, the current working directory is used.
-
archive_generation_has_finished
()[source]¶ Checks if the archive generation has finished.
Raises: OutputNotRequestedError – When the archive was not requested to be generated.
-
archive_generation_has_succeeded
()[source]¶ Checks if the archive generation has succeeded.
Raises: OutputNotRequestedError – When the archive was not requested to be generated.
-
archive_generation_has_failed
()[source]¶ Checks if the archive has failed to generate.
Raises: OutputNotRequestedError – When the archive was not requested to be generated.
-
get_archive_generation_error
()[source]¶ Returns the reason why the archive failed to generate.
Raises: OutputNotRequestedError – When the archive was not requested to be generated. If the archive has not failed, it returns
None
.
-
wait_until_archive_is_generated
(on_failure=<class 'retdec.exceptions.ArchiveGenerationFailedError'>)[source]¶ Waits until the archive containing all outputs from the decompilation is generated.
Parameters: on_failure (callable) – What should be done when the generation fails? Raises: OutputNotRequestedError – When the archive was not requested to be generated. If on_failure is
None
, nothing is done when the generation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.
-
save_archive
(directory=None)[source]¶ Saves the archive containing all outputs from the decompilation to the given directory.
Parameters: directory (str) – Path to a directory in which the file will be stored. Returns: Path to the saved file (str). If directory is
None
, the current working directory is used.
-
save_binary
(directory=None)[source]¶ Saves the compiled version of the input C file (provided that the input was a C file) to the given directory.
Parameters: directory (str) – Path to a directory in which the file will be stored. Returns: Path to the saved file (str). If directory is
None
, the current working directory is used.
-
retdec.decompiler module¶
Access to the decompiler (decompilation of files).
-
class
retdec.decompiler.
Decompiler
(*, api_key=None, api_url=None)[source]¶ Bases:
retdec.service.Service
Access to the decompilation service.
-
start_decompilation
(**kwargs)[source]¶ Starts a decompilation with the given parameters.
Parameters: - input_file (str or file-like object) – File to be analyzed (required).
- pdb_file (str or file-like object) – A PDB file associated with input_file containing debugging information.
- mode (str) – Decompilation mode.
- target_language (str) – Target high-level language.
- graph_format (str) – Format of the generated call and control-flow graphs.
- decomp_var_names (str) – Naming style for variables.
- decomp_optimizations (str) – Level of optimizations performed by the decompiler.
- decomp_unreach_funcs (bool) – Should all functions be decompiled, even if they are not reachable from the main function?
- decomp_emit_addresses (bool) – Should addresses in comments be emitted in the generated code?
- architecture (str) – Architecture. The precise meaning depends on the used mode.
- file_format (str) – File format. File format to be used when compiling input C source files.
- comp_compiler (str) – Compiler to be used when compiling input C source files.
- comp_optimizations (str) – Compiler optimizations to be used when compiling input C source files.
- comp_debug (bool) – Should the input C source file be compiled with debugging information?
- comp_strip (bool) – Should the compiled input C source file be stripped?
- sel_decomp_funcs (str/iterable) – Decompile only the selected functions. It can
be either an iterable of function names (e.g.
['func1', 'func2']
) or a string with comma-separated function names (e.g.'func1, func2'
). - sel_decomp_ranges (str/iterable) – Decompile only the selected address ranges.
It can be either an iterable of ranges (e.g.
[(0x100, 0x200), (0x400, 0x500)]
) or a string with comma-separated ranges (e.g.'0x100-0x200,0x400-0x500'
). - sel_decomp_decoding (str) – What instructions should be decoded when either sel_decomp_funcs or sel_decomp_ranges is given?
- endian (str) – Endianness of the machine code (
'little'
or'big'
). Only for theraw
mode. - raw_entry_point (str) – Virtual memory address where execution
flow should start in the raw machine code. Only for the
raw
mode. - raw_section_vma (str) – Address where the section created from the raw
machine code will be placed in virtual memory. Only for the
raw
mode. - ar_index (int/str) – Index of the object file in the input archive to be decompiled when decompiling an archive.
- ar_name (str) – Name of the object file in the input archive to be decompiled when decompiling an archive.
- generate_cg (bool) – Should a call graph be generated?
- generate_cfgs (bool) – Should control-flow graphs for all functions be generated?
- generate_archive (bool) – Should an archive containing all outputs from the decompilation be generated?
Returns: Started decompilation (
Decompilation
).If mode is not given, it is automatically determined based on the name of
input_file
. If the input file ends with.c
or.C
, the mode is set toc
. Otherwise, the mode is set tobin
.See the official documentation for more information about the parameters.
-
retdec.exceptions module¶
Custom exceptions raised by the library.
-
exception
retdec.exceptions.
RetdecError
[source]¶ Bases:
Exception
Base class of all custom exceptions raised by the library.
-
exception
retdec.exceptions.
MissingAPIKeyError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when an API key is missing.
-
exception
retdec.exceptions.
MissingParameterError
(name)[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when a required parameter is not set.
Parameters: name (str) – Name of the missing parameter.
-
exception
retdec.exceptions.
InvalidValueError
(name, value)[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when a parameter has an invalid value.
Parameters: - name (str) – Name of the parameter whose value is invalid.
- value – The invalid value.
-
exception
retdec.exceptions.
AuthenticationError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when authentication with the provided API key fails.
-
exception
retdec.exceptions.
ConnectionError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when there is a connection error.
-
exception
retdec.exceptions.
AnalysisFailedError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when a fileinfo analysis has failed.
-
exception
retdec.exceptions.
DecompilationFailedError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when a decompilation has failed.
-
exception
retdec.exceptions.
OutputNotRequestedError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when an output is queried which was not requested to be generated.
-
exception
retdec.exceptions.
CGGenerationFailedError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when the generation of a call graph fails.
-
exception
retdec.exceptions.
CFGGenerationFailedError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when the generation of a control-flow graph fails.
-
exception
retdec.exceptions.
NoSuchCFGError
(func)[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when a control-flow graph for a non-existing function is requested.
Parameters: func (str) – Name of the function whose control-flow graph was requested.
-
exception
retdec.exceptions.
ArchiveGenerationFailedError
[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when the generation of an archive fails.
-
exception
retdec.exceptions.
UnknownAPIError
(code, message, description)[source]¶ Bases:
retdec.exceptions.RetdecError
Exception raised when there is an unknown API error.
Parameters: - code (int) – Error code.
- message (str) – Short message describing what went wrong.
- description (str) – Longer description of what went wrong.
-
code
¶ Error code (int).
-
message
¶ Short message describing what went wrong (str).
-
description
¶ Longer description of what went wrong (str).
retdec.file module¶
Representation of a file.
-
class
retdec.file.
File
(file, name=None)[source]¶ Bases:
object
Representation of a file.
Parameters: - object file (str/file-like) – Either path to the file (str) or an opened file (a file-like object).
- name (str) – Name of the file to be used.
When name is not given or it is
None
, the name is taken from file. You can use name to set a custom file name that may be different from the real file’s name.-
name
¶ Name of the file (str).
May be
None
if the file has no name.
-
mode
¶ Mode in which the file is opened.
If the file does not have a mode, it returns
None
.
retdec.fileinfo module¶
Access to the file-analyzing service (fileinfo).
-
class
retdec.fileinfo.
Fileinfo
(*, api_key=None, api_url=None)[source]¶ Bases:
retdec.service.Service
Access to the file-analyzing service.
-
start_analysis
(**kwargs)[source]¶ Starts an analysis with the given parameters.
Parameters: - input_file (str or file-like object) – File to be analyzed (required).
- output_format (str) – Format of the output from the analysis.
- verbose (bool) – Should the analysis produce a detailed output?
Returns: Started analysis (
Analysis
).
-
retdec.resource module¶
Base class of all resources.
-
class
retdec.resource.
Resource
(id, conn)[source]¶ Bases:
object
Base class of all resources.
Parameters: - id (str) – Unique identifier of the resource.
- conn (retdec.conn.APIConnection) – Connection to the API to be used for sending API requests.
-
id
¶ Unique identifier of the resource.
-
is_pending
()[source]¶ Is the resource in a pending state?
A resource is pending if it is scheduled to run but has not started yet.
-
has_failed
()[source]¶ Has the resource failed?
For finished resources, this is always the negation of
has_succeeded()
.
retdec.service module¶
Base class of all services.
-
class
retdec.service.
Service
(*, api_key=None, api_url=None)[source]¶ Bases:
object
Base class of all services.
Parameters: - api_key (str) – API key to be used for authentication.
- api_url (str) – URL to the API.
-
api_key
¶ API key that is being used for authentication (str).
-
api_url
¶ URL to the API (str).
retdec.test module¶
Access to the testing service.
-
class
retdec.test.
Test
(*, api_key=None, api_url=None)[source]¶ Bases:
retdec.service.Service
Access to the testing service.
-
auth
()[source]¶ Tries to authenticate.
Raises: AuthenticationError – When the authentication fails. Does nothing when the authentication succeeds.
-
echo
(**kwargs)[source]¶ Echoes the given parameters.
Returns: Echoed kwargs (dict). Raises: AuthenticationError – When the authentication fails.
-
Module contents¶
The main package of a Python library and tools providing easy access to the retdec.com decompilation service through their public REST API.
-
retdec.
DEFAULT_API_URL
= 'https://retdec.com/service/api'¶ Default API URL.