# PyMD: Python-Powered Markdown
PyMD is a revolutionary markup language that combines familiar markdown syntax with the full power of Python execution. Write beautiful documents using standard markdown headers, lists, and text, while executing Python code in clearly separated code blocks!
## ✨ Features
- **📝 Markdown Syntax**: Use familiar markdown headers (#), lists (-), and plain text
- **🐍 Dual Code Block Types**:
- **``` (3 backticks)**: Execute Python code and show output
- **```` (4 backticks)**: Display code with syntax highlighting only
- **🔗 Variable Persistence**: Variables persist across code blocks in the same document
- **🔴 Live Preview**: Real-time rendering with auto-refresh as you edit
- **📊 Rich Visualizations**: Built-in support for matplotlib, pandas, and other data science libraries
- **🧮 Dynamic Content**: Execute Python code and display results inline
- **📱 Beautiful Output**: Clean, responsive HTML with modern styling
- **⚡ Fast Rendering**: Efficient parsing and rendering engine
- **🔄 Auto-Refresh**: Changes reflect immediately in the live preview
- **💬 Smart Comments**: Display blocks use `//` for cleaner code presentation
## 🚀 Quick Start
### Installation
**Option 1: Install from PyPI (Recommended)**
```bash
pip install pyexecmd
```
<details>
<summary> Option 2: Install from source </summary>
1. **Clone the repository:**
```bash
git clone https://www.github.com/treeleaves30760/PyMD
cd PyMD
```
2. **Install in development mode:**
```bash
pip install -e .
```
</details>
## Usage
1. **Create a new PyMD document:**
```bash
pyexecmd create my_document.pymd
```
2. **Start live preview:**
```bash
pyexecmd serve --file my_document.pymd --port 8080
```
Then open <http://localhost:8080> in your browser
> **Note for macOS users:** Port 5000 is often used by AirPlay. Use `--port 8000` or another port to avoid conflicts.
3. **Render to HTML:**
```bash
pyexecmd render my_document.pymd -o output.html
```
## 📝 PyMD Syntax
PyMD combines familiar markdown syntax with Python code execution:
### Markdown Content (Outside Code Blocks)
**Headers:**
```markdown
# Main Title
## Section Title
### Subsection Title
```
**Lists:**
```markdown
- Unordered list item
- Another unordered item
1. Ordered list item
2. Another ordered item
```
**Plain Text:**
```markdown
This is a paragraph of regular text.
You can write multiple paragraphs easily.
```
**Comments:**
```markdown
// This is a comment and will be ignored
```
### Python Code Blocks
**Simple Code Execution:**
````markdown
```
x = 42
y = "Hello, PyMD!"
print(f"{y} The answer is {x}")
```
````
**Data Analysis:**
````markdown
```
import pandas as pd
import numpy as np
# Create sample data
data = pd.DataFrame({
'Name': ['Alice', 'Bob', 'Charlie'],
'Score': [95, 87, 92]
})
print("Sample Data:")
pymd.table(data)
```
````
**Visualizations:**
````markdown
```
import matplotlib.pyplot as plt
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.figure(figsize=(8, 5))
plt.plot(x, y, 'b-', linewidth=2)
plt.title("Sine Wave Visualization")
plt.grid(True)
pymd.image(plt.gcf(), "Beautiful sine wave")
```
````
**Interactive Input with Mock Values:**
````markdown
```
# Get user input (with mock values for non-interactive execution)
name = input("Enter your name: ") # input: Alice
age = input("Enter your age: ") # input: 25
# Use the input values
pymd.h2(f"Welcome, {name}!")
pymd.text(f"You are {age} years old.")
# Input without mock value defaults to empty string
optional_input = input("Optional comment: ")
if optional_input:
print(f"Comment: {optional_input}")
else:
print("No comment provided")
```
````
**Code Display (Method 1 - Using pymd.code()):**
````markdown
```
sample_code = '''
def factorial(n):
if n <= 1:
return 1
return n * factorial(n-1)
'''
pymd.code(sample_code, "python")
print(f"Factorial of 5 is: {factorial(5)}")
```
````
**Code Display (Method 2 - Using four backticks):**
`````markdown
````
def factorial(n):
// Base case
if n <= 1:
return 1
// Recursive case
return n * factorial(n-1)
// Example usage (not executed)
result = factorial(5)
````
`````
### Key Features
- **Variable Persistence**: Variables defined in one code block are available in subsequent blocks
- **Mixed Content**: Alternate between markdown content and Python code seamlessly
- **Two Code Block Types**:
- **Three backticks (```)**: Execute Python code and show output
- **Four backticks (````)**: Display code with syntax highlighting (no execution)
- **Interactive Input Support**: Use `input()` with mock values for non-interactive execution
- **Clean Separation**: Clear visual distinction between documentation and executable code
- **Rich Output**: Code execution results are displayed with beautiful formatting
- **Smart Comment Styling**: Display blocks use `//` comments for cleaner presentation
### Input Mock System
PyMD supports interactive input through a mock system that allows documents to be rendered without user interaction:
- **With Mock Value**: `input("Prompt: ") # input: mock_value` - Returns "mock_value"
- **Without Mock Value**: `input("Prompt: ")` - Returns empty string ("")
- **Multiple Inputs**: Each `input()` call uses mock values in sequence
- **Silent Execution**: Mock inputs don't produce console output, only the actual code results are shown
## 📁 Project Structure
```file
PyMD/
├── pymd/ # Main package directory
│ ├── __init__.py # Package initialization
│ ├── cli.py # Command-line interface
│ ├── renderer.py # Core rendering engine
│ └── server.py # Live preview server
├── example.pymd # Example PyMD document
├── pyproject.toml # Package configuration
├── MANIFEST.in # Additional files to include
├── LICENSE # MIT License
├── requirements.txt # Python dependencies
└── README.md # This file
```
## 🛠️ API Reference
### Markdown Syntax (Outside Code Blocks)
- `# Header` - Create level 1 heading
- `## Header` - Create level 2 heading
- `### Header` - Create level 3 heading
- `- Item` - Unordered list item
- `1. Item` - Ordered list item
- `Plain text` - Regular paragraph text
- `// Comment` - Comments (ignored during rendering)
### PyMD Functions (Inside Code Blocks)
- `pymd.h1(text)` - Create level 1 heading programmatically
- `pymd.h2(text)` - Create level 2 heading programmatically
- `pymd.h3(text)` - Create level 3 heading programmatically
- `pymd.text(content)` - Create paragraph text programmatically
- `pymd.code(content, language)` - Display code block with syntax highlighting
- `pymd.image(plot_obj, caption)` - Render matplotlib plots
- `pymd.table(data)` - Render pandas DataFrames or tables
### CLI Commands
```bash
# Create new PyExecMD file from template
pyexecmd create <filename> [--force]
# Start live preview server
pyexecmd serve [--file FILE] [--port PORT] [--host HOST] [--debug]
# Render PyExecMD to HTML
pyexecmd render <input> [-o OUTPUT]
```
## 🎯 Use Cases
- **📊 Data Science Reports**: Combine analysis, visualizations, and explanations
- **📚 Interactive Documentation**: Living documents that update with code changes
- **🎓 Educational Materials**: Tutorials with executable examples
- **📈 Dashboard Reports**: Dynamic reports with real-time data
- **🔬 Research Papers**: Academic papers with reproducible results
## 🌟 Examples
Check out `example.pymd` for a comprehensive demonstration of PyMD features, including:
- Markdown-style headers, lists, and text
- Python code execution with output
- Beautiful data visualizations with matplotlib
- Dynamic calculations and variable persistence
- Interactive tables with pandas
- Mixed content workflow
- Real-time preview updates
## 🤝 Contributing
We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.
## 📄 License
This project is licensed under the MIT License.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "pyexecmd",
"maintainer": "PyExecMD Team",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "markdown, python, documentation, jupyter, notebook",
"author": "PyExecMD Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0d/4e/48ce0f88b24ed3f6bd7c1a137d15012c4b27a61f89c1cf5cacd95f9a61f3/pyexecmd-0.1.4.tar.gz",
"platform": null,
"description": "# PyMD: Python-Powered Markdown\n\nPyMD is a revolutionary markup language that combines familiar markdown syntax with the full power of Python execution. Write beautiful documents using standard markdown headers, lists, and text, while executing Python code in clearly separated code blocks!\n\n## \u2728 Features\n\n- **\ud83d\udcdd Markdown Syntax**: Use familiar markdown headers (#), lists (-), and plain text\n- **\ud83d\udc0d Dual Code Block Types**: \n - **``` (3 backticks)**: Execute Python code and show output\n - **```` (4 backticks)**: Display code with syntax highlighting only\n- **\ud83d\udd17 Variable Persistence**: Variables persist across code blocks in the same document\n- **\ud83d\udd34 Live Preview**: Real-time rendering with auto-refresh as you edit\n- **\ud83d\udcca Rich Visualizations**: Built-in support for matplotlib, pandas, and other data science libraries\n- **\ud83e\uddee Dynamic Content**: Execute Python code and display results inline\n- **\ud83d\udcf1 Beautiful Output**: Clean, responsive HTML with modern styling\n- **\u26a1 Fast Rendering**: Efficient parsing and rendering engine\n- **\ud83d\udd04 Auto-Refresh**: Changes reflect immediately in the live preview\n- **\ud83d\udcac Smart Comments**: Display blocks use `//` for cleaner code presentation\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n**Option 1: Install from PyPI (Recommended)**\n\n```bash\npip install pyexecmd\n```\n\n<details>\n\n<summary> Option 2: Install from source </summary>\n\n1. **Clone the repository:**\n\n ```bash\n git clone https://www.github.com/treeleaves30760/PyMD\n cd PyMD\n ```\n\n2. **Install in development mode:**\n\n ```bash\n pip install -e .\n ```\n\n</details>\n\n## Usage\n\n1. **Create a new PyMD document:**\n\n ```bash\n pyexecmd create my_document.pymd\n ```\n\n2. **Start live preview:**\n\n ```bash\n pyexecmd serve --file my_document.pymd --port 8080\n ```\n\n Then open <http://localhost:8080> in your browser\n\n > **Note for macOS users:** Port 5000 is often used by AirPlay. Use `--port 8000` or another port to avoid conflicts.\n\n3. **Render to HTML:**\n\n ```bash\n pyexecmd render my_document.pymd -o output.html\n ```\n\n## \ud83d\udcdd PyMD Syntax\n\nPyMD combines familiar markdown syntax with Python code execution:\n\n### Markdown Content (Outside Code Blocks)\n\n**Headers:**\n\n```markdown\n# Main Title\n## Section Title\n### Subsection Title\n```\n\n**Lists:**\n\n```markdown\n- Unordered list item\n- Another unordered item\n\n1. Ordered list item\n2. Another ordered item\n```\n\n**Plain Text:**\n\n```markdown\nThis is a paragraph of regular text.\nYou can write multiple paragraphs easily.\n```\n\n**Comments:**\n\n```markdown\n// This is a comment and will be ignored\n```\n\n### Python Code Blocks\n\n**Simple Code Execution:**\n\n````markdown\n```\nx = 42\ny = \"Hello, PyMD!\"\nprint(f\"{y} The answer is {x}\")\n```\n````\n\n**Data Analysis:**\n\n````markdown\n```\nimport pandas as pd\nimport numpy as np\n\n# Create sample data\n\ndata = pd.DataFrame({\n 'Name': ['Alice', 'Bob', 'Charlie'],\n 'Score': [95, 87, 92]\n})\n\nprint(\"Sample Data:\")\npymd.table(data)\n```\n````\n\n**Visualizations:**\n\n````markdown\n```\nimport matplotlib.pyplot as plt\n\nx = np.linspace(0, 10, 100)\ny = np.sin(x)\n\nplt.figure(figsize=(8, 5))\nplt.plot(x, y, 'b-', linewidth=2)\nplt.title(\"Sine Wave Visualization\")\nplt.grid(True)\n\npymd.image(plt.gcf(), \"Beautiful sine wave\")\n```\n````\n\n**Interactive Input with Mock Values:**\n\n````markdown\n```\n# Get user input (with mock values for non-interactive execution)\nname = input(\"Enter your name: \") # input: Alice\nage = input(\"Enter your age: \") # input: 25\n\n# Use the input values\npymd.h2(f\"Welcome, {name}!\")\npymd.text(f\"You are {age} years old.\")\n\n# Input without mock value defaults to empty string\noptional_input = input(\"Optional comment: \")\nif optional_input:\n print(f\"Comment: {optional_input}\")\nelse:\n print(\"No comment provided\")\n```\n````\n\n**Code Display (Method 1 - Using pymd.code()):**\n\n````markdown\n```\nsample_code = '''\ndef factorial(n):\n if n <= 1:\n return 1\n return n * factorial(n-1)\n'''\n\npymd.code(sample_code, \"python\")\nprint(f\"Factorial of 5 is: {factorial(5)}\")\n```\n````\n\n**Code Display (Method 2 - Using four backticks):**\n\n`````markdown\n````\ndef factorial(n):\n // Base case\n if n <= 1:\n return 1\n // Recursive case\n return n * factorial(n-1)\n\n// Example usage (not executed)\nresult = factorial(5)\n````\n`````\n\n### Key Features\n\n- **Variable Persistence**: Variables defined in one code block are available in subsequent blocks\n- **Mixed Content**: Alternate between markdown content and Python code seamlessly \n- **Two Code Block Types**: \n - **Three backticks (```)**: Execute Python code and show output\n - **Four backticks (````)**: Display code with syntax highlighting (no execution)\n- **Interactive Input Support**: Use `input()` with mock values for non-interactive execution\n- **Clean Separation**: Clear visual distinction between documentation and executable code\n- **Rich Output**: Code execution results are displayed with beautiful formatting\n- **Smart Comment Styling**: Display blocks use `//` comments for cleaner presentation\n\n### Input Mock System\n\nPyMD supports interactive input through a mock system that allows documents to be rendered without user interaction:\n\n- **With Mock Value**: `input(\"Prompt: \") # input: mock_value` - Returns \"mock_value\"\n- **Without Mock Value**: `input(\"Prompt: \")` - Returns empty string (\"\")\n- **Multiple Inputs**: Each `input()` call uses mock values in sequence\n- **Silent Execution**: Mock inputs don't produce console output, only the actual code results are shown\n\n## \ud83d\udcc1 Project Structure\n\n```file\nPyMD/\n\u251c\u2500\u2500 pymd/ # Main package directory\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 renderer.py # Core rendering engine\n\u2502 \u2514\u2500\u2500 server.py # Live preview server\n\u251c\u2500\u2500 example.pymd # Example PyMD document\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 MANIFEST.in # Additional files to include\n\u251c\u2500\u2500 LICENSE # MIT License\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83d\udee0\ufe0f API Reference\n\n### Markdown Syntax (Outside Code Blocks)\n\n- `# Header` - Create level 1 heading\n- `## Header` - Create level 2 heading \n- `### Header` - Create level 3 heading\n- `- Item` - Unordered list item\n- `1. Item` - Ordered list item\n- `Plain text` - Regular paragraph text\n- `// Comment` - Comments (ignored during rendering)\n\n### PyMD Functions (Inside Code Blocks)\n\n- `pymd.h1(text)` - Create level 1 heading programmatically\n- `pymd.h2(text)` - Create level 2 heading programmatically\n- `pymd.h3(text)` - Create level 3 heading programmatically\n- `pymd.text(content)` - Create paragraph text programmatically\n- `pymd.code(content, language)` - Display code block with syntax highlighting\n- `pymd.image(plot_obj, caption)` - Render matplotlib plots\n- `pymd.table(data)` - Render pandas DataFrames or tables\n\n### CLI Commands\n\n```bash\n# Create new PyExecMD file from template\npyexecmd create <filename> [--force]\n\n# Start live preview server\npyexecmd serve [--file FILE] [--port PORT] [--host HOST] [--debug]\n\n# Render PyExecMD to HTML\npyexecmd render <input> [-o OUTPUT]\n```\n\n## \ud83c\udfaf Use Cases\n\n- **\ud83d\udcca Data Science Reports**: Combine analysis, visualizations, and explanations\n- **\ud83d\udcda Interactive Documentation**: Living documents that update with code changes\n- **\ud83c\udf93 Educational Materials**: Tutorials with executable examples\n- **\ud83d\udcc8 Dashboard Reports**: Dynamic reports with real-time data\n- **\ud83d\udd2c Research Papers**: Academic papers with reproducible results\n\n## \ud83c\udf1f Examples\n\nCheck out `example.pymd` for a comprehensive demonstration of PyMD features, including:\n\n- Markdown-style headers, lists, and text\n- Python code execution with output\n- Beautiful data visualizations with matplotlib\n- Dynamic calculations and variable persistence\n- Interactive tables with pandas\n- Mixed content workflow\n- Real-time preview updates\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please feel free to submit issues, feature requests, or pull requests.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License.\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python-Powered Markdown with executable code and dynamic content",
"version": "0.1.4",
"project_urls": {
"Bug Reports": "https://github.com/treeleaves30760/PyMD/issues",
"Homepage": "https://github.com/treeleaves30760/PyMD",
"Source": "https://github.com/treeleaves30760/PyMD"
},
"split_keywords": [
"markdown",
" python",
" documentation",
" jupyter",
" notebook"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9391150fa3d2bf90e0b8b5ab2b4681c7feb4846339cc62ec3266d2296678a4ec",
"md5": "d5e3df107c246b66c84cd293e8708525",
"sha256": "ffc42a130af7603aa41930d967f6ebf1ea5a6b52d4981e0caa7de4bc91b18bb7"
},
"downloads": -1,
"filename": "pyexecmd-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5e3df107c246b66c84cd293e8708525",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26263,
"upload_time": "2025-08-19T10:34:13",
"upload_time_iso_8601": "2025-08-19T10:34:13.986096Z",
"url": "https://files.pythonhosted.org/packages/93/91/150fa3d2bf90e0b8b5ab2b4681c7feb4846339cc62ec3266d2296678a4ec/pyexecmd-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0d4e48ce0f88b24ed3f6bd7c1a137d15012c4b27a61f89c1cf5cacd95f9a61f3",
"md5": "87097cde6b8c628e4d5db74905c45078",
"sha256": "169ae659b17d081944e1fc132e811c242393be46f0d8534449a522535d3b20fd"
},
"downloads": -1,
"filename": "pyexecmd-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "87097cde6b8c628e4d5db74905c45078",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32309,
"upload_time": "2025-08-19T10:34:16",
"upload_time_iso_8601": "2025-08-19T10:34:16.996927Z",
"url": "https://files.pythonhosted.org/packages/0d/4e/48ce0f88b24ed3f6bd7c1a137d15012c4b27a61f89c1cf5cacd95f9a61f3/pyexecmd-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 10:34:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "treeleaves30760",
"github_project": "PyMD",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Flask",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.3.0"
]
]
},
{
"name": "Flask-SocketIO",
"specs": [
[
">=",
"5.3.0"
],
[
"<",
"6.0.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
],
[
"<",
"2.0.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "python-socketio",
"specs": [
[
">=",
"5.8.0"
]
]
},
{
"name": "Werkzeug",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.3.0"
]
]
}
],
"lcname": "pyexecmd"
}
JSON
