Mcpyrate

*No user-visible changes yet.*


---

**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`.


---

**Changed**:

- Small improvements to unparser:
- No space after unary `+`, `-` or `~`.
- Future-proofing: yell if an unsupported constant value type is encountered.

- Add a new troubleshooting item on another [Heisenbug](https://en.wikipedia.org/wiki/Heisenbug) that can occur when buggy macros are used inside a `with step_expansion`.


---

**Changed**:

- Documentation improved. Particularly, AST markers are now documented (in the main user manual).


---

**New**:

- Add `temporary_module`, a context manager that uses `create_module`, and automatically removes the temporary module from `sys.modules` when the context exits.

- Add a global postprocessor hook facility. Hooks are called, in the order registered, by `global_postprocess` when the macro expansion of a module is otherwise done. This e.g. allows a macro library to use its own `ASTMarker` subclasses for internal communication between macros, and delete (only) its own markers when done. See `add_postprocessor` and `remove_postprocessor` in `mcpyrate.core`.

**Fixed**:

- Run-time part of `n[]`: upon a parse error, make it clearer in the error message that what was being compiled was an invocation of `n[]`, not the whole source file. (Because these expressions are often one-liners, usually `lineno` will be `1`, which otherwise looks confusing.)

- Fix error message in run-time typecheck of `a` (ast-unquote). Now it mentions correctly what was expected.

- Now `ASTMarker` may contain a statement suite (`list` of AST nodes) as its `body`.
- The debug mode of `mcpyrate.unparse` now renders such bodies correctly.
- `mcpyrate.markers.delete_markers` now deletes such markers correctly, splicing in the `list` of AST nodes where the marker was.


---