diff options
Diffstat (limited to 'python-packages/order_utils/src')
4 files changed, 68 insertions, 20 deletions
diff --git a/python-packages/order_utils/src/conf.py b/python-packages/order_utils/src/conf.py index 6b6776d01..d8f56b29e 100644 --- a/python-packages/order_utils/src/conf.py +++ b/python-packages/order_utils/src/conf.py @@ -22,6 +22,7 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.viewcode", + "sphinx_autodoc_typehints", ] templates_path = ["doc_templates"] diff --git a/python-packages/order_utils/src/index.rst b/python-packages/order_utils/src/index.rst index 4d27a4b17..ce618c6ff 100644 --- a/python-packages/order_utils/src/index.rst +++ b/python-packages/order_utils/src/index.rst @@ -7,21 +7,27 @@ Python zero_ex.order_utils :maxdepth: 2 :caption: Contents: -.. autoclass:: zero_ex.order_utils.Order +.. automodule:: zero_ex.order_utils :members: -See source for class properties. Sphinx does not easily generate class property docs; pull requests welcome. +.. autoclass:: zero_ex.order_utils.Order -.. automodule:: zero_ex.order_utils - :members: + See source for class properties. Sphinx is having problems generating docs for ``TypedDict`` declarations; pull requests welcome. + +zero_ex.order_utils.asset_data_utils +------------------------------------ .. automodule:: zero_ex.order_utils.asset_data_utils :members: .. autoclass:: zero_ex.order_utils.asset_data_utils.ERC20AssetData + See source for class properties. Sphinx is having problems generating docs for ``TypedDict`` declarations; pull requests welcome. + .. autoclass:: zero_ex.order_utils.asset_data_utils.ERC721AssetData + See source for class properties. Sphinx is having problems generating docs for ``TypedDict`` declarations; pull requests welcome. + Indices and tables ================== diff --git a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py index 4697ad99c..39d411507 100644 --- a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py +++ b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py @@ -1,13 +1,11 @@ """Order utilities for 0x applications. -Some methods require the caller to pass in a `Web3.HTTPProvider` object. For -local testing one may construct such a provider pointing at an instance of +Some methods require the caller to pass in a `Web3.BaseProvider`:code: object. +For local testing one may construct such a provider pointing at an instance of `ganache-cli <https://www.npmjs.com/package/ganache-cli>`_ which has the 0x contracts deployed on it. For convenience, a docker container is provided for -just this purpose. To start it: ``docker run -d -p 8545:8545 0xorg/ganache-cli ---gasLimit 10000000 --db /snapshot --noVMErrorsOnRPCResponse -p 8545 ---networkId 50 -m "concert load couple harbor equip island argue ramp clarify -fence smart topic"``. +just this purpose. To start it: +`docker run -d -p 8545:8545 0xorg/ganache-cli:2.2.2`:code:. """ from copy import copy @@ -85,17 +83,53 @@ class Order(TypedDict): # pylint: disable=too-many-instance-attributes """A Web3-compatible representation of the Exchange.Order struct.""" makerAddress: str + """Address that created the order.""" + takerAddress: str + """Address that is allowed to fill the order. + + If set to 0, any address is allowed to fill the order. + """ + feeRecipientAddress: str + """Address that will recieve fees when order is filled.""" + senderAddress: str + """Address that is allowed to call Exchange contract methods that affect + this order. If set to 0, any address is allowed to call these methods. + """ + makerAssetAmount: int + """Amount of makerAsset being offered by maker. Must be greater than 0.""" + takerAssetAmount: int + """Amount of takerAsset being bid on by maker. Must be greater than 0.""" + makerFee: int + """Amount of ZRX paid to feeRecipient by maker when order is filled. If + set to 0, no transfer of ZRX from maker to feeRecipient will be attempted. + """ + takerFee: int + """Amount of ZRX paid to feeRecipient by taker when order is filled. If + set to 0, no transfer of ZRX from taker to feeRecipient will be attempted. + """ + expirationTimeSeconds: int + """Timestamp in seconds at which order expires.""" + salt: int + """Arbitrary number to facilitate uniqueness of the order's hash.""" + makerAssetData: bytes + """Encoded data that can be decoded by a specified proxy contract when + transferring makerAsset. The last byte references the id of this proxy. + """ + takerAssetData: bytes + """Encoded data that can be decoded by a specified proxy contract when + transferring takerAsset. The last byte references the id of this proxy. + """ def make_empty_order() -> Order: @@ -125,7 +159,7 @@ def order_to_jsdict( ) -> dict: """Convert a Web3-compatible order struct to a JSON-schema-compatible dict. - More specifically, do explicit decoding for the `bytes` fields. + More specifically, do explicit decoding for the `bytes`:code: fields. >>> import pprint >>> pprint.pprint(order_to_jsdict( @@ -175,7 +209,7 @@ def order_to_jsdict( def jsdict_order_to_struct(jsdict: dict) -> Order: r"""Convert a JSON-schema-compatible dict order to a Web3-compatible struct. - More specifically, do explicit encoding of the `bytes` fields. + More specifically, do explicit encoding of the `bytes`:code: fields. >>> import pprint >>> pprint.pprint(jsdict_order_to_struct( @@ -234,7 +268,7 @@ def generate_order_hash_hex(order: Order, exchange_address: str) -> str: :param order: The order to be hashed. Must conform to `the 0x order JSON schema <https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/order_schema.json>`_. :param exchange_address: The address to which the 0x Exchange smart contract has been deployed. - :rtype: A string, of ASCII hex digits, representing the order hash. + :returns: A string, of ASCII hex digits, representing the order hash. >>> generate_order_hash_hex( ... { @@ -296,8 +330,13 @@ class OrderInfo(NamedTuple): """A Web3-compatible representation of the Exchange.OrderInfo struct.""" order_status: str + """A `str`:code: describing the order's validity and fillability.""" + order_hash: bytes + """A `bytes`:code: object representing the EIP712 hash of the order.""" + order_taker_asset_filled_amount: int + """An `int`:code: indicating the amount that has already been filled.""" def is_valid_signature( @@ -305,15 +344,15 @@ def is_valid_signature( ) -> Tuple[bool, str]: """Check the validity of the supplied signature. - Check if the supplied ``signature`` corresponds to signing ``data`` with - the private key corresponding to ``signer_address``. + Check if the supplied `signature`:code: corresponds to signing `data`:code: + with the private key corresponding to `signer_address`:code:. :param provider: A Web3 provider able to access the 0x Exchange contract. :param data: The hex encoded data signed by the supplied signature. :param signature: The hex encoded signature. :param signer_address: The hex encoded address that signed the data to produce the supplied signature. - :rtype: Tuple consisting of a boolean and a string. Boolean is true if + :returns: Tuple consisting of a boolean and a string. Boolean is true if valid, false otherwise. If false, the string describes the reason. >>> is_valid_signature( @@ -428,8 +467,8 @@ def sign_hash( :param provider: A Web3 provider. :param signer_address: The address of the signing account. :param hash_hex: A hex string representing the hash, like that returned - from `generate_order_hash_hex()`. - :rtype: A string, of ASCII hex digits, representing the signature. + from `generate_order_hash_hex()`:code:. + :returns: A string, of ASCII hex digits, representing the signature. >>> provider = Web3.HTTPProvider("http://127.0.0.1:8545") >>> sign_hash( diff --git a/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py b/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py index fab7479d2..f8e9bc42b 100644 --- a/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py +++ b/python-packages/order_utils/src/zero_ex/order_utils/asset_data_utils.py @@ -17,6 +17,8 @@ class ERC20AssetData(TypedDict): """Object interface to ERC20 asset data.""" asset_proxy_id: str + """asset proxy id""" + token_address: str @@ -32,7 +34,7 @@ def encode_erc20_asset_data(token_address: str) -> str: """Encode an ERC20 token address into an asset data string. :param token_address: the ERC20 token's contract address. - :rtype: hex encoded asset data string, usable in the makerAssetData or + :returns: hex encoded asset data string, usable in the makerAssetData or takerAssetData fields in a 0x order. >>> encode_erc20_asset_data('0x1dc4c1cefef38a777b15aa20260a54e584b16c48') @@ -85,7 +87,7 @@ def encode_erc721_asset_data(token_address: str, token_id: int) -> str: :param token_address: the ERC721 token's contract address. :param token_id: the identifier of the asset's instance of the token. - :rtype: hex encoded asset data string, usable in the makerAssetData or + :returns: hex encoded asset data string, usable in the makerAssetData or takerAssetData fields in a 0x order. >>> encode_erc721_asset_data('0x1dc4c1cefef38a777b15aa20260a54e584b16c48', 1) |