puyapy 0.1.0__tar.gz

puyapy-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.1
+Name: puyapy
+Version: 0.1.0
+Summary: 
+Author: Adam Chidlow
+Author-email: achidlow@users.noreply.github.com
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: attrs (>=23.1.0,<24.0.0)
+Requires-Dist: docstring-parser (>=0.15,<0.16)
+Requires-Dist: immutabledict (>=4.0.0,<5.0.0)
+Requires-Dist: mypy_extensions (>=1.0.0,<2.0.0)
+Requires-Dist: networkx (>=3.1,<4.0)
+Requires-Dist: pycryptodomex (>=3.6.0,<4)
+Requires-Dist: structlog (>=23.2.0,<24.0.0)
+Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
+Description-Content-Type: text/markdown
+
+# PuyaPy - Python to TEAL compiler
+
+> [!WARNING]
+> PuyaPy is currently in alpha / developer preview. It is not recommended for production usage yet.
+
+PuyaPy is an optimising TEAL compiler that allows you to write code to execute on the Algorand
+Virtual Machine (AVM) with Python syntax.
+
+[Project background and guiding principles](docs/principles.md).
+
+PuyaPy supports a statically-typed subset of valid Python syntax. Importantly, that subset has 
+identical semantics when comparing Python behaviour and behaviour of the executed TEAL. 
+For example, `foo = spam() or eggs()` will only execute `eggs()` if `bool(spam())` is `False`.
+
+## Installation
+
+The minimum supported Python version for running PuyaPy itself is 3.12.
+
+You can install the developer preview of PuyaPy directly from this repo into your project virtualenv:
+```shell
+pip install git+https://github.com/algorandfoundation/puya.git
+```
+If you're using poetry for dependency and virutalenv management, the above URL should work with
+`poetry add`.
+
+Or if you just want to play with some examples, you can clone the repo and have a poke around.
+
+```shell
+git clone https://github.com/algorandfoundation/puya.git
+cd puya
+poetry install
+poetry shell
+```
+
+Note that with this method you'll need to activate the virtual environment created by poetry
+before using the puyapy command in each new shell that you open - you can do this by running
+`poetry shell` in the `puya` directory.
+
+## Compiler usage
+
+To check that you can run the `puyapy` command successfully after that, you can run the help command:
+
+`puyapy -h`
+
+To compile a contract or contracts, just supply the path(s) - either to the .py files themselves,
+or the containing directories. In the case of containing directories, any contracts discovered
+therein will be compiled, allowing you to compile multiple contracts at once. You can also supply
+more than one path at a time to the compiler.
+
+e.g. `puyapy my_project/` or `puyapy my_project/contract.py` will work to compile a single contract.
+
+## Language fundamentals
+
+> [!NOTE]
+> A more comprehensive guide is coming soon!
+
+### Contracts
+
+A smart contract is defined within a single class. You can extend other contracts (through inheritance),
+and also define standalone functions and reference them. This also works across different Python 
+packages - in other words, you can have a Python library with common functions and re-use that
+library across multiple projects!
+
+All contracts must inherit from the base class `puyapy.Contract` - either directly or indirectly,
+which can include inheriting from `puyapy.ARC4Contract`. For a non-ARC4 contract, a contract class
+must implement an `approval_program` and a `clear_state_program` method. For ARC4 contracts, these
+methods will be implemented for you, although you can optionally provide a `clear_state_program`
+(the default implementation just always approves).
+
+As an example, this is a valid contract that always approves:
+
+```python
+import puyapy
+
+class Contract(puyapy.Contract):
+    def approval_program(self) -> bool:
+        return True
+    
+    def clear_state_program(self) -> bool:
+        return True
+```
+
+The return value of these methods can be either a `bool` that indicates whether the transaction
+should approve or not, or a `puyapy.UInt64` value, where `UInt64(0)` indicates that the transaction
+should be rejected and any other value indicates that it should be approved.
+
+And here is a valid ARC4 contract:
+
+```python
+import puyapy
+
+class ABIContract(puyapy.ARC4Contract):
+    """This contract can be created, but otherwise does nothing"""
+    pass
+```
+
+### Primitive types
+
+The primitive types of the AVM, `uint64` and `bytes[]` are represented by `puyapy.UInt64` and 
+`puyapy.Bytes` respectively. `puyapy.BigUInt` is also available for AVM supported wide-math 
+(up to 512 bits).
+
+Note that Python builtin types such as `int` cannot be used as variables, for semantic compatibility 
+reasons - however you can define module level constants of this type.
+
+```python
+from puyapy import UInt64, subroutine
+
+SCALE = 100000
+SCALED_PI = 314159
+
+@subroutine
+def circle_area(radius: UInt64) -> UInt64:
+    scaled_result = SCALED_PI * radius**2 
+    result = scaled_result // SCALE
+    return result
+
+
+...
+
+
+
+```
+## Examples
+
+ There are many examples in this repo, here are some of the more useful ones that showcase what
+ is possible.
+
+- [voting](examples/voting/voting.py)
+- [AMM](examples/amm/contract.py)
+- [auction](examples/TEALScript/auction/contract.py)
+- [non-ABI calculator](examples/calculator/contract.py)
+- [local storage](examples/local_storage)
+
+The compiled output is available under the `out/` directory alongside these, e.g. the approval
+TEAL for `voting` is available at [examples/voting/out/voting.approval.teal](examples/voting/out/voting.approval.teal).
+

puyapy-0.1.0/README.md

@@ -0,0 +1,136 @@
+# PuyaPy - Python to TEAL compiler
+
+> [!WARNING]
+> PuyaPy is currently in alpha / developer preview. It is not recommended for production usage yet.
+
+PuyaPy is an optimising TEAL compiler that allows you to write code to execute on the Algorand
+Virtual Machine (AVM) with Python syntax.
+
+[Project background and guiding principles](docs/principles.md).
+
+PuyaPy supports a statically-typed subset of valid Python syntax. Importantly, that subset has 
+identical semantics when comparing Python behaviour and behaviour of the executed TEAL. 
+For example, `foo = spam() or eggs()` will only execute `eggs()` if `bool(spam())` is `False`.
+
+## Installation
+
+The minimum supported Python version for running PuyaPy itself is 3.12.
+
+You can install the developer preview of PuyaPy directly from this repo into your project virtualenv:
+```shell
+pip install git+https://github.com/algorandfoundation/puya.git
+```
+If you're using poetry for dependency and virutalenv management, the above URL should work with
+`poetry add`.
+
+Or if you just want to play with some examples, you can clone the repo and have a poke around.
+
+```shell
+git clone https://github.com/algorandfoundation/puya.git
+cd puya
+poetry install
+poetry shell
+```
+
+Note that with this method you'll need to activate the virtual environment created by poetry
+before using the puyapy command in each new shell that you open - you can do this by running
+`poetry shell` in the `puya` directory.
+
+## Compiler usage
+
+To check that you can run the `puyapy` command successfully after that, you can run the help command:
+
+`puyapy -h`
+
+To compile a contract or contracts, just supply the path(s) - either to the .py files themselves,
+or the containing directories. In the case of containing directories, any contracts discovered
+therein will be compiled, allowing you to compile multiple contracts at once. You can also supply
+more than one path at a time to the compiler.
+
+e.g. `puyapy my_project/` or `puyapy my_project/contract.py` will work to compile a single contract.
+
+## Language fundamentals
+
+> [!NOTE]
+> A more comprehensive guide is coming soon!
+
+### Contracts
+
+A smart contract is defined within a single class. You can extend other contracts (through inheritance),
+and also define standalone functions and reference them. This also works across different Python 
+packages - in other words, you can have a Python library with common functions and re-use that
+library across multiple projects!
+
+All contracts must inherit from the base class `puyapy.Contract` - either directly or indirectly,
+which can include inheriting from `puyapy.ARC4Contract`. For a non-ARC4 contract, a contract class
+must implement an `approval_program` and a `clear_state_program` method. For ARC4 contracts, these
+methods will be implemented for you, although you can optionally provide a `clear_state_program`
+(the default implementation just always approves).
+
+As an example, this is a valid contract that always approves:
+
+```python
+import puyapy
+
+class Contract(puyapy.Contract):
+    def approval_program(self) -> bool:
+        return True
+    
+    def clear_state_program(self) -> bool:
+        return True
+```
+
+The return value of these methods can be either a `bool` that indicates whether the transaction
+should approve or not, or a `puyapy.UInt64` value, where `UInt64(0)` indicates that the transaction
+should be rejected and any other value indicates that it should be approved.
+
+And here is a valid ARC4 contract:
+
+```python
+import puyapy
+
+class ABIContract(puyapy.ARC4Contract):
+    """This contract can be created, but otherwise does nothing"""
+    pass
+```
+
+### Primitive types
+
+The primitive types of the AVM, `uint64` and `bytes[]` are represented by `puyapy.UInt64` and 
+`puyapy.Bytes` respectively. `puyapy.BigUInt` is also available for AVM supported wide-math 
+(up to 512 bits).
+
+Note that Python builtin types such as `int` cannot be used as variables, for semantic compatibility 
+reasons - however you can define module level constants of this type.
+
+```python
+from puyapy import UInt64, subroutine
+
+SCALE = 100000
+SCALED_PI = 314159
+
+@subroutine
+def circle_area(radius: UInt64) -> UInt64:
+    scaled_result = SCALED_PI * radius**2 
+    result = scaled_result // SCALE
+    return result
+
+
+...
+
+
+
+```
+## Examples
+
+ There are many examples in this repo, here are some of the more useful ones that showcase what
+ is possible.
+
+- [voting](examples/voting/voting.py)
+- [AMM](examples/amm/contract.py)
+- [auction](examples/TEALScript/auction/contract.py)
+- [non-ABI calculator](examples/calculator/contract.py)
+- [local storage](examples/local_storage)
+
+The compiled output is available under the `out/` directory alongside these, e.g. the approval
+TEAL for `voting` is available at [examples/voting/out/voting.approval.teal](examples/voting/out/voting.approval.teal).

puyapy-0.1.0/pyproject.toml

@@ -0,0 +1,186 @@
+[tool.poetry]
+name = "puyapy"
+version = "0.1.0"
+description = ""
+authors = ["Adam Chidlow <achidlow@users.noreply.github.com>"]
+readme = "README.md"
+packages = [
+    { include = "puya", from = "src" },
+    { include = "puyapy-stubs", from = "src" },
+]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+typing-extensions = "^4.8.0"
+attrs = "^23.1.0"
+structlog = "^23.2.0"
+networkx = "^3.1"
+docstring-parser = "^0.15"
+pycryptodomex = ">=3.6.0,<4"
+immutabledict = "^4.0.0"
+# vendored mypy dependencies
+mypy_extensions = "^1.0.0"
+
+
+[tool.poetry.group.dev.dependencies]
+black = {extras = ["d"], version = "^23.10.1"}
+mypy = "1.7.0"
+ruff = "^0.1.3"
+pre-commit = "^3.3.3"
+pytest = "^7.4.0"
+pytest-xdist = {extras = ["psutil"], version = "^3.3.1"}
+cattrs = "^23.1.2"
+py-algorand-sdk = "^2.4.0"
+ruff-lsp = "^0.0.45"
+pytest-cov = "^4.1.0"
+pip-audit = "^2.6.1"
+algokit-utils = "^1.3.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.scripts]
+puyapy = "puya.__main__:main"
+
+[tool.pytest.ini_options]
+addopts = "-n auto --cov-config=.coveragerc"
+testpaths = [
+    "tests"
+]
+
+[tool.black]
+line-length = 99
+force-exclude = "src/puya/(_typeshed|_vendor)"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+untyped_calls_exclude = [
+    "algosdk",
+]
+exclude = [
+    "src/puya/_typeshed",
+    "src/puya/_vendor",
+]
+
+[[tool.mypy.overrides]]
+module = ["puyapy", "puyapy.*"]
+disallow_any_unimported = true
+disallow_any_expr = true
+disallow_any_decorated = true
+disallow_any_explicit = true
+
+[[tool.mypy.overrides]]
+module = ["algosdk", "algosdk.*"]
+disallow_untyped_calls = false
+
+[tool.ruff]
+line-length = 99
+select = [
+      # all possible codes as of this ruff version are listed here,
+      # ones we don't want/need are commented out to make it clear
+      # which have been omitted on purpose vs which ones get added
+      # in new ruff releases and should be considered for enabling
+      "F",      # pyflakes
+      "E", "W", # pycodestyle
+      "C90",    # mccabe
+      "I",      # isort
+      "N",      # PEP8 naming
+      "UP",     # pyupgrade
+      "YTT",    # flake8-2020
+      "ANN",    # flake8-annotations
+      # "S",    # flake8-bandit
+      # "BLE",  # flake8-blind-except
+      "FBT",    # flake8-boolean-trap
+      "B",      # flake8-bugbear
+      "A",      # flake8-builtins
+      # "COM",  # flake8-commas
+      "C4",     # flake8-comprehensions
+      "DTZ",    # flake8-datetimez
+      "T10",    # flake8-debugger
+      # "DJ",   # flake8-django
+      # "EM",   # flake8-errmsg
+      # "EXE",  # flake8-executable
+      "ISC",    # flake8-implicit-str-concat
+      "ICN",    # flake8-import-conventions
+      # "G",    # flake8-logging-format
+      # "INP",  # flake8-no-pep420
+      "PIE",    # flake8-pie
+      "T20",    # flake8-print
+      "PYI",    # flake8-pyi
+      "PT",     # flake8-pytest-style
+      "Q",      # flake8-quotes
+      "RSE",    # flake8-raise
+      # "RET",    # flake8-return
+      "SLF",    # flake8-self
+      "SIM",    # flake8-simplify
+      "TID",    # flake8-tidy-imports
+      "TCH",    # flake8-type-checking
+      "ARG",    # flake8-unused-arguments
+      "PTH",    # flake8-use-pathlib
+      "ERA",    # eradicate
+      # "PD",   # pandas-vet
+      "PGH",    # pygrep-hooks
+      "PL",     # pylint
+      # "TRY",  # tryceratops
+      # "NPY",  # NumPy-specific rules
+      "RUF",    # Ruff-specific rules
+]
+ignore = [
+    "ANN101",  # no type for self
+    "ANN102",  # no type for cls
+    "SIM108",  # allow if-else in place of ternary
+    "PLR2004", # magic values... can't configure to ignore simple low value ints like 2
+    "PLW2901", # allow updating loop value...
+    "PYI025",  # I can tell the difference between set and Set thank you very much
+    # TODO: REMOVE ALL THE BELOW vvv
+    "ERA001",  # don't automatically remove commented out code
+    "T201",    # allow prints (FOR NOW)
+    # TODO: REMOVE ALL THE BELOW AFTER REFACTORING BUILDING CODE vvv
+    "C901", # is too complex (> 10)
+    "PLR0911", # Too many return statements (> 6)
+    "PLR0912", # Too many branches (> 12)
+    "PLR0913", # Too many arguments to function call (> 5)
+    "PLR0915", # Too many statements (> 50)
+
+]
+unfixable = [
+    # TODO: REMOVE THE BELOW
+    # "ERA001", # don't automatically remove commented out code
+    "F841", # don't delete unused local variables automatically
+    "B011", # don't automatically convert assert False -> raise AssertionError - we want the former
+            # in any smart contracts in this repo
+]
+extend-exclude = [
+    "src/puya/_typeshed",
+    "src/puya/_vendor",
+]
+[tool.ruff.per-file-ignores]
+"src/**" = [
+    "PT",       # no pytest rules
+]
+"src/puyapy-stubs/**" = [
+    "PYI021",   # allow docstrings in stubs
+    "PYI053",   # allow "docstrings" in overloads
+]
+"examples/**" = [
+    "PT",       # no pytest rules
+    "B011",     # allow assert False, "msg"
+]
+"src/puya/awst_build/eb/**" = [
+    # TODO: remove the below
+    "ARG002",
+]
+
+[tool.ruff.flake8-annotations]
+allow-star-arg-any = true
+suppress-none-returning = true
+mypy-init-return = true
+
+[tool.ruff.isort]
+combine-as-imports = true
+force-wrap-aliases = true
+
+[tool.ruff.flake8-builtins]
+builtins-ignorelist = ["id"]

puyapy-0.1.0/src/puya/ARCHITECTURE.md

@@ -0,0 +1,91 @@
+# FAQ
+
+### There are too many things named "context"!
+Yes
+
+# Other
+
+## Layers
+
+In top-down order: 
+
+- puya/
+  - compile.py
+  - codegen/ 
+  - ir/
+  - awst/
+  - metadata.py
+  - parse.py
+  - errors.py 
+- puyapy/
+
+Nothing should ever import from something higher in the list.
+
+
+## IR Ops
+
+TEAL spec doesn't have "types" for immediate args
+(ie literal values that end up in the TEAL source)
+This diverges from mypyc Value, which has an rtype always on the Value
+class, even if that rtype is void.
+
+We might not even be able to resolve the type of an int literal in the Python source,
+until it's used in context with an actual AVM Type, eg:
+
+    UInt64(1) + 2
+vs
+
+    UInt512(1) + 2
+
+we don't know the "runtime type" of "2" until we expand the binary operation,
+(we probably don't even know the type of "1" unless we handle the compound CallExpr and
+IntLiteral together, which has some downsides).
+
+Option 1: parallel hierarchies
+
+    ImmediateValue(ctx: mypy.nodes.Context)
+        -> IntLiteral
+        -> BytesLiteral
+    AVMValue(ctx: mypy.nodes.Context, rtype: RType)
+        -> Ops
+        -> ...
+
+Option 2: one hierarchy, rtype not defined on Value
+    
+    Value(ctx: mypy.nodes.Context)
+        -> ImmediateValue
+            -> IntLiteral
+            -> BytesLiteral
+        -> AVMValue(rtype: RType)
+            -> Ops
+            -> ...
+
+Option 3: one hierarchy, rtype defined on Value but is optional
+
+    Value(ctx: mypy.nodes.Context, rtype: RType | None)
+        -> IntLiteral
+        -> BytesLiteral
+        -> Ops
+        -> ...
+
+
+Option 1 is annoying dealing with unions everywhere, too much typing.
+
+Out of Option 2 and Option 3, mishandling is probably more obvious in 2.
+
+Selecting Option 2.
+
+
+## Puya AST
+
+- no dependency on mypy past this point. We are insulated from either changes in mypy or changing to another parser
+- Validate as much as possible during conversion - most source information at this point & early validation means less error compounding causing confusion. 
+- This means fully normalised, and only what is required remains. Much easier to reason about this new ast when converting to ir
+- No python peculiarities eg a < b < c (which is the same as ((a < b) and (b < c)) _except_ that b is only evaluated once)
+  - e.g. a < func_with_side_effects() < c would be equivalent to (tmp = func_with_side_effects(); a < tmp and tmp < c)
+  - e.g., a and b and c *_returns_* the first one of (a, b, c) that is falsy or if all are truthy returns c, whilst only evaluating each of a, b, and c at most once (ie still short circuiting) 
+- Still high level though eg if else, not branch + go to 
+- All stubs fully resolved, ie no further dependence on “puyapy” component. This further insulates from python specifics. Maybe this ast can be target for other languages? Note: this includes any necessary ast code generation eg approval program for arc4
+- All types fully resolved & checked
+
+

puyapy-0.1.0/src/puya/__init__.py

@@ -0,0 +1,6 @@
+import pathlib
+import sys
+
+_VENDOR_PATH = pathlib.Path(__file__).parent / "_vendor"
+
+sys.path.insert(0, str(_VENDOR_PATH))

puyapy-0.1.0/src/puya/__main__.py

@@ -0,0 +1,101 @@
+import argparse
+from pathlib import Path
+
+from puya.compile import compile_to_teal
+from puya.logging_config import LogLevel, configure_logging
+from puya.options import PuyaOptions
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="puya",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "-g",  # -g chosen because it is the same option for debug in gcc
+        "--debug-level",
+        type=int,
+        choices=[0, 1, 2],
+        default=0,
+        help="debug information level",
+    )
+    parser.add_argument(
+        "-O",
+        "--optimization-level",
+        type=int,
+        choices=[0, 1, 2],
+        default=1,
+        help="set optimization level",
+    )
+    parser.add_argument(
+        "--output-teal",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Output TEAL",
+    )
+    parser.add_argument(
+        "--output-arc32",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Output ARC32 application.json",
+    )
+    parser.add_argument(
+        "--output-awst",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output parsed result of AST",
+    )
+    parser.add_argument(
+        "--output-ssa-ir",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output IR in SSA form",
+    )
+    parser.add_argument(
+        "--output-optimization-ir",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output IR after each optimization",
+    )
+    parser.add_argument(
+        "--output-final-ir",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output IR before codegen",
+    )
+    parser.add_argument(
+        "--output-cssa-ir",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output IR in cssa form",
+    )
+    parser.add_argument(
+        "--output-post-ssa-ir",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output IR post ssa form",
+    )
+    parser.add_argument(
+        "--output-parallel-copies-ir",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="output IR after parallel copy sequentialization",
+    )
+    parser.add_argument(
+        "--out-dir", type=Path, help="path for outputting artefacts", default=False
+    )
+    parser.add_argument(
+        "--log-level",
+        type=LogLevel.from_string,
+        choices=list(LogLevel),
+    )
+
+    parser.add_argument("paths", type=Path, nargs="+", metavar="PATH")
+    options = PuyaOptions()
+    parser.parse_args(namespace=options)
+    configure_logging(min_log_level=options.log_level)
+    compile_to_teal(options)
+
+
+if __name__ == "__main__":
+    main()