Package: nomisma.contractapi
Using the Nomisma Contract APIRequirements:Python 3.7.xWeb3 >= 4.9The API consists of a set of classes that wrap and enhance the Solidity smart contracts.
An asynchronous multi-threaded runtime is included and used by these classes.
Additionally, a test resource is available to make testing your code simpler.Testing your code that uses the APIThetest_utilpackage includes the following test resource classes that should be used in your tests.CapitalStructureTestResourceThese test resources have methods for deploying the contracts and loading python instances of these contracts.
The contracts are split into two sets: contracts that have no storage (just code) and should be deployed
just once, and contracts that have storage, which should be deployed with each independent test case.You have to choose an ethereum test implementation for your the tests. Two choices are: ganache or
eth_tester (native python).GanacheRun ganache-cli with these parameters:ganache-cli --account '0x0000000000000000000000000000000000000000000000000000000000000001',10000000000000000000000This creates a locally running Ethereum test chain and creates 100 accounts with known addresses.
Adding-b 1to the command line args will result in some transaction batching, which is more realistic, but slows down testing.In the test resource initialization, point to the ganache instance like this:CapitalStructureTestResource(web3=Web3(Web3.HTTPProvider("http://127.0.0.1:8545")))Eth-TesterAs of 0.0.3, Eth-tester seems to be broken. Don't use for now.
You'll have to install eth-tester (via pip or similar). eth-tester seems limited to 10 accounts, so don't use
any more accounts than 10 in your tests (the test resource uses some accounts, configurable in its constructor).In the test resource initialization, use this form:CapitalStructureTestResource(web3=Web3(EthereumTesterProvider()))Why code generation?Web3.py comes with various ways to invoke contracts and it does it without code generation (using
python's highly dynamic object structure). With code generation, we get the following benefits,
as compared to web3.py out of the box:The contract functions are visible and readable. This is ultimately much better for developers,
because both them and their tools (IDE with auto-completion) have access to the method declarations.python 3 type hinting for parameters and return typespayable functions have an extra parameter (to_pay_ether) with a sensible unit (ether)The contract functions can be documented from the solidity docs.idiomatic python snake case names, e.g.getAddress->get_addressuser friendly parameter checking, e.g. correct length forunit256[4](python doesn't have fixed length arrays)performant(async)/user friendly call/transaction wrappingDevelopment Tool SetupRequirements:Python 3.7.xPipenv:pip install pipenvganache-cli for testing (which usually means installing npm, thennpm install ganache-cli)SetPIPENV_VENV_IN_PROJECT=truein your environment variables to have a.venvdirectory inside
the project folder.pipenv shellopens a shell prompt within the virtual environment for the project.pipenv installwill install the project dependencies.pipenv install --devinstalls
the development dependencies.Running TestsFor dev purposes, we run most tests with ganache (see above).Technical NotesWeb3.py converts Solidityaddresstype to Pythonstr, but we don't type hint addresses as such in the generated
code, to make it clear they are not arbitrary strings.ReleasingMake suresetup.pyhas a new version, based on semantic versioning.
Add a git tag:git tag nomisma.contractapi-x.y.z -m "Release x.y.z"git push upstream nomisma.contractapi-x.y.zClean the dist directory:rm -rf distCreate a distribution (in the project's virtual env, usually viapipenv shell):python setup.py sdistUpload to pypi (requires username/pw):twine upload dist/*