Brownie API¶
brownie
¶
The brownie
package is the main package containing all of Brownie’s functionality.
>>> from brownie import *
>>> dir()
['Gui', 'accounts', 'alert', 'brownie', 'check', 'compile_source', 'config', 'history', 'network', 'project', 'rpc', 'web3', 'wei']
brownie.convert
¶
The convert
module contains methods relating to data conversion.
Type Conversions¶
The following classes and methods are used to convert arguments supplied to ContractTx
and ContractCall
.
-
brownie.convert.
to_uint
(value, type_="uint256")¶ Converts a value to an unsigned integer. This is equivalent to calling
Wei
and then applying checks for over/underflows.
-
brownie.convert.
to_int
(value, type_="int256")¶ Converts a value to a signed integer. This is equivalent to calling
Wei
and then applying checks for over/underflows.
-
brownie.convert.
to_bool
(value)¶ Converts a value to a boolean. Raises
ValueError
if the given value does not match a value in(True, False, 0, 1)
.
-
brownie.convert.
to_address
(value)¶ Converts a value to a checksummed address. Raises
ValueError
if value cannot be converted.
-
brownie.convert.
to_bytes
(value, type_="bytes32")¶ Converts a value to bytes.
value
can be given as bytes, a hex string, or an integer.Raises
OverflowError
if the length of the converted value exceeds that specified bytype_
.Pads left with
00
if the length of the converted value is less than that specified bytype_
.>>> to_bytes('0xff','bytes') b'\xff' >>> to_bytes('0xff','bytes16') b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff'
-
brownie.convert.
to_string
(value)¶ Converts a value to a string.
-
brownie.convert.
bytes_to_hex
(value)¶ Converts a bytes value to a hex string.
>>> from brownie.convert import bytes_to_hex >>> bytes_to_hex(b'\xff\x3a') 0xff3a >>> bytes_to_hex('FF') 0xFF >>> bytes_to_hex("Hello") File "brownie/types/convert.py", line 149, in bytes_to_hex raise ValueError("'{value}' is not a valid hex string".format(value)) ValueError: 'Hello' is not a valid hex string
Type Classes¶
For certain types of contract data, Brownie uses subclasses to assist with conversion and comparison.
-
class
brownie.convert.
Wei
(value)¶ Integer subclass that converts a value to wei and allows comparisons, addition and subtraction using the same conversion.
Wei
is useful for strings where you specify the unit, for large floats given in scientific notation, or where a direct conversion toint
would cause inaccuracy from floating point errors.Whenever a Brownie method takes an input referring to an amount of ether, the given value is converted to
Wei
. Balances anduint
/int
values returned in contract calls and events are given inWei
.>>> from brownie import Wei >>> Wei("1 ether") 1000000000000000000 >>> Wei("12.49 gwei") 12490000000 >>> Wei("0.029 shannon") 29000000 >>> Wei(8.38e32) 838000000000000000000000000000000 >>> Wei(1e18) == "1 ether" True >>> Wei("1 ether") < "2 ether" True >>> Wei("1 ether") - "0.75 ether" 250000000000000000
-
class
brownie.convert.
EthAddress
(value)¶ String subclass for address comparisons. Raises a
TypeError
when compared to a non-address.Addresses returned from a contract call or as part of an event log are given in this type.
>>> from brownie.convert import EthAddress >>> e = EthAddress("0x0035424f91fd33084466f402d5d97f05f8e3b4af") '0x0035424f91Fd33084466f402d5d97f05f8E3b4af' >>> e == "0x3506424F91fD33084466F402d5D97f05F8e3b4AF" False >>> e == "0x0035424F91fD33084466F402d5D97f05F8e3b4AF" True >>> e == "0x35424F91fD33084466F402d5D97f05F8e3b4AF" Traceback (most recent call last): File "brownie/convert.py", line 304, in _address_compare raise TypeError(f"Invalid type for comparison: '{b}' is not a valid address") TypeError: Invalid type for comparison: '0x35424F91fD33084466F402d5D97f05F8e3b4AF' is not a valid address >>> e == "potato" Traceback (most recent call last): File "brownie/convert.py", line 304, in _address_compare raise TypeError(f"Invalid type for comparison: '{b}' is not a valid address") TypeError: Invalid type for comparison: 'potato' is not a valid address >>> type(e) <class 'brownie.convert.EthAddress'>
-
class
brownie.convert.
HexString
(value, type_)¶ Bytes subclass for hexstring comparisons. Raises
TypeError
if compared to a non-hexstring. EvaluatesTrue
for hex strings with the same value but differing leading zeros or capitalization.All
bytes
values returned from a contract call or as part of an event log are given in this type.>>> from brownie.convert import HexString >>> h = HexString("0x00abcd", "bytes2") "0xabcd" >>> h == "0xabcd" True >>> h == "0x0000aBcD" True >>> h == "potato" File "<console>", line 1, in <module> File "brownie/convert.py", line 327, in _hex_compare raise TypeError(f"Invalid type for comparison: '{b}' is not a valid hex string") TypeError: Invalid type for comparison: 'potato' is not a valid hex string
-
class
brownie.network.return_value.
ReturnValue
¶ Tuple subclass with limited dict-like functionality. Used for iterable return values from contract calls or event logs.
>>> result = issuer.getCountry(784) >>> result (1, (0, 0, 0, 0), (100, 0, 0, 0)) >>> result[2] (100, 0, 0, 0) >>> result.dict() { '_count': (0, 0, 0, 0), '_limit': (100, 0, 0, 0), '_minRating': 1 } >>> result['_minRating'] 1
When checking equality,
ReturnValue
objects ignore the type of container compared against. Tuples and lists will both returnTrue
so long as they contain the same values.>>> result = issuer.getCountry(784) >>> result (1, (0, 0, 0, 0), (100, 0, 0, 0)) >>> result == (1, (0, 0, 0, 0), (100, 0, 0, 0)) True >>> result == [1, [0, 0, 0, 0], [100, 0, 0, 0]] True
-
classmethod
ReturnValue.
dict
()¶ Returns a
dict
of the named values within the object.
-
classmethod
ReturnValue.
items
()¶ Returns a set-like object providing a view on the object’s named items.
-
classmethod
ReturnValue.
keys
()¶ Returns a set-like object providing a view on the object’s keys.
Internal Methods¶
Formatting Contract Data¶
The following methods are used to convert multiple values based on a contract ABI specification. Values are formatted via calls to the methods outlined under type conversions, and where appropriate type classes are applied.
-
brownie.convert.
_format_input
(abi, inputs) → 'ReturnValue'¶ Formats inputs based on a contract method ABI.
Returns
abi
: A contract method ABI as a dict.inputs
: List or tuple of values to format.
Returns a tuple subclass (brownie.convert.ReturnValue) of values formatted for use by
ContractTx
orContractCall
.Each value in
inputs
is converted using the one of the methods outlined in Type Conversions.>>> from brownie.convert import format_input >>> abi = {'constant': False, 'inputs': [{'name': '_to', 'type': 'address'}, {'name': '_value', 'type': 'uint256'}], 'name': 'transfer', 'outputs': [{'name': '', 'type': 'bool'}], 'payable': False, 'stateMutability': 'nonpayable', 'type': 'function'} >>> format_input(abi, ["0xB8c77482e45F1F44dE1745F52C74426C631bDD52","1 ether"]) ('0xB8c77482e45F1F44dE1745F52C74426C631bDD52', 1000000000000000000)
-
brownie.convert.
_format_output
(abi, outputs) → 'ReturnValue'¶ Standardizes outputs from a contract call based on the contract’s ABI.
Returns a tuple sublcass (brownie.convert.ReturnValue).
abi
: A contract method ABI as a dict.outputs
: List or tuple of values to format.
Each value in
outputs
is converted using the one of the methods outlined in Type Conversions.This method is called internally by
ContractCall
to ensure that contract output formats remain consistent, regardless of the RPC client being used.>>> from brownie.convert import format_output >>> abi = {'constant': True, 'inputs': [], 'name': 'name', 'outputs': [{'name': '', 'type': 'string'}], 'payable': False, 'stateMutability': 'view', 'type': 'function'} >>> format_output(abi, ["0x5465737420546f6b656e"]) ('Test Token',)
-
brownie.convert.
_format_event
(event)¶ Standardizes outputs from an event fired by a contract.
event
: Decoded event data as given by thedecode_event
ordecode_trace
methods of the eth-event package.
The given event data is mutated in-place and returned. If an event topic is indexed, the type is changed to
bytes32
and" (indexed)"
is appended to the name.
brownie.exceptions
¶
The exceptions
module contains all Brownie Exception
classes.
-
exception
brownie.exceptions.
CompilerError
¶ Raised by the compiler when there is an error within a contract’s source code.
-
exception
brownie.exceptions.
ContractExists
¶ Raised when attempting to create a new
Contract
orContractABI
object, when one already exists for the given address.
-
exception
brownie.exceptions.
ContractNotFound
¶ Raised when attempting to access a
Contract
orContractABI
object that no longer exists because the local network was reverted.
-
exception
brownie.exceptions.
EventLookupError
¶ Raised during lookup errors by
EventDict
and_EventItem
.
-
exception
brownie.exceptions.
IncompatibleEVMVersion
¶ Raised when attempting to deploy a contract that was compiled to target an EVM version that is imcompatible than the currently active local RPC client.
-
exception
brownie.exceptions.
IncompatibleSolcVersion
¶ Raised when a project requires a version of solc that is not installed or not supported by Brownie.
-
exception
brownie.exceptions.
MainnetUndefined
¶ Raised when an action requires interacting with the main-net, but no
"mainnet"
network is defined inbrownie-config.json
.
-
exception
brownie.exceptions.
NamespaceCollision
¶ Raised by
project.sources
when the multiple source files contain a contract with the same name.
-
exception
brownie.exceptions.
PragmaError
¶ Raised when a contract has no pragma directive, or a pragma which requires a version of solc that cannot be installed.
-
exception
brownie.exceptions.
ProjectAlreadyLoaded
¶ Raised by
project.load_project
if a project has already been loaded.
-
exception
brownie.exceptions.
ProjectNotFound
¶ Raised by
project.load_project
when a project cannot be found at the given path.
-
exception
brownie.exceptions.
UndeployedLibrary
¶ Raised when attempting to deploy a contract that requires an unlinked library, but the library has not yet been deployed.
-
exception
brownie.exceptions.
UnknownAccount
¶ Raised when the
Accounts
container cannot locate a specifiedAccount
object.
-
exception
brownie.exceptions.
UnsetENSName
¶ Raised when an ENS name is unset (resolves to
0x00
).
-
exception
brownie.exceptions.
RPCConnectionError
¶ Raised when the RPC process is active and
web3
is connected, but Brownie is unable to communicate with it.
-
exception
brownie.exceptions.
RPCProcessError
¶ Raised when the RPC process fails to launch successfully.
-
exception
brownie.exceptions.
RPCRequestError
¶ Raised when a direct request to the RPC client has failed, such as a snapshot or advancing the time.
-
exception
brownie.exceptions.
VirtualMachineError
¶ Raised when a contract call causes the EVM to revert.
brownie._config
¶
The _config
module handles all Brownie configuration settings. It is not designed to be accessed directly. If you wish to view or modify config settings while Brownie is running, import brownie.config
which will return a ConfigDict
with the active settings:
>>> from brownie import config
>>> type(config)
<class 'brownie._config.ConfigDict'>
>>> config['network_defaults']
{'name': 'development', 'gas_limit': False, 'gas_price': False}
ConfigDict¶
-
class
brownie._config.
ConfigDict
¶ Subclass of dict that prevents adding new keys when locked. Used to hold config file settings.
>>> from brownie.types import ConfigDict >>> s = ConfigDict({'test': 123}) >>> s {'test': 123}
ConfigDict Internal Methods¶
-
classmethod
ConfigDict.
_lock
()¶ Locks the
ConfigDict
. When locked, attempts to add a new key will raise aKeyError
.>>> s._lock() >>> s['other'] = True Traceback (most recent call last): File "brownie/types/types.py", line 18, in __setitem__ raise KeyError("{} is not a known config setting".format(key)) KeyError: 'other is not a known config setting' >>>
-
classmethod
ConfigDict.
_unlock
()¶ Unlocks the
ConfigDict
. When unlocked, new keys can be added.>>> s._unlock() >>> s['other'] = True >>> s {'test': 123, 'other': True}
-
classmethod
ConfigDict.
_copy
()¶ Returns a copy of the object as a
dict
.