feat: puya debugging support (#106)

* refactor: disable persisting sources.avm.json by default; deprecate `persist_sourcemaps`

* docs: refresh docs

* chore: tweak docs

* chore: pip audit

* chore: bump deprecation version

* chore: updating teal.tok.map to teal.map extension

* fix: set state_change to true in simulate_response method

* chore: removing the # delimeter from trace file names

* chore: remove sources.avm.json generation as part of persist sourcemaps

* fix: filename generation for trace files and add a unit test

docs/html/_sources/apidocs/algokit_utils/algokit_utils.md.txt

@@ -1795,7 +1795,7 @@ Bases: {py:obj}`algokit_utils._transfer.TransferParametersBase`
 ````
 
 
-````{py:function} persist_sourcemaps(*, sources: list[algokit_utils._debugging.PersistSourceMapInput], project_root: pathlib.Path, client: algosdk.v2client.algod.AlgodClient, with_sources: bool = True) -> None
+````{py:function} persist_sourcemaps(*, sources: list[algokit_utils._debugging.PersistSourceMapInput], project_root: pathlib.Path, client: algosdk.v2client.algod.AlgodClient, with_sources: bool = True, persist_mappings: bool = False) -> None
 :canonical: algokit_utils._debugging.persist_sourcemaps
 
 ```{autodoc2-docstring} algokit_utils._debugging.persist_sourcemaps

docs/html/_sources/capabilities/debugger.md.txt

@@ -6,11 +6,11 @@ The AlgoKit Python Utilities package provides a set of debugging tools that can
 
 The `config.py` file contains the `UpdatableConfig` class which manages and updates configuration settings for the AlgoKit project. The class has the following attributes:
 
--   `debug`: Indicates whether debug mode is enabled.
--   `project_root`: The path to the project root directory. Can be ignored if you are using `algokit_utils` inside an `algokit` compliant project (containing `.algokit.toml` file). For non algokit compliant projects, simply provide the path to the folder where you want to store sourcemaps and traces to be used with [`AlgoKit AVM Debugger`](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). Alternatively you can also set the value via the `ALGOKIT_PROJECT_ROOT` environment variable.
--   `trace_all`: Indicates whether to trace all operations. Defaults to false, this means that when debug mode is enabled, any (or all) application client calls performed via `algokit_utils` will store responses from `simulate` endpoint. These files are called traces, and can be used with `AlgoKit AVM Debugger` to debug TEAL source codes, transactions in the atomic group and etc.
--   `trace_buffer_size_mb`: The size of the trace buffer in megabytes. By default uses 256 megabytes. When output folder containing debug trace files exceedes the size, oldest files are removed to optimize for storage consumption.
--   `max_search_depth`: The maximum depth to search for a an `algokit` config file. By default it will traverse at most 10 folders searching for `.algokit.toml` file which will be used to assume algokit compliant project root path.
+- `debug`: Indicates whether debug mode is enabled.
+- `project_root`: The path to the project root directory. Can be ignored if you are using `algokit_utils` inside an `algokit` compliant project (containing `.algokit.toml` file). For non algokit compliant projects, simply provide the path to the folder where you want to store sourcemaps and traces to be used with [`AlgoKit AVM Debugger`](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). Alternatively you can also set the value via the `ALGOKIT_PROJECT_ROOT` environment variable.
+- `trace_all`: Indicates whether to trace all operations. Defaults to false, this means that when debug mode is enabled, any (or all) application client calls performed via `algokit_utils` will store responses from `simulate` endpoint. These files are called traces, and can be used with `AlgoKit AVM Debugger` to debug TEAL source codes, transactions in the atomic group and etc.
+- `trace_buffer_size_mb`: The size of the trace buffer in megabytes. By default uses 256 megabytes. When output folder containing debug trace files exceedes the size, oldest files are removed to optimize for storage consumption.
+- `max_search_depth`: The maximum depth to search for a an `algokit` config file. By default it will traverse at most 10 folders searching for `.algokit.toml` file which will be used to assume algokit compliant project root path.
 
 The `configure` method can be used to set these attributes.
 
@@ -26,8 +26,7 @@ config.configure(debug=True)
 
 Debugging utilities can be used to simplify gathering artifacts to be used with [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) in non algokit compliant projects. The following methods are provided:
 
--   `persist_sourcemaps`: This method persists the sourcemaps for the given sources as AVM Debugger compliant artifacts. It takes a list of `PersistSourceMapInput` objects, a `Path` object representing the root directory of the project, an `AlgodClient` object for interacting with the Algorand blockchain, and a boolean indicating whether to dump teal source files along with sourcemaps.
--   `simulate_and_persist_response`: This method simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object, and persists the simulation response to an AVM Debugger compliant JSON file. It takes an `AtomicTransactionComposer` object representing the atomic transactions to be simulated and persisted, a `Path` object representing the root directory of the project, an `AlgodClient` object representing the Algorand client, and a float representing the size of the trace buffer in megabytes.
+- `simulate_and_persist_response`: This method simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object, and persists the simulation response to an AVM Debugger compliant JSON file. It takes an `AtomicTransactionComposer` object representing the atomic transactions to be simulated and persisted, a `Path` object representing the root directory of the project, an `AlgodClient` object representing the Algorand client, and a float representing the size of the trace buffer in megabytes.
 
 ### Trace filename format
 
@@ -39,8 +38,8 @@ The trace files are named in a specific format to provide useful information abo
 
 Where:
 
--   `timestamp`: The time when the trace file was created, in ISO 8601 format, with colons and periods removed.
--   `last_round`: The last round when the simulation was performed.
--   `transaction_types`: A string representing the types and counts of transactions in the atomic group. Each transaction type is represented as `${count}#${type}`, and different transaction types are separated by underscores.
+- `timestamp`: The time when the trace file was created, in ISO 8601 format, with colons and periods removed.
+- `last_round`: The last round when the simulation was performed.
+- `transaction_types`: A string representing the types and counts of transactions in the atomic group. Each transaction type is represented as `${count}${type}`, and different transaction types are separated by underscores.
 
-For example, a trace file might be named `20220301T123456Z_lr1000_2#pay_1#axfer.trace.avm.json`, indicating that the trace file was created at `2022-03-01T12:34:56Z`, the last round was `1000`, and the atomic group contained 2 payment transactions and 1 asset transfer transaction.
+For example, a trace file might be named `20220301T123456Z_lr1000_2pay_1axfer.trace.avm.json`, indicating that the trace file was created at `2022-03-01T12:34:56Z`, the last round was `1000`, and the atomic group contained 2 payment transactions and 1 asset transfer transaction.

docs/html/apidocs/algokit_utils/algokit_utils.html

@@ -1534,14 +1534,16 @@ <h3>Example<a class="headerlink" href="#example" title="Permalink to this headin
 
 <dl class="py function">
 <dt class="sig sig-object py" id="algokit_utils.persist_sourcemaps">
-<span class="sig-prename descclassname"><span class="pre">algokit_utils.</span></span><span class="sig-name descname"><span class="pre">persist_sourcemaps</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sources</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.13)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><span class="pre">algokit_utils._debugging.PersistSourceMapInput</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">project_root</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path" title="(in Python v3.13)"><span class="pre">pathlib.Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">client</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/v2client/algod.html#algosdk.v2client.algod.AlgodClient" title="(in algosdk)"><span class="pre">algosdk.v2client.algod.AlgodClient</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">with_sources</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="headerlink" href="#algokit_utils.persist_sourcemaps" title="Permalink to this definition"></a></dt>
+<span class="sig-prename descclassname"><span class="pre">algokit_utils.</span></span><span class="sig-name descname"><span class="pre">persist_sourcemaps</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sources</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.13)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><span class="pre">algokit_utils._debugging.PersistSourceMapInput</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">project_root</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path" title="(in Python v3.13)"><span class="pre">pathlib.Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">client</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/v2client/algod.html#algosdk.v2client.algod.AlgodClient" title="(in algosdk)"><span class="pre">algosdk.v2client.algod.AlgodClient</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">with_sources</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">persist_mappings</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="headerlink" href="#algokit_utils.persist_sourcemaps" title="Permalink to this definition"></a></dt>
 <dd><p>Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts.
 Args:
 sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects.
 project_root (Path): The root directory of the project.
 client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
 with_sources (bool): If True, it will dump teal source files along with sourcemaps.
-Default is True, as needed by an AlgoKit AVM debugger.</p>
+Default is True, as needed by an AlgoKit AVM debugger.
+persist_mappings (bool): Enables legacy behavior of persisting the <code class="docutils literal notranslate"><span class="pre">sources.avm.json</span></code> mappings to
+the project root. Default is False, given that the AlgoKit AVM VSCode extension will manage the mappings.</p>
 </dd></dl>
 
 <dl class="py function">

docs/html/capabilities/debugger.html

@@ -110,7 +110,6 @@ <h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to
 <h2>Debugging Utilities<a class="headerlink" href="#debugging-utilities" title="Permalink to this heading"></a></h2>
 <p>Debugging utilities can be used to simplify gathering artifacts to be used with <a class="reference external" href="https://github.com/algorandfoundation/algokit-avm-vscode-debugger">AlgoKit AVM Debugger</a> in non algokit compliant projects. The following methods are provided:</p>
 <ul class="simple">
-<li><p><code class="docutils literal notranslate"><span class="pre">persist_sourcemaps</span></code>: This method persists the sourcemaps for the given sources as AVM Debugger compliant artifacts. It takes a list of <code class="docutils literal notranslate"><span class="pre">PersistSourceMapInput</span></code> objects, a <code class="docutils literal notranslate"><span class="pre">Path</span></code> object representing the root directory of the project, an <code class="docutils literal notranslate"><span class="pre">AlgodClient</span></code> object for interacting with the Algorand blockchain, and a boolean indicating whether to dump teal source files along with sourcemaps.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">simulate_and_persist_response</span></code>: This method simulates the atomic transactions using the provided <code class="docutils literal notranslate"><span class="pre">AtomicTransactionComposer</span></code> object and <code class="docutils literal notranslate"><span class="pre">AlgodClient</span></code> object, and persists the simulation response to an AVM Debugger compliant JSON file. It takes an <code class="docutils literal notranslate"><span class="pre">AtomicTransactionComposer</span></code> object representing the atomic transactions to be simulated and persisted, a <code class="docutils literal notranslate"><span class="pre">Path</span></code> object representing the root directory of the project, an <code class="docutils literal notranslate"><span class="pre">AlgodClient</span></code> object representing the Algorand client, and a float representing the size of the trace buffer in megabytes.</p></li>
 </ul>
 <section id="trace-filename-format">
@@ -123,9 +122,9 @@ <h3>Trace filename format<a class="headerlink" href="#trace-filename-format" tit
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">timestamp</span></code>: The time when the trace file was created, in ISO 8601 format, with colons and periods removed.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">last_round</span></code>: The last round when the simulation was performed.</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">transaction_types</span></code>: A string representing the types and counts of transactions in the atomic group. Each transaction type is represented as <code class="docutils literal notranslate"><span class="pre">${count}#${type}</span></code>, and different transaction types are separated by underscores.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">transaction_types</span></code>: A string representing the types and counts of transactions in the atomic group. Each transaction type is represented as <code class="docutils literal notranslate"><span class="pre">${count}${type}</span></code>, and different transaction types are separated by underscores.</p></li>
 </ul>
-<p>For example, a trace file might be named <code class="docutils literal notranslate"><span class="pre">20220301T123456Z_lr1000_2#pay_1#axfer.trace.avm.json</span></code>, indicating that the trace file was created at <code class="docutils literal notranslate"><span class="pre">2022-03-01T12:34:56Z</span></code>, the last round was <code class="docutils literal notranslate"><span class="pre">1000</span></code>, and the atomic group contained 2 payment transactions and 1 asset transfer transaction.</p>
+<p>For example, a trace file might be named <code class="docutils literal notranslate"><span class="pre">20220301T123456Z_lr1000_2pay_1axfer.trace.avm.json</span></code>, indicating that the trace file was created at <code class="docutils literal notranslate"><span class="pre">2022-03-01T12:34:56Z</span></code>, the last round was <code class="docutils literal notranslate"><span class="pre">1000</span></code>, and the atomic group contained 2 payment transactions and 1 asset transfer transaction.</p>
 </section>
 </section>
 </section>

docs/markdown/apidocs/algokit_utils/algokit_utils.md

@@ -1049,7 +1049,7 @@ Returns:
 dict[int, str]: A dictionary where the keys are the asset IDs and the values are the transaction IDs of
 the executed transactions.
 
-### algokit_utils.persist_sourcemaps(\*, sources: [list](https://docs.python.org/3/library/stdtypes.html#list)[algokit_utils._debugging.PersistSourceMapInput], project_root: [pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path), client: [algosdk.v2client.algod.AlgodClient](https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/v2client/algod.html#algosdk.v2client.algod.AlgodClient), with_sources: [bool](https://docs.python.org/3/library/functions.html#bool) = True) → [None](https://docs.python.org/3/library/constants.html#None)
+### algokit_utils.persist_sourcemaps(\*, sources: [list](https://docs.python.org/3/library/stdtypes.html#list)[algokit_utils._debugging.PersistSourceMapInput], project_root: [pathlib.Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path), client: [algosdk.v2client.algod.AlgodClient](https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/v2client/algod.html#algosdk.v2client.algod.AlgodClient), with_sources: [bool](https://docs.python.org/3/library/functions.html#bool) = True, persist_mappings: [bool](https://docs.python.org/3/library/functions.html#bool) = False) → [None](https://docs.python.org/3/library/constants.html#None)
 
 Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts.
 Args:
@@ -1058,6 +1058,8 @@ project_root (Path): The root directory of the project.
 client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
 with_sources (bool): If True, it will dump teal source files along with sourcemaps.
 Default is True, as needed by an AlgoKit AVM debugger.
+persist_mappings (bool): Enables legacy behavior of persisting the `sources.avm.json` mappings to
+the project root. Default is False, given that the AlgoKit AVM VSCode extension will manage the mappings.
 
 ### algokit_utils.replace_template_variables(program: [str](https://docs.python.org/3/library/stdtypes.html#str), template_values: [algokit_utils.deploy.TemplateValueMapping](#algokit_utils.TemplateValueMapping)) → [str](https://docs.python.org/3/library/stdtypes.html#str)