ape.types
Address
- ape.types.address.AddressType
“A checksum address in Ape.”
alias of
ChecksumAddress
[ChecksumAddress
]
- ape.types.address.RawAddress
A raw data-type representation of an address.
alias of
Union
[str
,int
,HashStr20
,HashBytes20
]
Signatures
- class ape.types.signatures.SignableMessage(version: bytes, header: bytes, body: bytes)
Bases:
NamedTuple
A message compatible with EIP-191 that is ready to be signed.
The properties are components of an EIP-191 signable message. Other message formats can be encoded into this format for easy signing. This data structure doesn’t need to know about the original message format. For example, you can think of EIP-712 as compiling down to an EIP-191 message.
In typical usage, you should never need to create these by hand. Instead, use one of the available encode_* methods in this module, like:
encode_structured_data()
encode_intended_validator()
encode_defunct()
- body: bytes
Alias for field number 2
- header: bytes
Alias for field number 1
- version: bytes
Alias for field number 0
- class ape.types.signatures.MessageSignature(v: int, r: bytes, s: bytes)
Bases:
_Signature
A ECDSA signature (vrs) of a message.
- class ape.types.signatures.TransactionSignature(v: int, r: bytes, s: bytes)
Bases:
_Signature
A ECDSA signature (vrs) of a transaction.
- signatures.recover_signer(sig: MessageSignature) ChecksumAddress
Get the address of the signer.
- Parameters:
msg (
SignableMessage
) – A formatted and signable message.sig (
MessageSignature
) – Signature of the message.
- Returns:
address of message signer.
- Return type:
Coverage
- class ape.types.coverage.ContractCoverage(*, name: str, functions: List[FunctionCoverage] = [])
Bases:
BaseModel
An individual contract’s coverage.
- property function_hits: int
The number of functions with a hit counter greater than zero.
- property function_rate: float
The rate of functions hit versus total functions.
- functions: List[FunctionCoverage]
The coverage of each function individually.
- property line_rate: float
The number of lines hit divided by number of lines.
- property lines_covered: int
All lines that have a hit count greater than zero.
- property lines_valid: int
The number of lines valid for coverage.
- property miss_count: int
The number of lines missed.
- model_dump(*args, **kwargs) dict
Usage docs: https://docs.pydantic.dev/2.5/concepts/serialization/#modelmodel_dump
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
- Parameters:
mode – The mode in which to_python should run. If mode is ‘json’, the dictionary will only contain JSON serializable types. If mode is ‘python’, the dictionary may contain any Python objects.
include – A list of fields to include in the output.
exclude – A list of fields to exclude from the output.
by_alias – Whether to use the field’s alias in the dictionary key if defined.
exclude_unset – Whether to exclude fields that have not been explicitly set.
exclude_defaults – Whether to exclude fields that are set to their default value from the output.
exclude_none – Whether to exclude fields that have a value of None from the output.
round_trip – Whether to enable serialization and deserialization round-trip support.
warnings – Whether to log warnings when invalid fields are encountered.
- Returns:
A dictionary representation of the model.
- name: str
The name of the contract.
- property statements: List[CoverageStatement]
All valid coverage lines from every function in this contract.
- class ape.types.coverage.ContractSourceCoverage(*, source_id: str, contracts: List[ContractCoverage] = [])
Bases:
BaseModel
An individual source file with coverage collected.
- contracts: List[ContractCoverage]
Coverage for each contract in the source file.
- property function_hits: int
The number of functions with a hit counter greater than zero.
- property function_rate: float
The rate of functions hit versus total functions.
- include(contract_name: str) ContractCoverage
Ensure a contract is included in the report.
- property line_rate: float
The number of lines hit divided by number of lines.
- property lines_covered: int
All lines with a hit count greater than zero from every function in every contract in this source.
- property lines_valid: int
The number of lines valid for coverage.
- property miss_count: int
The number of lines missed.
- model_dump(*args, **kwargs) dict
Usage docs: https://docs.pydantic.dev/2.5/concepts/serialization/#modelmodel_dump
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
- Parameters:
mode – The mode in which to_python should run. If mode is ‘json’, the dictionary will only contain JSON serializable types. If mode is ‘python’, the dictionary may contain any Python objects.
include – A list of fields to include in the output.
exclude – A list of fields to exclude from the output.
by_alias – Whether to use the field’s alias in the dictionary key if defined.
exclude_unset – Whether to exclude fields that have not been explicitly set.
exclude_defaults – Whether to exclude fields that are set to their default value from the output.
exclude_none – Whether to exclude fields that have a value of None from the output.
round_trip – Whether to enable serialization and deserialization round-trip support.
warnings – Whether to log warnings when invalid fields are encountered.
- Returns:
A dictionary representation of the model.
- source_id: str
The ID of the source covered.
- property statements: List[CoverageStatement]
All valid coverage lines from every function in every contract in this source.
- property total_functions: int
The total number of functions in this source.
- class ape.types.coverage.CoverageProject(*, name: str, sources: List[ContractSourceCoverage] = [])
Bases:
BaseModel
A project with coverage collected.
- property function_hits: int
The number of functions with a hit counter greater than zero.
- property function_rate: float
The rate of functions hit versus total functions.
- property line_rate: float
The number of lines hit divided by number of lines.
- property lines_covered: int
The number of lines with a hit count greater than zero from every function in every contract in every source in this this project.
- property lines_valid: int
The number of lines valid for coverage.
- property miss_count: int
The number of lines missed.
- model_dump(*args, **kwargs) dict
Usage docs: https://docs.pydantic.dev/2.5/concepts/serialization/#modelmodel_dump
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
- Parameters:
mode – The mode in which to_python should run. If mode is ‘json’, the dictionary will only contain JSON serializable types. If mode is ‘python’, the dictionary may contain any Python objects.
include – A list of fields to include in the output.
exclude – A list of fields to exclude from the output.
by_alias – Whether to use the field’s alias in the dictionary key if defined.
exclude_unset – Whether to exclude fields that have not been explicitly set.
exclude_defaults – Whether to exclude fields that are set to their default value from the output.
exclude_none – Whether to exclude fields that have a value of None from the output.
round_trip – Whether to enable serialization and deserialization round-trip support.
warnings – Whether to log warnings when invalid fields are encountered.
- Returns:
A dictionary representation of the model.
- name: str
The name of the project being covered.
- sources: List[ContractSourceCoverage]
Coverage for each source in the project.
- property statements: List[CoverageStatement]
All valid coverage lines from every function in every contract in every source in this project.
- property total_functions: int
The total number of functions in this source.
- class ape.types.coverage.CoverageReport(*, source_folders: List[Path], timestamp: int, projects: List[CoverageProject] = [])
Bases:
BaseModel
Coverage report schema inspired from coverage.py.
- property function_hits: int
The number of functions with a hit counter greater than zero.
- property function_rate: float
The rate of functions hit versus total functions.
- get_html(verbose: bool = False) str
The coverage HTML report as a string.
- get_xml() str
The coverage XML report as a string. The XML coverage data schema is meant to be compatible with codecov.io. Thus, some of coverage is modified slightly, and some of the naming conventions (based on 90s Java) won’t be super relevant to smart-contract projects.
- property line_rate: float
The number of lines hit divided by number of lines.
- property lines_covered: int
All lines with a hit count greater than zero from every function in every contract in every source in every project in this report.
- property lines_valid: int
The number of lines valid for coverage.
- property miss_count: int
The number of lines missed.
- model_dump(*args, **kwargs) dict
Usage docs: https://docs.pydantic.dev/2.5/concepts/serialization/#modelmodel_dump
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
- Parameters:
mode – The mode in which to_python should run. If mode is ‘json’, the dictionary will only contain JSON serializable types. If mode is ‘python’, the dictionary may contain any Python objects.
include – A list of fields to include in the output.
exclude – A list of fields to exclude from the output.
by_alias – Whether to use the field’s alias in the dictionary key if defined.
exclude_unset – Whether to exclude fields that have not been explicitly set.
exclude_defaults – Whether to exclude fields that are set to their default value from the output.
exclude_none – Whether to exclude fields that have a value of None from the output.
round_trip – Whether to enable serialization and deserialization round-trip support.
warnings – Whether to log warnings when invalid fields are encountered.
- Returns:
A dictionary representation of the model.
- projects: List[CoverageProject]
Each project with individual coverage tracked.
- source_folders: List[Path]
All source folders to use. This is needed for codecov.
- property sources: List[str]
Every source ID in the report.
- property statements: List[CoverageStatement]
All valid coverage lines from every function in every contract in every source from every project in this report.
- timestamp: int
The timestamp the report was generated, in milliseconds.
- property total_functions: int
The total number of functions in this source.
- class ape.types.coverage.CoverageStatement(*, location: Tuple[int, int, int, int] | None = None, pcs: Set[int], hit_count: int = 0, tag: str | None = None)
Bases:
BaseModel
An item that can get hit during coverage. Examples of coverage items are line segments, which are generally calculated from groupings of AST nodes occupying the same location, that can be tracked by their PC values. During a transaction’s trace, we find these values and we find the corresponding coverage item and increment the hit count. Another example of a coverage item is a compiler-builtin check, also marked by a PC value. If we encounter such PC in a trace, its hit count is incremented. Builtin compiler checks may or may not correspond to an actual location in the source code, depending on the type of check.
- hit_count: int
The times this node was hit.
- location: Tuple[int, int, int, int] | None
The location of the item (line, column, endline, endcolumn). If multiple PCs share an exact location, it is only tracked as one.
- pcs: Set[int]
The PCs for this node.
- tag: str | None
An additional tag to mark this statement with. This is useful if the location field is empty.
- class ape.types.coverage.FunctionCoverage(*, name: str, full_name: str, statements: List[CoverageStatement] = [], hit_count: int = 0)
Bases:
BaseModel
The individual coverage of a function defined in a smart contact.
- full_name: str
The unique name of the function.
- hit_count: int
The times this function was called. NOTE: This is needed as a separate data point since not all methods may have statements (such as auto-getters).
- property line_rate: float
The number of lines hit divided by number of lines.
- property lines_covered: int
The number of lines with a hit counter greater than zero in this method.
- property lines_valid: int
All lines valid for coverage in this method.
- property miss_count: int
The number of lines missed.
- model_dump(*args, **kwargs) dict
Usage docs: https://docs.pydantic.dev/2.5/concepts/serialization/#modelmodel_dump
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
- Parameters:
mode – The mode in which to_python should run. If mode is ‘json’, the dictionary will only contain JSON serializable types. If mode is ‘python’, the dictionary may contain any Python objects.
include – A list of fields to include in the output.
exclude – A list of fields to exclude from the output.
by_alias – Whether to use the field’s alias in the dictionary key if defined.
exclude_unset – Whether to exclude fields that have not been explicitly set.
exclude_defaults – Whether to exclude fields that are set to their default value from the output.
exclude_none – Whether to exclude fields that have a value of None from the output.
round_trip – Whether to enable serialization and deserialization round-trip support.
warnings – Whether to log warnings when invalid fields are encountered.
- Returns:
A dictionary representation of the model.
- name: str
The display name of the function.
- profile_statement(pc: int, location: Tuple[int, int, int, int] | None = None, tag: str | None = None)
Initialize a statement in the coverage profile with a hit count starting at zero. This statement is ready to accumulate hits as tests execute.
- Parameters:
pc (int) – The program counter of the statement.
location (Optional[ethpm_types.source.SourceStatement]) – The location of the statement, if it exists.
tag (Optional[str]) – Optionally provide more information about the statements being hit. This is useful for builtin statements that may be missing context otherwise.
- statements: List[CoverageStatement]
For statement coverage, these are the individual items. See
CoverageStatement
for more details.
Miscellaneous
- class ape.types.BaseContractLog(*, event_name: str, contract_address: ChecksumAddress = '0x0000000000000000000000000000000000000000', event_arguments: Dict[str, Any] = {})
Base class representing information relevant to an event instance.
- contract_address: ChecksumAddress
The contract responsible for emitting the log.
- event_arguments: Dict[str, Any]
The arguments to the event, including both indexed and non-indexed data.
- event_name: str
The name of the event.
- ape.types.BlockID
An ID that can match a block, such as the literals
"earliest"
,"latest"
, or"pending"
as well as a block number or hash (HexBytes).alias of
Union
[int
,HexStr
,HexBytes
,Literal
[‘earliest’, ‘latest’, ‘pending’]]
- class ape.types.ContractLog(*, event_name: str, contract_address: ChecksumAddress = '0x0000000000000000000000000000000000000000', event_arguments: Dict[str, Any] = {}, transaction_hash: Any, block_number: int, block_hash: Any, log_index: int, transaction_index: int | None = None)
An instance of a log from a contract.
- block_hash: Any
The hash of the block containing the transaction that produced this log.
- block_number: int
The number of the block containing the transaction that produced this log.
- log_index: int
The index of the log on the transaction.
- property timestamp: int
The UNIX timestamp of when the event was emitted.
NOTE: This performs a block lookup.
- transaction_hash: Any
The hash of the transaction containing this log.
- transaction_index: int | None
The index of the transaction’s position when the log was created. Is None when from the pending block.
- class ape.types.MockContractLog(*, event_name: str, contract_address: ChecksumAddress = '0x0000000000000000000000000000000000000000', event_arguments: Dict[str, Any] = {})
A mock version of the ContractLog class used for testing purposes. This class is designed to match a subset of event arguments in a ContractLog instance by only comparing those event arguments that the user explicitly provides.
Inherits from
BaseContractLog
, and overrides the equality method for custom comparison of event arguments between a MockContractLog and a ContractLog instance.