feat: algokit-utils-py v3 implementation

[aorumbayev]

Proposed changes

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

Implemented in: #120

• 4. Implementing AppFactory, AppClient and AppDeployer abstractions

Implemented and refined in: #127

• 5. Initial documentation

Implemented in: #128

• 6. Refined documentation and deprecation warning instructions

Work in progress

• 7. Addressing final batch of suggestions/feedback

Work in progress

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/algokit_utils
_debugging.py	141	18	87%	21, 40–42, 45, 54, 62, 81, 87, 96, 110–114, 133, 141–143
account.py	3	3	0%	1–12
algorand.py	98	15	85%	62–63, 74–75, 95–96, 108–110, 119–120, 214, 234, 247, 263
application_client.py	3	3	0%	1–11
application_specification.py	7	7	0%	1–39
config.py	89	18	80%	26–28, 41, 53, 84–85, 100, 105, 110, 118–123, 153, 155, 157
deploy.py	3	3	0%	1–10
logic_error.py	3	3	0%	1–10
src/algokit_utils/_legacy_v2
_ensure_funded.py	71	1	99%	100
_transfer.py	70	3	96%	14, 75–76
account.py	93	13	86%	15–18, 70–74, 109, 126, 156, 159, 203
application_client.py	536	77	86%	56–57, 175, 180, 209, 321, 326–327, 329, 331, 800, 815, 833–836, 930, 970, 982, 995, 1037, 1097–1103, 1107–1112, 1114, 1150, 1157, 1270, 1306, 1320, 1358–1360, 1362, 1372–1429, 1440–1445, 1465–1468
asset.py	80	4	95%	24–27
common.py	13	1	92%	13
deploy.py	407	22	95%	32–35, 170, 174–175, 193, 249, 339–340, 361, 395, 406–414, 429, 437, 593–594, 618
network_clients.py	73	5	93%	77–78, 101–102, 135
src/algokit_utils/accounts
account_manager.py	213	33	85%	162, 181–182, 206–211, 229–230, 247, 264–269, 316–318, 347, 386, 406–410, 423, 482, 503, 660, 766, 845, 850, 869–870, 893
kmd_account_manager.py	72	8	89%	49–53, 94, 150, 157
src/algokit_utils/applications
abi.py	130	71	45%	14, 74, 110, 116, 118, 120, 124–125, 140–159, 175, 178–184, 200–213, 226–238, 253–264
app_client.py	720	211	71%	65–73, 131, 139, 401–404, 407, 410, 413, 416, 428–431, 434, 437, 440, 443, 455, 464, 473, 476–543, 556–614, 638–640, 657–660, 668–671, 679–682, 690–693, 701–704, 715–718, 731, 829–832, 866, 878, 890, 902, 914, 929, 944, 954, 964, 974, 984, 994, 1031–1044, 1060, 1077, 1094, 1111, 1132, 1153, 1243, 1388, 1435–1436, 1467, 1469, 1475, 1520–1528, 1561–1564, 1567–1570, 1591, 1639, 1713–1720, 1761, 1778, 1780, 1783, 1787, 1914, 1925–1926, 1949, 1959–1961, 1964–1986, 1996, 2005–2020, 2025–2030
app_deployer.py	209	40	81%	97, 195, 202, 212–217, 220–224, 262–276, 291–292, 481–494, 504, 509, 515, 521–523, 530, 544, 555–596
app_factory.py	269	27	90%	357, 367, 370, 514, 522, 534, 683, 697–702, 708–709, 727, 752, 763–764, 800, 808–822
app_manager.py	218	16	93%	226, 285–286, 318–323, 349, 367–368, 398, 419–422, 445, 454
src/algokit_utils/applications/app_spec
arc32.py	95	8	92%	198–207
arc56.py	470	36	92%	72–74, 183, 318, 336–337, 415, 437–439, 495, 504, 506, 574, 769, 779, 783, 943, 945, 978–989, 1002, 1004–1005, 1021
src/algokit_utils/assets
asset_manager.py	106	12	89%	266–267, 276, 282–306, 316
src/algokit_utils/clients
client_manager.py	176	54	69%	24–26, 74–81, 95, 127–129, 185, 196–199, 224, 263, 298–303, 338–340, 370, 388, 407, 441–444, 477–480, 514–517, 547–550, 568–593, 623, 632, 640
dispenser_api_client.py	83	12	86%	126–127, 131–134, 169–171, 190–192
src/algokit_utils/errors
logic_error.py	56	11	80%	14, 105–121
src/algokit_utils/models
account.py	86	12	86%	30, 32, 123, 131, 155–162, 176–177, 185, 193
amount.py	107	15	86%	119, 129, 135, 143, 148–150, 157, 162–164, 171, 178, 191, 197
application.py	42	1	98%	8
state.py	36	5	86%	51, 55–58
transaction.py	51	3	94%	66, 86, 91
src/algokit_utils/protocols
account.py	11	2	82%	17, 22
typed_clients.py	24	4	83%	12–24
src/algokit_utils/transactions
transaction_composer.py	952	130	86%	35–42, 620, 623, 628, 632–643, 675, 716, 783, 790, 806, 839, 902–965, 994, 1012–1014, 1020–1035, 1040, 1048, 1050, 1052, 1068, 1074, 1109–1116, 1119–1126, 1137, 1231, 1280, 1528–1529, 1568–1569, 1608, 1659–1663, 1819, 1822, 1841, 1846, 1870–1872, 1909–1945, 1952–1959, 2108, 2111, 2239, 2241–2242, 2292–2293
transaction_creator.py	75	7	91%	116, 121, 126, 131, 136, 141, 156
transaction_sender.py	148	10	93%	88, 243, 286–287, 431–436, 441–442, 487
TOTAL	6265	924	85%

Tests	Skipped	Failures	Errors	Time
396	0 💤	0 ❌	0 🔥	4m 35s ⏱️

[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)

[neilcampbell]

Still working through the code.