Skip to content

Commit 9d97d0d

Browse files
aorumbayevdaniel-makerx
aorumbayev
and
daniel-makerx
authored
docs: documentation for initial stable release of algorand-python-testing (#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 <daniel.mcgregor@makerx.com.au> * docs: addressing docs pr comments --------- Co-authored-by: Daniel McGregor <daniel.mcgregor@makerx.com.au>
1 parent 4e7368c commit 9d97d0d

27 files changed

+1924
-409
lines changed

‎README.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,15 @@ Alternatively, if you want to start from scratch:
3434
from your_contract import YourContract
3535
3636
def test_your_contract():
37-
with algopy_testing_context() as ctx:
38-
contract = YourContract() # Your test code here
37+
# Arrange
38+
contract = YourContract()
39+
expected_result = ... # Your expected result here
40+
41+
# Act
42+
result = contract.your_method() # Your test code here
43+
44+
# Assert
45+
assert result == expected_result
3946
```
4047

4148
5. Run your tests using your preferred Python testing framework (e.g., pytest, unittest)

‎docs/__init__.py‎

Whitespace-only changes.

‎docs/_static/custom.css‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
Hide the first element of attribute like items as algopy stubs are more like interfaces and as such
33
should not indicate a specific "value" for variables
44
*/
5-
.py.data,.py.attribute {
5+
.py.data,
6+
.py.attribute {
67
dd p:first-child {
78
display: none;
89
}

‎docs/algopy.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Algorand Python
2+
3+
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.
4+
5+
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.
6+
7+
## Quick start
8+
9+
To get started refer to the [official documentation](https://algorandfoundation.github.io/puya).

‎docs/api.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# API Reference
2+
3+
```{autodoc2-summary}
4+
:renderer: myst
5+
6+
algopy_testing.AlgopyTestContext
7+
algopy_testing.LedgerContext
8+
algopy_testing.TransactionContext
9+
algopy_testing.AVMValueGenerator
10+
algopy_testing.TxnValueGenerator
11+
algopy_testing.ARC4ValueGenerator
12+
```
13+
14+
> TODO: 1.0 Restructure algopy_testing index file once refactoring changes are merged

‎docs/conf.py‎

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
copyright = "2024, Algorand Foundation" # noqa: A001
1212
author = "Algorand Foundation"
1313

14+
1415
# -- General configuration ---------------------------------------------------
1516
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
1617

@@ -19,6 +20,9 @@
1920
"sphinx.ext.intersphinx",
2021
"sphinx_copybutton",
2122
"myst_parser",
23+
"autodoc2",
24+
"sphinx.ext.doctest",
25+
"sphinxmermaid",
2226
]
2327

2428
templates_path = ["_templates"]
@@ -42,7 +46,6 @@
4246

4347
# -- Options for HTML output -------------------------------------------------
4448
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
45-
4649
html_theme = "furo"
4750
html_static_path = ["_static"]
4851
html_css_files = [
@@ -52,7 +55,28 @@
5255
python_maximum_signature_line_length = 80
5356

5457
# -- Options for myst ---
55-
myst_enable_extensions = [
56-
"colon_fence",
57-
"fieldlist",
58+
myst_enable_extensions = ["colon_fence", "fieldlist"]
59+
60+
# -- Options for autodoc2
61+
autodoc2_packages = [
62+
{
63+
"path": "../src/algopy_testing",
64+
"auto_mode": False,
65+
},
66+
]
67+
autodoc2_render_plugin = "myst"
68+
autodoc2_hidden_objects = [
69+
"dunder",
70+
"private",
71+
"undoc",
5872
]
73+
add_module_names = False
74+
autodoc2_index_template = None
75+
76+
# -- Options for doctest --
77+
doctest_test_doctest_blocks = "default"
78+
79+
# -- Options for mermaid --
80+
sphinxmermaid_mermaid_init = {
81+
"theme": "dark",
82+
}

‎docs/coverage.md‎

Lines changed: 157 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,162 @@
11
# Coverage
22

3-
See which `algorand-python` stubs are implemented by the `algorand-python-testing` library. There are 3 general categories:
3+
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.
44

5-
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.
5+
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:
66

7-
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.
7+
| Name | Implementation type |
8+
| ------------------------------------------- | ------------------- |
9+
| algopy.Account | Emulated |
10+
| algopy.Application | Emulated |
11+
| algopy.Asset | Emulated |
12+
| algopy.BigUInt | Native |
13+
| algopy.Box | Emulated |
14+
| algopy.BoxMap | Emulated |
15+
| algopy.BoxRef | Emulated |
16+
| algopy.Bytes | Native |
17+
| algopy.BytesBacked | Native |
18+
| algopy.CompiledContract | Mockable |
19+
| algopy.CompiledLogicSig | Mockable |
20+
| algopy.Contract | Emulated |
21+
| algopy.Global | Emulated |
22+
| algopy.GlobalState | Emulated |
23+
| algopy.LocalState | Emulated |
24+
| algopy.LogicSig | Emulated |
25+
| algopy.OnCompleteAction | Native |
26+
| algopy.OpUpFeeSource | Native |
27+
| algopy.StateTotals | Emulated |
28+
| algopy.String | Native |
29+
| algopy.TemplateVar | Emulated |
30+
| algopy.TransactionType | Native |
31+
| algopy.Txn | Emulated |
32+
| algopy.UInt64 | Native |
33+
| algopy.compile_contract | Mockable |
34+
| algopy.compile_logicsig | Mockable |
35+
| algopy.ensure_budget | Emulated |
36+
| algopy.log | Emulated |
37+
| algopy.logicsig | Emulated |
38+
| algopy.subroutine | Native |
39+
| algopy.uenumerate | Native |
40+
| algopy.urange | Native |
41+
| algopy.arc4.ARC4Client | Emulated |
42+
| algopy.arc4.ARC4Contract | Emulated |
43+
| algopy.arc4.Address | Native |
44+
| algopy.arc4.BigUFixedNxM | Native |
45+
| algopy.arc4.BigUIntN | Native |
46+
| algopy.arc4.Bool | Native |
47+
| algopy.arc4.Byte | Native |
48+
| algopy.arc4.DynamicArray | Native |
49+
| algopy.arc4.DynamicBytes | Native |
50+
| algopy.arc4.StaticArray | Native |
51+
| algopy.arc4.String | Native |
52+
| algopy.arc4.Struct | Native |
53+
| algopy.arc4.Tuple | Native |
54+
| algopy.arc4.UFixedNxM | Native |
55+
| algopy.arc4.UInt128 | Native |
56+
| algopy.arc4.UInt16 | Native |
57+
| algopy.arc4.UInt256 | Native |
58+
| algopy.arc4.UInt32 | Native |
59+
| algopy.arc4.UInt512 | Native |
60+
| algopy.arc4.UInt64 | Native |
61+
| algopy.arc4.UInt8 | Native |
62+
| algopy.arc4.UIntN | Native |
63+
| algopy.arc4.abimethod | Emulated |
64+
| algopy.arc4.arc4_signature | Native |
65+
| algopy.arc4.baremethod | Emulated |
66+
| algopy.arc4.emit | Emulated |
67+
| algopy.arc4.abi_call | Mockable |
68+
| algopy.arc4.arc4_create | Mockable |
69+
| algopy.arc4.arc4_update | Mockable |
70+
| algopy.gtxn.ApplicationCallTransaction | Emulated |
71+
| algopy.gtxn.AssetConfigTransaction | Emulated |
72+
| algopy.gtxn.AssetFreezeTransaction | Emulated |
73+
| algopy.gtxn.AssetTransferTransaction | Emulated |
74+
| algopy.gtxn.KeyRegistrationTransaction | Emulated |
75+
| algopy.gtxn.PaymentTransaction | Emulated |
76+
| algopy.gtxn.Transaction | Emulated |
77+
| algopy.gtxn.TransactionBase | Emulated |
78+
| algopy.itxn.ApplicationCall | Emulated |
79+
| algopy.itxn.ApplicationCallInnerTransaction | Emulated |
80+
| algopy.itxn.AssetConfig | Emulated |
81+
| algopy.itxn.AssetConfigInnerTransaction | Emulated |
82+
| algopy.itxn.AssetFreeze | Emulated |
83+
| algopy.itxn.AssetFreezeInnerTransaction | Emulated |
84+
| algopy.itxn.AssetTransfer | Emulated |
85+
| algopy.itxn.AssetTransferInnerTransaction | Emulated |
86+
| algopy.itxn.InnerTransaction | Emulated |
87+
| algopy.itxn.InnerTransactionResult | Emulated |
88+
| algopy.itxn.KeyRegistration | Emulated |
89+
| algopy.itxn.KeyRegistrationInnerTransaction | Emulated |
90+
| algopy.itxn.Payment | Emulated |
91+
| algopy.itxn.PaymentInnerTransaction | Emulated |
92+
| algopy.itxn.submit_txns | Emulated |
93+
| algopy.op.Base64 | Native |
94+
| algopy.op.EC | Native |
95+
| algopy.op.ECDSA | Native |
96+
| algopy.op.JsonRef | Native |
97+
| algopy.op.addw | Native |
98+
| algopy.op.arg | Emulated |
99+
| algopy.op.base64_decode | Native |
100+
| algopy.op.bitlen | Native |
101+
| algopy.op.bsqrt | Native |
102+
| algopy.op.btoi | Native |
103+
| algopy.op.bzero | Native |
104+
| algopy.op.concat | Native |
105+
| algopy.op.divmodw | Native |
106+
| algopy.op.divw | Native |
107+
| algopy.op.ecdsa_pk_decompress | Native |
108+
| algopy.op.ecdsa_pk_recover | Native |
109+
| algopy.op.ecdsa_verify | Native |
110+
| algopy.op.ed25519verify | Native |
111+
| algopy.op.ed25519verify_bare | Native |
112+
| algopy.op.err | Native |
113+
| algopy.op.exit | Native |
114+
| algopy.op.exp | Native |
115+
| algopy.op.expw | Native |
116+
| algopy.op.extract | Native |
117+
| algopy.op.extract_uint16 | Native |
118+
| algopy.op.extract_uint32 | Native |
119+
| algopy.op.extract_uint64 | Native |
120+
| algopy.op.getbit | Native |
121+
| algopy.op.getbyte | Native |
122+
| algopy.op.itob | Native |
123+
| algopy.op.keccak256 | Native |
124+
| algopy.op.mulw | Native |
125+
| algopy.op.replace | Native |
126+
| algopy.op.select_bytes | Native |
127+
| algopy.op.select_uint64 | Native |
128+
| algopy.op.setbit_bytes | Native |
129+
| algopy.op.setbit_uint64 | Native |
130+
| algopy.op.setbyte | Native |
131+
| algopy.op.sha256 | Native |
132+
| algopy.op.sha3_256 | Native |
133+
| algopy.op.sha512_256 | Native |
134+
| algopy.op.shl | Native |
135+
| algopy.op.shr | Native |
136+
| algopy.op.sqrt | Native |
137+
| algopy.op.substring | Native |
138+
| algopy.op.AppGlobal | Emulated |
139+
| algopy.op.AppLocal | Emulated |
140+
| algopy.op.AppParamsGet | Emulated |
141+
| algopy.op.AssetHoldingGet | Emulated |
142+
| algopy.op.AssetParamsGet | Emulated |
143+
| algopy.op.Block | Emulated |
144+
| algopy.op.Box | Emulated |
145+
| algopy.op.GITxn | Emulated |
146+
| algopy.op.GTxn | Emulated |
147+
| algopy.op.Global | Emulated |
148+
| algopy.op.ITxn | Emulated |
149+
| algopy.op.ITxnCreate | Emulated |
150+
| algopy.op.Scratch | Emulated |
151+
| algopy.op.Txn | Emulated |
152+
| algopy.op.app_opted_in | Emulated |
153+
| algopy.op.balance | Emulated |
154+
| algopy.op.gaid | Emulated |
155+
| algopy.op.gload_bytes | Emulated |
156+
| algopy.op.gload_uint64 | Emulated |
157+
| algopy.op.min_balance | Emulated |
158+
| algopy.op.AcctParamsGet | Emulated |
159+
| algopy.op.EllipticCurve | Mockable |
160+
| algopy.op.VrfVerify | Mockable |
161+
| algopy.op.vrf_verify | Mockable |
8162

9-
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).
10-
11-
> Note, below table not exhaustive yet, but will be expanded along with initial stable release.
12-
13-
| Name | Implementation Status |
14-
| ------------------------------------------------------------ | --------------------- |
15-
| Primitives (UInt64, BigUInt, Bytes, String) | Implemented |
16-
| urange | Implemented |
17-
| All crypto ops in op.\* namespace (to be expanded in detail) | Implemented |
18-
| arc4.\* namespace (to be expanded in detail) | Implemented |
19-
| uenumerate | Implemented |
20-
| StateTotals | Implemented |
21-
| Txn, GTxn, ITxn | Emulated |
22-
| Asset | Emulated |
23-
| Account | Emulated |
24-
| Application | Emulated |
25-
| subroutine | Emulated |
26-
| Global | Emulated |
27-
| op.Box.\* | Emulated |
28-
| Box | Emulated |
29-
| BoxRef | Emulated |
30-
| BoxMap | Emulated |
31-
| Block | Emulated |
32-
| logicsig | Emulated |
33-
| log | Emulated |
34-
| itxn.\* namespace (inner transactions) | Emulated |
35-
| gtxn.\* namespace (group transactions) | Emulated |
36-
| op.ITxnCreate | Emulated |
37-
| ensure_budget | Mockable |
38-
| op.EllipticCurve | Mockable |
39-
| op.AssetParamsGet | Emulated |
40-
| op.AppParamsGet | Emulated |
41-
| op.AppLocal | Emulated |
42-
| op.AppGlobal | Emulated |
43-
| op.AcctParamsGet | Emulated |

0 commit comments

Comments
 (0)