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 by type_.

Pads left with 00 if the length of the converted value is less than that specified by type_.

>>> 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 to int 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 and uint/int values returned in contract calls and events are given in Wei.

>>> 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. Evaluates True 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 return True 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 or ContractCall.

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 the decode_event or decode_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 or ContractABI object, when one already exists for the given address.

exception brownie.exceptions.ContractNotFound¶: Raised when attempting to access a Contract or ContractABI 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.InvalidManifest¶: Raised when attempting to process an improperly formatted ethPM package.

exception brownie.exceptions.MainnetUndefined¶: Raised when an action requires interacting with the main-net, but no "mainnet" network is defined in brownie-config.yaml.

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 specified Account 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 a KeyError.

>>> 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.

`brownie._singleton`¶

class brownie._singleton._Singleton¶

Internal metaclass used to create singleton objects. Instantiating a class derived from this metaclass will always return the same instance, regardless of how the child class was imported.