Update documentation for format strings #2501
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
By default, when creating a
FmtStr
class or usingfmtstr_payload()
, all the documentation (and examples) state that thevalue
in thewrites
dictionary should be anint
. However, this int is automatically expanded to a bytestring of size long internally. If someone wants to write data shorter than a long, they need to provide a bytestring as the value instead of an integer (either raw usingb'\x37\x13'
or helper functions likep16(0x1337)
). However, this is never documented anywhere or provided in any examples.This has led to a number of issues being filed, such as:
This pull requests expands on the current documentation to explicitly lay out whether an
int
orbytes
argument is needed and examples are provided to show how providing a bytestring creates a different format string payload.Hopefully this helps to reduce confusion and prevent similar future issues from being filed.