# 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/5f/02/5ad6ce56e3f7c545ed6a4096515d4a2bf6d88ad892ef41d7618941c2ce49/mpl_ascii-1.0.1.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.1",
"project_urls": {
"Homepage": "https://github.com/chriscave/mpl_ascii"
},
"split_keywords": [
"matplotlib",
" plotting",
" ascii"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0a745a3396f1e594afed85324ec43fe069336e112db26461093647be074ce1c5",
"md5": "7f0a8da6c445cb641792088d8ad7e22d",
"sha256": "c15e902309c0b5192d1fabefe61017b258566a9929da39c27f7b476240006d9b"
},
"downloads": -1,
"filename": "mpl_ascii-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f0a8da6c445cb641792088d8ad7e22d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35892,
"upload_time": "2025-09-20T05:58:18",
"upload_time_iso_8601": "2025-09-20T05:58:18.053655Z",
"url": "https://files.pythonhosted.org/packages/0a/74/5a3396f1e594afed85324ec43fe069336e112db26461093647be074ce1c5/mpl_ascii-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5f025ad6ce56e3f7c545ed6a4096515d4a2bf6d88ad892ef41d7618941c2ce49",
"md5": "14a47b315c47fff20c081cd5906619ad",
"sha256": "7c33911d47a8bd970f7ad0133695bd2d003a09a36d1a32fe74535d87f294dad5"
},
"downloads": -1,
"filename": "mpl_ascii-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "14a47b315c47fff20c081cd5906619ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 100584,
"upload_time": "2025-09-20T05:58:19",
"upload_time_iso_8601": "2025-09-20T05:58:19.409770Z",
"url": "https://files.pythonhosted.org/packages/5f/02/5ad6ce56e3f7c545ed6a4096515d4a2bf6d88ad892ef41d7618941c2ce49/mpl_ascii-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-20 05:58:19",
"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
