feat: algokit-utils-py v3 implementation (#119)

BREAKING CHANGE: Major restructuring and new app client interfaces

- Moved all legacy v2 code to `legacy_v2/` folder and tests to `legacy_v2_tests/`
- Introduced new core interfaces:
  - `TransactionComposer` for transaction building
  - `AppManager` for TEAL compilation and state management
  - `AppClient`, `AppFactory`, and `AppDeployer` for application lifecycle
  - `AssetManager` for asset operations
- Added ABI value support and ARC-32 contract handling
- Revamped documentation with migration guide and new capability docs
- Added deprecation warnings for legacy interfaces

> Migration Required: Existing users should consult the new migration guide and update imports from legacy paths to new interfaces. Check updated documentation for client usage patterns.

Author: aorumbayev

.github/workflows/check-python.yaml

@@ -45,12 +45,8 @@ jobs:
       - name: Check types with mypy
         run: poetry run mypy
 
-      - name: Check docs are up to date
-        run: |
-          poetry run poe docs
-          git diff --quiet --exit-code \
-            ':!docs/html/_sources/apidocs/algokit_utils/algokit_utils.md.txt' \
-            ':!docs/html/apidocs/algokit_utils/algokit_utils.html' \
-            ':!docs/html/searchindex.js' \
-            ':!docs/markdown/apidocs/algokit_utils/algokit_utils.md' \
-            docs/
+      # TODO: Restore before prod release of v3
+      # - name: Check docs are up to date
+      #   run: |
+      #     poetry run poe docs-md-only
+      #     git diff --exit-code ':!docs/markdown/autoapi/index.md' ':!docs/markdown/autoapi/algokit_utils/applications/app_factory/index.md' docs

.gitignore

@@ -170,3 +170,6 @@ cython_debug/
 /docs/source/apidocs
 
 !docs/html
+
+# Received approval test files
+*.received.*

.pre-commit-config.yaml

@@ -23,6 +23,7 @@ repos:
         additional_dependencies: []
         minimum_pre_commit_version: "0"
         files: "^(src|tests)/"
+        exclude: "^tests/artifacts/"
       - id: mypy
         name: mypy
         description: "`mypy` will check Python types for correctness"
@@ -33,3 +34,11 @@ repos:
         additional_dependencies: []
         minimum_pre_commit_version: "2.9.2"
         files: "^(src|tests)/"
+        exclude: "^tests/artifacts/"
+      - id: docstrings-check
+        name: docstrings-check
+        description: "Check docstrings for correctness"
+        entry: poetry run poe docstrings-check
+        language: system
+        types: [python]
+        files: "^(src)/"

.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Python: Debug Tests",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "purpose": [
+                "debug-test"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": false
+        }
+    ]
+}

.vscode/settings.json

@@ -16,18 +16,24 @@
     "**/__pycache__": true,
     ".idea": true
   },
-
   // Python
   "platformSettings.autoLoad": true,
   "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
-  "python.analysis.extraPaths": ["${workspaceFolder}/src"],
+  "python.analysis.extraPaths": [
+    "${workspaceFolder}/src"
+  ],
   "[python]": {
     "editor.defaultFormatter": "charliermarsh.ruff"
   },
+  "python.analysis.exclude": [
+    "tests/artifacts/**"
+  ],
   "python.analysis.typeCheckingMode": "basic",
   "ruff.enable": true,
   "ruff.lint.run": "onSave",
-  "ruff.lint.args": ["--config=pyproject.toml"],
+  "ruff.lint.args": [
+    "--config=pyproject.toml"
+  ],
   "ruff.importStrategy": "fromEnvironment",
   "ruff.fixAll": true, //lint and fix all files in workspace
   "ruff.organizeImports": true, //organize imports on save
@@ -37,7 +43,6 @@
   "ruff.codeAction.fixViolation": {
     "enable": true
   },
-
   "mypy.configFile": "pyproject.toml",
   // set to empty array to use config from project
   "mypy.targets": [],
@@ -52,11 +57,7 @@
       }
     ]
   },
-
-  // PowerShell
-  "[powershell]": {
-    "editor.defaultFormatter": "ms-vscode.powershell"
-  },
-  "powershell.codeFormatting.preset": "Stroustrup",
-  "python.testing.pytestArgs": ["."]
+  "python.testing.pytestArgs": [
+    "."
+  ],
 }

README.md

@@ -1,9 +1,9 @@
 # AlgoKit Python Utilities
 
-A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand. 
+A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand.
 This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit-cli).
 
-The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand. 
+The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand.
 Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.
 
 > **Note**
@@ -19,13 +19,17 @@ This library can be installed using pip, e.g.:
 pip install algokit-utils
 ```
 
+## Migration from `v2.x` to `v3.x`
+
+Refer to the [v3 migration guide](./docs/source/v3-migration-guide.md) for more information on how to migrate to latest version of `algokit-utils-py`.
+
 ## Guiding principles
 
 This library follows the [Guiding Principles of AlgoKit](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md#guiding-principles).
 
 ## Contributing
 
-This is an open source project managed by the Algorand Foundation. 
+This is an open source project managed by the Algorand Foundation.
 See the [AlgoKit contributing page](https://github.com/algorandfoundation/algokit-cli/blob/main/CONTRIBUTING.MD) to learn about making improvements.
 
 To successfully run the tests in this repository you need to be running LocalNet via [AlgoKit](https://github.com/algorandfoundation/algokit-cli):

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd