mirror of
https://github.com/idapython/src
synced 2026-06-08 14:47:00 +00:00
Arnaud Diederen
61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
|
|
# IDAPython examples
|
|
|
|
This directory contains a variety of examples demonstrating
|
|
how IDA can be scripted using IDAPython.
|
|
|
|
## Adding a new example (for Hex-Rays developers)
|
|
|
|
When adding an example, the author (i.e., a Hex-Rays developer)
|
|
must add a corresponding test, making sure the example is properly
|
|
tested, and doesn't regress over time (see `idapython-examples`,
|
|
and `idapython_hr-examples` test suites.) This has the added benefit
|
|
that this ensures our APIs remain stable.
|
|
|
|
Also, any significant addition to IDAPython APIs should come
|
|
with one or many examples, and those should be also put under test
|
|
(in other words: it's better if a test relies on a real example,
|
|
rather than if it consists of a bunch of IDAPython code our
|
|
users will never see, and cannot be inspired from.)
|
|
|
|
### Best practices
|
|
|
|
* don't use `idc.py`: some of its operations are a bit too elusive
|
|
* don't use `idaapi`: that "hides" the provenance of the
|
|
function/type/item being used, and makes it that much harder to
|
|
group ideas by module
|
|
* don't `from <something> import <whatever>`: for the same reason
|
|
* use double-quotes for all string literals, unless there's a good
|
|
reason not to do so (e.g., the string literal contains some `"`
|
|
characters, and `\`-escaping them would be inconvenient & make the
|
|
code awkward to read).
|
|
Double-quoted string literals let us grep more predictably & reliably.
|
|
|
|
## Example header
|
|
|
|
Every example must have a valid header, holding a one-liner `summary:`,
|
|
as well as a description further explaining what the example is about.
|
|
|
|
Some notes:
|
|
|
|
* `summary:`: the one-liner must not end with a `.`
|
|
* `summary:`: prefer the `list something...` form over the `listing something...`
|
|
|
|
## Helping our customers, teaching IDAPython in the process
|
|
|
|
In addition, when a customer asks for help on support@ (or the forums)
|
|
and we end up sending a significant body of IDAPython code as a reply,
|
|
since that body of code should be tested anyway, it's better to make
|
|
a real example out of it ... and, of course, put that example under
|
|
test as well.
|
|
|
|
## Maintaining quality
|
|
|
|
There should be no such thing as a non-tested example.
|
|
|
|
## Updating the examples index
|
|
|
|
All examples are automatically integrated in the examples index.
|
|
In order to show user-friendly & relevant information, a proper
|
|
header (docstring) needs to be present.
|