Mcpyrate

*No user-visible changes yet.*


---

**Fixed**

- Fix interactive console failing on macro imports.
- Now `__init__.py` imports `mcpyrate.activate` as soon as possible.
- Neither in-tree tests nor the CI automation detected this. It was only when running `macropython -i` (or IPython with the `mcpyrate.repl.iconsole` extension) in a separate terminal window, against an installed `mcpyrate`, that this error came up.
- For those arriving from Google, the error message was: `ImportError: cannot import name 'macros' from 'mcpyrate.quotes'`


---

**IMPORTANT**:

- Minimum Python language version is now 3.8.
- We support 3.8, 3.9, 3.10, 3.11, 3.12, and PyPy3 (language versions 3.8, 3.9, and 3.10).
- Python 3.6 and 3.7 support dropped, as these language versions have officially reached end-of-life. If you need `mcpyrate` for Python 3.6 or 3.7, use version 3.6.1.


**New**:

- **Python 3.12 support**.
- Support the `type` statement (Python 3.12 type alias) when fixing `ctx` attributes in the global postprocess pass.
- The unparser now supports the `type` statement (Python 3.12 type alias).
- Please note that I pretty much don't use the static typing features of Python myself. This is implemented following the spec, but testing has been rather minimal, so bug reports are welcome!
- For the curious, the relevant parts of the official Python documentation are:
- https://docs.python.org/3/library/ast.html#type-parameters
- https://docs.python.org/3/library/ast.html#ast.TypeAlias
- https://docs.python.org/3/library/ast.html#ast.TypeVar
- https://docs.python.org/3/library/ast.html#ast.ParamSpec
- https://docs.python.org/3/library/ast.html#ast.TypeVarTuple
- https://docs.python.org/3/library/typing.html#typing.TypeVar
- https://docs.python.org/3/library/typing.html#typing.ParamSpec
- https://docs.python.org/3/library/typing.html#typing.TypeVarTuple

- **Python 3.11 support**.
- Consider also `end_lineno` and `end_col_offset` when fixing AST locations in the global postprocess pass.
- This is literally the only thing we currently do with `end_lineno` and `end_col_offset`.
- Python 3.11's AST validator (now part of the CPython compiler as of 3.11+) checks e.g. that `end_lineno >= lineno`.
- The unparser now supports the `try`/`except*` construct (Python 3.11 exception groups).

- New module `mcpyrate.astcompat`, moved from `unpythonic.syntax.astcompat`. This module handles version differences in the `ast` module in various versions of Python.


**Fixed**:

- Fix https://github.com/Technologicat/mcpyrate/issues/41. The unparser now supports `match`/`case` (Python 3.10 pattern matching).
- Fix bug in unparser: a class definition with no bases or keywords should not emit parentheses after the class name.
- Fix bug in `rename`: rename also in `global` and `nonlocal` declarations, and (Python 3.10+) in `match`/`case` captures.
- Update links in relevant parts of `mcpyrate` documentation to point to Python's official AST documentation instead of GTS (Green Tree Snakes).
- Nowadays Python has proper [AST documentation](https://docs.python.org/3/library/ast.html).
- Thus the separate GTS resource is no longer needed, and is effectively dead as of September 2024.


---

**Fixed**:

- Fix https://github.com/Technologicat/mcpyrate/issues/33, with thanks to set-soft. That is, `distutils` is no longer required.


---

**Added**:

- Python 3.10 support.
- Add block macro `mcpyrate.metatools.expand_first`. This can be used to force, within the `with expand_first[macro0, ...]:` block, the given macros to expand before others. Macros can be specified either by name (will be looked up in the current expander's bindings) or by hygienic capture. See [examples in unit tests](mcpyrate/test/test_quotes.py).
- Add function `mcpyrate.utils.get_lineno` to conveniently extract a `lineno` from an AST-node-ish thing, no matter if that thing is an actual AST node, a list of AST nodes (i.e. statement suite), or an AST marker containing either of those, possibly recursively.
- Facilitate programmatic inspection of the whole public API of `mcpyrate`. See the recipes in [troubleshooting](doc/troubleshooting.md).
- This is an interim solution while we decide whether to start supporting [Sphinx](https://www.sphinx-doc.org/en/master/) at some point, so that we could auto-generate proper API docs from the docstrings (which are carefully maintained, and already contain all the necessary content).


**Fixed**:

- Fix https://github.com/Technologicat/mcpyrate/issues/29, with thanks to set-soft and brathis for reporting. **`mcpyrate` should now support Python 3.10.**
- Dialect subsystem fixes.
- Fix https://github.com/Technologicat/mcpyrate/issues/30, thus extending the fix of #28 (in the previous release) into the dialect subsystem, too.
- `__future__` imports are accounted for both the dialect template and in user code that invokes the template.
- This is implemented in the utility function `mcpyrate.splicing.splice_dialect`, so if your dialect definition uses that function in its AST transformer, now your dialect should not choke when the template and/or the user code have `__future__` imports.
- Fix https://github.com/Technologicat/mcpyrate/issues/31; the dialect machinery now has the infrastructure to pass in the source location info of the dialect-import statement.
- This allows dialects to mark any lines coming from the dialect template as effectively coming from the line that contains the dialect-import. If you import one dialect per line, this makes it easy to see which lines of the expanded code were injected by which dialect, for debugging purposes. (Recall that you can use the `StepExpansion` dialect from `mcpyrate.debug` to see the line numbers before and after dialect expansion.)
- During dialect expansion, `DialectExpander` automatically makes this info available in `self.lineno` and `self.col_offset` of your dialect definition (i.e. in the instance of your subclass of `Dialect`, which has the transformer methods). In your AST transformer, you can pass these to `mcpyrate.splicing.splice_dialect`.
- See updated example dialects in [`unpythonic.dialects`](https://github.com/Technologicat/unpythonic/tree/master/unpythonic/dialects).
- Fix handling of rare case where the dialect template consists of a single statement that is not wrapped in a list.
- Docstring of `mcpyrate.utils.NestingLevelTracker` now has usage examples.


---

**Fixed**:

- Fix https://github.com/Technologicat/mcpyrate/issues/28, with thanks to geezmolycos for reporting. Using `__future__` imports when multiphase compilation is enabled no longer causes `SyntaxError`.


---