` ([500ed1b](https://github.com/pawamoy/markdown-exec/commit/500ed1b3a6bb94edd3d5d7152cd818bc3db27bbd) by Timothée Mazzucotelli).
## [1.8.3](https://github.com/pawamoy/markdown-exec/releases/tag/1.8.3) - 2024-05-22
[Compare with 1.8.2](https://github.com/pawamoy/markdown-exec/compare/1.8.2...1.8.3)
### Bug Fixes
- Don't leak future annotations in user code ([ba0c35e](https://github.com/pawamoy/markdown-exec/commit/ba0c35e89e3056325b3dcbc7e61b6f108ec55885) by Timothée Mazzucotelli). [Issue-47](https://github.com/pawamoy/markdown-exec/issues/47)
## [1.8.2](https://github.com/pawamoy/markdown-exec/releases/tag/1.8.2) - 2024-05-20
[Compare with 1.8.1](https://github.com/pawamoy/markdown-exec/compare/1.8.1...1.8.2)
### Bug Fixes
- Give `__name__` to executed Python "modules", and populate `sys.modules` too ([db25ee7](https://github.com/pawamoy/markdown-exec/commit/db25ee703da9b70cb4a13b2b4b61634d697119c4) by Timothée Mazzucotelli). [Issue-47](https://github.com/pawamoy/markdown-exec/issues/47)
## [1.8.1](https://github.com/pawamoy/markdown-exec/releases/tag/1.8.1) - 2024-04-15
[Compare with 1.8.0](https://github.com/pawamoy/markdown-exec/compare/1.8.0...1.8.1)
### Bug Fixes
- Add missing CSS classes to the ANSI stylesheet ([51493f2](https://github.com/pawamoy/markdown-exec/commit/51493f255dd91f28ce6c8d7e7176ec5687e28b4a) by Timothée Mazzucotelli). [Issue-43](https://github.com/pawamoy/markdown-exec/issues/43)
## [1.8.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.8.0) - 2024-01-05
[Compare with 1.7.0](https://github.com/pawamoy/markdown-exec/compare/1.7.0...1.8.0)
### Features
- Add `pyodide` fence ([3a2fab0](https://github.com/pawamoy/markdown-exec/commit/3a2fab0b23196a4122bcee6d9b81d3f421f11bbb) by Timothée Mazzucotelli).
- Add `ansi` option to mark ANSI extra as required or not ([27743c2](https://github.com/pawamoy/markdown-exec/commit/27743c20f56dd00ce730e1d028d362a4f95e48c7) by Timothée Mazzucotelli). [Issue #28](https://github.com/pawamoy/markdown-exec/issues/28), [Issue #29](https://github.com/pawamoy/markdown-exec/issues/29)
### Code Refactoring
- Modernize MkDocs plugin ([4864608](https://github.com/pawamoy/markdown-exec/commit/48646081746c6c5ece0c6566a4b9733ace518791) by Timothée Mazzucotelli).
## [1.7.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.7.0) - 2023-10-17
[Compare with 1.6.0](https://github.com/pawamoy/markdown-exec/compare/1.6.0...1.7.0)
### Features
- Set `MKDOCS_CONFIG_DIR` environment variable to build file path relative to it ([a2cbea5](https://github.com/pawamoy/markdown-exec/commit/a2cbea52d39ef43960c910830eae14dc846624d0) by Timothée Mazzucotelli).
## [1.6.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.6.0) - 2023-04-18
[Compare with 1.5.3](https://github.com/pawamoy/markdown-exec/compare/1.5.3...1.6.0)
### Features
- Add `idprefix` option allowing to change/remove HTML id/href prefixes ([4d91463](https://github.com/pawamoy/markdown-exec/commit/4d914630e5642feb87103644800d3c9f7b59c6ad) by Timothée Mazzucotelli).
## [1.5.3](https://github.com/pawamoy/markdown-exec/releases/tag/1.5.3) - 2023-04-18
[Compare with 1.5.2](https://github.com/pawamoy/markdown-exec/compare/1.5.2...1.5.3)
### Code Refactoring
- Reuse Markdown configuration as declared in mkdocs.yml ([afe091c](https://github.com/pawamoy/markdown-exec/commit/afe091caa33ed54fd65e25e4f90b8b60786ba3f9) by Timothée Mazzucotelli).
## [1.5.2](https://github.com/pawamoy/markdown-exec/releases/tag/1.5.2) - 2023-04-18
[Compare with 1.5.1](https://github.com/pawamoy/markdown-exec/compare/1.5.1...1.5.2)
### Code Refactoring
- Reset counter in post build event ([3bf80de](https://github.com/pawamoy/markdown-exec/commit/3bf80deabe9a7438b459c73e962c9693bce71135) by Timothée Mazzucotelli).
## [1.5.1](https://github.com/pawamoy/markdown-exec/releases/tag/1.5.1) - 2023-04-17
[Compare with 1.5.0](https://github.com/pawamoy/markdown-exec/compare/1.5.0...1.5.1)
### Bug Fixes
- Remove pycon output lines when rendering source as console ([fb5a23d](https://github.com/pawamoy/markdown-exec/commit/fb5a23d8d1d50aa2a1ede97150c269a07fa200ec) by Timothée Mazzucotelli).
- Fix nested rendering ([a110d44](https://github.com/pawamoy/markdown-exec/commit/a110d446209b390ec8a4ad8868818352f72a9808) by Timothée Mazzucotelli).
## [1.5.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.5.0) - 2023-04-17
[Compare with 1.4.1](https://github.com/pawamoy/markdown-exec/compare/1.4.1...1.5.0)
### Features
- Update ToC with generated headings ([5ea2263](https://github.com/pawamoy/markdown-exec/commit/5ea2263d53729b6d3e79da69c29b171bb6c3e22d) by Timothée Mazzucotelli).
## [1.4.1](https://github.com/pawamoy/markdown-exec/releases/tag/1.4.1) - 2023-04-16
[Compare with 1.4.0](https://github.com/pawamoy/markdown-exec/compare/1.4.0...1.4.1)
### Bug Fixes
- Improve handling of errors within sessions ([87ac5f3](https://github.com/pawamoy/markdown-exec/commit/87ac5f352ce44370f52a7fb56d846c04b76447f9) by Timothée Mazzucotelli).
- Swallow non-extra parameters in run functions ([f5d4fef](https://github.com/pawamoy/markdown-exec/commit/f5d4fef1f78d94c3f8850f873076e3cd68c0a981) by Timothée Mazzucotelli).
### Code Refactoring
- Simplify tree formatter signature ([09d5427](https://github.com/pawamoy/markdown-exec/commit/09d542772ccb0d1250366b39fa3a9c9362e1ed42) by Timothée Mazzucotelli).
## [1.4.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.4.0) - 2023-03-15
[Compare with 1.3.0](https://github.com/pawamoy/markdown-exec/compare/1.3.0...1.4.0)
### Features
- Sessions: persist and reuse state for Python and Pycon code blocks ([a8fef5e](https://github.com/pawamoy/markdown-exec/commit/a8fef5e90b1d7165e16ff5afe4b84e8441503098) by Timothée Mazzucotelli). [Issue #16](https://github.com/pawamoy/markdown-exec/issues/16)
## [1.3.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.3.0) - 2023-02-18
[Compare with 1.2.0](https://github.com/pawamoy/markdown-exec/compare/1.2.0...1.3.0)
### Features
- Support wrapping result with console source ([268c82e](https://github.com/pawamoy/markdown-exec/commit/268c82e6f005dcaa1ddc75608d2f28927f069761) by Timothée Mazzucotelli). [Issue #13](https://github.com/pawamoy/markdown-exec/issues/13)
### Code Refactoring
- Remove margin hack from Material source ([beec237](https://github.com/pawamoy/markdown-exec/commit/beec2374b27075e66ddb4a7cdc2f2c81b7455b95) by Timothée Mazzucotelli).
- Better support pycon syntax ([22b51c6](https://github.com/pawamoy/markdown-exec/commit/22b51c64155060922e46ea10e6c0d1c1c1b00a2f) by Timothée Mazzucotelli).
## [1.2.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.2.0) - 2023-02-01
[Compare with 1.1.0](https://github.com/pawamoy/markdown-exec/compare/1.1.0...1.2.0)
### Features
- Support ANSI code blocks ([39719c5](https://github.com/pawamoy/markdown-exec/commit/39719c5d7ac1bbde6d60002082a0ad3b48730545) by Timothée Mazzucotelli). [Issue #11](https://github.com/pawamoy/markdown-exec/issues/11)
## [1.1.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.1.0) - 2023-01-27
[Compare with 1.0.0](https://github.com/pawamoy/markdown-exec/compare/1.0.0...1.1.0)
### Features
- Log details to help debugging errors ([4c0228d](https://github.com/pawamoy/markdown-exec/commit/4c0228da41f5970e719b20a40c0fab47a9d12244) by Timothée Mazzucotelli). [Issue #12](https://github.com/pawamoy/markdown-exec/issues/12)
- Allow expecting specific exit codes ([620ec66](https://github.com/pawamoy/markdown-exec/commit/620ec66182dd0f84600258408720779822615085) by Timothée Mazzucotelli). [Issue #10](https://github.com/pawamoy/markdown-exec/issues/10)
### Code Refactoring
- Formatters now only accept keyword arguments ([0940ca9](https://github.com/pawamoy/markdown-exec/commit/0940ca98e81548474351e234715df2fc290fdc1e) by Timothée Mazzucotelli).
## [1.0.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.0.0) - 2022-11-24
[Compare with 0.7.4](https://github.com/pawamoy/markdown-exec/compare/0.7.4...1.0.0)
### Features
- Allow defining IDs on code blocks (for warnings) ([0091167](https://github.com/pawamoy/markdown-exec/commit/009116719e81dd91190b391c82709fb179a62364) by Timothée Mazzucotelli).
### Code Refactoring
- Use base format everywhere (more flexible) ([cefba70](https://github.com/pawamoy/markdown-exec/commit/cefba704ae45df1b115b969e3d4d5105ebd052dd) by Timothée Mazzucotelli).
## [0.7.4](https://github.com/pawamoy/markdown-exec/releases/tag/0.7.4) - 2022-11-13
[Compare with 0.7.3](https://github.com/pawamoy/markdown-exec/compare/0.7.3...0.7.4)
### Bug Fixes
- Render source for non-HTML output (regression) ([3028dcd](https://github.com/pawamoy/markdown-exec/commit/3028dcd4f20f94b578995c326fd68d53a6dc3638) by Timothée Mazzucotelli).
## [0.7.3](https://github.com/pawamoy/markdown-exec/releases/tag/0.7.3) - 2022-11-13
[Compare with 0.7.2](https://github.com/pawamoy/markdown-exec/compare/0.7.2...0.7.3)
### Bug Fixes
- Don't wrap HTML in `p` tag ([420d79d](https://github.com/pawamoy/markdown-exec/commit/420d79d67c2a6bdc925b3bc3d89790258f922317) by Timothée Mazzucotelli).
## [0.7.2](https://github.com/pawamoy/markdown-exec/releases/tag/0.7.2) - 2022-09-01
[Compare with 0.7.1](https://github.com/pawamoy/markdown-exec/compare/0.7.1...0.7.2)
### Bug Fixes
- Make `tree` formatter forward extra options ([54996a9](https://github.com/pawamoy/markdown-exec/commit/54996a9bc2c803bb8c9de0861af69723ddb000fa) by Timothée Mazzucotelli).
- Fix race condition issue ([37d7f86](https://github.com/pawamoy/markdown-exec/commit/37d7f86eeaa73029ae89c1c5d07146d2387b10d3) by Timothée Mazzucotelli).
## [0.7.1](https://github.com/pawamoy/markdown-exec/releases/tag/0.7.1) - 2022-08-28
[Compare with 0.7.0](https://github.com/pawamoy/markdown-exec/compare/0.7.0...0.7.1)
### Bug Fixes
- Allow printing non-string objects ([ceaa482](https://github.com/pawamoy/markdown-exec/commit/ceaa482d16adfbd1609595a2ed6a241bad71f9de) by Timothée Mazzucotelli). [Issue #7](https://github.com/pawamoy/markdown-exec/issues/7)
## [0.7.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.7.0) - 2022-05-28
[Compare with 0.6.0](https://github.com/pawamoy/markdown-exec/compare/0.6.0...0.7.0)
### Features
- Add ability to hide source lines ([3cb1934](https://github.com/pawamoy/markdown-exec/commit/3cb19345fa2b65478ac439b5f486d04bf5ff5337) by Timothée Mazzucotelli).
## [0.6.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.6.0) - 2022-05-21
[Compare with 0.5.0](https://github.com/pawamoy/markdown-exec/compare/0.5.0...0.6.0)
### Features
- Add tree formatter ([8096990](https://github.com/pawamoy/markdown-exec/commit/8096990dcbf6795572e5e5afee12195d5a56c6f6) by Timothée Mazzucotelli).
- Handle code blocks execution errors and log warnings ([34e16db](https://github.com/pawamoy/markdown-exec/commit/34e16db679721db7d1df375912d512b5aed80b1a) by Timothée Mazzucotelli).
### Bug Fixes
- Fix Python execution to support nested scopes ([74b9a95](https://github.com/pawamoy/markdown-exec/commit/74b9a95ade3862752fb78d6c64be8b9b1d4d3886) by Timothée Mazzucotelli).
## [0.5.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.5.0) - 2022-05-09
[Compare with 0.4.0](https://github.com/pawamoy/markdown-exec/compare/0.4.0...0.5.0)
### Features
- Allow wrapping result in code block ([37201e4](https://github.com/pawamoy/markdown-exec/commit/37201e4409badec903f311bcc0a6ab7acddff37c) by Timothée Mazzucotelli).
- Add support for shell code blocks ([f2b4b67](https://github.com/pawamoy/markdown-exec/commit/f2b4b671f4399637d0dac235a0af7739033f9526) by Timothée Mazzucotelli).
### Code Refactoring
- Fetch plugin languages from dict ([de8309e](https://github.com/pawamoy/markdown-exec/commit/de8309e6895a079031461bfea317215bcff9bc21) by Timothée Mazzucotelli).
- Add reusable base formatter ([c265bee](https://github.com/pawamoy/markdown-exec/commit/c265bee9abf0ad545b7fdc6ccf2e320071295a18) by Timothée Mazzucotelli).
## [0.4.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.4.0) - 2022-05-09
[Compare with 0.3.1](https://github.com/pawamoy/markdown-exec/compare/0.3.1...0.4.0)
### Features
- Add literate Markdown support ([8d3ed7e](https://github.com/pawamoy/markdown-exec/commit/8d3ed7ef5c9a88849be0a5da44e7b478eb44c180) by Timothée Mazzucotelli).
- Add `material-block` style to show source ([ff10ee1](https://github.com/pawamoy/markdown-exec/commit/ff10ee1f0b55b2e77b97f272b49b24024f9de2ac) by Timothée Mazzucotelli).
- Support up to 8 levels of exec code block nesting ([bfde808](https://github.com/pawamoy/markdown-exec/commit/bfde8087ca6f4eb91aba8eb01b37755dfacb4cdb) by Timothée Mazzucotelli).
## [0.3.1](https://github.com/pawamoy/markdown-exec/releases/tag/0.3.1) - 2022-05-07
[Compare with 0.3.0](https://github.com/pawamoy/markdown-exec/compare/0.3.0...0.3.1)
### Bug Fixes
- Actually prevent HTML re-rendering ([4374852](https://github.com/pawamoy/markdown-exec/commit/4374852706207beac3b8dbd8dc9d75be51b1df0d) by Timothée Mazzucotelli).
## [0.3.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.3.0) - 2022-05-01
[Compare with 0.2.0](https://github.com/pawamoy/markdown-exec/compare/0.2.0...0.3.0)
### Features
- Support `pycon` code blocks ([2c86394](https://github.com/pawamoy/markdown-exec/commit/2c86394417858654af21316c3555aff0e9fd2d26) by Timothée Mazzucotelli).
- Add `console` source integration option ([62dfd74](https://github.com/pawamoy/markdown-exec/commit/62dfd74185f7f33cdf6f4726b3aa898a1ac5d22f) by Timothée Mazzucotelli).
- Provide a MkDocs plugin for easier setup ([5fce814](https://github.com/pawamoy/markdown-exec/commit/5fce81462063b7c61d9833939e44958a466d4b24) by Timothée Mazzucotelli).
- Support changing tabs titles ([d150596](https://github.com/pawamoy/markdown-exec/commit/d150596beda1e5a5304bc06e27668294a75ff220) by Timothée Mazzucotelli).
- Allow using `print` in code blocks ([7c124fd](https://github.com/pawamoy/markdown-exec/commit/7c124fd416d6923bea2834479d972b14c3e22112) by Timothée Mazzucotelli).
- Allow passing extra opts like title to source code blocks ([bb3252a](https://github.com/pawamoy/markdown-exec/commit/bb3252a3e959cea198966ba59a70f6f5aa57a963) by Timothée Mazzucotelli).
### Code Refactoring
- Split Python formatter to allow reuse ([fc56702](https://github.com/pawamoy/markdown-exec/commit/fc56702b9c393323adc30abba42c823f601ef738) by Timothée Mazzucotelli).
- Setup a more robust Markdown converter ([395f4c4](https://github.com/pawamoy/markdown-exec/commit/395f4c4c21ab7f4afcc88250c1fd882269a06d02) by Timothée Mazzucotelli).
## [0.2.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.2.0) - 2022-04-18
[Compare with 0.1.0](https://github.com/pawamoy/markdown-exec/compare/0.1.0...0.2.0)
### Features
- Add ability to render using tabs ([91a95ae](https://github.com/pawamoy/markdown-exec/commit/91a95ae4c6ad82e85dac24a110d09ca71eff688a) by Timothée Mazzucotelli).
## [0.1.0](https://github.com/pawamoy/markdown-exec/releases/tag/0.1.0) - 2022-02-19
[Compare with first commit](https://github.com/pawamoy/markdown-exec/compare/41c8d81992d2443cd5c3418df0f461b0af1a6ec8...0.1.0)
### Features
- Implement execution of code blocks ([41c8d81](https://github.com/pawamoy/markdown-exec/commit/41c8d81992d2443cd5c3418df0f461b0af1a6ec8) by Timothée Mazzucotelli).
markdown-exec-1.10.2/CODE_OF_CONDUCT.md 0000664 0000000 0000000 00000012536 14766364173 0017166 0 ustar 00root root 0000000 0000000 # Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at dev@pawamoy.fr. All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of actions.
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations
markdown-exec-1.10.2/CONTRIBUTING.md 0000664 0000000 0000000 00000010075 14766364173 0016614 0 ustar 00root root 0000000 0000000 # Contributing
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
## Environment setup
Nothing easier!
Fork and clone the repository, then:
```bash
cd markdown-exec
make setup
```
> NOTE: If it fails for some reason, you'll need to install [uv](https://github.com/astral-sh/uv) manually.
>
> You can install it with:
>
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
>
> Now you can try running `make setup` again, or simply `uv sync`.
You now have the dependencies installed.
Run `make help` to see all the available actions!
## Tasks
The entry-point to run commands and tasks is the `make` Python script, located in the `scripts` directory. Try running `make` to show the available commands and tasks. The *commands* do not need the Python dependencies to be installed,
while the *tasks* do. The cross-platform tasks are written in Python, thanks to [duty](https://github.com/pawamoy/duty).
If you work in VSCode, we provide [an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup) for the project.
## Development
As usual:
1. create a new branch: `git switch -c feature-or-bugfix-name`
1. edit the code and/or the documentation
**Before committing:**
1. run `make format` to auto-format the code
1. run `make check` to check everything (fix any warning)
1. run `make test` to run the tests (fix any issue)
1. if you updated the documentation or the project dependencies:
1. run `make docs`
1. go to http://localhost:8000 and check that everything looks good
1. follow our [commit message convention](#commit-message-convention)
If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during review.
Don't bother updating the changelog, we will take care of this.
## Commit message convention
Commit messages must follow our convention based on the [Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message) or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html):
```
`
sponsors.forEach(function (sponsor) {
html += `
/ Bold! Bold! **Bold!**\n Bold! **Bold!**\n
If you sponsor publicly, you're automatically added here with a link to your profile and avatar to show your support for *Markdown Exec*. Alternatively, if you wish to keep your sponsorship private, you'll be a silent +1. You can select visibility during checkout and change it afterwards.
## Funding
### Goals
The following section lists all funding goals. Each goal contains a list of features prefixed with a checkmark symbol, denoting whether a feature is :octicons-check-circle-fill-24:{ style="color: #00e676" } already available or :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features are released for general availability.
```python exec="1" session="insiders" idprefix=""
for goal in goals.values():
if not goal.complete:
goal.render()
```
### Goals completed
This section lists all funding goals that were previously completed, which means that those features were part of Insiders, but are now generally available and can be used by all users.
```python exec="1" session="insiders" idprefix=""
for goal in goals.values():
if goal.complete:
goal.render()
```
## Frequently asked questions
### Compatibility
> We're building an open source project and want to allow outside collaborators to use *Markdown Exec* locally without having access to Insiders. Is this still possible?
Yes. Insiders is compatible with *Markdown Exec*. Almost all new features and configuration options are either backward-compatible or implemented behind feature flags. Most Insiders features enhance the overall experience, though while these features add value for the users of your project, they shouldn't be necessary for previewing when making changes to content.
### Payment
> We don't want to pay for sponsorship every month. Are there any other options?
Yes. You can sponsor on a yearly basis by [switching your GitHub account to a yearly billing cycle][billing cycle]. If for some reason you cannot do that, you could also create a dedicated GitHub account with a yearly billing cycle, which you only use for sponsoring (some sponsors already do that).
If you have any problems or further questions, please reach out to insiders@pawamoy.fr.
### Terms
> Are we allowed to use Insiders under the same terms and conditions as *Markdown Exec*?
Yes. Whether you're an individual or a company, you may use *Markdown Exec Insiders* precisely under the same terms as *Markdown Exec*, which are given by the [ISC license][license]. However, we kindly ask you to respect our **fair use policy**:
- Please **don't distribute the source code** of Insiders. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy.
- If you cancel your subscription, your access to the private repository is revoked, and you will miss out on all future updates of Insiders. However, you may **use the latest version** that's available to you **as long as you like**. Just remember that [GitHub deletes private forks][private forks].
[backlog]: https://pawamoy.github.io/backlog/
[insiders]: #what-is-insiders
[sponsorship]: #what-sponsorships-achieve
[sponsors]: #how-to-become-a-sponsor
[features]: #whats-in-it-for-me
[funding]: #funding
[goals completed]: #goals-completed
[github sponsor profile]: https://github.com/sponsors/pawamoy
[billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
[license]: ../license.md
[private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
markdown-exec-1.10.2/docs/insiders/installation.md 0000664 0000000 0000000 00000005504 14766364173 0022157 0 ustar 00root root 0000000 0000000 ---
title: Getting started with Insiders
---
# Getting started with Insiders
*Markdown Exec Insiders* is a compatible drop-in replacement for *Markdown Exec*, and can be installed similarly using `pip` or `git`. Note that in order to access the Insiders repository, you need to [become an eligible sponsor][] of @pawamoy on GitHub.
## Installation
### with the `insiders` tool
[`insiders`][insiders-tool] is a tool that helps you keep up-to-date versions of Insiders projects in the PyPI index of your choice (self-hosted, Google registry, Artifactory, etc.).
**We kindly ask that you do not upload the distributions to public registries, as it is against our [Terms of use][].**
### with pip (ssh/https)
*Markdown Exec Insiders* can be installed with `pip` [using SSH][install-pip-ssh]:
```bash
pip install git+ssh://git@github.com/pawamoy-insiders/markdown-exec.git
```
Or using HTTPS:
```bash
pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/markdown-exec.git
```
>? NOTE: **How to get a GitHub personal access token?** The `GH_TOKEN` environment variable is a GitHub token. It can be obtained by creating a [personal access token][github-pat] for your GitHub account. It will give you access to the Insiders repository, programmatically, from the command line or GitHub Actions workflows:
>
> 1. Go to https://github.com/settings/tokens
> 2. Click on [Generate a new token][github-pat-new]
> 3. Enter a name and select the [`repo`][scopes] scope
> 4. Generate the token and store it in a safe place
>
> Note that the personal access token must be kept secret at all times, as it allows the owner to access your private repositories.
### with Git
Of course, you can use *Markdown Exec Insiders* directly using Git:
```
git clone git@github.com:pawamoy-insiders/markdown-exec
```
When cloning with Git, the package must be installed:
```
pip install -e markdown-exec
```
## Upgrading
When upgrading Insiders, you should always check the version of *Markdown Exec* which makes up the first part of the version qualifier. For example, a version like `8.x.x.4.x.x` means that Insiders `4.x.x` is currently based on `8.x.x`.
If the major version increased, it's a good idea to consult the [changelog][] and go through the steps to ensure your configuration is up to date and all necessary changes have been made.
[become an eligible sponsor]: ./index.md#how-to-become-a-sponsor
[changelog]: ./changelog.md
[github-pat]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[github-pat-new]: https://github.com/settings/tokens/new
[insiders-tool]: https://pawamoy.github.io/insiders-project/
[install-pip-ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
[scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
[terms of use]: ./index.md#terms
markdown-exec-1.10.2/docs/js/ 0000775 0000000 0000000 00000000000 14766364173 0015724 5 ustar 00root root 0000000 0000000 markdown-exec-1.10.2/docs/js/feedback.js 0000664 0000000 0000000 00000000775 14766364173 0020017 0 ustar 00root root 0000000 0000000 const feedback = document.forms.feedback;
feedback.hidden = false;
feedback.addEventListener("submit", function(ev) {
ev.preventDefault();
const commentElement = document.getElementById("feedback");
commentElement.style.display = "block";
feedback.firstElementChild.disabled = true;
const data = ev.submitter.getAttribute("data-md-value");
const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']");
if (note) {
note.hidden = false;
}
})
markdown-exec-1.10.2/docs/js/insiders.js 0000664 0000000 0000000 00000005473 14766364173 0020113 0 ustar 00root root 0000000 0000000 function humanReadableAmount(amount) {
const strAmount = String(amount);
if (strAmount.length >= 4) {
return `${strAmount.slice(0, strAmount.length - 3)},${strAmount.slice(-3)}`;
}
return strAmount;
}
function getJSON(url, callback) {
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.responseType = 'json';
xhr.onload = function () {
var status = xhr.status;
if (status === 200) {
callback(null, xhr.response);
} else {
callback(status, xhr.response);
}
};
xhr.send();
}
function updatePremiumSponsors(dataURL, rank) {
let capRank = rank.charAt(0).toUpperCase() + rank.slice(1);
getJSON(dataURL + `/sponsors${capRank}.json`, function (err, sponsors) {
const sponsorsDiv = document.getElementById(`${rank}-sponsors`);
if (sponsors.length > 0) {
let html = '';
html += `${capRank} sponsors
`
});
html += '
`;
});
if (privateSponsors > 0) {
sponsorsElem.innerHTML += `
+${privateSponsors}
`;
}
});
});
updatePremiumSponsors(dataURL, "gold");
updatePremiumSponsors(dataURL, "silver");
updatePremiumSponsors(dataURL, "bronze");
}
markdown-exec-1.10.2/docs/license.md 0000664 0000000 0000000 00000000115 14766364173 0017251 0 ustar 00root root 0000000 0000000 ---
title: License
hide:
- feedback
---
# License
```
--8<-- "LICENSE"
```
markdown-exec-1.10.2/docs/reference/ 0000775 0000000 0000000 00000000000 14766364173 0017246 5 ustar 00root root 0000000 0000000 markdown-exec-1.10.2/docs/reference/api.md 0000664 0000000 0000000 00000000160 14766364173 0020336 0 ustar 00root root 0000000 0000000 ---
title: API reference
hide:
- navigation
---
# ::: markdown_exec
options:
show_submodules: true
markdown-exec-1.10.2/docs/schema.json 0000664 0000000 0000000 00000001470 14766364173 0017445 0 ustar 00root root 0000000 0000000 {
"$schema": "https://json-schema.org/draft-07/schema",
"title": "Utilities to execute code blocks in Markdown files.nto your site.",
"oneOf": [
{
"markdownDescription": "https://pawamoy.github.io/markdown-exec",
"enum": [
"markdown-exec"
]
},
{
"type": "object",
"properties": {
"markdown-exec": {
"markdownDescription": "https://pawamoy.github.io/markdown-exec",
"type": "object",
"properties": {
"languages": {
"title": "The languages to enabled execution for.",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
} markdown-exec-1.10.2/docs/snippets/ 0000775 0000000 0000000 00000000000 14766364173 0017155 5 ustar 00root root 0000000 0000000 markdown-exec-1.10.2/docs/snippets/gallery/ 0000775 0000000 0000000 00000000000 14766364173 0020614 5 ustar 00root root 0000000 0000000 markdown-exec-1.10.2/docs/snippets/gallery/ansi.sh 0000664 0000000 0000000 00000001052 14766364173 0022100 0 ustar 00root root 0000000 0000000 #!/bin/bash
# credits to https://github.com/42picky/42picky.github.io
text="xYz" # Some test text
echo -e "\n 40m 41m 42m 43m 44m 45m 46m 47m"
for FGs in ' m' ' 1m' ' 30m' '1;30m' ' 31m' '1;31m' ' 32m' \
'1;32m' ' 33m' '1;33m' ' 34m' '1;34m' ' 35m' '1;35m' \
' 36m' '1;36m' ' 37m' '1;37m'; do
FG=${FGs// /}
echo -en " $FGs \033[$FG ${text} "
for BG in 40m 41m 42m 43m 44m 45m 46m 47m; do
echo -en "$EINS \033[$FG\033[${BG} ${text} \033[0m"
done
echo
done
echo markdown-exec-1.10.2/docs/snippets/gallery/argparse.py 0000664 0000000 0000000 00000001132 14766364173 0022767 0 ustar 00root root 0000000 0000000 import argparse
from duty.cli import get_parser
parser = get_parser()
lines = []
lines.append(f"## duty")
if parser.description:
lines.append(parser.description)
lines.append("\nOptions:\n")
for action in parser._actions:
opts = [f"`{opt}`" for opt in action.option_strings]
if not opts:
continue
line = "- " + ",".join(opts)
if action.metavar:
line += f" `{action.metavar}`"
line += f": {action.help}"
if action.default and action.default != argparse.SUPPRESS:
line += f"(default: {action.default})"
lines.append(line)
print("\n".join(lines))
markdown-exec-1.10.2/docs/snippets/gallery/argparse_format.py 0000664 0000000 0000000 00000000142 14766364173 0024337 0 ustar 00root root 0000000 0000000 from duty.cli import get_parser
parser = get_parser()
print(f"```\n{parser.format_help()}\n```")
markdown-exec-1.10.2/docs/snippets/gallery/chalk.py 0000664 0000000 0000000 00000001175 14766364173 0022254 0 ustar 00root root 0000000 0000000 from tempfile import NamedTemporaryFile
from chalk import Diagram, triangle, unit_x
from colour import Color
papaya = Color("#ff9700")
def sierpinski(n: int, size: int) -> Diagram:
if n <= 1:
return triangle(size)
else:
smaller = sierpinski(n - 1, size / 2)
return smaller.above(smaller.beside(smaller, unit_x).center_xy())
d = sierpinski(5, 4).fill_color(papaya)
# Chalk doesn't provide an easy method to get a string directly,
# so we use a temporary file.
with NamedTemporaryFile("w+") as tmpfile:
d.render_svg(tmpfile.name, height=256)
tmpfile.seek(0)
svg = tmpfile.read()
print(svg)
markdown-exec-1.10.2/docs/snippets/gallery/d2.py 0000664 0000000 0000000 00000002366 14766364173 0021502 0 ustar 00root root 0000000 0000000 import os # markdown-exec: hide
if "CI" in os.environ: # markdown-exec: hide
print("D2 is not installed in CI, skipping this gallery example.") # markdown-exec: hide
raise SystemExit(0) # markdown-exec: hide
import subprocess
diagram = """
direction: right
Before and after becoming friends: {
2007: Office chatter in 2007 {
shape: sequence_diagram
alice: Alice
bob: Bobby
awkward small talk: {
alice -> bob: uhm, hi
bob -> alice: oh, hello
icebreaker attempt: {
alice -> bob: what did you have for lunch?
}
unfortunate outcome: {
bob -> alice: that's personal
}
}
}
2012: Office chatter in 2012 {
shape: sequence_diagram
alice: Alice
bob: Bobby
alice -> bob: Want to play with ChatGPT?
bob -> alice: Yes!
bob -> alice.play: Write a play...
alice.play -> bob.play: about 2 friends...
bob.play -> alice.play: who find love...
alice.play -> bob.play: in a sequence diagram
}
2007 -> 2012: Five\nyears\nlater
}
"""
# We simply run `d2` in a subprocess, passing it our diagram as input and capturing its output to print it.
svg = subprocess.check_output(["d2", "-", "-"], input=diagram, stderr=subprocess.DEVNULL, text=True)
print(svg)
markdown-exec-1.10.2/docs/snippets/gallery/diagrams.py 0000664 0000000 0000000 00000002444 14766364173 0022761 0 ustar 00root root 0000000 0000000 from base64 import b64encode
from contextlib import suppress
from diagrams import Diagram
from diagrams.k8s.clusterconfig import HPA
from diagrams.k8s.compute import Deployment, Pod, ReplicaSet
from diagrams.k8s.network import Ingress, Service
# By default, Diagrams tries to write the result on disk, so we prevent that by patching its `render` method,
# and by ignoring the `FileNotFoundError` that ensues.
#
# Then we use its internal `dot` object and its `pipe` method to store the diagram in a variable,
# as base64 encoded PNG data.
#
# Finally we output an HTML image with the base64 data.
# Using SVG is not possible here since Diagrams embeds actual, smaller PNG files in the result,
# files which are not automatically added to the final site.
with suppress(FileNotFoundError):
with Diagram("Exposed Pod with 3 Replicas", show=False) as diagram:
diagram.render = lambda: None
net = Ingress("domain.com") >> Service("svc")
net >> [Pod("pod1"), Pod("pod2"), Pod("pod3")] << ReplicaSet("rs") << Deployment("dp") << HPA("hpa")
png = b64encode(diagram.dot.pipe(format="png")).decode()
# Wrapping the image in a div prevents it from being wrapped in a paragraph,
# which would add unnecessary space around it.
print(f'
"))
markdown-exec-1.10.2/docs/snippets/gallery/runpy.py 0000664 0000000 0000000 00000000676 14766364173 0022354 0 ustar 00root root 0000000 0000000 import sys
import warnings
from contextlib import suppress
from io import StringIO
from runpy import run_module
old_argv = list(sys.argv)
sys.argv = ["mkdocs"]
old_stdout = sys.stdout
sys.stdout = StringIO()
warnings.filterwarnings("ignore", category=RuntimeWarning)
with suppress(SystemExit):
run_module("mkdocs", run_name="__main__")
output = sys.stdout.getvalue()
sys.stdout = old_stdout
sys.argv = old_argv
print(f"```\n{output}\n```")
markdown-exec-1.10.2/docs/snippets/gallery/textual.py 0000664 0000000 0000000 00000001132 14766364173 0022651 0 ustar 00root root 0000000 0000000 from textual.app import App, ComposeResult
from textual.widgets import Static
from textual._doc import take_svg_screenshot
class TextApp(App):
CSS = """
Screen {
background: darkblue;
color: white;
layout: vertical;
}
Static {
height: auto;
padding: 2;
border: heavy white;
background: #ffffff 30%;
content-align: center middle;
}
"""
def compose(self) -> ComposeResult:
yield Static("Hello")
yield Static("[b]World![/b]")
print(take_svg_screenshot(app=TextApp(), terminal_size=(80, 24)))
markdown-exec-1.10.2/docs/snippets/usage/ 0000775 0000000 0000000 00000000000 14766364173 0020261 5 ustar 00root root 0000000 0000000 markdown-exec-1.10.2/docs/snippets/usage/boolean_matrix.py 0000664 0000000 0000000 00000000244 14766364173 0023636 0 ustar 00root root 0000000 0000000 print()
print("a | b | a \\|\\| b")
print("--- | --- | ---")
for a in (True, False):
for b in (True, False):
print(f"{a} | {b} | {a or b}")
print()
markdown-exec-1.10.2/docs/snippets/usage/hide.py 0000664 0000000 0000000 00000000073 14766364173 0021544 0 ustar 00root root 0000000 0000000 print("Hello World!")
print("{code}
") # markdown-exec: hide
markdown-exec-1.10.2/docs/snippets/usage/multiple.pycon 0000664 0000000 0000000 00000000114 14766364173 0023162 0 ustar 00root root 0000000 0000000 >>> name = "Baron"
>>> print(name)
Baron
>>> age = "???"
>>> print(age)
???
markdown-exec-1.10.2/docs/snippets/usage/platform_html.py 0000664 0000000 0000000 00000000436 14766364173 0023506 0 ustar 00root root 0000000 0000000 import platform
print(
f"""
"""
)
markdown-exec-1.10.2/docs/snippets/usage/platform_md.py 0000664 0000000 0000000 00000000530 14766364173 0023135 0 ustar 00root root 0000000 0000000 import platform
from textwrap import dedent
print(
# we must dedent, otherwise Markdown
# will render it as a code block!
dedent(
f"""
- machine: `{platform.machine()}`
- version: `{platform.version()}`
- platform: `{platform.platform()}`
- system: `{platform.system()}`
"""
)
)
markdown-exec-1.10.2/docs/snippets/usage/source.py 0000664 0000000 0000000 00000000031 14766364173 0022125 0 ustar 00root root 0000000 0000000 print("I'm the result!")
markdown-exec-1.10.2/docs/snippets/usage/source.pycon 0000664 0000000 0000000 00000000063 14766364173 0022632 0 ustar 00root root 0000000 0000000 >>> print("I'm the result!")
I'm not the result...
markdown-exec-1.10.2/docs/usage/ 0000775 0000000 0000000 00000000000 14766364173 0016414 5 ustar 00root root 0000000 0000000 markdown-exec-1.10.2/docs/usage/index.md 0000664 0000000 0000000 00000034066 14766364173 0020056 0 ustar 00root root 0000000 0000000 # Usage
Once the extension is configured (see README/Overview),
you can execute code blocks by enabling the `exec` option:
````md
```python exec="on"
print("Hello Markdown!")
```
````
The `exec` option will be true for every possible value
except `0`, `no`, `off` and `false` (case insensitive).
To enable automatic execution of code blocks for specific languages
(without having to add the `exec="on"` option to your code blocks),
set the `MARKDOWN_EXEC_AUTO` environment variable:
```bash
MARKDOWN_EXEC_AUTO=python,bash
```
## Options summary
As the number of options grew over time,
we now provide this summary listing every option,
linking to their related documentation:
- [`exec`](#usage): The mother of all other options, enabling code execution.
- [`html`](#html-vs-markdown): Whether the output is alredady HTML, or needs to be converted from Markdown to HTML.
- [`id`](#handling-errors): Give an identifier to your code blocks to help
[debugging errors](#handling-errors), or to [prefix HTML ids](#html-ids).
- [`idprefix`](#html-ids): Change or remove the prefix in front of HTML ids/hrefs.
- [`result`](#wrap-result-in-a-code-block): Choose the syntax highlight of your code block output.
- [`returncode`](shell.md#expecting-a-non-zero-exit-code): Tell what return code is expected (shell code).
- [`session`](#sessions): Execute code blocks within a named session, reusing previously defined variables, etc..
- [`source`](#render-the-source-code-as-well): Render the source as well as the output.
- [`tabs`](#change-the-titles-of-tabs): When rendering the source using tabs, choose the tabs titles.
- [`width`](#change-the-console-width): Change the console width through the `COLUMNS` environment variable.
- [`workdir`](#change-the-working-directory): Change the working directory.
- [`title`](#additional-options): Title is a [Material for MkDocs][material] option.
- [`updatetoc`](#generated-headings-in-table-of-contents): Whether to update the Table of Contents with generated headings.
## HTML vs. Markdown
By default, Markdown Exec will render what you print as Markdown.
If you want to skip rendering, to inject HTML directly,
you can set the `html` option to true.
HTML Example:
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
System information:
```python exec="true" html="true"
--8<-- "usage/platform_html.py"
```
````
Markdown Example:
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
System information:
```python exec="true"
--8<-- "usage/platform_md.py"
```
````
## Generated headings in Table of Contents
If you are using Python Markdown's `toc` extension,
or writing docs with MkDocs, you will notice that the headings
you generated by executing a code block appear in the table of contents.
If you don't want those headings to appear in the ToC, you can use
the `updatetoc="no"` boolean option:
````md
```python exec="1" updatetoc="no"
print("# XL heading\n")
print("## L heading\n")
print("### M heading\n")
print("#### S heading\n")
```
````
## HTML ids
When your executed code blocks output Markdown,
this Markdown is rendered to HTML, and every HTML id
is automatically prefixed with `exec-N--`, where N
is an integer incremented with each code block.
To avoid breaking links, every `href` attribute
is also updated when relevant.
You can change this prefix, or completely remove it
with the `idprefix` option.
The following ids are not prefixed:
````md exec="1" source="material-block"
```python exec="1" idprefix="" updatetoc="no"
print("#### Commands")
print("\n[link to commands](#commands)")
```
````
The following ids are prefixed with `cli-`:
````md exec="1" source="material-block"
```python exec="1" idprefix="cli-" updatetoc="no"
print("#### Commands")
print("\n[link to commands](#commands)")
```
````
If `idprefix` is not specified, and `id` is specified,
then the id is used as prefix:
The following ids are prefixed with `super-cli-`:
````md exec="1" source="material-block"
```python exec="1" id="super-cli" updatetoc="no"
print("#### Commands")
print("\n[link to commands](#commands)")
```
````
## Render the source code as well
It's possible to render both the result of the executed code block
*and* the code block itself. For this, use the `source` option
with one of the following values:
- `above`: The source code will be rendered above the result.
- `below`: The source code will be rendered below the result.
- `material-block`: The source code and result will be wrapped in a nice-looking block
(only works with [Material for MkDocs][material],
and requires the [`md_in_html`][md_in_html] extension)
- `tabbed-left`: The source code and result will be rendered in tabs, in that order
(requires the [`pymdownx.tabbed`][pymdownx.tabbed] extension).
- `tabbed-right`: The result and source code will be rendered in tabs, in that order
(requires the [`pymdownx.tabbed`][pymdownx.tabbed] extension).
- `console`: The source and result are concatenated in a single code block, like an interactive console session.
**Source above:**
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="true" source="above"
--8<-- "usage/source.py"
```
````
---
**Source below:**
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="true" source="below"
--8<-- "usage/source.py"
```
````
---
**Material block:**
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="true" source="material-block"
--8<-- "usage/source.py"
```
````
NOTE: **Important:**
The `material-block` source option requires that you enable the [`md_in_html`][md_in_html] Markdown extension.
---
**Tabbed on the left:**
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="true" source="tabbed-left"
--8<-- "usage/source.py"
```
````
NOTE: **Important:**
The `tabbed-left` source option requires that you enable the [`pymdownx.tabbed`][pymdownx.tabbed] Markdown extension.
---
**Tabbed on the right:**
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="true" source="tabbed-right"
--8<-- "usage/source.py"
```
````
NOTE: **Important:**
The `tabbed-left` source option requires that you enable the [`pymdownx.tabbed`][pymdownx.tabbed] Markdown extension.
---
**Console** (best used with actual session syntax like
[`pycon`](python.md#python-console-code) or [`console`](shell.md#console)):
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```pycon exec="true" source="console"
--8<-- "usage/source.pycon"
```
````
[md_in_html]: https://python-markdown.github.io/extensions/md_in_html/
[pymdownx.tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
## Hiding lines from the source
Every line that contains the string `markdown-exec: hide` will be hidden from the
displayed source.
=== "Markdown"
````md
```python exec="true" source="above"
--8<-- "usage/hide.py"
```
````
=== "Rendered"
```python exec="true" source="above"
--8<-- "usage/hide.py"
```
## Change the titles of tabs
In the previous example, we didn't specify any title for tabs,
so Markdown Exec used "Source" and "Result" by default.
You can customize the titles with the `tabs` option:
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="1" source="tabbed-left" tabs="Source code|Output"
--8<-- "usage/source.py"
```
````
As you can see, titles are separated with a pipe `|`. Both titles are stripped
so you can add space around the pipe. If you need to use that character in a title,
simply escape it with `\|`:
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="1" source="tabbed-left" tabs="OR operator: a \|\| b | Boolean matrix"
--8<-- "usage/boolean_matrix.py"
```
````
IMPORTANT: The `tabs` option ***always*** expects the "Source" tab title first,
and the "Result" tab title second. It allows to switch from tabbed-left
to tabbed-right and inversely without having to switch the titles as well.
WARNING: **Limitation:**
Changing the title for only one tab is not supported.
## Wrap result in a code block
You can wrap the result in a code block by specifying a code block language:
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```console exec="1" result="ini"
$ cat .git/config
```
````
WARNING: **Limitation:**
Wrapping the result is not possible when HTML output is enabled.
## Change the console width
To change the console width for the execution of a code block, use the `width` option.
Internally, Markdown Exec will set the `COLUMNS` environment variable accordingly,
and restore its previous value after execution.
If the executed code doesn't support this environment variable,
the default console width will be used (it could be the current width or some arbitrary value).
````md exec="1" source="tabbed-left"
```bash exec="1" width="10"
echo $COLUMNS
```
```bash exec="1" width="1000"
echo $COLUMNS
```
````
## Change the working directory
To change the working directory for the execution of a code block, use the `workdir` option.
````md exec="1" source="tabbed-left"
```bash exec="1"
pwd
```
```bash exec="1" workdir=".."
pwd
```
````
## Additional options
If you are using [Material for MkDocs][material],
you are probably familiar with the `title` option on code blocks:
````md
```python title="setup.py"
from setuptools import setup
setup(...)
```
````
Markdown Exec will add back these unrecognized options
when rendering the source, so you can keep using them normally.
Example:
````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
```python exec="1" source="above" title="source.py"
--8<-- "usage/source.py"
```
````
## Handling errors
Code blocks execution can fail.
For example, your Python code may raise exceptions,
or your shell code may return a non-zero exit code
(for shell commands that are expected to return non-zero,
see [Expecting a non-zero exit code](shell.md#expecting-a-non-zero-exit-code)).
In these cases, the exception and traceback (Python),
or the current output (shell) will be rendered
instead of the result, and a warning will be logged.
Example of failing code:
````md
```python exec="true"
print("hello")
assert 1 + 1 == 11
```
````
```text title="MkDocs output"
WARNING - markdown_exec: Execution of python code block exited with errors
```
```python title="Rendered traceback"
Traceback (most recent call last):
File "/path/to/markdown_exec/formatters/python.py", line 23, in _run_python
exec(code, exec_globals) # noqa: S102
File "{platform.machine()}{platform.version()}{platform.platform()}{platform.system()}%(initial_code)s
"
def _run_python(
code: str,
returncode: int | None = None, # noqa: ARG001
session: str | None = None,
id: str | None = None, # noqa: A002
**extra: str,
) -> str:
title = extra.get("title")
code_block_id = _code_block_id(id, session, title)
_code_blocks[code_block_id] = code.split("\n")
exec_globals = _sessions_globals[session] if session else {}
# Other libraries expect functions to have a valid `__module__` attribute.
# To achieve this, we need to add a `__name__` attribute to the globals.
# We compute the name from the code block ID, replacing invalid characters with `_`.
# We also create a module object with the same name and add it to `sys.modules`,
# because that's what yet other libraries expect (`dataclasses` for example).
module_name = re.sub(r"[^a-zA-Z\d]+", "_", code_block_id)
exec_globals["__name__"] = module_name
sys.modules[module_name] = ModuleType(module_name)
buffer = StringIO()
exec_globals["print"] = partial(_buffer_print, buffer)
try:
exec_python(code, code_block_id, exec_globals)
except Exception as error:
trace = traceback.TracebackException.from_exception(error)
for frame in trace.stack:
if frame.filename.startswith("= (3, 13):
frame._lines = _code_blocks[frame.filename][frame.lineno - 1] # type: ignore[attr-defined,operator]
else:
frame._line = _code_blocks[frame.filename][frame.lineno - 1] # type: ignore[attr-defined,operator]
raise ExecutionError(code_block("python", "".join(trace.format()), **extra)) from error
return buffer.getvalue()
def _format_python(**kwargs: Any) -> str:
return base_format(language="python", run=_run_python, **kwargs)
markdown-exec-1.10.2/src/markdown_exec/_internal/formatters/sh.py 0000664 0000000 0000000 00000001605 14766364173 0025124 0 ustar 00root root 0000000 0000000 # Formatter for executing shell code.
from __future__ import annotations
import subprocess
from typing import Any
from markdown_exec._internal.formatters.base import ExecutionError, base_format
from markdown_exec._internal.rendering import code_block
def _run_sh(
code: str,
returncode: int | None = None,
session: str | None = None, # noqa: ARG001
id: str | None = None, # noqa: A002,ARG001
**extra: str,
) -> str:
process = subprocess.run( # noqa: S603
["sh", "-c", code], # noqa: S607
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True,
check=False,
)
if process.returncode != returncode:
raise ExecutionError(code_block("sh", process.stdout, **extra), process.returncode)
return process.stdout
def _format_sh(**kwargs: Any) -> str:
return base_format(language="sh", run=_run_sh, **kwargs)
markdown-exec-1.10.2/src/markdown_exec/_internal/formatters/tree.py 0000664 0000000 0000000 00000004004 14766364173 0025445 0 ustar 00root root 0000000 0000000 # Formatter for file-system trees.
from __future__ import annotations
from textwrap import dedent
from typing import TYPE_CHECKING, Any
from markdown_exec._internal.rendering import MarkdownConverter, code_block
if TYPE_CHECKING:
from markdown import Markdown
def _rec_build_tree(lines: list[str], parent: list, offset: int, base_indent: int) -> int:
while offset < len(lines):
line = lines[offset]
lstripped = line.lstrip()
indent = len(line) - len(lstripped)
if indent == base_indent:
parent.append((lstripped, []))
offset += 1
elif indent > base_indent:
offset = _rec_build_tree(lines, parent[-1][1], offset, indent)
else:
return offset
return offset
def _build_tree(code: str) -> list[tuple[str, list]]:
lines = dedent(code.strip()).split("\n")
root_layer: list[tuple[str, list]] = []
_rec_build_tree(lines, root_layer, 0, 0)
return root_layer
def _rec_format_tree(tree: list[tuple[str, list]], *, root: bool = True) -> list[str]:
lines = []
n_items = len(tree)
for index, node in enumerate(tree):
last = index == n_items - 1
prefix = "" if root else f"{'└' if last else '├'}── "
if node[1]:
lines.append(f"{prefix}📁 {node[0]}")
sublines = _rec_format_tree(node[1], root=False)
if root:
lines.extend(sublines)
else:
indent_char = " " if last else "│"
lines.extend([f"{indent_char} {line}" for line in sublines])
else:
name = node[0].split()[0]
icon = "📁" if name.endswith("/") else "📄"
lines.append(f"{prefix}{icon} {node[0]}")
return lines
def _format_tree(code: str, md: Markdown, result: str, **options: Any) -> str:
markdown = MarkdownConverter(md)
output = "\n".join(_rec_format_tree(_build_tree(code)))
return markdown.convert(code_block(result or "bash", output, **options.get("extra", {})))
markdown-exec-1.10.2/src/markdown_exec/_internal/logger.py 0000664 0000000 0000000 00000004547 14766364173 0023613 0 ustar 00root root 0000000 0000000 from __future__ import annotations
import logging
from typing import Any, Callable, ClassVar
class _Logger:
_default_logger: Any = logging.getLogger
_instances: ClassVar[dict[str, _Logger]] = {}
# See same code in Griffe project.
def __init__(self, name: str) -> None:
# Default logger that can be patched by third-party.
self._logger = self.__class__._default_logger(name)
def __getattr__(self, name: str) -> Any:
# Forward everything to the logger.
return getattr(self._logger, name)
@classmethod
def get(cls, name: str) -> _Logger:
"""Get a logger instance.
Parameters:
name: The logger name.
Returns:
The logger instance.
"""
if name not in cls._instances:
cls._instances[name] = cls(name)
return cls._instances[name]
@classmethod
def _patch_loggers(cls, get_logger_func: Callable) -> None:
# Patch current instances.
for name, instance in cls._instances.items():
instance._logger = get_logger_func(name)
# Future instances will be patched as well.
cls._default_logger = get_logger_func
def get_logger(name: str) -> _Logger:
"""Create and return a new logger instance.
Parameters:
name: The logger name.
Returns:
The logger.
"""
return _Logger.get(name)
def patch_loggers(get_logger_func: Callable[[str], Any]) -> None:
"""Patch loggers.
We provide the `patch_loggers`function so dependant libraries
can patch loggers as they see fit.
For example, to fit in the MkDocs logging configuration
and prefix each log message with the module name:
```python
import logging
from markdown_exec.logger import patch_loggers
class LoggerAdapter(logging.LoggerAdapter):
def __init__(self, prefix, logger):
super().__init__(logger, {})
self.prefix = prefix
def process(self, msg, kwargs):
return f"{self.prefix}: {msg}", kwargs
def get_logger(name):
logger = logging.getLogger(f"mkdocs.plugins.{name}")
return LoggerAdapter(name.split(".", 1)[0], logger)
patch_loggers(get_logger)
```
Parameters:
get_logger_func: A function accepting a name as parameter and returning a logger.
"""
_Logger._patch_loggers(get_logger_func)
markdown-exec-1.10.2/src/markdown_exec/_internal/main.py 0000664 0000000 0000000 00000010244 14766364173 0023247 0 ustar 00root root 0000000 0000000 from __future__ import annotations
import os
import re
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from markdown import Markdown
from markdown_exec._internal.formatters.base import default_tabs
from markdown_exec._internal.formatters.bash import _format_bash
from markdown_exec._internal.formatters.console import _format_console
from markdown_exec._internal.formatters.markdown import _format_markdown
from markdown_exec._internal.formatters.pycon import _format_pycon
from markdown_exec._internal.formatters.pyodide import _format_pyodide
from markdown_exec._internal.formatters.python import _format_python
from markdown_exec._internal.formatters.sh import _format_sh
from markdown_exec._internal.formatters.tree import _format_tree
MARKDOWN_EXEC_AUTO = [lang.strip() for lang in os.getenv("MARKDOWN_EXEC_AUTO", "").split(",")]
"""Languages to automatically execute."""
formatters = {
"bash": _format_bash,
"console": _format_console,
"md": _format_markdown,
"markdown": _format_markdown,
"py": _format_python,
"python": _format_python,
"pycon": _format_pycon,
"pyodide": _format_pyodide,
"sh": _format_sh,
"tree": _format_tree,
}
"""Formatters for each language."""
# negative look behind: matches only if | (pipe) if not preceded by \ (backslash)
_tabs_re = re.compile(r"(? bool:
"""Validate code blocks inputs.
Parameters:
language: The code language, like python or bash.
inputs: The code block inputs, to be sorted into options and attrs.
options: The container for options.
attrs: The container for attrs:
md: The Markdown instance.
Returns:
Success or not.
"""
exec_value = language in MARKDOWN_EXEC_AUTO or _to_bool(inputs.pop("exec", "no"))
if language not in {"tree", "pyodide"} and not exec_value:
return False
id_value = inputs.pop("id", "")
id_prefix_value = inputs.pop("idprefix", None)
html_value = _to_bool(inputs.pop("html", "no"))
source_value = inputs.pop("source", "")
result_value = inputs.pop("result", "")
returncode_value = int(inputs.pop("returncode", "0"))
session_value = inputs.pop("session", "")
update_toc_value = _to_bool(inputs.pop("updatetoc", "yes"))
tabs_value = inputs.pop("tabs", "|".join(default_tabs))
tabs = tuple(_tabs_re.split(tabs_value, maxsplit=1))
workdir_value = inputs.pop("workdir", None)
width_value = int(inputs.pop("width", "0"))
options["id"] = id_value
options["id_prefix"] = id_prefix_value
options["html"] = html_value
options["source"] = source_value
options["result"] = result_value
options["returncode"] = returncode_value
options["session"] = session_value
options["update_toc"] = update_toc_value
options["tabs"] = tabs
options["workdir"] = workdir_value
options["width"] = width_value
options["extra"] = inputs
return True
def formatter(
source: str,
language: str,
css_class: str, # noqa: ARG001
options: dict[str, Any],
md: Markdown,
classes: list[str] | None = None, # noqa: ARG001
id_value: str = "", # noqa: ARG001
attrs: dict[str, Any] | None = None, # noqa: ARG001
**kwargs: Any, # noqa: ARG001
) -> str:
"""Execute code and return HTML.
Parameters:
source: The code to execute.
language: The code language, like python or bash.
css_class: The CSS class to add to the HTML element.
options: The container for options.
attrs: The container for attrs:
md: The Markdown instance.
classes: Additional CSS classes.
id_value: An optional HTML id.
attrs: Additional attributes
**kwargs: Additional arguments passed to SuperFences default formatters.
Returns:
HTML contents.
"""
fmt = formatters.get(language, lambda source, **kwargs: source)
return fmt(code=source, md=md, **options) # type: ignore[operator]
def _to_bool(value: str) -> bool:
return value.lower() not in {"", "no", "off", "false", "0"}
markdown-exec-1.10.2/src/markdown_exec/_internal/mkdocs_plugin.py 0000664 0000000 0000000 00000012465 14766364173 0025170 0 ustar 00root root 0000000 0000000 # This module contains an optional plugin for MkDocs.
from __future__ import annotations
import logging
import os
from pathlib import Path
from typing import TYPE_CHECKING, Any
from mkdocs.config import config_options
from mkdocs.config.base import Config
from mkdocs.exceptions import PluginError
from mkdocs.plugins import BasePlugin
from mkdocs.utils import write_file
from markdown_exec._internal.logger import patch_loggers
from markdown_exec._internal.main import formatter, formatters, validator
from markdown_exec._internal.rendering import MarkdownConverter, markdown_config
if TYPE_CHECKING:
from collections.abc import MutableMapping
from jinja2 import Environment
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import Files
try:
__import__("pygments_ansi_color")
except ImportError:
_ansi_ok = False
else:
_ansi_ok = True
class _LoggerAdapter(logging.LoggerAdapter):
def __init__(self, prefix: str, logger: logging.Logger) -> None:
super().__init__(logger, {})
self.prefix = prefix
def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, MutableMapping[str, Any]]:
return f"{self.prefix}: {msg}", kwargs
def _get_logger(name: str) -> _LoggerAdapter:
logger = logging.getLogger(f"mkdocs.plugins.{name}")
return _LoggerAdapter(name.split(".", 1)[0], logger)
patch_loggers(_get_logger)
class MarkdownExecPluginConfig(Config):
"""Configuration of the plugin (for `mkdocs.yml`)."""
ansi = config_options.Choice(("auto", "off", "required", True, False), default="auto")
"""Whether the `ansi` extra is required when installing the package."""
languages = config_options.ListOfItems(
config_options.Choice(formatters.keys()),
default=list(formatters.keys()),
)
"""Which languages to enabled the extension for."""
class MarkdownExecPlugin(BasePlugin[MarkdownExecPluginConfig]):
"""MkDocs plugin to easily enable custom fences for code blocks execution."""
def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
"""Configure the plugin.
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we add custom fences for all the supported languages.
We also save the Markdown extensions configuration
into [`markdown_config`][markdown_exec.markdown_config].
Arguments:
config: The MkDocs config object.
Returns:
The modified config.
"""
if "pymdownx.superfences" not in config["markdown_extensions"]:
message = "The 'markdown-exec' plugin requires the 'pymdownx.superfences' Markdown extension to work."
raise PluginError(message)
if self.config.ansi in ("required", True) and not _ansi_ok:
raise PluginError(
"The configuration for the 'markdown-exec' plugin requires "
"that it is installed with the 'ansi' extra. "
"Install it with 'pip install markdown-exec[ansi]'.",
)
self.mkdocs_config_dir = os.getenv("MKDOCS_CONFIG_DIR")
os.environ["MKDOCS_CONFIG_DIR"] = os.path.dirname(config["config_file_path"])
self.languages = self.config.languages
mdx_configs = config.setdefault("mdx_configs", {})
superfences = mdx_configs.setdefault("pymdownx.superfences", {})
custom_fences = superfences.setdefault("custom_fences", [])
for language in self.languages:
custom_fences.append(
{
"name": language,
"class": language,
"validator": validator,
"format": formatter,
},
)
markdown_config.save(config.markdown_extensions, config.mdx_configs)
return config
def on_env(
self,
env: Environment,
*,
config: MkDocsConfig,
files: Files, # noqa: ARG002
) -> Environment | None:
"""Add assets to the environment."""
if self.config.ansi in ("required", True) or (self.config.ansi == "auto" and _ansi_ok):
self._add_css(config, "ansi.css")
if "pyodide" in self.languages:
self._add_css(config, "pyodide.css")
self._add_js(config, "pyodide.js")
return env
def on_post_build(self, *, config: MkDocsConfig) -> None: # noqa: ARG002
"""Reset the plugin state."""
MarkdownConverter.counter = 0
markdown_config.reset()
if self.mkdocs_config_dir is None:
os.environ.pop("MKDOCS_CONFIG_DIR", None)
else:
os.environ["MKDOCS_CONFIG_DIR"] = self.mkdocs_config_dir
def _add_asset(self, config: MkDocsConfig, asset_file: str, asset_type: str) -> None:
asset_filename = f"assets/_markdown_exec_{asset_file}"
asset_content = Path(__file__).parent.parent.joinpath("assets", asset_file).read_text()
write_file(asset_content.encode("utf-8"), os.path.join(config.site_dir, asset_filename))
config[f"extra_{asset_type}"].insert(0, asset_filename)
def _add_css(self, config: MkDocsConfig, css_file: str) -> None:
self._add_asset(config, css_file, "css")
def _add_js(self, config: MkDocsConfig, js_file: str) -> None:
self._add_asset(config, js_file, "javascript")
markdown-exec-1.10.2/src/markdown_exec/_internal/processors.py 0000664 0000000 0000000 00000011257 14766364173 0024532 0 ustar 00root root 0000000 0000000 # This module contains a Markdown extension
# allowing to integrate generated headings into the ToC.
from __future__ import annotations
import copy
import re
from typing import TYPE_CHECKING
from xml.etree.ElementTree import Element
from markdown.treeprocessors import Treeprocessor
from markdown.util import HTML_PLACEHOLDER_RE
if TYPE_CHECKING:
from markdown import Markdown
from markupsafe import Markup
# code taken from mkdocstrings, credits to @oprypin
class IdPrependingTreeprocessor(Treeprocessor):
"""Prepend the configured prefix to IDs of all HTML elements."""
name = "markdown_exec_ids"
"""The name of the treeprocessor."""
def __init__(self, md: Markdown, id_prefix: str) -> None:
super().__init__(md)
self.id_prefix = id_prefix
"""The prefix to prepend to IDs."""
def run(self, root: Element) -> None:
"""Run the treeprocessor."""
if not self.id_prefix:
return
for el in root.iter():
id_attr = el.get("id")
if id_attr:
el.set("id", self.id_prefix + id_attr)
href_attr = el.get("href")
if href_attr and href_attr.startswith("#"):
el.set("href", "#" + self.id_prefix + href_attr[1:])
name_attr = el.get("name")
if name_attr:
el.set("name", self.id_prefix + name_attr)
if el.tag == "label":
for_attr = el.get("for")
if for_attr:
el.set("for", self.id_prefix + for_attr)
# code taken from mkdocstrings, credits to @oprypin
class HeadingReportingTreeprocessor(Treeprocessor):
"""Records the heading elements encountered in the document."""
name = "markdown_exec_record_headings"
"""The name of the treeprocessor."""
regex = re.compile("[Hh][1-6]")
"""The regex to match heading tags."""
def __init__(self, md: Markdown, headings: list[Element]):
super().__init__(md)
self.headings = headings
"""The list of heading elements."""
def run(self, root: Element) -> None:
"""Run the treeprocessor."""
for el in root.iter():
if self.regex.fullmatch(el.tag):
el = copy.copy(el) # noqa: PLW2901
# 'toc' extension's first pass (which we require to build heading stubs/ids) also edits the HTML.
# Undo the permalink edit so we can pass this heading to the outer pass of the 'toc' extension.
if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class: # type: ignore[attr-defined]
del el[-1]
self.headings.append(el)
class InsertHeadings(Treeprocessor):
"""Our headings insertor."""
name = "markdown_exec_insert_headings"
"""The name of the treeprocessor."""
def __init__(self, md: Markdown):
"""Initialize the object.
Arguments:
md: A `markdown.Markdown` instance.
"""
super().__init__(md)
self.headings: dict[Markup, list[Element]] = {}
"""The dictionary of headings."""
def run(self, root: Element) -> None:
"""Run the treeprocessor."""
if not self.headings:
return
for el in root.iter():
match = HTML_PLACEHOLDER_RE.match(el.text or "")
if match:
counter = int(match.group(1))
markup: Markup = self.md.htmlStash.rawHtmlBlocks[counter] # type: ignore[assignment]
if headings := self.headings.get(markup):
div = Element("div", {"class": "markdown-exec"})
div.extend(headings)
el.append(div)
class RemoveHeadings(Treeprocessor):
"""Our headings remover."""
name = "markdown_exec_remove_headings"
"""The name of the treeprocessor."""
def run(self, root: Element) -> None:
"""Run the treeprocessor."""
self._remove_duplicated_headings(root)
def _remove_duplicated_headings(self, parent: Element) -> None:
carry_text = ""
for el in reversed(parent): # Reversed mainly for the ability to mutate during iteration.
if el.tag == "div" and el.get("class") == "markdown-exec":
# Delete the duplicated headings along with their container, but keep the text (i.e. the actual HTML).
carry_text = (el.text or "") + carry_text
parent.remove(el)
else:
if carry_text:
el.tail = (el.tail or "") + carry_text
carry_text = ""
self._remove_duplicated_headings(el)
if carry_text:
parent.text = (parent.text or "") + carry_text
markdown-exec-1.10.2/src/markdown_exec/_internal/rendering.py 0000664 0000000 0000000 00000022577 14766364173 0024314 0 ustar 00root root 0000000 0000000 # Markdown extensions and helpers.
from __future__ import annotations
from contextlib import contextmanager
from functools import cache
from textwrap import indent
from typing import TYPE_CHECKING, Any
from markdown import Markdown
from markupsafe import Markup
from markdown_exec._internal.processors import (
HeadingReportingTreeprocessor,
IdPrependingTreeprocessor,
InsertHeadings,
RemoveHeadings,
)
if TYPE_CHECKING:
from collections.abc import Iterator
from xml.etree.ElementTree import Element
from markdown import Extension
def code_block(language: str, code: str, **options: str) -> str:
"""Format code as a code block.
Parameters:
language: The code block language.
code: The source code to format.
**options: Additional options passed from the source, to add back to the generated code block.
Returns:
The formatted code block.
"""
opts = " ".join(f'{opt_name}="{opt_value}"' for opt_name, opt_value in options.items())
return f"````````{language} {opts}\n{code}\n````````"
def tabbed(*tabs: tuple[str, str]) -> str:
"""Format tabs using `pymdownx.tabbed` extension.
Parameters:
*tabs: Tuples of strings: title and text.
Returns:
The formatted tabs.
"""
parts = []
for title, text in tabs:
title = title.replace(r"\|", "|").strip() # noqa: PLW2901
parts.append(f'=== "{title}"')
parts.append(indent(text, prefix=" " * 4))
parts.append("")
return "\n".join(parts)
def _hide_lines(source: str) -> str:
return "\n".join(line for line in source.split("\n") if "markdown-exec: hide" not in line).strip()
def add_source(
*,
source: str,
location: str,
output: str,
language: str,
tabs: tuple[str, str],
result: str = "",
**extra: str,
) -> str:
"""Add source code block to the output.
Parameters:
source: The source code block.
location: Where to add the source (above, below, tabbed-left, tabbed-right, console).
output: The current output.
language: The code language.
tabs: Tabs titles (if used).
result: Syntax to use when concatenating source and result with "console" location.
**extra: Extra options added back to source code block.
Raises:
ValueError: When the given location is not supported.
Returns:
The updated output.
"""
source = _hide_lines(source)
if location == "console":
return code_block(result or language, source + "\n" + output, **extra)
source_block = code_block(language, source, **extra)
if location == "above":
return source_block + "\n\n" + output
if location == "below":
return output + "\n\n" + source_block
if location == "material-block":
return source_block + f'\n\n
"
html = base_format(
language="whatever",
run=lambda code, **_: code,
code=code,
md=md,
html=True,
)
assert html == code
@pytest.mark.parametrize("html", [True, False])
def test_render_source(md: Markdown, html: bool) -> None:
"""Assert source is rendered.
Parameters:
md: A Markdown instance (fixture).
html: Whether output is HTML or not.
"""
markup = base_format(
language="python",
run=lambda code, **_: code,
code="hello",
md=md,
html=html,
source="tabbed-left",
)
assert "Source" in markup
def test_render_console_plus_ansi_result(md: Markdown) -> None:
"""Assert we can render source as console style with `ansi` highlight.
Parameters:
md: A Markdown instance (fixture).
"""
markup = base_format(
language="bash",
run=lambda code, **_: code,
code="echo -e '\033[31mhello'",
md=md,
html=False,
source="console",
result="ansi",
)
assert "helloansi" in markup
def test_dont_render_anything_if_output_is_empty(md: Markdown) -> None:
"""Assert nothing is rendered if output is empty.
Parameters:
md: A Markdown instance (fixture).
"""
markup = base_format(
language="bash",
run=lambda code, **_: "",
code="whatever",
md=md,
)
assert not markup
def test_render_source_even_if_output_is_empty(md: Markdown) -> None:
"""Assert source is rendered even if output is empty.
Parameters:
md: A Markdown instance (fixture).
"""
markup = base_format(
language="bash",
run=lambda code, **_: "",
code="whatever",
md=md,
source="tabbed-left",
)
assert "Source" in markup
@pytest.mark.skipif(os.name != "posix", reason="No time for the annoying OS.")
def test_changing_working_directory(md: Markdown) -> None:
"""Assert we can change the working directory with `workdir`.
Parameters:
md: A Markdown instance (fixture).
"""
markup = base_format(
language="python",
run=lambda code, **_: subprocess.check_output(code, shell=True, text=True), # noqa: S602
code="pwd",
md=md,
workdir="/",
)
assert markup == "Int" not in html
assert re.search(r"class '_code_block_n\d+_\.Int'", html)
markdown-exec-1.10.2/tests/test_shell.py 0000664 0000000 0000000 00000003753 14766364173 0020252 0 ustar 00root root 0000000 0000000 """Tests for the shell formatters."""
from __future__ import annotations
from textwrap import dedent
from typing import TYPE_CHECKING
if TYPE_CHECKING:
import pytest
from markdown import Markdown
def test_output_markdown(md: Markdown) -> None:
"""Assert Markdown is converted to HTML.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```sh exec="yes"
echo "**Bold!**"
```
""",
),
)
assert html == "