API Documentation
plotext
The plotext module is the main package: it holds the functions listed below, the primitive classes and the prettydoc module, each described in its own section of this page, and four attributes: the master figure plotext.figure, the plotext.terminal object, the plotext.doc documentation container and the plotext.file toolkit.
Two module-level constants are also available:
plotext.version: the installedplotextversion string, the same asplotext.__version__.plotext.platform:"unix"or"windows", detected when the package is imported and used internally for the differences in terminal handling.
- plotext.sin(periods=2, length=200, amplitude=1, phase=0, decay=0, offset=0)[source]
Generates a sinusoidal signal, useful for example to test plotting routines.
Source: plotext
These are its parameters:
periods: number of sinusoidal cycles. type: a numeric value default: 2
length: total number of sample points. type: an integer default: 200
amplitude: half the peak-to-peak amplitude of the sine wave. type: a numeric value default: 1
phase: phase shift in units of pi (half cycle): 0.5 turns the sine into a cosine, 1 into its negative. type: a numeric value default: 0
decay: exponential decay over the signal length; the final amplitude shrinks by a factor exp(-decay). type: a numeric value default: 0
offset: additional vertical offset. type: a numeric value default: 0
Returns: list of floats representing the generated signal. type: a list of numeric values
- plotext.square(periods=2, length=200, amplitude=1)[source]
Generates a square wave signal alternating between +amplitude and -amplitude, useful for example to test plotting routines.
Source: plotext
These are its parameters:
periods: number of complete square-wave cycles. type: a numeric value default: 2
length: total number of sample points. type: an integer default: 200
amplitude: half the peak-to-peak value of the square wave. type: a numeric value default: 1
Returns: list of floats representing the generated signal. type: a list of numeric values
- plotext.noise(length=200, amplitude=1, offset=0, seed=None)[source]
Generates Gaussian noise samples, useful for example to test histogram rendering.
Source: plotext
These are its parameters:
length: total number of sample points. type: an integer default: 200
amplitude: standard deviation of the Gaussian distribution. type: a numeric value default: 1
offset: mean of the Gaussian distribution (shifts every sample by this amount). type: a numeric value default: 0
seed: integer seed for reproducible output; None (default) draws fresh values at each call. type: an integer default: None
Returns: list of floats representing the noise samples. type: a list of numeric values
- plotext.sample(name='puppy')[source]
Returns the location of a sample file shipped with plotext, useful to try the media and file methods without providing your own files.
Source: plotext
This is its parameter:
name: name of the sample file, without extension: puppy (an image), shaq (a gif), pizzas or stock (csv tables). type: a string default: ‘puppy’
Returns: the full path of the sample file. type: a string
- plotext.uncolorize(item)[source]
Removes all color and style codes, returning a plain string.
Source: plotext
This is its parameter:
item: the string, colorized object or matrix to strip. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: string without the color and style codes. type: a string
- plotext.colors()[source]
Prints every available color: the named string codes, the 256 integer codes, and the RGB tuple form. Each entry is rendered in its own color.
Source: plotext
- plotext.styles()[source]
Prints every available text style code (bold, italic, and so on), each rendered in its own style.
Source: plotext
- plotext.markers()[source]
Prints every available marker code: the named character codes and the higher resolution codes (hd, fhd, braille), each shown next to the characters it renders with.
Source: plotext
- plotext.line_styles()[source]
Prints every available line and axis style, each shown as a box with a middle horizontal and vertical line, with a note on which methods accept which styles.
Source: plotext
- plotext.themes()[source]
Displays every available color theme as a grid of mini-plots, one plot per theme, each titled with its name. Use a theme name in plotext.figure.theme() or plotext.figure.subplot().theme() to apply it.
Source: plotext
- plotext.add_theme(name, canvas=None, text=None, sequence=None, grid=None)[source]
Registers a custom color theme under the given name, overwriting any existing one. The theme is then applied by name with the theme() method, and shown by plotext.themes().
Source: plotext
These are its parameters:
name: the theme name. type: a string
canvas: canvas background color; Use plotext.colors() for the available color codes. type: a string color code, an integer (from 0 to 255), or a tuple of 3 integers (each from 0 to 255)
text: pixel shared by the axes, rulers, labels and legend. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
sequence: the signal colors, completed with the standard palette. type: a list of color codes or pixel objects
grid: grid lines pixel; if None, they take the text one. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
- plotext.effect(text, name='shimmer', step=0.0, period=None)[source]
Colors each character of the text with the chosen effect, returning a single-row matrix; increase step between calls to animate, for example on a title updated in a loop.
Source: plotext
These are its parameters:
text: the string to style. type: a string
name: effect name: one of shimmer, pulse, rainbow, gradient. type: a string default: shimmer
step: animation phase; advance between frames to animate. type: a numeric value default: 0.0
period: number of step units after which the effect repeats; if None, it defaults to 10 for pulse and rainbow, and to the text length for shimmer and gradient. type: a numeric value
Returns: styled 1-row matrix. type: a plotext matrix object
See Colored Text for usage and Streaming Plots for the animation pattern.
- plotext.sleep(seconds=0)[source]
Pauses execution for the given number of seconds, useful between frames when streaming a continuous flow of data, to reduce screen flickering. Tweak the value manually to balance smoothness against responsiveness.
Source: plotext
This is its parameter:
seconds: seconds to pause; may be fractional. type: a numeric value default: 0
See Streaming Plots for the animation pattern.
- plotext.image(path, gray=False, width=None, height=None, ratio=True)[source]
Opens an image file, from a local path or a web address, and paints it into a plotext matrix; call .print() on the result. Roughly 5-10x faster than figure.image().
Source: plotext
These are its parameters:
path: local path or web address of the file; web addresses are downloaded once and reused on later calls. type: a string
gray: converts the image to grayscale before rendering. type: a boolean value default: False
width: image width in canvas characters. type: an integer
height: image height in canvas characters. type: an integer
ratio: keeps the image proportions (accounting for terminal cells being taller than wide), otherwise the image is stretched to exactly the given width and height. type: a boolean value default: True
Returns: a painted plotext.matrix ready to print. type: a plotext matrix object
See Media for full usage notes and a comparison with the figure-integrated plotext.figure.image().
- plotext.gif(path, gray=False, width=None, height=None, ratio=True, loop=False, seconds=None, _hint=True)[source]
Plays a GIF, from a local path or a web address. Pressing q stops the stream.
Source: plotext
These are its parameters:
path: local path or web address of the file; web addresses are downloaded once and reused on later calls. type: a string
gray: converts each frame to grayscale before rendering. type: a boolean value default: False
width: image width in canvas characters. type: an integer
height: image height in canvas characters. type: an integer
ratio: keeps each frame’s proportions (accounting for terminal cells being taller than wide), otherwise each frame is stretched to exactly the given width and height. type: a boolean value default: True
loop: replays forever until q is pressed, otherwise plays once and returns. type: a boolean value default: False
seconds: stops the stream after this many seconds, if None it goes on until its natural end or when q is pressed. type: a numeric value default: None
See Media for full usage notes.
- plotext.video(path, gray=False, width=None, height=None, ratio=True, loop=False, seconds=None, _hint=True)[source]
Plays a video, with its audio, from a local path, a web address or a YouTube address. Pressing q stops the stream.
Source: plotext
These are its parameters:
path: local path, web address or YouTube address of the video; web addresses are downloaded once and reused on later calls, while YouTube addresses are streamed directly. type: a string
gray: converts each frame to grayscale before rendering. type: a boolean value default: False
width: image width in canvas characters. type: an integer
height: image height in canvas characters. type: an integer
ratio: keeps each frame’s proportions (accounting for terminal cells being taller than wide), otherwise each frame is stretched to exactly the given width and height. type: a boolean value default: True
loop: replays forever until q is pressed, otherwise plays once and returns. type: a boolean value default: False
seconds: stops the stream after this many seconds, if None it goes on until its natural end or when q is pressed. type: a numeric value default: None
See Media for full usage notes, plotext.video handles local files, direct media URLs, and YouTube URLs natively.
- plotext.matplotlib(figure)[source]
Converts a matplotlib Figure into the plotext figure. Matplotlib is only imported by this method, so plotext does not require it.
Source: plotext
This is its parameter:
figure: a matplotlib figure object to convert. type: a matplotlib figure object
Returns: the figure itself. type: a plotext figure object
pixel
- class plotext.pixel(foreground=None, background=None, style=None, _pointer=None)[source]
A pixel bundles a foreground color, background color and style into one object.
Source: plotext
These are its parameters:
foreground: foreground color; Use plotext.colors() for the available color codes. type: a string color code, an integer (from 0 to 255), or a tuple of 3 integers (each from 0 to 255)
background: background color; Use plotext.colors() for the available color codes. type: a string color code, an integer (from 0 to 255), or a tuple of 3 integers (each from 0 to 255)
style: styling attributes; Use plotext.styles() for the available style codes. type: a style code string, or multiple codes combined into one space-separated string
Returns: a pixel object. type: a plotext pixel object
- clear()[source]
Clears all color and style properties of the pixel.
Source: plotext.pixel()
Returns: the pixel object itself. type: a plotext pixel object
- foreground()[source]
Returns the foreground color of the pixel, as an (r, g, b) tuple, and None when the pixel carries no foreground. A name, or a number from 0 to 255, is translated into red, green and blue values by the plotext color table.
Source: plotext.pixel()
Returns: the foreground color. type: a tuple of three integers, each from 0 to 255, or None
- background()[source]
Returns the background color of the pixel, as an (r, g, b) tuple, and None when the pixel carries no background. A name, or a number from 0 to 255, is translated into red, green and blue values by the plotext color table.
Source: plotext.pixel()
Returns: the background color. type: a tuple of three integers, each from 0 to 255, or None
- copy()[source]
Returns a copy of the pixel.
Source: plotext.pixel()
Returns: pixel copy. type: a plotext pixel object
colorize
- class plotext.colorize(string=None, pixel=None, _pointer=None)[source]
Wraps a string with color and style attributes.
Source: plotext
These are its parameters:
string: the string to colorize. type: a string default: ‘’
pixel: pixel that determines the color and style. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
Returns: a colorized object. type: a plotext colorize object
- fill(pixel=None)[source]
Applies the color and style settings of a pixel to the colorized object.
Source: plotext.colorize()
This is its parameter:
pixel: pixel that determines the color and style. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
Returns: the colorized object itself. type: a plotext colorize object
- write(string)[source]
Replaces the string content, preserving the current pixel.
Source: plotext.colorize()
This is its parameter:
string: new string content. type: a string
Returns: the colorized object itself. type: a plotext colorize object
- upper()[source]
Uppercases the string in place, preserving the color and style.
Source: plotext.colorize()
Returns: the colorized object itself. type: a plotext colorize object
- lower()[source]
Lowercases the string in place, preserving the color and style.
Source: plotext.colorize()
Returns: the colorized object itself. type: a plotext colorize object
- title()[source]
Title-cases the string in place (first letter of every word uppercased), preserving the color and style.
Source: plotext.colorize()
Returns: the colorized object itself. type: a plotext colorize object
- length()[source]
Returns the string length excluding the color and style ansi codes.
Source: plotext.colorize()
Returns: length of colorless string. type: an integer
- pixel()[source]
Returns the pixel holding the colorized object’s color and style.
Source: plotext.colorize()
Returns: a pixel object. type: a plotext pixel object
- matrix()[source]
Converts the colorized object to a matrix. Newlines in the string split the result into multiple rows; the width matches the widest line.
Source: plotext.colorize()
Returns: matrix representation of the colorized object. type: a plotext matrix object
- string(colorless=False)[source]
Returns the string, optionally stripping color and style ansi codes.
Source: plotext.colorize()
This is its parameter:
colorless: excludes the color and style ansi codes. type: a boolean value default: False
Returns: string, optionally including color codes. type: a string
- print(colorless=False, flush=False)[source]
Prints the colorized string.
Source: plotext.colorize()
These are its parameters:
colorless: prints without the color and style ansi codes. type: a boolean value default: False
flush: flushes the output after printing. type: a boolean value default: False
Returns: the colorized object itself. type: a plotext colorize object
- copy()[source]
Returns a copy of the colorized object.
Source: plotext.colorize()
Returns: colorized copy. type: a plotext colorize object
- hstack(item, adapt=True)[source]
Horizontally stacks this colorized object with another item (a colorize, matrix, or raw string), returning a matrix. The + operator between any such pair is a shortcut for this method (with adapt = True).
Source: plotext.colorize()
These are its parameters:
item: object to stack: a colorize, matrix, or raw string. type: a plotext.matrix, plotext.colorize, or raw string
adapt: adjusts heights to match. type: a boolean value default: True
Returns: resulting matrix. type: a plotext matrix object
- vstack(item, adapt=True)[source]
Vertically stacks this colorized object with another item (a colorize, matrix, or raw string), returning a matrix. The / operator between any such pair is a shortcut for this method (with adapt = True).
Source: plotext.colorize()
These are its parameters:
item: object to stack: a colorize, matrix, or raw string. type: a plotext.matrix, plotext.colorize, or raw string
adapt: adjusts widths to match. type: a boolean value default: True
Returns: resulting matrix. type: a plotext matrix object
matrix
- class plotext.matrix(width, height, pixel=None, _pointer=None)[source]
Creates a matrix of the given dimensions, with an optional default pixel.
Source: plotext
These are its parameters:
width: matrix width in columns. type: an integer
height: matrix height in rows. type: an integer
pixel: default pixel used for every cell. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone default: PlotextPixel()
Returns: a matrix object. type: a plotext matrix object
- clear()[source]
Clears the content of every cell in the matrix; its size remains unchanged.
Source: plotext.matrix()
Returns: the matrix object itself. type: a plotext matrix object
- width()[source]
Returns the matrix width in columns.
Source: plotext.matrix()
Returns: matrix width. type: an integer
- height()[source]
Returns the matrix height in rows.
Source: plotext.matrix()
Returns: matrix height. type: an integer
- size()[source]
Returns the matrix size as a (width, height) tuple.
Source: plotext.matrix()
Returns: a (width, height) tuple. type: a tuple of integer values
- get(row, col)[source]
Returns the pixel coloring the character at the given row and column; negative indexes count from the end, and an index outside the matrix raises an error.
Source: plotext.matrix()
These are its parameters:
row: row index of the character. type: an integer
col: column index of the character. type: an integer
Returns: the pixel of that character. type: a plotext pixel object
- insert(col, row, item, ha=-1, va=-1)[source]
Inserts a matrix, colorize, or raw string at the given position.
Source: plotext.matrix()
These are its parameters:
col: column index position where to insert the item. type: an integer
row: row index position where to insert the item. type: an integer
item: object to insert. type: a plotext.matrix, plotext.colorize, or raw string
ha: horizontal alignment anchor. type: the strings left, center or right (short l, c, r), or the integers -1, 0 or 1 default: -1
va: vertical alignment anchor. type: the strings top, center or bottom (short t, c, b), or the integers -1, 0 or 1 default: -1
Returns: the matrix object itself. type: a plotext matrix object
- hstack(item, adapt=False)[source]
Horizontally stacks this matrix with another item (a matrix, colorize, or raw string). The + operator between any such pair is a shortcut for this method (with adapt = True).
Source: plotext.matrix()
These are its parameters:
item: object to stack horizontally: a matrix, colorize, or raw string. type: a plotext.matrix, plotext.colorize, or raw string
adapt: adjusts heights to match. type: a boolean value default: False
Returns: resulting matrix. type: a plotext matrix object
- vstack(item, adapt=False)[source]
Vertically stacks this matrix with another item (a matrix, colorize, or raw string). The / operator between any such pair is a shortcut for this method (with adapt = True).
Source: plotext.matrix()
These are its parameters:
item: object to stack vertically: a matrix, colorize, or raw string. type: a plotext.matrix, plotext.colorize, or raw string
adapt: adjusts widths to match. type: a boolean value default: False
Returns: resulting matrix. type: a plotext matrix object
- copy()[source]
Returns a copy of the matrix.
Source: plotext.matrix()
Returns: matrix copy. type: a plotext matrix object
- clone(matrix)[source]
Copies the contents of another matrix into this one in place.
Source: plotext.matrix()
This is its parameter:
matrix: matrix whose contents are to be copied. type: a plotext matrix object
Returns: the matrix object itself. type: a plotext matrix object
- transpose()[source]
Transposes the matrix in place: rows become columns.
Source: plotext.matrix()
Returns: the matrix object itself. type: a plotext matrix object
- string(colorless=False)[source]
Returns the rendered matrix as a multi-line string, one line per row.
Source: plotext.matrix()
This is its parameter:
colorless: excludes the color and style ansi codes. type: a boolean value default: False
Returns: rendered matrix string. type: a string
- html()[source]
Returns the HTML representation of the matrix.
Source: plotext.matrix()
Returns: html string for the matrix, the colored block alone, ready to sit inside a page of your own. type: a string
- save(path, colorless=None, append=False, log=False)[source]
Saves the matrix to a file. The file extension determines the format: .html saves a whole web page, naming the character set and a monospaced font so that a browser draws it correctly, .ansi saves text with ANSI color codes, anything else saves plain uncolored text.
Source: plotext.matrix()
These are its parameters:
path: output file path. type: a string
colorless: overrides the extension default: True forces plain text, False keeps color codes/spans. type: a boolean value
append: appends to the file instead of overwriting. type: a boolean value default: False
log: prints a confirmation of the operation. type: a boolean value default: False
Returns: the matrix object itself. type: a plotext matrix object
- print(colorless=False, flush=True)[source]
Prints the matrix.
Source: plotext.matrix()
These are its parameters:
colorless: prints without the color and style ansi codes. type: a boolean value default: False
flush: flushes the output after printing. type: a boolean value default: False
Returns: the matrix object itself. type: a plotext matrix object
- fill(pixel=None)[source]
Applies the given pixel to every cell of the matrix, preserving each cell’s existing glyph (only color and style are overwritten).
Source: plotext.matrix()
This is its parameter:
pixel: pixel whose color and style are copied onto every cell. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
Returns: the matrix object itself. type: a plotext matrix object
marker
- class plotext.marker(symbol=None, pixel=None, ha=-1, va=-1, _pointer=None)[source]
Creates a marker used to render a point on the plot canvas. This is a symbol with an optional pixel that carries its color and style.
Source: plotext
These are its parameters:
symbol: the symbol to use to represent the point on canvas. It could be a single character; a string code from plotext.markers(), a raw string or a plotext.matrix / plotext.colorize (ha and va parameters apply). type: a single character, a code from plotext.markers(), or a plotext.matrix or plotext.colorize for a multi-cell marker default: ‘hd’
pixel: pixel that determines the marker’s color and style. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
ha: horizontal alignment of a matrix/colorize marker around the data point. Ignored for single-cell markers. type: the strings left, center or right (short l, c, r), or the integers -1, 0 or 1 default: -1
va: vertical alignment of a matrix/colorize marker around the data point. Ignored for single-cell markers. type: the strings top, center or bottom (short t, c, b), or the integers -1, 0 or 1 default: -1
Returns: a marker object. type: a plotext marker object
- fill(pixel=None)[source]
Applies a pixel to the marker, replacing its current color and style.
Source: plotext.marker()
This is its parameter:
pixel: pixel that determines the color and style. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
Returns: the marker object itself. type: a plotext marker object
line
- class plotext.line(orientation=0, pixel=PlotextPixel(), style='default', _pointer=None)[source]
Creates a line marker: a single character drawn as a horizontal or vertical line, matching the plot axes styles. Useful as a signal marker to draw straight lines across the canvas.
Source: plotext
These are its parameters:
orientation: line orientation: 0 for horizontal, 1 for vertical. type: an integer default: 0
pixel: pixel that determines the line color and style. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
style: line style. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy or dotted default: ‘default’
Returns: a line object. type: a plotext line object
signal
A signal is a sequence of points plus its drawing settings, created by signal() and passed to draw().
- class plotext._signal.signal.signal_class[source]
- clear()[source]
Removes all points from the signal, making it empty.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
Returns: the signal object itself. type: a plotext signal object
- label(label=None)[source]
Sets the signal label shown on the legend. Labelling a signal is enough to make the legend appear, so legend() is needed only to place it, color it, or switch it off. A signal left unlabelled stays out of the legend.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
label: the label to display on the legend. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the signal object itself. type: a plotext signal object
- lines(active=True)[source]
Draw lines between all consecutive points. Use signal.line() to draw a single segment at a given point instead.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
active: true to connect all points, False to disconnect them. type: a boolean value default: True
Returns: the signal object itself. type: a plotext signal object
- line(index, active=True)[source]
Draw a line from a point to the one before.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
These are its parameters:
index: position of the point whose segment to toggle. Out-of-range indices are silently ignored. The first point (index 0) has no predecessor and is therefore always ignored. type: an integer
active: true to draw the segment, False to break it. type: a boolean value default: True
Returns: the signal object itself. type: a plotext signal object
- fillx(active=True)[source]
Draws a vertical line from each point down to the x axis.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
active: whether to draw the vertical line. type: a boolean value default: True
Returns: the signal object itself. type: a plotext signal object
- filly(active=True)[source]
Draws a horizontal line from each point across to the y axis.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
active: whether to draw the horizontal line. type: a boolean value default: True
Returns: the signal object itself. type: a plotext signal object
- density(method=None, scope=None)[source]
Sets how densely the connecting or filling lines are drawn. Use simple for evenly-spaced points (light and fast, may leave small gaps on steep segments) or full to fill every cell crossed (denser, visually continuous). Connecting lines are turned on via lines() or line() while filling lines are activated using fillx(), filly(), fill().
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
These are its parameters:
method: line drawing method for connecting lines or filling lines. type: the strings simple or full, or the integers 0 or 1 default: ‘simple’
scope: which lines to apply the method to: connecting, filling, or both. type: the strings line, fill or both default: ‘both’
Returns: the signal object itself. type: a plotext signal object
- fill(signal)[source]
Uses the points of another signal as fill points on the current one, useful when building custom stem plots or filled regions.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
signal: signal to copy the fill information from. type: a plotext signal object
Returns: the signal object itself. type: a plotext signal object
- get(index)[source]
Returns the point at the given index.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
index: position of the point in the signal. type: an integer
Returns: the point at that position. type: a plotext point object
- length()[source]
Returns the number of points currently in the signal.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
Returns: number of points. type: an integer
- copy()[source]
Creates and returns a deep copy of the signal.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
Returns: a deep copy of the signal. type: a plotext signal object
- clone(signal)[source]
Overwrites this signal in place with a copy of another: both its points and its settings. Useful to update a signal already registered with the draw() method, which keeps its place in the plot while taking the new content.
Source: plotext.figure.signal(), plotext.figure.subplot().signal()
This is its parameter:
signal: signal copied into this one. type: a plotext signal object
Returns: the signal object itself. type: a plotext signal object
point
The point class is what signal.get() returns: one data point, with its coordinates and marker. It cannot be created directly.
- class plotext._signal.point_filled.point[source]
- x()[source]
Returns the x coordinate of the point.
Source: plotext.figure.signal().get(), plotext.figure.subplot().signal().get()
Returns: the x coordinate. type: a numeric value
figure
plotext.figure is the master figure instance. The same methods are available on any subplot returned by plotext.figure.subplot().
- class plotext._plotter.plot.plot_class[source]
- subplots(rows=None, cols=None)[source]
Divides this plot into a grid of subplots.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
rows: number of subplot rows. type: an integer
cols: number of subplot columns. type: an integer
Returns: the figure itself. type: a plotext figure object
- signal(*args, marker=None, xside=None, yside=None)[source]
Creates a signal, a sequence of points to be plotted.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
*args: input data: x, y coordinates, or a single y sequence, whose points are counted along x from 1 to their number; date values are also supported. type: one or two sequences of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
marker: symbol used to represent each data point. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘hd’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: a signal object. type: a plotext signal object
- ruler(axis=None, side=None)[source]
Returns the ruler relative to the selected axis and side. A ruler is the area alongside its axis where the numerical ticks and their labels appear: it sets which range of data is on display (lim), where the ticks fall and what they read (ticks, frequency), how values grow along it (scale, direction), and how it is drawn (alignment, pixel, grid).
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
axis: axis to access: x, y, or both. type: the strings x or y, or the integers 0 or 1; a list of the two axes, or the word both, is also allowed default: ‘x’
side: axis side to access: one or both. type: the strings lower or upper for the x axis, left or right for the y axis, or the integers 0 or 1; a list of the two sides, or the word both, is also allowed default: 0
Returns: the selection of the chosen rulers. type: a plotext ruler selection object
- date(axis=None, side=None)[source]
Returns the date converter relative to the selected axis and side. A date converter adds date and time support to the selected axis: its methods turn the support on and off (activate, active, clear), convert dates between forms (convert), and report reference dates (today, origin).
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
axis: axis to access: x, y, or both. type: the strings x or y, or the integers 0 or 1; a list of the two axes, or the word both, is also allowed default: ‘x’
side: axis side to access: one or both. type: the strings lower or upper for the x axis, left or right for the y axis, or the integers 0 or 1; a list of the two sides, or the word both, is also allowed default: 0
Returns: the selection of the chosen date converters. type: a plotext date selection object
- title(label=None)[source]
Sets the title of this plot.
Source: plotext.figure, plotext.figure.subplot()
This is its parameter:
label: the title label. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the figure itself. type: a plotext figure object
- label(label=None, axis=None, side=None)[source]
Sets the label of the selected axis and axis side.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
label: the axis label. type: a string, a plotext.colorize object, or a plotext.matrix object
axis: axis to access: x, y, or both. type: the strings x or y, or the integers 0 or 1; a list of the two axes, or the word both, is also allowed default: ‘x’
side: axis side to access. type: the strings lower or upper for the x axis, left or right for the y axis, or the integers 0 or 1; a list of the two sides, or the word both, is also allowed default: 0
Returns: the figure itself. type: a plotext figure object
- axes(active=True, style=None, pixel=None, axis=[0, 1], side=[0, 1])[source]
Controls the visibility, style and pixel of the selected axes, all four by default.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
active: whether the axis is visible. type: a boolean value default: True
style: axis line style. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy, dotted or rounded default: ‘default’
pixel: pixel used to paint the axis. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone default: PlotextPixel()
axis: axis to access: x, y, or both. type: the strings x or y, or the integers 0 or 1; a list of the two axes, or the word both, is also allowed default: ‘both’
side: axis side to access: one or both. type: the strings lower or upper for the x axis, left or right for the y axis, or the integers 0 or 1; a list of the two sides, or the word both, is also allowed default: ‘both’
Returns: the figure itself. type: a plotext figure object
- canvas(background=None)[source]
Sets the background color of the plot canvas: the central area of the plot where points are drawn. The canvas holds no characters of its own: the foreground colors and styles on it come from the drawn signals, each through its marker. These markers are colored automatically, unless explicitly set by the user.
Source: plotext.figure, plotext.figure.subplot()
This is its parameter:
background: canvas background color; the color default leaves it unpainted, so whatever the terminal shows stays behind the plot. Use plotext.colors() for the available color codes. type: a string color code, an integer (from 0 to 255), or a tuple of 3 integers (each from 0 to 255) default: ‘white’
Returns: the figure itself. type: a plotext figure object
- legend(active=True, x=None, y=None, ha=None, va=None, relative=None, pixel=None, style=None, xside=None, yside=None)[source]
Configures the plot legend in the canvas: visibility, position, alignment and color. The legend appears on its own as soon as a signal, or a line, carries a label, listing only what is labelled; this method is needed to move it, color it, or switch it off with active = False.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
active: whether the legend is visible; False keeps it hidden even when labels are present. type: a boolean value default: True
x: x position of the legend anchor. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object. default: 0
y: y position of the legend anchor. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object. default: 0
ha: horizontal alignment of the legend: left, center, or right. type: the strings left, center or right (short l, c, r), or the integers -1, 0 or 1 default: ‘left’
va: vertical alignment of the legend: top, center, or bottom. type: the strings top, center or bottom (short t, c, b), or the integers -1, 0 or 1 default: ‘top’
relative: x and y are read in the ruler numerical units, otherwise as character positions inside the canvas. type: a boolean value default: False
pixel: pixel used to paint the legend: its border, background and plain text labels; colorized labels and the marker samples keep their own colors. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone default: PlotextPixel()
style: line style of the legend box. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy, dotted or rounded default: ‘default’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the figure itself. type: a plotext figure object
- theme(name='default')[source]
Colors the whole plot in one call, following the chosen theme: it sets the canvas background, the axes, the tick labels, the title and axis labels, the legend, and the sequence of colors given to successive signals. The default theme restores the out-of-the-box look, with every color back to its package default. Use plotext.themes() for a preview of the available themes.
Source: plotext.figure, plotext.figure.subplot()
This is its parameter:
name: theme name; unknown names fall back to the default theme. type: one string among: default, simple, colorless, dusk, sand, wine, garden, dark, dreamland, retro, windows, matrix default: ‘default’
Returns: the figure itself. type: a plotext figure object
- time(full=True)[source]
Prints a timing report of the most recent show or build, total elapsed time and, optionally, the time spent in each step, recursing into subplots (if present). Useful when investigating slow renders.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
full: whether to include the time spent in each step; when False, only the total elapsed time is shown. type: a boolean value default: True
full: includes the time spent in each build step and recurses into subplots, otherwise prints only this plot’s total. type: a boolean value default: True
Returns: total elapsed time of this plot in milliseconds. type: a numeric value
- show(colorless=False, flush=True)[source]
Builds and prints the final figure to the terminal: equivalent to build().print(), with the same parameters passed along.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
colorless: renders the output without colors. type: a boolean value default: False
flush: flushes the terminal after printing. type: a boolean value default: False
Returns: the figure itself. type: a plotext figure object
- build()[source]
Builds the final figure as a matrix, without printing it. Use show() to both build and print.
Source: plotext.figure, plotext.figure.subplot()
Returns: the final figure matrix. type: a plotext matrix object
- bar(*args, marker=None, width=None, orientation=None, lines=True, fill=True, labeled=False, stacked=False, xside=None, yside=None, _reset_ticks=True, _offset=None)
Creates a bar plot signal, optionally grouped or stacked.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
*args: bar input data: a single sequence sets the bar heights, with the bar coordinates automatically ranging from 1 onwards; two sequences set the bar coordinates and heights; three sequences set the bar coordinates, baselines and heights (for floating bars). String labels or dates are accepted as bar coordinates. The heights may also be a list of sequences, one per group, for grouped or stacked bars. type: one, two, or three sequences of numeric values or dates: one sets the bar heights, two set the bar coordinates and heights, three set the bar coordinates, baselines and heights; the heights may also be a list of sequences, one per group. dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
marker: symbol used to render the bars; its color is taken automatically from the color cycler. A list gives one marker per bar, or one per group when the bars are grouped or stacked, and is repeated when shorter. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘full’
width: bar width as a fraction of the (smallest) spacing between bar coordinates. For grouped bars this value is divided by the number of groups. type: a numeric value default: 0.8
orientation: bar orientation, either vertical (v in short) or horizontal (h in short). type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘vertical’
lines: draws the bar outline. type: a boolean value default: True
fill: fills the bar body with markers. type: a boolean value default: True
labeled: text written in the middle of each bar: True writes the bar height, a list writes your own text, one entry per bar. Its colors are picked automatically: over a filled shape they contrast the fill, over an outlined one they match the outline. type: a boolean value, or a list of texts, one per bar, each a string, a plotext.colorize object, or a plotext.matrix object; with grouped or stacked bars, a list of such lists, one per series, as the heights are given default: False
stacked: stacks grouped bars on top of each other, so heights add up cumulatively per coordinate, instead of placing them side by side; only meaningful when the heights are a list of sequences. type: a boolean value default: False
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the bar signal. type: a plotext signal object
- box(*args, marker=None, width=None, orientation=None, lines=True, fill=True, xside=None, yside=None)
Creates a box plot signal: each category’s values are summarized by a rectangle stretching from the 25% value to the 75% value of the sorted data, with a line at the median, and thin lines reaching out to the minimum and maximum.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
*args: two sequences: categorical labels (or numeric x positions) and a list of per-category value lists. type: one or two sequences of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
marker: symbol used for the box outline / fill; the median and minimum/maximum lines inherit color from this marker. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘full’
width: box width as a fraction of the smallest spacing between box coordinates. type: a numeric value default: 0.8
orientation: box orientation, either vertical (v in short) or horizontal (h in short). type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘vertical’
lines: draws the box outline. type: a boolean value default: True
fill: fills the box body with markers. type: a boolean value default: True
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the composed box-plot signal. type: a plotext signal object
- candlestick(data, style=None, tick=None, orientation=None, xside=None, yside=None)
Creates a candlestick plot signal. Each candle summarizes prices over one time interval using a rectangle from the opening to the closing price, and a thin vertical line spanning from the lowest to the highest price; the candle is green when the price rose and red when it fell.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
data: a dictionary containing date, open, close, high, low keys and values; dates are interpreted automatically once plotext.date() has been called on the relevant axis. type: a dict with keys date, open, close, high, low; each holding a sequence of values (date may be strings, timestamps, or datetime objects; the others are numeric)
style: candle drawing style. With candle (default), a thick body is drawn from the opening to the closing price. With ohlc, the body is replaced by two short horizontal lines: one to the left of the vertical line at the opening price, one to the right at the closing price; lighter, useful when many candles are packed together. type: a string default: ‘candle’
tick: length, in character cells, of the ohlc style’s short horizontal lines; ignored for candle style. type: an integer default: 2
orientation: candlestick orientation, either vertical (or v) or horizontal (or h). type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘vertical’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the candlestick signal. type: a plotext signal object
- cmatrix(actual, predicted, labels=None, norm=False, map='gray')
Creates a confusion matrix signal, comparing predicted labels against true ones: each cell counts how many samples with a given true label received a given predicted label, and is drawn as a filled rectangle whose color scales with the count, with the count itself as a centered label.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
actual: the list of true labels. type: a sequence of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
predicted: the list of predicted labels, same length as actual. type: a sequence of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
labels: the labels to show on the matrix, in the given row/column order; pairs with labels outside this list are ignored. If None, every distinct label found in actual or predicted is used, in sorted order. type: a sequence of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
norm: cell labels show percentages relative to their row total instead of raw counts; cell colors always use raw counts. type: a boolean value default: False
map: color scale used to turn the counts into cell colors. type: the strings gray or viridis default: ‘gray’
Returns: the composite confusion-matrix signal. type: a plotext signal object
- draw(signal)
Registers a signal to be rendered when plotext.show() or plotext.build() is called. Signals are the objects returned by methods like signal(), bar(), text() or candlestick().
Source: plotext.figure, plotext.figure.subplot()
This is its parameter:
signal: the signal to render. type: a plotext signal object
Returns: the figure itself. type: a plotext figure object
- error(*args, pixel=None, style=None, xside=None, yside=None)
Creates an error bar plot: each point is drawn with a vertical and a horizontal line centered on it, whose lengths are the given vertical and horizontal errors, showing the uncertainty around the point. Dates are not accepted at this stage.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
*args: error input data, given as positional sequences. One sequence sets the vertical coordinates of the points, with the horizontal ones automatically ranging from 1 onwards; two sequences set the horizontal and vertical coordinates, with no errors; three sequences add the vertical errors; four sequences add the vertical and horizontal errors, in this order. Each error can be given as a single number, applied to every point, or as a sequence with one value per point. type: one to four sequences of numeric values; the third and fourth (the errors) may also be single numbers
pixel: pixel used for every stroke of the error bars; if None, a fresh color is taken from the cycler. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
style: line drawing style applied to the bars. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy or dotted default: ‘default’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the composed error-bar signal. type: a plotext signal object
- event(data, orientation=None, pixel=None, style=None, side=None, label=None)
Draws a line spanning the whole canvas at every event coordinate, vertical or horizontal depending on orientation. The lines are added directly to the plot’s draw sequence.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
data: sequence of event coordinates along the chosen orientation. type: a sequence of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
orientation: line orientation, either vertical (or v) or horizontal (or h). type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘vertical’
pixel: pixel used for every line; if None, a fresh color is taken from the color cycler. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
style: line drawing style. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy or dotted default: ‘default’
side: axis side the events are anchored to (x axis side if vertical, y axis side if horizontal). type: the strings lower or upper for the x axis, left or right for the y axis, or the integers 0 or 1 default: 0
label: legend label for the event series (only the first line carries the label so the legend stays a single entry). type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the figure itself. type: a plotext figure object
- heatmap(data, map='gray', fill=False, symbol=None, xside=None, yside=None)
Creates a heatmap plot signal: a 2D data grid drawn as colored cells.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
data: a 2D sequence; either numeric values (colormap applied) or (r, g, b) integer triples (used as cell color directly). type: a 2D sequence; either numeric values, or (r, g, b) integer triples
map: color scale used to turn numeric values into cell colors; ignored when the input is already RGB. type: the strings gray or viridis default: ‘gray’
fill: stretches each cell into a rectangle, otherwise each cell is a single character. type: a boolean value default: False
symbol: symbol used to render every cell; high resolution codes are accepted but not recommended. type: a single character or a named symbol code from plotext.markers(); high resolution codes (hd, fhd, braille) are accepted but not recommended default: ‘█’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the composed heatmap signal. type: a plotext signal object
- hist(data, bins=10, marker=None, width=1, orientation=None, norm=False, lines=True, fill=True, xside=None, yside=None)
Creates a histogram plot signal.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
data: the flat numerical sequence to bin. type: a sequence of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
bins: number of evenly-spaced buckets. type: an integer default: 10
marker: symbol used to render the bars. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘full’
width: bar width as a fraction of the bin size, 1 makes adjacent bins touch. type: a numeric value default: 1
orientation: bar orientation, either vertical (v in short) or horizontal (h in short). type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘vertical’
norm: divides each bin count by the total number of points so all bins sum to 1 (density form), otherwise bin heights are raw counts. type: a boolean value default: False
lines: draws the bar outline. type: a boolean value default: True
fill: fills the bar body with markers. type: a boolean value default: True
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the histogram bar signal. type: a plotext signal object
- image(path, gray=False, symbol=None)
Creates an image signal from a local path or a web address. Slower than plotext.image, but it renders as a normal plot.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
path: local path or web address of the file; web addresses are downloaded once and reused on later calls. type: a string
gray: converts the image to grayscale before rendering. type: a boolean value default: False
symbol: symbol used to render every cell; high resolution codes are accepted but not recommended. type: a single character or a named symbol code from plotext.markers(); high resolution codes (hd, fhd, braille) are accepted but not recommended default: ‘█’
Returns: the composed image signal. type: a plotext signal object
- interactive(active=True)
Toggles the interactive mode: when on, every method that changes the figure (draw, title, theme, …) reprints the whole figure immediately, so each change shows without calling show(). The mode persists across clear(), until interactive(False) is called.
Source: plotext.figure, plotext.figure.subplot()
This is its parameter:
active: turns interactive mode on or off. type: a boolean value default: True
Returns: the figure itself. type: a plotext figure object
- line(position, orientation=0, relative=True, pixel=None, style=None, label=None, xside=None, yside=None)
Adds a horizontal or vertical line spanning the whole plot canvas at the given coordinate. The line is added directly to the plot’s draw sequence.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
position: position of the line along the perpendicular axis: a y value when horizontal, an x value when vertical. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
orientation: line orientation, either horizontal (or h) or vertical (or v). type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘horizontal’
relative: measures position relative to the axis units and limits, otherwise in character cells. type: a boolean value default: True
pixel: pixel used to draw the line. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone default: PlotextPixel()
style: line drawing style. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy or dotted default: ‘default’
label: legend label for the line. type: a string, a plotext.colorize object, or a plotext.matrix object
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the figure itself. type: a plotext figure object
- log()
Prints the tree of nested subplots, one indented line per plot, showing its position, its size, and the rows and columns of subplots it is divided into.
Source: plotext.figure, plotext.figure.subplot()
Returns: the figure itself. type: a plotext figure object
- master()
Returns the master plot, the top-level plot that owns this subtree of subplots.
Source: plotext.figure, plotext.figure.subplot()
Returns: the master figure. type: a plotext figure object
- parent(level=1)
Climbs the hierarchy of nested subplots and returns the plot at the given nesting level: 0 is this plot itself, 1 its immediate parent, and so on. The parent of the master is the terminal, which is its own parent, so every climb ends there.
Source: plotext.figure, plotext.figure.subplot()
This is its parameter:
level: how many steps to climb, each step moving to the parent plot. type: an integer default: 1
Returns: the parent at the requested level. type: a plotext figure object up to the master, then a plotext terminal object
- plot_size(width=None, height=None, direction=None, policy=None)
Sets the size of this plot, in terminal cells, and optionally how subplot sizes are redistributed and harmonized.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
width: plot width in terminal columns. type: an integer
height: plot height in terminal rows. type: an integer
direction: direction of the redistribution of subplot sizes within the maximum available size: with +1 it runs left-to-right across widths and top-to-bottom across heights, and the last subplot absorbs whatever space is left; with -1 the order is reversed, so the first subplot absorbs the leftover instead. If None, the previously set direction remains unchanged. type: the integers 1 or -1 default: None
policy: how nested subplot sizes among rows or columns are harmonized when they disagree: with maximum the subplot size along each column or row takes the largest requested one; with minimum it takes the smallest. If None, the previously set policy remains unchanged. type: the strings minimum or maximum (short min, max), or the integers 0 or 1 default: None
Returns: the figure itself. type: a plotext figure object
- polygon(x=0, y=0, radius=1, sides=3, up=0, marker=None, lines=True, fill=False, xside=None, yside=None)
Creates a polygon signal centered at the given coordinates.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
x: the polygon center x coordinate. type: a numeric value default: 0
y: the polygon center y coordinate. type: a numeric value default: 0
radius: distance of each vertex from the center; for a circle it is the actual radius. type: a numeric value default: 1
sides: number of polygon sides; values above ~50 approximate a circle. type: an integer default: 3
up: 1 places a vertex at the top, 0 places a flat side at the top, any value in between produces a custom tilt. type: a numeric value default: 0
marker: symbol used to render the polygon vertices. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘hd’
lines: draws the polygon outline between consecutive vertices, otherwise only the vertex points are drawn. type: a boolean value default: True
fill: connects each vertex to the polygon center (x, y) with a line; with lines=True the polygon appears filled, with lines=False only the vertex-to-center fills are drawn. type: a boolean value default: False
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the polygon signal. type: a plotext signal object
- position()
Returns this subplot’s position within its parent grid.
Source: plotext.figure, plotext.figure.subplot()
Returns: the subplot’s position tuple. type: a tuple of integer values
- rectangle(x=(0, 1), y=(0, 1), marker=None, lines=True, fill=True, label=None, xside=None, yside=None)
Creates a rectangle signal between the given x and y ranges.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
x: x coordinates of the rectangle corners. type: a two-value tuple or list default: (0, 1)
y: y coordinates of the rectangle corners. type: a two-value tuple or list default: (0, 1)
marker: symbol used to render the rectangle. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘hd’
lines: draws the rectangle’s outline; otherwise only the four corner vertices are drawn. type: a boolean value default: True
fill: fills the rectangle’s body with markers. type: a boolean value default: True
label: optional label drawn at the rectangle’s center. Its colors are picked automatically: over a filled shape they contrast the fill, over an outlined one they match the outline. type: a string, a plotext.colorize object, or a plotext.matrix object
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the rectangle signal. type: a plotext signal object
- segment(x, y, marker=None, xside=None, yside=None)
Creates a straight line segment between two endpoints.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
x: x coordinates of the segment endpoints. type: a two-value tuple or list
y: y coordinates of the segment endpoints. type: a two-value tuple or list
marker: symbol used to render the segment. type: a single character, a code from plotext.markers(), a plotext.matrix or plotext.colorize for a multi-cell marker, a plotext.marker() object, or a list of any of these (one per point) default: ‘hd’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the segment signal. type: a plotext signal object
- size()
Returns the figure or subplot’s size in terminal cells.
Source: plotext.figure, plotext.figure.subplot()
Returns: a (width, height) tuple. type: a tuple of integer values
- subplot(row=None, col=None)
Returns the subplot at the given position within the grid of subplots, to be used like the figure itself.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
row: row index of the subplot. type: an integer default: 1
col: column index of the subplot. type: an integer default: 1
Returns: the subplot at (row, col). type: a plotext figure object
- text(x, y, label, orientation=None, alignment=None, xside=None, yside=None)
Creates a text annotation signal at the given coordinates.
Source: plotext.figure, plotext.figure.subplot()
These are its parameters:
x: x coordinate of the text. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
y: y coordinate of the text. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
label: text content. type: a string, a plotext.colorize object, or a plotext.matrix object
orientation: text orientation, horizontal or vertical. type: the strings horizontal or vertical (short h, v), or the integers 0 or 1 default: ‘horizontal’
alignment: alignment along the writing direction. type: the strings left, center or right for horizontal text (short l, c, r), top, center or bottom for vertical text (short t, c, b), or the integers -1, 0 or 1 default: ‘left’
xside: which x axis to plot against. type: the strings lower or upper, or the integers 0 or 1 default: ‘lower’
yside: which y axis to plot against. type: the strings left or right, or the integers 0 or 1 default: ‘left’
Returns: the text signal. type: a plotext signal object
ruler
plotext.figure.ruler() returns the ruler of the selected axis and side.
- class plotext._plotter.frame.ruler.ruler_class[source]
- frequency(frequency=None)[source]
Sets the number of automatically-placed ticks along the axis. To specify exact tick positions instead, use ticks(), which overrides this setting.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
This is its parameter:
frequency: the number of ticks along the axis. type: an integer default: 7 for x axis; 5 for y axis
Returns: the ruler selection itself. type: a plotext ruler selection object
- ticks(positions=None, labels=None)[source]
Sets explicit tick positions, and optionally their labels, along the axis; when no labels are given, each tick shows its own position value.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
These are its parameters:
positions: a list of numerical tick positions along the axis; an empty list removes the ticks, as frequency(0) does. Dates (as string, timestamp, or datetime) are accepted once activated on the axis via figure.date().activate(). type: a sequence of numeric values or dates; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
labels: optional list of labels to display at the tick positions. type: a list of strings, plotext.colorize objects, or plotext.matrix objects
Returns: the ruler selection itself. type: a plotext ruler selection object
- lim(lower=None, upper=None)[source]
Sets the visible numerical range of the axis. Data values outside this range are clipped. Limits may be specified as numbers or date strings.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
These are its parameters:
lower: lower (minimum) plot limit of the axis. Dates (as string, timestamp, or datetime) are accepted once activated on the axis via figure.date().activate(). If not provided, the limit is calculated automatically. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
upper: upper (maximum) plot limit of the axis. Dates (as string, timestamp, or datetime) are accepted once activated on the axis via figure.date().activate(). If not provided, the limit is calculated automatically. type: a numeric value or date; dates, once activated on the relevant axis via figure.date().activate(), may be provided as string, timestamp (int or float), or a Python/Pandas datetime object.
Returns: the ruler selection itself. type: a plotext ruler selection object
- scale(scale=None)[source]
Sets the scale of the axis: with linear (default), equal value differences take equal space; with log, each multiplication by 10 takes equal space, so small and large values stay readable on the same plot.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
This is its parameter:
scale: scale of the axis. type: the strings linear or log default: ‘linear’
Returns: the ruler selection itself. type: a plotext ruler selection object
- direction(direction=None)[source]
Sets the direction in which values increase along the axis. Use 1 for the standard direction (left to right on x, bottom to top on y) or -1 to reverse it.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
This is its parameter:
direction: direction of the axis. type: the integers 1 or -1 default: 1
Returns: the ruler selection itself. type: a plotext ruler selection object
- alignment(lim=None, tick=None)[source]
Sets the two ruler alignments, which refer to two different settings: the limits alignment (lim), controlling where an axis numerical limit sits within its dedicated character cell; the ticks alignment (tick), controlling how the tick labels are placed relative to their actual positions.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
These are its parameters:
lim: numerical limits alignment: with center (default), the lower (or upper) limit sits at the middle of the first (or last) cell; with edge, at its left (or right) on the x axis, and at its bottom (or top) on the y axis. type: the strings center or edge default: ‘center’
tick: tick label alignment relative to the tick position: left, center or right, or dynamic, which finds an intermediate position between the left and right anchors, depending on the space available, aiming at the center one. type: on the x axis, the strings left, center, right or dynamic (short l, c, r, integers -1, 0, 1 or 2); on the y axis, the strings left, center or right (short l, c, r, integers -1, 0 or 1); on both, the string default, which is the dynamic alignment on the x axis and the alignment against the axis on the y one default: ‘default’
Returns: the ruler selection itself. type: a plotext ruler selection object
- pixel(pixel=None)[source]
Sets the pixel used to paint the tick area of the axis: the tick labels and the whole strip they sit in, beside the axes frame.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
This is its parameter:
pixel: pixel used to paint the tick labels. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone default: PlotextPixel()
Returns: the ruler selection itself. type: a plotext ruler selection object
- grid(active=True, style=None, pixel=None)[source]
Controls the grid lines drawn from the ruler ticks, spanning the whole canvas at every numerical tick position: vertical lines for an x ruler, horizontal for a y ruler.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
These are its parameters:
active: whether the grid is visible or not. type: a boolean value default: True
style: line style for the grid. Use plotext.line_styles() for a preview of the available styles. type: the strings default, double, heavy or dotted default: ‘default’
pixel: pixel used to paint the grid. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone default: PlotextPixel()
Returns: the ruler selection itself. type: a plotext ruler selection object
- clear()[source]
Resets the selected rulers only: their settings (limits, ticks, frequency, scale, direction, alignments, date support, grid) and their pixels return to defaults, leaving the rest of the plot untouched.
Source: plotext.figure.ruler(), plotext.figure.subplot().ruler()
Returns: the ruler selection itself. type: a plotext ruler selection object
date
plotext.figure.date() returns the date selection of the chosen rulers; its methods turn date support on and off, convert dates between forms and report reference dates.
- class plotext._plotter.frame.date.date_class[source]
- clear()[source]
Resets the date form and origin and turns date support off.
Source: plotext.figure.date(), plotext.figure.subplot().date()
Returns: the date selection itself. type: a plotext date selection object
- activate(active=True, form=None, origin=None, zone=None)[source]
Enables (or disables) date support on the axis, optionally setting the date form, origin and zone in one call.
Source: plotext.figure.date(), plotext.figure.subplot().date()
These are its parameters:
active: enables or disables date support. type: a boolean value default: True
form: string format used to interpret and display dates. type: a string default: ‘%d/%m/%Y’
origin: the date used as time zero: every timestamp counts from it. Dates close to the origin keep timestamps small, making log scaled date axes readable. The origin must match the current form. type: a date as string, timestamp (int or float), or a Python/Pandas datetime object default: ‘01/01/1900’
zone: the hours from UTC the axis is written in, 3 for Moscow and 5.5 for India: a date given with no zone of its own is read in it, and every date is written back in it. type: a numeric value default: 0
Returns: the date selection itself. type: a plotext date selection object
- origin(output='datetime')[source]
Returns the date used as time zero, in the requested form.
Source: plotext.figure.date(), plotext.figure.subplot().date()
This is its parameter:
output: output form of the date. type: one string among: string, datetime or timestamp default: ‘datetime’
Returns: the origin date. type: a date as string, timestamp (int or float), or a Python/Pandas datetime object
- today(output='datetime')[source]
Returns today’s date in the requested form.
Source: plotext.figure.date(), plotext.figure.subplot().date()
This is its parameter:
output: output form of the date. type: one string among: string, datetime or timestamp default: ‘datetime’
Returns: today’s date. type: a date as string, timestamp (int or float), or a Python/Pandas datetime object
- active()[source]
Returns whether date support is on for the axis.
Source: plotext.figure.date(), plotext.figure.subplot().date()
Returns: whether date support is on for the axis. type: a boolean value
- convert(time, output='timestamp')[source]
Converts a date, or a list of dates, between string, datetime and timestamp forms.
Source: plotext.figure.date(), plotext.figure.subplot().date()
These are its parameters:
time: the date to convert, or a list of dates. type: a date as string, timestamp (int or float), or a Python/Pandas datetime object; a list of dates is also allowed
output: output form of the conversion. type: one string among: string, datetime or timestamp default: ‘timestamp’
Returns: the converted date, or list of dates. type: a date as string, timestamp (int or float), or a Python/Pandas datetime object; a list of dates is also allowed
clear
plotext.figure.clear groups the clearing methods; each method resets one aspect of the plot. Calling it directly, as plotext.figure.clear(), resets everything, and it is equivalent to plotext.figure.clear.all().
- class plotext._plotter.clear.clear_class[source]
- size()[source]
Resets the plot size, so that every subplot takes a fresh share at the next plot_size call. On the master plot the terminal size is read again, while the terminal own settings, its prompt height and its size limits, are left as they were set: only plotext.terminal.clear() resets those.
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
- subplots()[source]
Wipes the subplot grid configured via subplots(), so the figure holds a single plot again.
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
- data()[source]
Drops the plotted data: every signal added via draw(), the lines placed by line() and event(), and the corresponding legend entries; the color cycler rewinds to a full pool.
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
- settings()[source]
Resets the plot’s settings back to defaults: the title, the axis labels, the axes visibility, the legend visibility, position and alignment, and the rulers (limits, ticks, frequency, scale, direction, alignments, date support, grid).
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
- pixels()[source]
Resets every pixel on this plot (labels, rulers, axes, legend and canvas) to the package defaults.
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
- styles()[source]
Resets the line styles of the axes and grid lines to the default style.
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
- all()[source]
Clears all signals, subplots, sizes and settings (including colors and styles), reverting the plot to default: equivalent to calling all the methods within the clear attribute, or the attribute itself as a method, like clear().
Source: plotext.figure.clear, plotext.figure.subplot().clear
Returns: the clear component itself. type: a plotext clear object
file
plotext.file is the pre-built file toolkit object; its methods read, write and manage files.
- class plotext._methods.file.file_class[source]
Basic file I/O helpers: text read/write, csv table reading and serialization, URL download, existence checks, deletion, parent/script-folder lookup and path joining.
- static read(path, log=False)
Reads the contents of a file as a string.
Source: plotext.file
These are its parameters:
path: file path. type: a string
log: prints a confirmation of the operation. type: a boolean value default: False
Returns: the file’s text. type: a string
- static write(text, path, append=False, log=False)
Writes a string to a file.
Source: plotext.file
These are its parameters:
text: the text to write. type: a string
path: file path. type: a string
append: appends to the file instead of overwriting. type: a boolean value default: False
log: prints a confirmation of the operation. type: a boolean value default: False
- static csv(path, delimiter=',', log=False)
Reads a csv file as a table: a list of rows, each being a list of strings.
Source: plotext.file
These are its parameters:
path: file path. type: a string
delimiter: character separating the values of a row. type: a string default: ‘,’
log: prints a confirmation of the operation. type: a boolean value default: False
Returns: the file’s table. type: a list of rows, each being a list of strings
- static string(data, delimiter=',')
Turns a table (a list of rows, holding strings or numbers) into a single string in csv form, ready to be written with write().
Source: plotext.file
These are its parameters:
data: the table to convert. type: a list of rows, each being a list of strings or numbers
delimiter: character separating the values of a row. type: a string default: ‘,’
Returns: the string version of the data. type: a string
- static exists(path)
Returns True if the given path exists.
Source: plotext.file
This is its parameter:
path: path to check. type: a string
Returns: true if the path exists. type: a boolean value
- static delete(path, safe=True, log=False)
Deletes the file at the given path; nothing happens if the file does not exist, and a folder is never removed.
Source: plotext.file
These are its parameters:
path: path to remove. type: a string
safe: only files inside the folder the program runs in can be removed; with False any file the program can reach can be, so never pass a path your program did not build itself. type: a boolean value default: True
log: prints a confirmation of the operation. type: a boolean value default: False
- static parent(path=None, level=1)
Returns the parent directory of a path. With no path argument, returns the caller’s script folder. level > 1 walks further up.
Source: plotext.file
These are its parameters:
path: path whose parent is wanted; None means the caller’s script. type: a string
level: how many levels to walk up. type: an integer default: 1
Returns: parent path. type: a string
- static join(*args)
Joins path components into an absolute path. The first part can be ~ to mean the home folder.
Source: plotext.file
This is its parameter:
*args: path parts to join. type: a string
Returns: absolute joined path. type: a string
- static download(url, path, log=False)
Downloads a URL to a local path.
Source: plotext.file
These are its parameters:
url: url path to download. type: a string
path: local file path. type: a string
log: prints a confirmation of the operation. type: a boolean value default: False
terminal
plotext.terminal is the pre-built terminal object: its methods read and limit the terminal size, wipe printed rows and check key presses.
- class plotext._kernel.terminal.terminal[source]
- clean(lines=None)[source]
Cleans the terminal output. Called with no argument, it clears the whole terminal; called with a number of lines, it cleans only the lines printed last, so the next print takes their place, useful when streaming plots. The experimental value -1 also cleans the whole screen, but keeps the older output reachable by scrolling up, which None erases entirely; not used by plotext yet.
Source: plotext.terminal
This is its parameter:
lines: number of last lines to clean, the whole terminal if None (default). type: an integer
Returns: the terminal itself. type: a plotext terminal object
- clear()[source]
Resets terminal settings, including prompt height, limit settings, and current terminal size.
Source: plotext.terminal
Returns: the terminal itself. type: a plotext terminal object
- prompt(height=None)[source]
Sets the height of the terminal prompt (the area reserved for user input).
Source: plotext.terminal
This is its parameter:
height: number of lines reserved for the terminal prompt; if None, defaults to the standard prompt height. type: an integer default: 2
Returns: the terminal itself. type: a plotext terminal object
- limit(width=None, height=None)[source]
Sets whether to limit the master plot size to the terminal’s plottable area.
Source: plotext.terminal
These are its parameters:
width: limits the plot width to the terminal width, otherwise the plot width is not limited. type: a boolean value default: True
height: limits the plot height to the terminal height, otherwise the plot height is not limited. type: a boolean value default: True
Returns: the terminal itself. type: a plotext terminal object
- size(update=False, plottable=True)[source]
Returns the current terminal size.
Source: plotext.terminal
These are its parameters:
update: updates the terminal size before returning it, otherwise returns the last known size. type: a boolean value default: False
plottable: returns only the plottable size (excluding prompt lines), otherwise returns the total size. type: a boolean value default: True
Returns: a (width, height) tuple. type: a tuple of integer values
- log()[source]
Prints the terminal state, its size, prompt height and size limits, followed by the tree of nested subplots, one indented line per plot, showing its position, its size, and the rows and columns of subplots it is divided into.
Source: plotext.terminal
Returns: the terminal itself. type: a plotext terminal object
- is_pressed(key='q')[source]
Tells whether the user has typed the given key, answering right away: if nothing was typed, it returns False instead of pausing the program to wait. It is meant to be called repeatedly inside a loop, to let the user stop a stream of plots by typing a single key; the key is caught the moment it is typed, with no need for Enter. If the program input does not come from a keyboard, as when scripts run automatically, it always returns False.
Source: plotext.terminal
This is its parameter:
key: the key to check, a single character, case-insensitive. type: a string default: ‘q’
Returns: true if the user has typed the key, False otherwise. type: a boolean value
- parent(level=1)[source]
Returns the terminal itself: the terminal sits at the top of the plots hierarchy, above the master figure, and is its own parent at every level. This method exists so that every parent() climb, from any subplot, safely ends at the terminal; calling it directly has little use.
Source: plotext.terminal
This is its parameter:
level: ignored: the terminal is its own parent at every level. type: an integer default: 1
Returns: the terminal itself. type: a plotext terminal object
prettydoc
The prettydoc module is responsible for managing and customizing docstrings and their formatting.
- class plotext.prettydoc.docs(colorless=False, separator=None)[source]
Initializes a docs manager, which builds visually styled docstrings: its methods register the objects to document, together with each piece of their docstring (the description, the parameters, the output and so on), and its update() method creates the documentation container, a final and distinct object.
Source: plotext.prettydoc
These are its parameters:
colorless: whether to write each __doc__ as plain text, without color codes; the interactive menu and the doc() methods always print colored. The interactive menu is opened by calling the documentation container, returned by update(), as a method. type: a boolean value default: False
separator: string placed between a field label and its content in every rendered docstring line, as in ‘Source: plotext’ or ‘type: an integer’. type: a string default: ‘: ‘
Returns: the initialized docs manager. type: a plotext.prettydoc docs manager object
- title(title=None)[source]
Sets the title shown above the interactive menu. The interactive menu is opened by calling the documentation container, returned by update(), as a method.
Source: plotext.prettydoc.docs()
This is its parameter:
title: title text, or None to remove it. type: a string
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- section(section=None)[source]
Sets the current section name: every entry added afterwards with function() belongs to it, grouped together in the interactive menu, until section() is called again. Call it with no argument, or with None, to leave the following entries without a section. The interactive menu is opened by calling the documentation container, returned by update(), as a method.
Source: plotext.prettydoc.docs()
This is its parameter:
section: the section name; if None, the following entries belong to no section. type: a string
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- pixel(component, pixel=None)[source]
Configures the default color and style of the selected docstring component. The component named attribute is special: it colors the menu entries documenting attributes, the objects reached by name without parentheses, like plotext.figure, telling them visually apart from methods.
Source: plotext.prettydoc.docs()
These are its parameters:
component: component to modify; call plotext.prettydoc.components() to see the available component names. type: a string
pixel: pixel carrying the desired color and style. type: a plotext.pixel object, a foreground string or integer, a tuple specifying (foreground, background, style), or an (r, g, b) integer triple used as foreground alone
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- function(*function, name=None)[source]
Registers a function to be documented. All subsequent manager calls apply to the most recently added function until another is registered. Each function is stored under a unique key, based on its name (the name parameter, or the function’s __name__ attribute when no name is given); if a source path is set with the source() method, the key becomes the source path joined with the name: for example, in plotext.figure.bar, plotext.figure is the source path and bar the name.
Source: plotext.prettydoc.docs()
These are its parameters:
function: the function to document; a list of functions all receive the same docstring, useful for aliases. type: a Python callable, or a list of callables
name: name of the entry; if None, the function’s own __name__ attribute is used. type: a string
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- description(doc=None, alias=None)[source]
Adds the main body of documentation for the most recently added function, and the alternative name it also answers to. Each of the two is added only when given, so a function with no alias is documented with the description alone, and an alias can be added on its own.
Source: plotext.prettydoc.docs()
These are its parameters:
doc: description of what the function does. type: a string, a plotext.colorize object, or a plotext.matrix object
alias: alternative name of the function. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- parameter(name=None, doc=None, type=None, default=None)[source]
Adds a parameter to the most recently added function, with the type and default value shown under its description. The type accepts any string, including one registered in a plotext.prettydoc registry: for example, parameter(‘degrees’, ‘the angle’, registry(‘celsius’), 25) renders the type as ‘a temperature in Celsius degrees’ and the default as 25, once ‘celsius’ has been registered there.
Source: plotext.prettydoc.docs()
These are its parameters:
name: parameter name. type: a string, a plotext.colorize object, or a plotext.matrix object
doc: parameter description. type: a string, a plotext.colorize object, or a plotext.matrix object
type: parameter type. type: a string, a plotext.colorize object, or a plotext.matrix object
default: parameter default value. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- past_parameter(name, function, type=None, default=None)[source]
Copies a parameter from a previously documented function onto the current one. The type and default value replace the copied ones when given, and keep them otherwise; an empty string removes the field.
Source: plotext.prettydoc.docs()
These are its parameters:
name: name of the parameter to copy. type: a string
function: unique key of the function that already defines this parameter. type: a string: the function __name__ attribute, or the name set with the function() name parameter, prefixed by the source path when one is set using the source() method
type: parameter type. type: a string, a plotext.colorize object, or a plotext.matrix object
default: parameter default value. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- source(value=None)[source]
A method is called from an object: in plotext.figure.bar(), the method bar() is called from plotext.figure. Prettydoc cannot retrieve this calling object’s name (or sequence of objects) on its own: with this method, the user can declare the source path for the most recently added function. The source path is rendered in the Source field of the docstring. The source may also be a list of source paths, for methods reachable from several places: for example, both plotext.figure and plotext.figure.subplot() are valid source paths for the bar() method. All paths appear in the Source field, while only the first enters the function unique key, described in the function() method.
Source: plotext.prettydoc.docs()
This is its parameter:
value: the source path, or a list of source paths; if None, no Source field is rendered. type: a string, or a list of strings
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- output(doc=None, type=None)[source]
Documents the output of the most recently added function.
Source: plotext.prettydoc.docs()
These are its parameters:
doc: description of the output. type: a string, a plotext.colorize object, or a plotext.matrix object
type: output type. type: a string, a plotext.colorize object, or a plotext.matrix object
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- past_output(function)[source]
Copies the output specification from a previously documented function.
Source: plotext.prettydoc.docs()
This is its parameter:
function: unique key of the function whose output should be reused. type: a string: the function __name__ attribute, or the name set with the function() name parameter, prefixed by the source path when one is set using the source() method
Returns: the docs manager itself. type: a plotext.prettydoc docs manager object
- update(_container=None)[source]
Creates the documentation container: a distinct object with one method per documented entry, carrying the same name and printing its docstring. Called as a method, the documentation container opens the interactive menu: three scrollable columns, holding the sections, the methods of the picked section, and the docstring of the picked method. It also writes each registered docstring into the __doc__ of its documented method or attribute, and attaches to each a doc() method that prints the docstring in color.
Source: plotext.prettydoc.docs()
Returns: the documentation of every registered entry. type: a plotext.prettydoc documentation container object
- class plotext.prettydoc.registry[source]
Initializes a registry: it keeps long strings under short names, so that a text needed in many docstrings is written once and asked for by name. A type explanation, a recurring message, a long sentence: store it with the add() method, then pass registry(‘name’) wherever it is needed.
Source: plotext.prettydoc
Returns: the initialized registry. type: a plotext.prettydoc registry object
- add(name, doc)[source]
Stores a string under a short name. For example, after add(‘celsius’, ‘a temperature in Celsius degrees’), registry(‘celsius’) gives that sentence back.
Source: plotext.prettydoc.registry()
These are its parameters:
name: name the string is stored under. type: a string
doc: the string to store. type: a string
Returns: the registry itself. type: a plotext.prettydoc registry object
- get(name, default=None)[source]
Gives the string stored under a name, or the given default when nothing is stored under it. Calling the registry with the name does the same, but complains when the name is missing.
Source: plotext.prettydoc.registry()
These are its parameters:
name: name to store the string under. type: a string
default: value given back when nothing is stored under that name. type: a string
Returns: the string stored under the name. type: a string
- plotext.prettydoc.components()[source]
Prints the list of available docstring components with a short description of each. A component is one piece of the rendered docstring, like the title, the description, a parameter name or its type, each with its own color and style, configurable with the pixel() method of the docs manager.
Source: plotext.prettydoc