diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 00000000..1e4778fe --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,46 @@ +name: Build and deploy sphinx docs + +on: + push: + branches: main + pull_request: + branches: + - main + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v3 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + pip install -r requirements-dev.txt + - name: Build documentation + run: | + cd docs/ + make html + + - uses: actions/checkout@v4 + with: + ref: "gh-pages" + repository: ${{ github.event.pull_request.head.repo.full_name }} + path: "gh-pages-docs" + + - name: Deploy to GitHub Pages + run: | + git config --global user.email "actions@github.com" + git config --global user.name "GitHub Actions" + rm -rf ./gh-pages-docs/* + mv -f ${{ github.workspace }}/docs/_build/html/* ./gh-pages-docs + cd ./gh-pages-docs + touch .nojekyll + git add . + git commit -m "Deploy documentation from GitHub Actions" --allow-empty + git push origin gh-pages diff --git a/.gitignore b/.gitignore index 11a51a3b..348cbe5e 100644 --- a/.gitignore +++ b/.gitignore @@ -139,3 +139,5 @@ typings/** !libbls.dll examples/output + +./docs/_build/* diff --git a/README.md b/README.md index 552ff158..f3876df3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ The Python SDK for interacting with MultiversX. It's an all in one sdk that can be used to create transactions (including smart contract calls and deployments), sign and broadcast transactions, create wallets and many more. +## Documentation + +- [Cookbook](./examples/Cookbook.ipynb) +- [Auto-generated documentation](https://multiversx.github.io/mx-sdk-py-incubator/) + ## Development setup ### Virtual environment @@ -40,3 +45,14 @@ If you want to skip network interaction tests run: ``` pytest -m "not networkInteraction" ``` + +### Regenerating the docs + +Each time a new module/submodule is added it needs to be added to the docs, as well. To do so `cd` in the root directory then run the following command: +```bash +sphinx-apidoc -f -o docs/ multiversx_sdk/ *_test.py *constants.py +``` + +This command will regenerate the `.rst` files for each module, excluding the tests and the `constants.py` files. + +Also, each time a new version is released, the [**conf.py**](/docs/conf.py) file should be updated accordingly. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..12e12646 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,33 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +project = 'multiversx-sdk' +copyright = '2024, MultiversX' +author = 'MultiversX' +release = '0.9.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc"] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] +autoclass_content = 'both' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..f6751aa3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. multiversx-sdk documentation master file, created by + sphinx-quickstart on Wed Apr 3 14:19:32 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to multiversx-sdk's documentation! +========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modules + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 00000000..158a017c --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +multiversx_sdk +============== + +.. toctree:: + :maxdepth: 4 + + multiversx_sdk diff --git a/docs/multiversx_sdk.core.adapters.rst b/docs/multiversx_sdk.core.adapters.rst new file mode 100644 index 00000000..3ca21881 --- /dev/null +++ b/docs/multiversx_sdk.core.adapters.rst @@ -0,0 +1,21 @@ +multiversx\_sdk.core.adapters package +===================================== + +Submodules +---------- + +multiversx\_sdk.core.adapters.query\_runner\_adapter module +----------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.adapters.query_runner_adapter + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core.adapters + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.core.proto.rst b/docs/multiversx_sdk.core.proto.rst new file mode 100644 index 00000000..6544a8a1 --- /dev/null +++ b/docs/multiversx_sdk.core.proto.rst @@ -0,0 +1,29 @@ +multiversx\_sdk.core.proto package +================================== + +Submodules +---------- + +multiversx\_sdk.core.proto.transaction\_pb2 module +-------------------------------------------------- + +.. automodule:: multiversx_sdk.core.proto.transaction_pb2 + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.proto.transaction\_serializer module +--------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.proto.transaction_serializer + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core.proto + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.core.rst b/docs/multiversx_sdk.core.rst new file mode 100644 index 00000000..6fa2f124 --- /dev/null +++ b/docs/multiversx_sdk.core.rst @@ -0,0 +1,170 @@ +multiversx\_sdk.core package +============================ + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + multiversx_sdk.core.adapters + multiversx_sdk.core.proto + multiversx_sdk.core.transaction_builders + multiversx_sdk.core.transaction_parsers + multiversx_sdk.core.transactions_factories + multiversx_sdk.core.transactions_outcome_parsers + +Submodules +---------- + +multiversx\_sdk.core.account module +----------------------------------- + +.. automodule:: multiversx_sdk.core.account + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.address module +----------------------------------- + +.. automodule:: multiversx_sdk.core.address + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.bech32 module +---------------------------------- + +.. automodule:: multiversx_sdk.core.bech32 + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.code\_metadata module +------------------------------------------ + +.. automodule:: multiversx_sdk.core.code_metadata + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.codec module +--------------------------------- + +.. automodule:: multiversx_sdk.core.codec + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.contract\_query module +------------------------------------------- + +.. automodule:: multiversx_sdk.core.contract_query + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.contract\_query\_builder module +---------------------------------------------------- + +.. automodule:: multiversx_sdk.core.contract_query_builder + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.errors module +---------------------------------- + +.. automodule:: multiversx_sdk.core.errors + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.interfaces module +-------------------------------------- + +.. automodule:: multiversx_sdk.core.interfaces + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.message module +----------------------------------- + +.. automodule:: multiversx_sdk.core.message + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.serializer module +-------------------------------------- + +.. automodule:: multiversx_sdk.core.serializer + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.smart\_contract\_queries\_controller module +---------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.smart_contract_queries_controller + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.smart\_contract\_query module +-------------------------------------------------- + +.. automodule:: multiversx_sdk.core.smart_contract_query + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.token\_payment module +------------------------------------------ + +.. automodule:: multiversx_sdk.core.token_payment + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.tokens module +---------------------------------- + +.. automodule:: multiversx_sdk.core.tokens + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction module +--------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_payload module +------------------------------------------------ + +.. automodule:: multiversx_sdk.core.transaction_payload + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.typecheck module +------------------------------------- + +.. automodule:: multiversx_sdk.core.typecheck + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.core.transaction_builders.rst b/docs/multiversx_sdk.core.transaction_builders.rst new file mode 100644 index 00000000..023b1182 --- /dev/null +++ b/docs/multiversx_sdk.core.transaction_builders.rst @@ -0,0 +1,77 @@ +multiversx\_sdk.core.transaction\_builders package +================================================== + +Submodules +---------- + +multiversx\_sdk.core.transaction\_builders.contract\_builders module +-------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.contract_builders + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.default\_configuration module +------------------------------------------------------------------------ + +.. automodule:: multiversx_sdk.core.transaction_builders.default_configuration + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.esdt\_builders module +---------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.esdt_builders + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.other\_builders module +----------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.other_builders + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.relayed\_v1\_builder module +---------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.relayed_v1_builder + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.relayed\_v2\_builder module +---------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.relayed_v2_builder + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.transaction\_builder module +---------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.transaction_builder + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_builders.transfers\_builders module +--------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_builders.transfers_builders + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core.transaction_builders + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.core.transaction_parsers.rst b/docs/multiversx_sdk.core.transaction_parsers.rst new file mode 100644 index 00000000..7d627f5f --- /dev/null +++ b/docs/multiversx_sdk.core.transaction_parsers.rst @@ -0,0 +1,45 @@ +multiversx\_sdk.core.transaction\_parsers package +================================================= + +Submodules +---------- + +multiversx\_sdk.core.transaction\_parsers.interfaces module +----------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_parsers.interfaces + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_parsers.token\_operations\_outcome\_parser module +----------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_parsers.token_operations_outcome_parser + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_parsers.token\_operations\_outcome\_parser\_types module +------------------------------------------------------------------------------------------ + +.. automodule:: multiversx_sdk.core.transaction_parsers.token_operations_outcome_parser_types + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transaction\_parsers.transaction\_on\_network\_wrapper module +---------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transaction_parsers.transaction_on_network_wrapper + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core.transaction_parsers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.core.transactions_factories.rst b/docs/multiversx_sdk.core.transactions_factories.rst new file mode 100644 index 00000000..6d5b3ec8 --- /dev/null +++ b/docs/multiversx_sdk.core.transactions_factories.rst @@ -0,0 +1,85 @@ +multiversx\_sdk.core.transactions\_factories package +==================================================== + +Submodules +---------- + +multiversx\_sdk.core.transactions\_factories.account\_transactions\_factory module +---------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.account_transactions_factory + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.delegation\_transactions\_factory module +------------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.delegation_transactions_factory + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.relayed\_transactions\_factory module +---------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.relayed_transactions_factory + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.smart\_contract\_transactions\_factory module +------------------------------------------------------------------------------------------ + +.. automodule:: multiversx_sdk.core.transactions_factories.smart_contract_transactions_factory + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.token\_management\_transactions\_factory module +-------------------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.token_management_transactions_factory + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.token\_transfers\_data\_builder module +----------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.token_transfers_data_builder + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.transaction\_builder module +------------------------------------------------------------------------ + +.. automodule:: multiversx_sdk.core.transactions_factories.transaction_builder + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.transactions\_factory\_config module +--------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.transactions_factory_config + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_factories.transfer\_transactions\_factory module +----------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_factories.transfer_transactions_factory + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core.transactions_factories + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.core.transactions_outcome_parsers.rst b/docs/multiversx_sdk.core.transactions_outcome_parsers.rst new file mode 100644 index 00000000..397b957f --- /dev/null +++ b/docs/multiversx_sdk.core.transactions_outcome_parsers.rst @@ -0,0 +1,37 @@ +multiversx\_sdk.core.transactions\_outcome\_parsers package +=========================================================== + +Submodules +---------- + +multiversx\_sdk.core.transactions\_outcome\_parsers.resources module +-------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_outcome_parsers.resources + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_outcome\_parsers.token\_management\_transactions\_outcome\_parser module +----------------------------------------------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.core.transactions_outcome_parsers.token_management_transactions_outcome_parser + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.core.transactions\_outcome\_parsers.token\_management\_transactions\_outcome\_parser\_types module +------------------------------------------------------------------------------------------------------------------ + +.. automodule:: multiversx_sdk.core.transactions_outcome_parsers.token_management_transactions_outcome_parser_types + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.core.transactions_outcome_parsers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.network_providers.rst b/docs/multiversx_sdk.network_providers.rst new file mode 100644 index 00000000..3ecbf285 --- /dev/null +++ b/docs/multiversx_sdk.network_providers.rst @@ -0,0 +1,189 @@ +multiversx\_sdk.network\_providers package +========================================== + +Submodules +---------- + +multiversx\_sdk.network\_providers.accounts module +-------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.accounts + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.api\_network\_provider module +---------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.api_network_provider + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.config module +------------------------------------------------ + +.. automodule:: multiversx_sdk.network_providers.config + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.contract\_query\_requests module +------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.contract_query_requests + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.contract\_query\_response module +------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.contract_query_response + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.contract\_results module +----------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.contract_results + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.errors module +------------------------------------------------ + +.. automodule:: multiversx_sdk.network_providers.errors + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.interface module +--------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.interface + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.network\_config module +--------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.network_config + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.network\_general\_statistics module +---------------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.network_general_statistics + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.network\_stake module +-------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.network_stake + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.network\_status module +--------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.network_status + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.proxy\_network\_provider module +------------------------------------------------------------------ + +.. automodule:: multiversx_sdk.network_providers.proxy_network_provider + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.resources module +--------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.resources + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.token\_definitions module +------------------------------------------------------------ + +.. automodule:: multiversx_sdk.network_providers.token_definitions + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.tokens module +------------------------------------------------ + +.. automodule:: multiversx_sdk.network_providers.tokens + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.transaction\_events module +------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.transaction_events + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.transaction\_logs module +----------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.transaction_logs + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.transaction\_receipt module +-------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.transaction_receipt + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.transaction\_status module +------------------------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.transaction_status + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.transactions module +------------------------------------------------------ + +.. automodule:: multiversx_sdk.network_providers.transactions + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.network\_providers.utils module +----------------------------------------------- + +.. automodule:: multiversx_sdk.network_providers.utils + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.network_providers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.rst b/docs/multiversx_sdk.rst new file mode 100644 index 00000000..2a1d9894 --- /dev/null +++ b/docs/multiversx_sdk.rst @@ -0,0 +1,20 @@ +multiversx\_sdk package +======================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + multiversx_sdk.core + multiversx_sdk.network_providers + multiversx_sdk.wallet + +Module contents +--------------- + +.. automodule:: multiversx_sdk + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.wallet.crypto.rst b/docs/multiversx_sdk.wallet.crypto.rst new file mode 100644 index 00000000..2b5f54e7 --- /dev/null +++ b/docs/multiversx_sdk.wallet.crypto.rst @@ -0,0 +1,45 @@ +multiversx\_sdk.wallet.crypto package +===================================== + +Submodules +---------- + +multiversx\_sdk.wallet.crypto.decryptor module +---------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.crypto.decryptor + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.crypto.encrypted\_data module +---------------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.crypto.encrypted_data + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.crypto.encryptor module +---------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.crypto.encryptor + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.crypto.randomness module +----------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.crypto.randomness + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.wallet.crypto + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.wallet.libraries.rst b/docs/multiversx_sdk.wallet.libraries.rst new file mode 100644 index 00000000..fcdcee72 --- /dev/null +++ b/docs/multiversx_sdk.wallet.libraries.rst @@ -0,0 +1,29 @@ +multiversx\_sdk.wallet.libraries package +======================================== + +Submodules +---------- + +multiversx\_sdk.wallet.libraries.bls\_facade module +--------------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.libraries.bls_facade + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.libraries.libbls module +---------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.libraries.libbls + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.wallet.libraries + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/multiversx_sdk.wallet.rst b/docs/multiversx_sdk.wallet.rst new file mode 100644 index 00000000..81034b10 --- /dev/null +++ b/docs/multiversx_sdk.wallet.rst @@ -0,0 +1,134 @@ +multiversx\_sdk.wallet package +============================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + multiversx_sdk.wallet.crypto + multiversx_sdk.wallet.libraries + +Submodules +---------- + +multiversx\_sdk.wallet.core module +---------------------------------- + +.. automodule:: multiversx_sdk.wallet.core + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.errors module +------------------------------------ + +.. automodule:: multiversx_sdk.wallet.errors + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.interfaces module +---------------------------------------- + +.. automodule:: multiversx_sdk.wallet.interfaces + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.mnemonic module +-------------------------------------- + +.. automodule:: multiversx_sdk.wallet.mnemonic + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.pem\_entry module +---------------------------------------- + +.. automodule:: multiversx_sdk.wallet.pem_entry + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.user\_keys module +---------------------------------------- + +.. automodule:: multiversx_sdk.wallet.user_keys + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.user\_pem module +--------------------------------------- + +.. automodule:: multiversx_sdk.wallet.user_pem + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.user\_signer module +------------------------------------------ + +.. automodule:: multiversx_sdk.wallet.user_signer + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.user\_verifer module +------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.user_verifer + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.user\_wallet module +------------------------------------------ + +.. automodule:: multiversx_sdk.wallet.user_wallet + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.validator\_keys module +--------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.validator_keys + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.validator\_pem module +-------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.validator_pem + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.validator\_signer module +----------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.validator_signer + :members: + :undoc-members: + :show-inheritance: + +multiversx\_sdk.wallet.validator\_verifier module +------------------------------------------------- + +.. automodule:: multiversx_sdk.wallet.validator_verifier + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: multiversx_sdk.wallet + :members: + :undoc-members: + :show-inheritance: diff --git a/multiversx_sdk/core/account.py b/multiversx_sdk/core/account.py index 631c0e32..b0bb5faf 100644 --- a/multiversx_sdk/core/account.py +++ b/multiversx_sdk/core/account.py @@ -1,19 +1,22 @@ +class AccountNonceHolder(): + """An abstraction representing an account's nonce on the Network.""" -from multiversx_sdk.core.interfaces import INonce - + def __init__(self, initial_nonce: int = 0): + """Creates an acount nonce holder object from an initial nonce. -class AccountNonceHolder(): - """ - An abstraction representing an account (user or Smart Contract) on the Network. - """ + Args: + initial_nonce (int): the current nonce of the account""" + self.nonce = initial_nonce - def __init__(self, initial_nonce: INonce = 0): - self.nonce: INonce = initial_nonce + def get_nonce_then_increment(self) -> int: + """Returns the current nonce then increments it - def get_nonce_then_increment(self) -> INonce: + Returns: + int: the current nonce""" nonce = self.nonce self.increment_nonce() return nonce def increment_nonce(self): + """Increments the current nonce""" self.nonce += 1 diff --git a/multiversx_sdk/core/address.py b/multiversx_sdk/core/address.py index 48647eb1..4dfe8518 100644 --- a/multiversx_sdk/core/address.py +++ b/multiversx_sdk/core/address.py @@ -24,7 +24,14 @@ def get_hrp(self) -> str: class Address: + """An Address, as an immutable object.""" + def __init__(self, pubkey: bytes, hrp: str) -> None: + """Creates an address object, given a sequence of bytes and the human readable part(hrp). + + Args: + pubkey (bytes): the sequence of bytes\n + hrp (str): the human readable part""" if len(pubkey) != PUBKEY_LENGTH: raise ErrBadPubkeyLength(len(pubkey), PUBKEY_LENGTH) @@ -33,6 +40,10 @@ def __init__(self, pubkey: bytes, hrp: str) -> None: @classmethod def new_from_bech32(cls, value: str) -> 'Address': + """Creates an address object from the bech32 representation of an address. + + Args: + value (str): the bech32 address representation""" hrp, pubkey = _decode_bech32(value) return cls(pubkey, hrp) @@ -43,6 +54,11 @@ def from_bech32(cls, value: str) -> 'Address': @classmethod def new_from_hex(cls, value: str, hrp: str) -> 'Address': + """Creates an address object from the hexed sequence of bytes and the human readable part(hrp). + + Args: + value (str): the sequence of bytes as a hex string\n + hrp (str): the human readable part""" pubkey = bytes.fromhex(value) return cls(pubkey, hrp) @@ -52,6 +68,7 @@ def from_hex(cls, value: str, hrp: str) -> 'Address': return Address.new_from_hex(value, hrp) def to_hex(self) -> str: + """Returns the hex representation of the address (pubkey)""" return self.pubkey.hex() def hex(self) -> str: @@ -59,6 +76,7 @@ def hex(self) -> str: return self.to_hex() def to_bech32(self) -> str: + """Returns the bech32 representation of the address""" converted = bech32.convertbits(self.pubkey, 8, 5) assert converted is not None encoded = bech32.bech32_encode(self.hrp, converted) @@ -69,26 +87,37 @@ def bech32(self) -> str: return self.to_bech32() def get_public_key(self) -> bytes: + """Returns the pubkey as bytes""" return self.pubkey def get_hrp(self) -> str: + """Returns the human-readable-part of the bech32 address""" return self.hrp - def is_smart_contract(self): + def is_smart_contract(self) -> bool: + """Returns whether the address is a smart contract address""" return self.to_hex().startswith(SC_HEX_PUBKEY_PREFIX) # this will be removed in v1.0.0; it's here for compatibility reasons with the deprecated transaction builders # the transaction builders will also be removed in v1.0.0 def serialize(self) -> bytes: + """This method is deprecated and will soon be removed. Also displays a deprecation warning when used.""" logger.warning("The `serialize()` method is deprecated and will soon be removed") return self.get_public_key() class AddressFactory: + """A factory used to create address objects.""" + def __init__(self, hrp: str = DEFAULT_HRP) -> None: + """All the addresses created with the factory have the same human readable part + + Args: + hrp (str): the human readable part of the address (default: erd)""" self.hrp = hrp def create_from_bech32(self, value: str) -> Address: + """Creates an address object from the bech32 representation of an address""" hrp, pubkey = _decode_bech32(value) if hrp != self.hrp: raise ErrBadAddress(value) @@ -96,20 +125,35 @@ def create_from_bech32(self, value: str) -> Address: return Address(pubkey, hrp) def create_from_public_key(self, pubkey: bytes) -> Address: + """Creates an address object from the sequence of bytes""" return Address(pubkey, self.hrp) def create_from_hex(self, value: str) -> Address: + """Creates an address object from the hexed sequence of bytes""" return Address.new_from_hex(value, self.hrp) class AddressComputer: + """A class for computing contract addresses and getting shard numbers.""" + def __init__(self, number_of_shards: int = 3) -> None: + """Initializes the AddressComputer with the number of shards. + + Args: + number_of_shards (int): The number of shards in the network (default: 3).""" self.number_of_shards = number_of_shards def compute_contract_address(self, deployer: IAddress, deployment_nonce: int) -> Address: - """ - 8 bytes of zero + 2 bytes for VM type + 20 bytes of hash(owner) + 2 bytes of shard(owner) - """ + """Computes the contract address based on the deployer's address and deployment nonce. + + Args: + deployer (IAddress): The address of the deployer\n + deployment_nonce (int): The nonce of the deployment + + Returns: + Address: The computed contract address as below: + + 8 bytes of zero + 2 bytes for VM type + 20 bytes of hash(owner) + 2 bytes of shard(owner)""" deployer_pubkey = deployer.get_public_key() nonce_bytes = deployment_nonce.to_bytes(8, byteorder="little") bytes_to_hash = deployer_pubkey + nonce_bytes @@ -118,6 +162,13 @@ def compute_contract_address(self, deployer: IAddress, deployment_nonce: int) -> return Address(contract_pubkey, deployer.get_hrp()) def get_shard_of_address(self, address: IAddress) -> int: + """Returns the shard number of a given address. + + Args: + address (IAddress): The address for which to determine the shard. + + Returns: + int: The shard number.""" return get_shard_of_pubkey(address.get_public_key(), self.number_of_shards) diff --git a/pyproject.toml b/pyproject.toml index f4c0e8de..003a13a9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ allow-direct-references = true [project] name = "multiversx-sdk" -version = "0.1.0" +version = "0.9.0" authors = [ { name="MultiversX" }, ] @@ -36,5 +36,6 @@ exclude = [ ".github", "./examples", ".vscode", - "./multiversx_sdk/testutils/" + "./multiversx_sdk/testutils/", + "./docs" ] diff --git a/requirements-dev.txt b/requirements-dev.txt index 7f0fd9bf..494509ba 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -3,3 +3,5 @@ flake8 autopep8 pre-commit ipykernel +sphinx +sphinx-rtd-theme