feat: algokit-utils-py v3 implementation [WIP DRAFT]

[aorumbayev]

Proposed changes

Work in progress ...

This PR is to be used as a temporary dev branch for all feature parity prs as we gradually progress with the refactoring efforts.

Implementation plan

• 1. Preparing codebase for breaking changes

• Moving all v2 code into legacy_v2 folder inside src

• Moving all v2 tests into legacy_v2_tests

• Moving all beta abstractions related tests into tests - which will be expanding as refactoring progresses (some tests might be pulled back from legacy_v2_tests folder).

• Keeping all individual .py files at the root of the algokit-utils to forward exports to ensure backwards compatibility

• 2. Breaking down beta module into dedicated modules that will represent the refactored v3 of utils-py

The proposed new structure is as follows:

algokit_utils/
├── __init__.py # contains old v2 exports from _legacy_v2 + new abstractions (eventually old exports will be phased out)
├── _legacy_v2/ # contents of most of current v2 .py files
├── clients/
│   ├── __init__.py
|   ├── models.py # data models specific to clients namespace 
│   ├── client_manager.py
│   ├── dispenser_api_client.py # unchanged from v2 as there are no major breaking changes
│   └── algorand_client.py
├── accounts/
│   ├── __init__.py
|   ├── models.py # data models specific to accounts namespace 
│   └── account_manager.py
├── assets/
│   ├── __init__.py
|   ├── models.py # data models specific to assets namespace 
│   └── assets_manager.py
├── applications/
│   ├── __init__.py
|   ├── models.py # data models specific to applications namespace 
│   ├── app_manager.py
│   ├── app_deployer.py
│   ├── app_client.py
│   └── app_factory.py
├── transactions/
│   ├── __init__.py
|   ├── models.py # data models specific to transactions namespace 
│   ├── transaction_sender.py
│   └── transaction_creator.py
│   └── transaction_composer.py
├── models/
│   ├── __init__.py # currently exposes contents of old models.py which resides in _legacy_v2
│   └── common.py # Any number of common models reused in at least 2 different namespaces
├── _utils/ # marked as private module
│   ├── __init__.py
│   ├── debugging.py # previously was at the root as _debugging.py, instead it will now reside in a private _utils namespace, this is partly to also avoid awkward `from algokit_utils.utils` statements, all utils exposed to end user in _utils would need to be explicitly exported via `__all__` dunder in root `__init__.py`
│   └── ... any other misc # of .py files for commonly used methods
├── errors/
│   ├── __init__.py
│   ├── ... # any other custom errors which may benefit from extracting into separate module
│   └── logic_error.py
├── config.py # unchanged from v2 as there are no major breaking changes
└── ... `account.py` `application_client.py` and other legacy files all re exporting contents from `_legacy_v2` folder which contains the v2 abstractions -> required to insure backwards compatibility after users upgrade to this version AND to establish clear boundary between old vs new abstractions

• New abstractions are significantly more type heavy, the v2 of utils-py contained a module named models at the root represented as a file, its turned into a folder now and re exposes the old legacy models, however the intent is to reuse it and later add more granular files inside for various abstractions (assets, apps, and etc)

• Note that some files from legacy_v2 and/or root .py files that expose the contents of legacy_v2 for backwards compatibility will be resurrected and repurposed (if it will make sense, similar to what was done with models.py -> models folder)

• 3. Implement TransactionComposer (previously AlgoKitComposer) and any dependant abstractions

PR in progress - #120

• 4. ... to be defined along with other steps

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/algokit_utils
_debugging.py	140	7	95%	20, 41, 76, 80, 89, 129, 157
application_client.py	1	1	0%	1
config.py	51	18	65%	38–39, 50, 55, 60, 64–69, 100–109
deploy.py	1	1	0%	1
logic_error.py	1	1	0%	1
src/algokit_utils/_legacy_v2
_ensure_funded.py	69	1	99%	99
_transfer.py	67	3	96%	13, 76–77
account.py	85	13	85%	14–17, 61–65, 96, 109, 136, 139, 183
application_client.py	528	77	85%	59–60, 167, 172, 201, 313, 318–319, 321, 323, 788, 803, 821–824, 914, 954, 966, 979, 1021, 1081–1087, 1091–1096, 1098, 1134, 1141, 1254, 1284, 1298, 1336–1338, 1340, 1350–1407, 1418–1423, 1443–1446
application_specification.py	97	11	89%	92, 94, 193–202, 206
asset.py	79	5	94%	9, 27–30
common.py	13	1	92%	13
deploy.py	463	25	95%	30–33, 168, 172–173, 190, 246, 362–363, 418, 429–437, 454–457, 467, 475, 668–669, 693
logic_error.py	39	2	95%	8, 31
models.py	131	6	95%	45, 50–52, 61–62
network_clients.py	63	3	95%	93–94, 125
src/algokit_utils/accounts
account_manager.py	55	14	75%	39–40, 64, 94–101, 131–135, 138–140
src/algokit_utils/clients
algorand_client.py	101	15	85%	112–113, 122–123, 144–146, 155–156, 225, 260, 275, 291, 304, 320
client_manager.py	37	10	73%	30, 51–53, 58–60, 65–68
dispenser_api_client.py	82	12	85%	112–113, 117–120, 155–157, 176–178
src/algokit_utils/transactions
transaction_composer.py	320	71	78%	251–252, 255–256, 259–260, 263–264, 271–272, 275–276, 305, 307, 309, 312, 315, 320, 323, 327, 330, 372–405, 410–421, 426–432, 437–445, 465–478, 482, 506, 509–526, 534, 559, 575–576, 578–579, 581–582, 584–585, 587–588, 594–598
TOTAL	2444	297	88%

Tests	Skipped	Failures	Errors	Time
204	0 💤	0 ❌	0 🔥	2m 39s ⏱️

[aorumbayev]

@neilcampbell @robdmoore , please note the bit around proposal with each folder having its own models.py might be revised. As im implementing the composer and moving out some of the legacy abstractions back to root models folder i might have to ditch the initial models per folder idea and create files account, transaction and etc under root models so that all models are under one namespace but primarily to avoid circular imports for abstractions that were moved out from legacy but are also used within legacy code (instead of duplicating them which i think can lead to bigger issues)