Initial commit

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

.coveragerc

@@ -0,0 +1,7 @@
+[run]
+source = src/wyvern
+omit = src/wyvern/_vendor/*
+
+[report]
+show_missing = true
+skip_covered = true

.editorconfig

@@ -0,0 +1,10 @@
+root=true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+insert_final_newline = true
+
+[{*.py,*.pyi}]
+max_line_length = 99

.gitattributes

@@ -0,0 +1,4 @@
+examples/**/*.ir linguist-generated=true
+examples/**/*.debug.teal linguist-generated=true
+examples/**/*.log linguist-generated=true
+examples/**/*.awst linguist-generated=true

.github/workflows/check-python.yaml

@@ -0,0 +1,55 @@
+name: Check Python Code
+
+on:
+  workflow_call:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check-python:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: "poetry"
+
+      - name: Install dependencies
+        run: poetry install --no-interaction
+
+      - name: Check pre-commits
+        run: |
+            set -o pipefail
+            poetry run pre-commit run --all-files && git diff --exit-code
+
+      - name: Install algokit
+        run: pipx install algokit
+
+      - name: Start LocalNet
+        run: algokit localnet start
+
+      - name: pytest + coverage
+        shell: bash
+        run: |
+          set -o pipefail
+          poetry run pytest --junitxml=pytest-junit.xml --cov | tee pytest-coverage.txt
+
+      - name: Stop LocalNet
+        run: algokit localnet stop
+
+      - name: pytest coverage comment - using Python 3.11 on ubuntu-latest
+        if: matrix.python == '3.11' && matrix.os == 'ubuntu-latest'
+        continue-on-error: true # forks fail to add a comment, so continue any way
+        uses: MishaKav/pytest-coverage-comment@main
+        with:
+          pytest-coverage-path: ./pytest-coverage.txt
+          junitxml-path: ./pytest-junit.xml

.gitignore

@@ -0,0 +1,4 @@
+.idea
+__pycache__
+.DS_Store
+examples/**/*.trace

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        description: "Black: The uncompromising Python code formatter"
+        entry: poetry run black
+        language: system
+        minimum_pre_commit_version: 2.9.2
+        require_serial: true
+        types_or: [ python, pyi ]
+        exclude: '^src/wyvern/(_vendor|_typeshed)/'
+      - id: ruff
+        name: ruff
+        description: "Run 'ruff' for extremely fast Python linting"
+        entry: poetry run ruff
+        language: system
+        'types': [python]
+        args: [--fix]
+        require_serial: false
+        additional_dependencies: []
+        minimum_pre_commit_version: '0'
+        files: '^(src|tests|scripts)/'
+        exclude: '^src/wyvern/(_vendor|_typeshed)/'
+      - id: mypy
+        name: mypy
+        description: '`mypy` will check Python types for correctness'
+        entry: poetry run mypy
+        language: system
+        types_or: [ python, pyi ]
+        require_serial: true
+        additional_dependencies: [ ]
+        minimum_pre_commit_version: '2.9.2'
+        files: '^(src|tests|examples|scripts)/'
+        exclude: '^src/wyvern/(_vendor|_typeshed)/'

.run/compile_all_examples.run.xml

@@ -0,0 +1,24 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="compile_all_examples" type="PythonConfigurationType" factoryName="Python" nameIsGenerated="true">
+    <module name="wyvern-hacking" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/scripts" />
+    <option name="IS_MODULE_SDK" value="true" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/scripts/compile_all_examples.py" />
+    <option name="PARAMETERS" value="" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="MODULE_MODE" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>

.run/wyvern examples_simplish.run.xml

@@ -0,0 +1,24 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="wyvern examples/simplish" type="PythonConfigurationType" factoryName="Python">
+    <module name="wyvern-hacking" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/examples" />
+    <option name="IS_MODULE_SDK" value="true" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/scripts/debug_example.py" />
+    <option name="PARAMETERS" value="simplish" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="MODULE_MODE" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "DragMZ.teal"
+    ]
+}

README.md

@@ -0,0 +1,61 @@
+TODO:
+How to handle identity for compound objects i.e. dataclasses so that semantic compatability is retained
+    Ideas:
+        Enforce value equality (dataclasses implement data equality by default)
+        Could carry a unique identifier for the object to represent it's identity
+
+how to handle user libs with type stubs:
+    option: don't. only want to handle algopy specific code anyway, which needs
+            to be fully typed.
+
+
+THOUGHTS:
+- mypy call expr resolves to full node (ie FuncDef) when not through member ref
+- user classes (ie not contracts) can't be allowed to override (maybe not even define??) methods, unless we want to implement vtables..................
+
+
+we probably want to vendor mypy, for a few reasons:
+1) we want to pin to an exact version, without possibly getting in the way of user updating their venv version and/or CI/CD config changes
+2) we need to stop mypy from being compiled with mypyc, which I don't think we can do with a wheel package? and
+3) even if we can/could stop it being compiled, it slows things down a lot for the user, so that's not a great experience
+4) can simplify our debugging/development experience (not really a reason by itself, but a nice bonus)
+
+mypy is MIT licensed, except for some files in mypy/mypyc
+git submodules could be one approach here, but we can't point it to a subdirectory (ie mypy/mypy)
+we can possibly exclude these after the fact in our build to prevent our package becoming too larg
+and/or licensing violations, but the import paths might get a bit verbose (ie wyvern.vendor(?).mypy.mypy).
+maybe a manual approach is best, possibly with a script to do the update.
+we definitely don't want any alterations to the mypy code base, except perhaps in the most dire of
+circumstances where we need to patch a particular bug (but really, even then, we should contribute this back upstream ASAP)
+
+
+
+TODOs:
+error handling at expression level, needs stub data. current handling could generate spurious extra errors
+
+
+### Parking lot
+- match statements
+- efficient compound types including pass-by-ref using bytes[] as scratch pointers with loadss/storess
+- type tags at end of bytes[] pointers, allowing union types as args and isinstance checks 
+- inlineable functions either via explicit hints or via optimisation
+- improved constant folding when encountering a non-literal (e.g UInt64) that wraps a known-constant value
+- support properties - probably requires inlining?
+- More Pythonic ways of using Txn et al:
+  - `for arg in Txna.application_args`
+  - `len(Txna.application_args)`
+  - `Txna.application_args[0]`
+- for functions like `box_get` that return `value, did exist: bool` - translate to `value | None`
+- support for user defined Protocols (PEP 544)
+- support user reserved scratch slots (and syntax to load / store values)
+  -  `gloads` allows an application to query another transaction's scratch space, in order for this to be useful a wyvern built app needs a way to push values to `well known` slots
+- on reference to `app_(local|global)_get(_ex)?` et. al. extract keys if literals,
+  and if dynamic then warn if storage schema not specified explicitly
+- allow overrides of local and global storage keys... somehow. or maybe we allow compacting them
+  for more storage space as a compiler flag? this would be less helpful though if you wanted to
+  read them off chain directly...
+- allow more idiomatic `is not None` for `Local.__getitem__` result rather than returning a tuple
+  - similarly, allow global (ie member vars) to be ` | None = None` ??
+- default values for subroutine arguments
+- optimize large x in (...y) ops to use `match` op
+-