# mpl_ascii
A matplotlib backend that produces plots using only ASCII characters. It is available for python 3.9+.
## Quick start
Install `mpl_ascii` using pip
```bash
pip install mpl_ascii
```
To use mpl_ascii, add to your python program
```python
import matplotlib as mpl
mpl.use("module://mpl_ascii")
```
When you use `plt.show()` then it will print the plots as strings that consists of ASCII characters.
If you want to save a figure to a `.txt` file then just use `figure.savefig("my_figure.txt")`
See more information about using backends here: https://matplotlib.org/stable/users/explain/figure/backends.html
## Examples
### Bar chart
```python
import matplotlib.pyplot as plt
import matplotlib as mpl
mpl.use("module://mpl_ascii")
import matplotlib.pyplot as plt
# Example data
fruits = ['apple', 'blueberry', 'cherry', 'orange']
counts = [10, 15, 7, 5]
colors = ['red', 'blue', 'red', 'orange'] # Colors corresponding to each fruit
fig, ax = plt.subplots()
# Plot each bar individually
for fruit, count, color in zip(fruits, counts, colors):
ax.bar(fruit, count, color=color, label=color)
# Display the legend
ax.legend(title='Fruit color')
plt.show()
```
### Scatter plot
```python
import matplotlib.pyplot as plt
import numpy as np
import matplotlib as mpl
mpl.use("module://mpl_ascii")
np.random.seed(0)
x = np.random.rand(40)
y = np.random.rand(40)
colors = np.random.choice(['red', 'green', 'blue', 'yellow'], size=40)
color_labels = ['Red', 'Green', 'Blue', 'Yellow'] # Labels corresponding to colors
# Create a scatter plot
fig, ax = plt.subplots()
for color, label in zip(['red', 'green', 'blue', 'yellow'], color_labels):
# Plot each color as a separate scatter plot to enable legend tracking
idx = np.where(colors == color)
ax.scatter(x[idx], y[idx], color=color, label=label)
# Set title and labels
ax.set_title('Scatter Plot with 4 Different Colors')
ax.set_xlabel('X axis')
ax.set_ylabel('Y axis')
# Add a legend
ax.legend(title='Point Colors')
plt.show()
```
### Line plot
```python
import matplotlib.pyplot as plt
import numpy as np
import matplotlib as mpl
import mpl_ascii
mpl.use("module://mpl_ascii")
# Data for plotting
t = np.arange(0.0, 2.0, 0.01)
s = 1 + np.sin(2 * np.pi * t)
c = 1 + np.cos(2 * np.pi * t)
fig, ax = plt.subplots()
ax.plot(t, s)
ax.plot(t, c)
ax.set(xlabel='time (s)', ylabel='voltage (mV)',
title='About as simple as it gets, folks')
plt.show()
```
You can find more examples in the `tests/accepted` folder.
## Use cases
### Using Version Control for Plots
Handling plots with version control can pose challenges, especially when dealing with binary files. Here are some issues you might encounter:
- Binary Files: Committing binary files like PNGs can significantly increase your repository’s size. They are also difficult to compare (diff) and can lead to complex merge conflicts.
- SVG Files: Although SVGs are more version control-friendly than binary formats, they can still cause problems:
- Large or complex graphics can result in excessively large SVG files.
- Diffs can be hard to interpret.
To mitigate these issues, ASCII plots serve as an effective alternative:
- Size: ASCII representations are much smaller in size.
- Version Control Compatibility: They are straightforward to diff and simplify resolving merge conflicts.
This package acts as a backend for Matplotlib, enabling you to continue creating plots in your usual formats (PNG, SVG) during development. When you’re ready to commit your plots to a repository, simply switch to the `mpl_ascii` backend to convert them into ASCII format.
## Feedback
Please help make this package better by:
- reporting bugs.
- making feature requests. Matplotlib is an enormous library and this supports only a part of it. Let me know if there particular charts that you would like to be converted to ASCII
- letting me know what you use this for.
If you want to tell me about any of the above just use the Issues tab for now.
Thanks for reading and I hope you will like these plots as much as I do :-)
Raw data
{
"_id": null,
"home_page": null,
"name": "mpl-ascii",
"maintainer": "Chris Cave",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "matplotlib, plotting, ASCII",
"author": "Chris Cave",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0a/91/d746c7a5ec879522d92197628f4346911377b22ce67ab26482802a55398d/mpl_ascii-1.0.0.tar.gz",
"platform": null,
"description": "# mpl_ascii\n\nA matplotlib backend that produces plots using only ASCII characters. It is available for python 3.9+.\n\n## Quick start\n\nInstall `mpl_ascii` using pip\n\n```bash\npip install mpl_ascii\n```\n\nTo use mpl_ascii, add to your python program\n\n```python\nimport matplotlib as mpl\n\nmpl.use(\"module://mpl_ascii\")\n```\n\nWhen you use `plt.show()` then it will print the plots as strings that consists of ASCII characters.\n\nIf you want to save a figure to a `.txt` file then just use `figure.savefig(\"my_figure.txt\")`\n\nSee more information about using backends here: https://matplotlib.org/stable/users/explain/figure/backends.html\n\n## Examples\n\n### Bar chart\n\n\n```python\nimport matplotlib.pyplot as plt\nimport matplotlib as mpl\n\nmpl.use(\"module://mpl_ascii\")\n\nimport matplotlib.pyplot as plt\n\n# Example data\nfruits = ['apple', 'blueberry', 'cherry', 'orange']\ncounts = [10, 15, 7, 5]\ncolors = ['red', 'blue', 'red', 'orange'] # Colors corresponding to each fruit\n\nfig, ax = plt.subplots()\n\n# Plot each bar individually\nfor fruit, count, color in zip(fruits, counts, colors):\n ax.bar(fruit, count, color=color, label=color)\n\n# Display the legend\nax.legend(title='Fruit color')\n\nplt.show()\n```\n\n\n\n### Scatter plot\n\n\n```python\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport matplotlib as mpl\n\n\nmpl.use(\"module://mpl_ascii\")\n\nnp.random.seed(0)\nx = np.random.rand(40)\ny = np.random.rand(40)\ncolors = np.random.choice(['red', 'green', 'blue', 'yellow'], size=40)\ncolor_labels = ['Red', 'Green', 'Blue', 'Yellow'] # Labels corresponding to colors\n\n# Create a scatter plot\nfig, ax = plt.subplots()\nfor color, label in zip(['red', 'green', 'blue', 'yellow'], color_labels):\n # Plot each color as a separate scatter plot to enable legend tracking\n idx = np.where(colors == color)\n ax.scatter(x[idx], y[idx], color=color, label=label)\n\n# Set title and labels\nax.set_title('Scatter Plot with 4 Different Colors')\nax.set_xlabel('X axis')\nax.set_ylabel('Y axis')\n\n# Add a legend\nax.legend(title='Point Colors')\nplt.show()\n```\n\n\n\n### Line plot\n\n```python\nimport matplotlib.pyplot as plt\nimport numpy as np\nimport matplotlib as mpl\nimport mpl_ascii\n\n\nmpl.use(\"module://mpl_ascii\")\n\n\n# Data for plotting\nt = np.arange(0.0, 2.0, 0.01)\ns = 1 + np.sin(2 * np.pi * t)\nc = 1 + np.cos(2 * np.pi * t)\n\nfig, ax = plt.subplots()\nax.plot(t, s)\nax.plot(t, c)\n\nax.set(xlabel='time (s)', ylabel='voltage (mV)',\n title='About as simple as it gets, folks')\n\nplt.show()\n```\n\n\nYou can find more examples in the `tests/accepted` folder.\n\n## Use cases\n\n### Using Version Control for Plots\n\nHandling plots with version control can pose challenges, especially when dealing with binary files. Here are some issues you might encounter:\n\n- Binary Files: Committing binary files like PNGs can significantly increase your repository\u2019s size. They are also difficult to compare (diff) and can lead to complex merge conflicts.\n\n- SVG Files: Although SVGs are more version control-friendly than binary formats, they can still cause problems:\n - Large or complex graphics can result in excessively large SVG files.\n - Diffs can be hard to interpret.\n\nTo mitigate these issues, ASCII plots serve as an effective alternative:\n\n- Size: ASCII representations are much smaller in size.\n- Version Control Compatibility: They are straightforward to diff and simplify resolving merge conflicts.\n\n\nThis package acts as a backend for Matplotlib, enabling you to continue creating plots in your usual formats (PNG, SVG) during development. When you\u2019re ready to commit your plots to a repository, simply switch to the `mpl_ascii` backend to convert them into ASCII format.\n\n## Feedback\n\nPlease help make this package better by:\n- reporting bugs.\n- making feature requests. Matplotlib is an enormous library and this supports only a part of it. Let me know if there particular charts that you would like to be converted to ASCII\n- letting me know what you use this for.\n\nIf you want to tell me about any of the above just use the Issues tab for now.\n\nThanks for reading and I hope you will like these plots as much as I do :-)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A matplotlib backend that produces plots using only ASCII characters",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/chriscave/mpl_ascii"
},
"split_keywords": [
"matplotlib",
" plotting",
" ascii"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "60b1c9e93fa771ee01f77d3bec68184d0596ebf568bd3dc707290af61745484b",
"md5": "74d984766892ad32a180d4685ec57b93",
"sha256": "d2fc3a5750bf47aafdf0666ece0aa03edb7dc561d85f739c455344d97ccdebfc"
},
"downloads": -1,
"filename": "mpl_ascii-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74d984766892ad32a180d4685ec57b93",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35858,
"upload_time": "2025-09-06T18:08:52",
"upload_time_iso_8601": "2025-09-06T18:08:52.651468Z",
"url": "https://files.pythonhosted.org/packages/60/b1/c9e93fa771ee01f77d3bec68184d0596ebf568bd3dc707290af61745484b/mpl_ascii-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0a91d746c7a5ec879522d92197628f4346911377b22ce67ab26482802a55398d",
"md5": "1cae9c2c52f5134457715cbce84a28eb",
"sha256": "35e5f11c602e8717063aa61e87dc65817ea3d94f14f340ffd0c0ffab16111380"
},
"downloads": -1,
"filename": "mpl_ascii-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1cae9c2c52f5134457715cbce84a28eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 100543,
"upload_time": "2025-09-06T18:08:53",
"upload_time_iso_8601": "2025-09-06T18:08:53.895416Z",
"url": "https://files.pythonhosted.org/packages/0a/91/d746c7a5ec879522d92197628f4346911377b22ce67ab26482802a55398d/mpl_ascii-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 18:08:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chriscave",
"github_project": "mpl_ascii",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.3"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.7.1"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.4"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"62"
]
]
},
{
"name": "setuptools_scm",
"specs": [
[
">=",
"7.1.0"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"4.0.2"
]
]
},
{
"name": "build",
"specs": [
[
">=",
"1.1.1"
]
]
}
],
"lcname": "mpl-ascii"
}
JSON
