├── __init__.py ├── .gitignore ├── pyproject.toml ├── README.md ├── matplotlib-backend-notcurses └── __init__.py └── LICENSE /__init__.py: -------------------------------------------------------------------------------- 1 | matplotlib-backend-notcurses/__init__.py -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .pyc 2 | __pycache__ 3 | dist/ 4 | *.egg-info/ 5 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "matplotlib-backend-notcurses" 3 | version = "1.0.2" 4 | description = "show matplotlib plots inline in most terminals, via notcurses" 5 | readme = "README.md" 6 | classifiers = [ 7 | "Programming Language :: Python :: 3", 8 | "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication", 9 | "Framework :: Matplotlib", 10 | "Topic :: Terminals", 11 | ] 12 | dependencies = [ "matplotlib" ] 13 | 14 | [project.urls] 15 | "Homepage" = "https://github.com/jktr/matplotlib-backend-notcurses" 16 | "Bug Tracker" = "https://github.com/jktr/matplotlib-backend-notcurses/issues" 17 | 18 | [build-system] 19 | requires = [ "setuptools>=61.0" ] 20 | build-backend = "setuptools.build_meta" 21 | 22 | [tool.setuptools.packages.find] 23 | where = [ "." ] 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # matplotlib-backend-notcurses 2 | 3 | This python module allows you to show the plots generated 4 | by python's [matplotlib](https://github.com/matplotlib/matplotlib) 5 | in many modern and older terminals by using 6 | [notcurses](https://github.com/dankamongmen/notcurses/). 7 | 8 | To install it, you will need to do one of the following 9 | 10 | - `$ pip install --user matplotlib-backend-notcurses` 11 | - clone this repo into your python's `site-packages` directory 12 | - clone this repo and add the parent directory to `sys.path` or `$PYTHONPATH` 13 | 14 | Then, configure matplotlib to use the module by either setting the 15 | environment variable `MPLBACKEND` to `module://matplotlib-backend-notcurses` 16 | or by initializing matplotlib as follows. 17 | 18 | ```python 19 | import matplotlib 20 | matplotlib.use('module://matplotlib-backend-notcurses') 21 | import matplotlib.pyplot as plt 22 | ``` 23 | 24 | Please make sure that you have the programs `ncplayer` 25 | and `notcurses-info`, both from `notcurses`, in your `PATH`. 26 | 27 | If you've installed this module correctly, you can now use 28 | the following sample code to draw a plot in your terminal. 29 | 30 | ``` 31 | $ export MPLBACKEND='module://matplotlib-backend-notcurses' 32 | $ python -i 33 | >>> import numpy as np; import pandas as pd 34 | >>> n = 10000 35 | >>> df = pd.DataFrame({'x': np.random.randn(n), 36 | 'y': np.random.randn(n)}) 37 | >>> df.plot.hexbin(x='x', y='y', gridsize=20) 38 | 39 | ``` 40 | 41 | If you set your matplotlib to interactive mode via 42 | `matplotlib.pyplot.ion()` or by running python as 43 | `python -i`, non-empty figures are drawn on construction 44 | where possible. This allows you to use pandas' `plot()` 45 | calls directly, without calling `plt.show()`, and still 46 | enables you to manually construct and `plt.show()`. 47 | 48 | If your matplotlib is in non-interactive mode, 49 | you can construct your figures as usual, and then call 50 | `plt.show()` to render them to your terminal. This 51 | works from both a repl and when running scripts. 52 | 53 | Figures are resized to the size of your terminal by default. 54 | If you'd rather control the sizing of figures manually, 55 | set the `MPLBACKEND_NOTCURSES_SIZING` environment variable to `manual`. 56 | 57 | Internally, this backend is somewhat based on matplotlib's 58 | IPython support: it's a hybrid of image and GUI backend types. 59 | It works by using matplotlib's `Agg` backend to render the 60 | plot, and then calls notcurses's `ncplayer` to place the rendered 61 | image on your terminal. This means that plotting works as 62 | expected, but the image drawn to your terminal isn't 63 | interactive and animations aren't supported. 64 | 65 | This is a port of my matplotlib-backend-kitty to notcurses 66 | tooling, which provides support for more terminal graphics 67 | protocols and reasonable auto-detection and fallbacks for these. 68 | -------------------------------------------------------------------------------- /matplotlib-backend-notcurses/__init__.py: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: CC0-1.0 2 | 3 | import os 4 | import sys 5 | 6 | from subprocess import run 7 | 8 | from matplotlib import interactive, is_interactive 9 | from matplotlib._pylab_helpers import Gcf 10 | from matplotlib.backend_bases import (_Backend, FigureManagerBase) 11 | from matplotlib.backends.backend_agg import FigureCanvasAgg 12 | 13 | 14 | # XXX heuristic for interactive repl 15 | if sys.flags.interactive: 16 | interactive(True) 17 | 18 | 19 | class FigureManagerNotcurses(FigureManagerBase): 20 | 21 | def show(self): 22 | 23 | margins = '0' 24 | 25 | if os.environ.get('MPLBACKEND_NOTCURSES_SIZING', 'automatic') != 'manual': 26 | 27 | # gather terminal dimensions 28 | # FIXME should use a less hacky way for getting width/height in pixels 29 | info = run(['notcurses-info'], text=True, capture_output=True).stdout.rstrip() 30 | dims = info.splitlines()[1].split(' ') 31 | rows, height, width = map(int, [dims[0].split('[K')[-1], *dims[6].split('x')]) 32 | 33 | # account for post-display prompt scrolling 34 | # 3 line shift for [\n, >>] after the figure 35 | height -= int(3*(height/rows)) 36 | margins = '0,0,3,0' # format: top, right, bottom, left 37 | 38 | dpi = self.canvas.figure.dpi 39 | self.canvas.figure.set_size_inches((width / dpi, height / dpi)) 40 | 41 | r, w = os.pipe() 42 | try: 43 | with os.fdopen(w, 'wb') as wf: 44 | self.canvas.figure.savefig(wf, format='png', facecolor='#888888') 45 | run(['ncplayer', '-k', '-t0', '-q', '-m', margins, f'/dev/fd/{r}'], pass_fds=(r,)) 46 | finally: 47 | os.close(r) 48 | 49 | 50 | class FigureCanvasNotcurses(FigureCanvasAgg): 51 | manager_class = FigureManagerNotcurses 52 | 53 | 54 | @_Backend.export 55 | class _BackendNotcursesAgg(_Backend): 56 | 57 | FigureCanvas = FigureCanvasNotcurses 58 | FigureManager = FigureManagerNotcurses 59 | 60 | # Noop function instead of None signals that 61 | # this is an "interactive" backend 62 | mainloop = lambda: None 63 | 64 | # XXX: `draw_if_interactive` isn't really intended for 65 | # on-shot rendering. We run the risk of being called 66 | # on a figure that isn't completely rendered yet, so 67 | # we skip draw calls for figures that we detect as 68 | # not being fully initialized yet. Our heuristic for 69 | # that is the presence of axes on the figure. 70 | @classmethod 71 | def draw_if_interactive(cls): 72 | manager = Gcf.get_active() 73 | if is_interactive() and manager.canvas.figure.get_axes(): 74 | cls.show() 75 | 76 | @classmethod 77 | def show(cls, *args, **kwargs): 78 | _Backend.show(*args, **kwargs) 79 | Gcf.destroy_all() 80 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for th benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | --------------------------------------------------------------------------------