Skip to content

Commit

Permalink
docs: revamping docs with latest features
Browse files Browse the repository at this point in the history
  • Loading branch information
@aorumbayev
aorumbayev committed Aug 20, 2024
1 parent 1e71d5b commit 5f131ec
Show file tree
Hide file tree
Showing 19 changed files with 953 additions and 681 deletions.
2 changes: 0 additions & 2 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,3 @@ examples/**/*.trace
# coverage output
.coverage
coverage.xml

docs/jupyter_execute/
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).
15 changes: 10 additions & 5 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,9 @@
"sphinx.ext.intersphinx",
"sphinx_copybutton",
"myst_parser",
"autodoc2", # Add this line
"autodoc2",
"sphinx.ext.doctest",
"sphinxmermaid",
]

templates_path = ["_templates"]
Expand All @@ -45,24 +46,22 @@

# -- 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 = [
"custom.css",
]
html_js_files = ["https://unpkg.com/thebe@latest/lib/index.js"]

python_maximum_signature_line_length = 80

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

# Add autodoc2 configuration
# -- Options for autodoc2
autodoc2_packages = [
{
"path": "../src/algopy_testing",
"auto_mode": True,
"auto_mode": False,
},
]
autodoc2_render_plugin = "myst"
Expand All @@ -74,10 +73,16 @@
add_module_names = False
autodoc2_index_template = None

# -- Options for doctest --
doctest_global_setup = """
import algopy
from algopy import arc4
import algopy_testing
from algopy_testing import AlgopyTestContext, algopy_testing_context
"""
doctest_test_doctest_blocks = "default"

# -- Options for mermaid --
sphinxmermaid_mermaid_init = {
"theme": "dark",
}
292 changes: 146 additions & 146 deletions docs/coverage.md
View file

Large diffs are not rendered by default.

17 changes: 10 additions & 7 deletions docs/examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,13 @@

Below is a showcase of various examples of unit testing real and sample Algorand Python smart contracts using `algorand-python-testing`.

| Contract Name | Test File | Key Features Demonstrated | Test versions of Algopy Abstractions used |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Auction | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/auction/test_contract.py) | - Use of algopy_testing_context<br>- Mocking of global state and transaction fields<br>- Testing of ARC4 contract methods<br>- Emulation of asset creation and transfers<br>- Verification of inner transactions | - **ARC4Contract**<br>- **Global**<br>- **Txn**<br>- **Asset**<br>- **Account** |
| Proof of Attendance | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/proof_of_attendance/test_contract.py) | - Creation and management of dummy assets<br>- Testing of box storage operations<br>- Verification of inner transactions for asset transfers<br>- Use of any\_\* methods for generating test data | - **Contract**<br>- **Box**<br>- **Asset**<br>- **Account**<br>- **op** (for various operations) |
| Simple Voting | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/simple_voting/test_contract.py) | - Testing of global and local state operations<br>- Verification of transaction group operations<br>- Mocking of payment transactions | - **Contract**<br>- **GlobalState**<br>- **LocalState**<br>- **Txn**<br>- **GTxn** (group transactions) |
| ZK Whitelist | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/zk_whitelist/test_contract.py) | - Testing of zero-knowledge proof verification<br>- Mocking of external application calls<br>- Use of ARC4 types and methods | - **ARC4Contract**<br>- **arc4 types** (Address, DynamicArray, StaticArray, etc.)<br>- Application logs |
| HTLC LogicSig | [test_signature.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/htlc_logicsig/test_signature.py) | - Testing of LogicSig contracts<br>- Verification of time-based conditions<br>- Mocking of transaction parameters | - **LogicSig**<br>- **Txn**<br>- **Global** |
| Contract Name | Test File | Key Features Demonstrated | Test versions of Algopy Abstractions used |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Auction | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/auction/test_contract.py) | - Use of algopy_testing_context<br>- Mocking of global state and transaction fields<br>- Testing of ARC4 contract methods<br>- Emulation of asset creation and transfers<br>- Verification of inner transactions | - **ARC4Contract**<br>- **Global**<br>- **Txn**<br>- **Asset**<br>- **Account**<br>- **LocalState** |
| Proof of Attendance | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/proof_of_attendance/test_contract.py) | - Creation and management of dummy assets<br>- Testing of box storage operations<br>- Verification of inner transactions for asset transfers<br>- Use of any\_\* methods for generating test data | - **ARC4Contract**<br>- **Box**<br>- **BoxMap**<br>- **Asset**<br>- **Account**<br>- **op** |
| Simple Voting | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/simple_voting/test_contract.py) | - Testing of global and local state operations<br>- Verification of transaction group operations<br>- Mocking of payment transactions | - **Contract**<br>- **GlobalState**<br>- **LocalState**<br>- **Txn**<br>- **op.GTxn** |
| ZK Whitelist | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/zk_whitelist/test_contract.py) | - Testing of zero-knowledge proof verification<br>- Mocking of external application calls<br>- Use of ARC4 types and methods | - **ARC4Contract**<br>- **arc4 types**<br>- **LocalState**<br>- **Global**<br>- **Txn** |
| HTLC LogicSig | [test_signature.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/htlc_logicsig/test_signature.py) | - Testing of LogicSig contracts<br>- Verification of time-based conditions<br>- Mocking of transaction parameters | - **logicsig**<br>- **Account**<br>- **Txn**<br>- **Global**<br>- **op** |
| Box | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/box/test_contract.py) | - Testing of box storage operations<br>- Use of enums in box storage | - **ARC4Contract**<br>- **Box**<br>- **op** |
| Marketplace | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/marketplace/test_contract.py) | - Testing of complex marketplace operations<br>- Use of BoxMap for listings<br>- Testing of asset transfers and payments | - **ARC4Contract**<br>- **BoxMap**<br>- **Asset**<br>- **arc4 types**<br>- **Global**<br>- **Txn** |
| Scratch Storage | [test_contract.py](https://github.com/algorandfoundation/algorand-python-testing/blob/main/examples/scratch_storage/test_contract.py) | - Testing of scratch space usage<br>- Verification of scratch slot values | - **ARC4Contract**<br>- **Contract**<br>- **op** |
1 change: 1 addition & 0 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -173,4 +173,5 @@ examples
coverage
glossary
api
algopy
```
61 changes: 39 additions & 22 deletions docs/testing-guide/arc4-types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,27 @@
These types are available under the `algopy.arc4` namespace. Refer to the [ARC4 specification](https://arc.algorand.foundation/ARCs/arc-0004) for more details on the spec.

```{hint}
Test context manager provides _value generators_ for ARC4 types. To access those, use `{context_instance}.arc4` property. See more examples below.
Test context manager provides _value generators_ for ARC4 types. To access their _value generators_, use `{context_instance}.any.arc4` property. See more examples below.
```

```{note}
For all `algopy.arc4` types with and without respective _value generator_, instantiation can be performed directly. If you have a suggestion for a new _value generator_ implementation, please open an issue in the [`algorand-python-testing`](https://github.com/algorand-sdk/algorand-python-testing) repository or contribute by following the [contribution guide](https://github.com/algorand-sdk/algorand-python-testing/blob/main/CONTRIBUTING.md).
For all `algopy.arc4` types with and without respective _value generator_, instantiation can be performed directly. If you have a suggestion for a new _value generator_ implementation, please open an issue in the [`algorand-python-testing`](https://github.com/algorandfoundation/algorand-python-testing) repository or contribute by following the [contribution guide](https://github.com/algorandfoundation/algorand-python-testing/blob/main/CONTRIBUTING.md).
```

```{testsetup}
import algopy
import algopy_testing
# Create the context manager for snippets below
ctx_manager = algopy_testing_context()
# Enter the context
ctx = ctx_manager.__enter__()
```

## Unsigned Integers

```python
```{testcode}
from algopy import arc4
# Integer types
Expand All @@ -23,53 +34,59 @@ uint64_value = arc4.UInt64(18446744073709551615)
... # instantiate test context
# Generate a random unsigned arc4 integer with default range
uint8 = ctx.arc4.any_uint8()
uint16 = ctx.arc4.any_uint16()
uint32 = ctx.arc4.any_uint32()
uint64 = ctx.arc4.any_uint64()
uint128 = ctx.arc4.any_biguint128()
uint256 = ctx.arc4.any_biguint256()
uint512 = ctx.arc4.any_biguint512()
uint8 = ctx.any.arc4.uint8()
uint16 = ctx.any.arc4.uint16()
uint32 = ctx.any.arc4.uint32()
uint64 = ctx.any.arc4.uint64()
biguint128 = ctx.any.arc4.biguint128()
biguint256 = ctx.any.arc4.biguint256()
biguint512 = ctx.any.arc4.biguint512()
# Generate a random unsigned arc4 integer with specified range
uint8_custom = ctx.arc4.any_uint8(min_value=10, max_value=100)
uint16_custom = ctx.arc4.any_uint16(min_value=1000, max_value=5000)
uint32_custom = ctx.arc4.any_uint32(min_value=100000, max_value=1000000)
uint64_custom = ctx.arc4.any_uint64(min_value=1000000000, max_value=10000000000)
uint128_custom = ctx.arc4.any_biguint128(min_value=1000000000000000, max_value=10000000000000000)
uint256_custom = ctx.arc4.any_biguint256(min_value=1000000000000000000000000, max_value=10000000000000000000000000)
uint512_custom = ctx.arc4.any_biguint512(min_value=1000000000000000000000000000000000, max_value=10000000000000000000000000000000000)
uint8_custom = ctx.any.arc4.uint8(min_value=10, max_value=100)
uint16_custom = ctx.any.arc4.uint16(min_value=1000, max_value=5000)
uint32_custom = ctx.any.arc4.uint32(min_value=100000, max_value=1000000)
uint64_custom = ctx.any.arc4.uint64(min_value=1000000000, max_value=10000000000)
biguint128_custom = ctx.any.arc4.biguint128(min_value=1000000000000000, max_value=10000000000000000)
biguint256_custom = ctx.any.arc4.biguint256(min_value=1000000000000000000000000, max_value=10000000000000000000000000)
biguint512_custom = ctx.any.arc4.biguint512(min_value=10000000000000000000000000000000000, max_value=10000000000000000000000000000000000)
```

## Address

```python
```{testcode}
from algopy import arc4
# Address type
address_value = arc4.Address("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ")
# Generate a random address
random_address = ctx.arc4.any_address()
random_address = ctx.any.arc4.address()
# Access native underlaying type
native = random_address.native
```

## Dynamic Bytes

```python
```{testcode}
from algopy import arc4
# Dynamic byte string
bytes_value = arc4.DynamicBytes(b"Hello, Algorand!")
# Generate random dynamic bytes
random_dynamic_bytes = ctx.arc4.any_dynamic_bytes()
random_dynamic_bytes = ctx.any.arc4.dynamic_bytes(n=123) # n is the number of bits in the arc4 dynamic bytes
```

## String

```python
```{testcode}
from algopy import arc4
# UTF-8 encoded string
string_value = arc4.String("Hello, Algorand!")
# Generate random string
random_string = ctx.any.arc4.string(n=12) # n is the number of bits in the arc4 string
```
Loading

0 comments on commit 5f131ec

Please sign in to comment.