Skip to content

Commit

Permalink
docs: documentation for initial stable release of `algorand-python-te…
Browse files Browse the repository at this point in the history 
…sting` (#8)

* docs: wip

* chore: refresh pyproject

* docs: refining docs (wip)

* chore: integrating doctests

* docs: revamping docs with latest features

* docs: minor consistency with main readme; patching doctests

* docs: removing the box from examples

* docs: refine op codes section

* chore: merge conflicts

* chore: apply suggestions from code review

Co-authored-by: Daniel McGregor <[email protected]>

* docs: addressing docs pr comments

---------

Co-authored-by: Daniel McGregor <[email protected]>
  • Loading branch information
@aorumbayev @daniel-makerx
aorumbayev and daniel-makerx authored Aug 21, 2024
1 parent 4e7368c commit 9d97d0d
Show file tree
Hide file tree
Showing 27 changed files with 1,924 additions and 409 deletions.
11 changes: 9 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,15 @@ Alternatively, if you want to start from scratch:
from your_contract import YourContract
def test_your_contract():
with algopy_testing_context() as ctx:
contract = YourContract() # Your test code here
# Arrange
contract = YourContract()
expected_result = ... # Your expected result here
# Act
result = contract.your_method() # Your test code here
# Assert
assert result == expected_result
```

5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)
Expand Down
Empty file added docs/__init__.py
View file
Empty file.
3 changes: 2 additions & 1 deletion docs/_static/custom.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
Hide the first element of attribute like items as algopy stubs are more like interfaces and as such
should not indicate a specific "value" for variables
*/
.py.data,.py.attribute {
.py.data,
.py.attribute {
dd p:first-child {
display: none;
}
Expand Down
9 changes: 9 additions & 0 deletions docs/algopy.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Algorand Python

Algorand Python is a partial implementation of the Python programming language that runs on the AVM. It includes a statically typed framework for development of Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality that works with standard Python tooling.

Algorand Python is compiled for execution on the AVM by PuyaPy, an optimising compiler that ensures the resulting AVM bytecode execution semantics that match the given Python code. PuyaPy produces output that is directly compatible with [AlgoKit typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to make deployment and calling easy.

## Quick start

To get started refer to the [official documentation](https://algorandfoundation.github.io/puya).
14 changes: 14 additions & 0 deletions docs/api.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# API Reference

```{autodoc2-summary}
:renderer: myst
algopy_testing.AlgopyTestContext
algopy_testing.LedgerContext
algopy_testing.TransactionContext
algopy_testing.AVMValueGenerator
algopy_testing.TxnValueGenerator
algopy_testing.ARC4ValueGenerator
```

> TODO: 1.0 Restructure algopy_testing index file once refactoring changes are merged
32 changes: 28 additions & 4 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
copyright = "2024, Algorand Foundation" # noqa: A001
author = "Algorand Foundation"


# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

Expand All @@ -19,6 +20,9 @@
"sphinx.ext.intersphinx",
"sphinx_copybutton",
"myst_parser",
"autodoc2",
"sphinx.ext.doctest",
"sphinxmermaid",
]

templates_path = ["_templates"]
Expand All @@ -42,7 +46,6 @@

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "furo"
html_static_path = ["_static"]
html_css_files = [
Expand All @@ -52,7 +55,28 @@
python_maximum_signature_line_length = 80

# -- Options for myst ---
myst_enable_extensions = [
"colon_fence",
"fieldlist",
myst_enable_extensions = ["colon_fence", "fieldlist"]

# -- Options for autodoc2
autodoc2_packages = [
{
"path": "../src/algopy_testing",
"auto_mode": False,
},
]
autodoc2_render_plugin = "myst"
autodoc2_hidden_objects = [
"dunder",
"private",
"undoc",
]
add_module_names = False
autodoc2_index_template = None

# -- Options for doctest --
doctest_test_doctest_blocks = "default"

# -- Options for mermaid --
sphinxmermaid_mermaid_init = {
"theme": "dark",
}
195 changes: 157 additions & 38 deletions docs/coverage.md
View file
Original file line number Diff line number Diff line change
@@ -1,43 +1,162 @@
# Coverage

See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. There are 3 general categories:
See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. See the [Concepts](testing-guide/concepts.md#types-of-algopy-stub-implementations) section for more details on the implementation categories.

1. **Implemented**: Full native Python equivalent matching AVM computation. For example, `algopy.op.sha256` and other cryptographic operations behave identically in AVM and unit tests written with this library.
Based on the definitions provided and the implementation details in the `src` directory, here is the classification for the abstractions outlined in the table under the `Name` column:

2. **Emulated**: Implemented with the aid of the `AlgopyTestContext` manager, which mimics major AVM behavior to allow this abstraction to function as expected in a test context. For example, when you call `Box.put` on an `algopy.Box` object within a test context, it won't interact with the real Algorand network. Instead, it will store the data in the test context manager behind the scenes, while still providing the same interface as the real `Box` class.
| Name | Implementation type |
| ------------------------------------------- | ------------------- |
| algopy.Account | Emulated |
| algopy.Application | Emulated |
| algopy.Asset | Emulated |
| algopy.BigUInt | Native |
| algopy.Box | Emulated |
| algopy.BoxMap | Emulated |
| algopy.BoxRef | Emulated |
| algopy.Bytes | Native |
| algopy.BytesBacked | Native |
| algopy.CompiledContract | Mockable |
| algopy.CompiledLogicSig | Mockable |
| algopy.Contract | Emulated |
| algopy.Global | Emulated |
| algopy.GlobalState | Emulated |
| algopy.LocalState | Emulated |
| algopy.LogicSig | Emulated |
| algopy.OnCompleteAction | Native |
| algopy.OpUpFeeSource | Native |
| algopy.StateTotals | Emulated |
| algopy.String | Native |
| algopy.TemplateVar | Emulated |
| algopy.TransactionType | Native |
| algopy.Txn | Emulated |
| algopy.UInt64 | Native |
| algopy.compile_contract | Mockable |
| algopy.compile_logicsig | Mockable |
| algopy.ensure_budget | Emulated |
| algopy.log | Emulated |
| algopy.logicsig | Emulated |
| algopy.subroutine | Native |
| algopy.uenumerate | Native |
| algopy.urange | Native |
| algopy.arc4.ARC4Client | Emulated |
| algopy.arc4.ARC4Contract | Emulated |
| algopy.arc4.Address | Native |
| algopy.arc4.BigUFixedNxM | Native |
| algopy.arc4.BigUIntN | Native |
| algopy.arc4.Bool | Native |
| algopy.arc4.Byte | Native |
| algopy.arc4.DynamicArray | Native |
| algopy.arc4.DynamicBytes | Native |
| algopy.arc4.StaticArray | Native |
| algopy.arc4.String | Native |
| algopy.arc4.Struct | Native |
| algopy.arc4.Tuple | Native |
| algopy.arc4.UFixedNxM | Native |
| algopy.arc4.UInt128 | Native |
| algopy.arc4.UInt16 | Native |
| algopy.arc4.UInt256 | Native |
| algopy.arc4.UInt32 | Native |
| algopy.arc4.UInt512 | Native |
| algopy.arc4.UInt64 | Native |
| algopy.arc4.UInt8 | Native |
| algopy.arc4.UIntN | Native |
| algopy.arc4.abimethod | Emulated |
| algopy.arc4.arc4_signature | Native |
| algopy.arc4.baremethod | Emulated |
| algopy.arc4.emit | Emulated |
| algopy.arc4.abi_call | Mockable |
| algopy.arc4.arc4_create | Mockable |
| algopy.arc4.arc4_update | Mockable |
| algopy.gtxn.ApplicationCallTransaction | Emulated |
| algopy.gtxn.AssetConfigTransaction | Emulated |
| algopy.gtxn.AssetFreezeTransaction | Emulated |
| algopy.gtxn.AssetTransferTransaction | Emulated |
| algopy.gtxn.KeyRegistrationTransaction | Emulated |
| algopy.gtxn.PaymentTransaction | Emulated |
| algopy.gtxn.Transaction | Emulated |
| algopy.gtxn.TransactionBase | Emulated |
| algopy.itxn.ApplicationCall | Emulated |
| algopy.itxn.ApplicationCallInnerTransaction | Emulated |
| algopy.itxn.AssetConfig | Emulated |
| algopy.itxn.AssetConfigInnerTransaction | Emulated |
| algopy.itxn.AssetFreeze | Emulated |
| algopy.itxn.AssetFreezeInnerTransaction | Emulated |
| algopy.itxn.AssetTransfer | Emulated |
| algopy.itxn.AssetTransferInnerTransaction | Emulated |
| algopy.itxn.InnerTransaction | Emulated |
| algopy.itxn.InnerTransactionResult | Emulated |
| algopy.itxn.KeyRegistration | Emulated |
| algopy.itxn.KeyRegistrationInnerTransaction | Emulated |
| algopy.itxn.Payment | Emulated |
| algopy.itxn.PaymentInnerTransaction | Emulated |
| algopy.itxn.submit_txns | Emulated |
| algopy.op.Base64 | Native |
| algopy.op.EC | Native |
| algopy.op.ECDSA | Native |
| algopy.op.JsonRef | Native |
| algopy.op.addw | Native |
| algopy.op.arg | Emulated |
| algopy.op.base64_decode | Native |
| algopy.op.bitlen | Native |
| algopy.op.bsqrt | Native |
| algopy.op.btoi | Native |
| algopy.op.bzero | Native |
| algopy.op.concat | Native |
| algopy.op.divmodw | Native |
| algopy.op.divw | Native |
| algopy.op.ecdsa_pk_decompress | Native |
| algopy.op.ecdsa_pk_recover | Native |
| algopy.op.ecdsa_verify | Native |
| algopy.op.ed25519verify | Native |
| algopy.op.ed25519verify_bare | Native |
| algopy.op.err | Native |
| algopy.op.exit | Native |
| algopy.op.exp | Native |
| algopy.op.expw | Native |
| algopy.op.extract | Native |
| algopy.op.extract_uint16 | Native |
| algopy.op.extract_uint32 | Native |
| algopy.op.extract_uint64 | Native |
| algopy.op.getbit | Native |
| algopy.op.getbyte | Native |
| algopy.op.itob | Native |
| algopy.op.keccak256 | Native |
| algopy.op.mulw | Native |
| algopy.op.replace | Native |
| algopy.op.select_bytes | Native |
| algopy.op.select_uint64 | Native |
| algopy.op.setbit_bytes | Native |
| algopy.op.setbit_uint64 | Native |
| algopy.op.setbyte | Native |
| algopy.op.sha256 | Native |
| algopy.op.sha3_256 | Native |
| algopy.op.sha512_256 | Native |
| algopy.op.shl | Native |
| algopy.op.shr | Native |
| algopy.op.sqrt | Native |
| algopy.op.substring | Native |
| algopy.op.AppGlobal | Emulated |
| algopy.op.AppLocal | Emulated |
| algopy.op.AppParamsGet | Emulated |
| algopy.op.AssetHoldingGet | Emulated |
| algopy.op.AssetParamsGet | Emulated |
| algopy.op.Block | Emulated |
| algopy.op.Box | Emulated |
| algopy.op.GITxn | Emulated |
| algopy.op.GTxn | Emulated |
| algopy.op.Global | Emulated |
| algopy.op.ITxn | Emulated |
| algopy.op.ITxnCreate | Emulated |
| algopy.op.Scratch | Emulated |
| algopy.op.Txn | Emulated |
| algopy.op.app_opted_in | Emulated |
| algopy.op.balance | Emulated |
| algopy.op.gaid | Emulated |
| algopy.op.gload_bytes | Emulated |
| algopy.op.gload_uint64 | Emulated |
| algopy.op.min_balance | Emulated |
| algopy.op.AcctParamsGet | Emulated |
| algopy.op.EllipticCurve | Mockable |
| algopy.op.VrfVerify | Mockable |
| algopy.op.vrf_verify | Mockable |

3. **Mockable**: No implementation provided, but can be easily mocked or patched to inject intended behavior. For example, `algopy.abi_call` can be mocked to return or act as needed; otherwise, it will raise a "not implemented" exception. Mockable types are exceptional cases where behavior or functionality does not make sense within a unit testing context or would require an unnecessary amount of complexity without significant benefit to the end user (a developer writing offline unit tests).

> Note, below table not exhaustive yet, but will be expanded along with initial stable release.
| Name | Implementation Status |
| ------------------------------------------------------------ | --------------------- |
| Primitives (UInt64, BigUInt, Bytes, String) | Implemented |
| urange | Implemented |
| All crypto ops in op.\* namespace (to be expanded in detail) | Implemented |
| arc4.\* namespace (to be expanded in detail) | Implemented |
| uenumerate | Implemented |
| StateTotals | Implemented |
| Txn, GTxn, ITxn | Emulated |
| Asset | Emulated |
| Account | Emulated |
| Application | Emulated |
| subroutine | Emulated |
| Global | Emulated |
| op.Box.\* | Emulated |
| Box | Emulated |
| BoxRef | Emulated |
| BoxMap | Emulated |
| Block | Emulated |
| logicsig | Emulated |
| log | Emulated |
| itxn.\* namespace (inner transactions) | Emulated |
| gtxn.\* namespace (group transactions) | Emulated |
| op.ITxnCreate | Emulated |
| ensure_budget | Mockable |
| op.EllipticCurve | Mockable |
| op.AssetParamsGet | Emulated |
| op.AppParamsGet | Emulated |
| op.AppLocal | Emulated |
| op.AppGlobal | Emulated |
| op.AcctParamsGet | Emulated |
Loading

0 comments on commit 9d97d0d

Please sign in to comment.