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()

encode_typed_data()

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:

AddressType

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_dump(*args, **kwargs) → dict

Usage docs: https://docs.pydantic.dev/2.7/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 output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.
include – A set of fields to include in the output.
exclude – A set of fields to exclude from the output.
context – Additional context to pass to the serializer.
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.
exclude_none – Whether to exclude fields that have a value of None.
round_trip – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
serialize_as_any – Whether to serialize fields with duck-typing serialization behavior.

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_dump(*args, **kwargs) → dict

Usage docs: https://docs.pydantic.dev/2.7/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 output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.
include – A set of fields to include in the output.
exclude – A set of fields to exclude from the output.
context – Additional context to pass to the serializer.
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.
exclude_none – Whether to exclude fields that have a value of None.
round_trip – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
serialize_as_any – Whether to serialize fields with duck-typing serialization behavior.

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_dump(*args, **kwargs) → dict

Usage docs: https://docs.pydantic.dev/2.7/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 output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.
include – A set of fields to include in the output.
exclude – A set of fields to exclude from the output.
context – Additional context to pass to the serializer.
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.
exclude_none – Whether to exclude fields that have a value of None.
round_trip – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
serialize_as_any – Whether to serialize fields with duck-typing serialization behavior.

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_dump(*args, **kwargs) → dict

Usage docs: https://docs.pydantic.dev/2.7/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 output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.
include – A set of fields to include in the output.
exclude – A set of fields to exclude from the output.
context – Additional context to pass to the serializer.
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.
exclude_none – Whether to exclude fields that have a value of None.
round_trip – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
serialize_as_any – Whether to serialize fields with duck-typing serialization behavior.

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.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_dump(*args, **kwargs) → dict

Usage docs: https://docs.pydantic.dev/2.7/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 output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.
include – A set of fields to include in the output.
exclude – A set of fields to exclude from the output.
context – Additional context to pass to the serializer.
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.
exclude_none – Whether to exclude fields that have a value of None.
round_trip – If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings – How to handle serialization errors. False/”none” ignores them, True/”warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
serialize_as_any – Whether to serialize fields with duck-typing serialization behavior.

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.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

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.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

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.

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.