From c08f7532b255d175d207d2062afb88a2a07e4308 Mon Sep 17 00:00:00 2001 From: "Rob Moore (MakerX)" Date: Thu, 28 Mar 2024 09:00:22 +0800 Subject: [PATCH] docs: Adding missing install step to install algorand-python --- README.md | 15 +++++++------- docs/index.md | 13 ++++++------ docs/language-guide.md | 47 +++++++++++++++++++++++++----------------- 3 files changed, 43 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 5c28d20ed2..07386ba5fb 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # 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. @@ -20,7 +20,8 @@ Alternatively, if you want to start from scratch you can do the following: # OR algokit compile py -h ``` -4. Create a contract in a (e.g.) `contact.py` file: +4. Install Algorand Python into your project `poetry add algorand-python` +5. Create a contract in a (e.g.) `contact.py` file: ```python from algopy import ARC4Contract, arc4 class HelloWorldContract(ARC4Contract): @@ -28,25 +29,25 @@ Alternatively, if you want to start from scratch you can do the following: def hello(self, name: arc4.String) -> arc4.String: return "Hello, " + name ``` -5. Compile the contract: +6. Compile the contract: ```shell # After running `poetry shell`: puyapy contract.py # OR if using AlgoKit CLI: algokit compile py contract.py ``` -6. You should now have `HelloWorldContract.approval.teal` and `HelloWorldContract.clear.teal` on the file system! -7. We generally recommend using ARC-32 and [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to have the most optimal deployment and consumption experience; to do this you need to ask PuyaPy to output an ARC-32 compatible app spec file: +7. You should now have `HelloWorldContract.approval.teal` and `HelloWorldContract.clear.teal` on the file system! +8. We generally recommend using ARC-32 and [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to have the most optimal deployment and consumption experience; to do this you need to ask PuyaPy to output an ARC-32 compatible app spec file: ```shell puyapy contract.py --output-arc32 --no-output-teal # OR algokit compile py contract.py --output-arc32 --no-output-teal ``` -8. You should now have `HelloWorldContract.arc32.json`, which can be generated into a client e.g. using AlgoKit CLI: +9. You should now have `HelloWorldContract.arc32.json`, which can be generated into a client e.g. using AlgoKit CLI: ```shell algokit generate client HelloWorldContract.arc32.json --output client.py ``` -9. From here you can dive into the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) or look at the [documentation](https://algorandfoundation.github.io/puya/). +10. From here you can dive into the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) or look at the [documentation](https://algorandfoundation.github.io/puya/). ## Examples diff --git a/docs/index.md b/docs/index.md index 04323ff958..743d8600ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,8 @@ Alternatively, if you want to start from scratch you can do the following: 1. Ensure you have Python 3.12+ 2. [Install the PuyaPy compiler](./compiler.md#compiler-installation) 3. [Check you can run the compiler](./compiler.md#using-the-compiler) -4. Create a contract in a (e.g.) `contact.py` file: +4. Install Algorand Python into your project `pip install algorand-python` or `poetry add algorand-python` +5. Create a contract in a (e.g.) `contact.py` file: ```python from algopy import ARC4Contract, arc4 class HelloWorldContract(ARC4Contract): @@ -21,25 +22,25 @@ Alternatively, if you want to start from scratch you can do the following: def hello(self, name: arc4.String) -> arc4.String: return "Hello, " + name ``` -5. Compile the contract: +6. Compile the contract: ```shell # After running `poetry shell`: puyapy contract.py # OR if using AlgoKit CLI: algokit compile py contract.py ``` -6. You should now have `HelloWorldContract.approval.teal` and `HelloWorldContract.clear.teal` on the file system! -7. We generally recommend using ARC-32 and [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to have the most optimal deployment and consumption experience; to do this you need to ask PuyaPy to output an ARC-32 compatible app spec file: +7. You should now have `HelloWorldContract.approval.teal` and `HelloWorldContract.clear.teal` on the file system! +8. We generally recommend using ARC-32 and [generated typed clients](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients) to have the most optimal deployment and consumption experience; to do this you need to ask PuyaPy to output an ARC-32 compatible app spec file: ```shell puyapy contract.py --output-arc32 --no-output-teal # OR algokit compile py contract.py --output-arc32 --no-output-teal ``` -8. You should now have `HelloWorldContract.arc32.json`, which can be generated into a client e.g. using AlgoKit CLI: +9. You should now have `HelloWorldContract.arc32.json`, which can be generated into a client e.g. using AlgoKit CLI: ```shell algokit generate client HelloWorldContract.arc32.json --output client.py ``` -9. From here you can dive into the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) or look at the [documentation](docs/index.md). +10. From here you can dive into the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) or look at the [documentation](docs/index.md). ## Programming with Algorand Python diff --git a/docs/language-guide.md b/docs/language-guide.md index 3281d1f333..63fca3d396 100644 --- a/docs/language-guide.md +++ b/docs/language-guide.md @@ -3,54 +3,63 @@ Algorand Python is conceptually two things: 1. A partial implementation of the Python programming language that runs on the AVM. -2. A framework for development of Algorand smart contracts and logic signatures, with Pythonic +2. A framework for development of Algorand smart contracts and logic signatures, with Pythonic interfaces to underlying AVM functionality. +You can install the Algorand Python types from PyPi: + +> `pip install algorand-python` + +or + +> `poetry add algorand-python` + +--- + As a partial implementation of the Python programming language, it maintains the syntax and semantics of Python. The subset of the language that is supported will grow over time, but it will never be a complete implementation due to the restricted nature of the AVM as an execution environment. As a trivial example, the `async` and `await` keywords, and all associated features, do not make sense to implement. -Being a partial implementation of Python means that existing developer tooling like IDE syntax +Being a partial implementation of Python means that existing developer tooling like IDE syntax highlighting, static type checkers, linters, and auto-formatters, will work out-of-the-box. This is -as opposed to an approach to smart contract development that adds or alters language elements or -semantics, which then requires custom developer tooling support, and more importantly, requires the -developer to learn and understand the potentially non-obvious differences from regular Python. +as opposed to an approach to smart contract development that adds or alters language elements or +semantics, which then requires custom developer tooling support, and more importantly, requires the +developer to learn and understand the potentially non-obvious differences from regular Python. -The greatest advantage to maintaining semantic and syntactic compatibility, however, is only +The greatest advantage to maintaining semantic and syntactic compatibility, however, is only realised in combination with the framework approach. Supplying a set of interfaces representing smart contract development and AVM functionality required allows for the possibility of implementing those interfaces in pure Python! This will make it possible in the near future for you to execute tests against your smart contracts without deploying them to Algorand, and even step into and break-point debug your code from those tests. -The framework provides interfaces to the underlying AVM types and operations. By virtue of the AVM -being statically typed, these interfaces are also statically typed, and require your code to be as +The framework provides interfaces to the underlying AVM types and operations. By virtue of the AVM +being statically typed, these interfaces are also statically typed, and require your code to be as well. The most basic types on the AVM are `uint64` and `bytes[]`, representing unsigned 64-bit integers -and byte arrays respectively. These are represented by [`UInt64`](#algopy.UInt64) and -[`Bytes`](#algopy.Bytes) in Algorand Python. There are further "bounded" types supported by the AVM -which are backed by these two simple primitives. For example, `bigint` represents a variably sized -(up to 512-bits), unsigned integer, but is actually backed by a `bytes[]`. This is represented by +and byte arrays respectively. These are represented by [`UInt64`](#algopy.UInt64) and +[`Bytes`](#algopy.Bytes) in Algorand Python. There are further "bounded" types supported by the AVM +which are backed by these two simple primitives. For example, `bigint` represents a variably sized +(up to 512-bits), unsigned integer, but is actually backed by a `bytes[]`. This is represented by [`BigUInt`](#algopy.BigUInt) in Algorand Python. -Unfortunately, none of these types map to standard Python primitives. In Python, an `int` is +Unfortunately, none of these types map to standard Python primitives. In Python, an `int` is unsigned, and effectively unbounded. A `bytes` similarly is limited only by the memory available, -whereas an AVM `bytes[]` has a maximum length of 4096. In order to both maintain semantic -compatibility and allow for a framework implementation in plain Python that will fail under the -same conditions as when deployed to the AVM, support for Python primitives is -[limited](lg-types.md#python-built-in-types). +whereas an AVM `bytes[]` has a maximum length of 4096. In order to both maintain semantic +compatibility and allow for a framework implementation in plain Python that will fail under the +same conditions as when deployed to the AVM, support for Python primitives is +[limited](lg-types.md#python-built-in-types). For more information on the philosophy and design of Algorand Python, please see ["Principles"](principles.md#principles). If you aren't familiar with Python, a good place to start before continuing below is with the -[official tutorial](https://docs.python.org/3/tutorial/index.html). Just beware that as mentioned +[official tutorial](https://docs.python.org/3/tutorial/index.html). Just beware that as mentioned above, [not all features are supported](./lg-unsupported-python-features.md). - ## Table of Contents ```{toctree}