Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/plotext/_doc.py: 99%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# this file contains all docstrings
3from ._doc_utils import method, doc, par, past, out, t
5method("subplots")
6doc("It creates a matrix of subplots.\n\nNested subplots are allowed; for example: subplots(2, 2); subplot(1, 1); subplots(3, 4) - or directly subplots(2, 2).subplot(1, 1).subplots(3, 4) - creates a 2 by 2 matrix where the first subplot is a 3 by 4 matrix.")
7par("rows", "sets the number of rows relative to the matrix of subplots.", t.int, 1)
8par("cols", "sets the number of columns relative to the matrix of subplots.", t.int, 1)
9out('the figure object containing the matrix of subplots', t.fig)
12method("subplot")
13doc("It sets (and returns) the active subplot in the matrix of subplots, such that further commands will refer to it.\n\nNote that most of the commands referring to the active subplot, could be alternatively passed directly to it. Eg: subplot(1, 3); plotsize(100, 30) becomes subplot(1, 3).plotsize(300, 30).")
14par("row", "sets the row relative to the active subplot in the matrix of subplots, from above and counting from 1.", t.int, 1)
15par("col", "sets the column relative to the active subplot in the matrix of subplots, from left and counting from 1.", t.int, 1)
16out('the selected figure object', t.fig)
19method("main")
20doc("It returns the main figure (at the uppermost level in the matrix of subplots, if present), and sets the active figure to it. Any further commands will apply to the entire figure and to any of its subplots.")
21out('the main figure object', t.fig)
24method("active")
25doc("It returns the active figure, which can be changed using the subplot() method.")
26out('the active figure object', t.fig)
29method("interactive")
30doc("It allows to plot dynamically without using the show() method. A new plot is shown automatically when any change is made to the plot. By default plots are not shown dynamically.")
31par("interactive", "is the Boolean required to make the plot dynamic.", 'bool', False)
34method("plot_size", "plotsize")
35doc("It sets the plot size of the active figure.\n\n")
36par("width", "sets the width of the active subplot (in unit of character width). If None the terminal width is used.", t.int, None)
37par("height", "sets the height of the active subplot (in unit of character height). If None the terminal height is used.", t.int, None)
38out('The plot width and height (in character units).', t.list_int(2))
41method("limit_size", "limitsize"),
42doc("It sets, whatever or not, to limit the plot size to the terminal dimensions. To manually set the plot dimensions use the plot_size() method afterwards.\n\nThis method is only available to the main figure and not to its subplots, if present ")
43par("width", "sets whatever or not to limit the plot width to the terminal width.", t.bool, True)
44par("height", "sets whatever or not to limit the plot height to the terminal height.", t.bool, True)
47method("take_min", "takemin")
48doc("In a matrix of subplots, the plot widths/heights will be set to the same value for each column/row.\n\nBy default the maximum value is considered, but if the take_min() method is called, the minimum is considered instead.\n\nThis method is available to the main figure, as well any of its subplot independently.")
51method("title")
52doc("It sets the title of the active plot.")
53par("label", "the string label required", t.str)
57method("xlabel")
58doc("It sets the label relative to the x axis.")
59past("label", "title")
60par("xside", "it allows to independently address either the 'lower' or 'upper' x axis (1 or 2 in short).", t.str_int, 'lower')
63method("ylabel")
64doc("It sets the label of the y axis.")
65past("label", "xlabel")
66par("yside", "it allows to independently address either the 'left' or 'right' y axis (1 or 2 in short).", t.str_int, 'left')
69lim_message = ' If \'None\', the limit is calculated automatically.'
71method("xlim")
72doc("It sets the numerical limits relative to the x axis. Values outside this range will not be plotted.")
73par("left", "it sets the left (or minimum) plot limit relative to the x axis. A date in string form is accepted." + lim_message, t.str_num, None)
74par("right", "it sets the right (or maximum) plot limit relative to the x axis. A date in string form is accepted." + lim_message, t.str_num, None)
75past("xside", "xlabel")
78method("ylim")
79doc("It sets the limits relative to the y axis. Values outside this range will not be plotted.")
80par("lower", "it sets the lower (or minimum) plot limit relative the y axis. A date in string form is accepted." + lim_message, t.str_num, None)
81par("upper", "it sets the upper (or maximum) plot limit relative the y axis. A date in string form is accepted." + lim_message, t.str_num, None)
82past("yside", "ylabel")
85method("xscale")
86doc("It sets the scale (linear or base 10 logarithmic) relative to the x axis.")
87par("scale", "the axis scale, either 'linear' or 'log'.", t.str, 'linear')
88past("xside", "xlim")
91method("yscale")
92doc("It sets the scale (linear or base 10 logarithmic) relative to the y axis.")
93past("scale", "xscale")
94past("yside", "ylim")
97method("xticks")
98doc("It sets the numerical data ticks and string labels relative to the x axis.")
99par("ticks", "the list of numerical data ticks. Dates in string form are accepted.", t.list_str_num())
100par("labels", "the optional list of ticks labels to be printed at the ticks coordinates given.", t.list_str_num())
101past("xside", "xlim")
105method("yticks")
106doc("It sets the numerical data ticks and string labels relative to the y axis.")
107past("ticks", "xticks")
108past("labels", "xticks")
109past("yside", "ylim")
112method("xfrequency")
113doc("It sets the number of numerical ticks relative to the x axis. The actual numerical values are calculated automatically.\n\nTo set the ticks manually use the xticks() method instead. Note that xticks() overrules xfrequency().")
114par("frequency", "the integer number of numerical ticks.", t.int, 5)
115past("xside", "xlim")
117method("yfrequency")
118doc("It sets the number of numerical ticks relative to the y axis. The actual numerical values are calculated automatically.\n\nTo set the ticks manually use the yticks() method instead. Note that yticks() overrules yfrequency().")
119par("frequency", "the integer number of numerical ticks.", t.int, 7)
120past("yside", "ylim")
123method("xreverse")
124doc("It reverses the x axis direction.")
125par("reverse", "the Boolean required to reverse the axis (if True).", t.bool, False)
126past("xside", "xlim")
129method("yreverse")
130doc("It reverses the y axis direction.")
131past("reverse", "xreverse")
132past("yside", "ylim")
135method("xaxes")
136doc("It is used to show or remove the x axes independently.")
137par("lower", "the Boolean required to show or not the lower x axis.", t.bool, True)
138par("upper", "the Boolean required to show or not the upper x axis.", t.bool, True)
141method("yaxes")
142doc("It is used to show or remove the y axes independently.")
143par("left", "the Boolean required to show or not the left y axis.", t.bool)
144par("right", "the Boolean required to show or not the right y axis.", t.bool)
147method("frame")
148doc("It is used to show or remove all 4 axes (which constitute the canvas frame) at the same time.\n\nTo address any individual axis use the xaxes() and yaxes() methods instead.")
149par("frame", "the Boolean required to show or not all plot axes.", t.bool, True)
152method("grid")
153doc("It is used to show or remove the plot grid lines.")
154par("horizontal", "the Boolean required to show the horizontal grid lines.", t.bool, False)
155par("vertical", "the Boolean required to show the vertical grid lines.", t.bool, False)
158method("canvas_color")
159doc("It sets the background color relative to the plot canvas, which is the area where the data points are plotted.")
160par("color", "the color code: access the colors() method for the available codes.", t.color, 'white')
163method("axes_color")
164doc("It sets the background color relative to the axes, which is the area where the axes are plotted, and include the axes numerical ticks, the axes labels and the plot title (but not the plot legend, which is set automatically using the canvas_color() method).")
165past("color", "canvas_color")
168method("ticks_color")
169doc("It sets the color relative to any writing on the plot: the axes, its numerical ticks and labels, the plot title and the plot legend.")
170past("color", "canvas_color", 'black')
173method("ticks_style")
174doc("It sets the style relative to any writing on the plot: the axes, its numerical ticks and labels, the plot title and the plot legend.")
175par("style", "the style code: access the styles() method for the available style codes.", t.str, 'default')
178method("theme")
179doc("It sets the color theme relative to the active plot.")
180par("theme", "the string theme code: access the themes() method for the available theme codes.", t.str, 'default')
183method("clear_figure", "clf")
184doc("It clears everything relative to the addressed figure, including its subplots.")
187method("clear_data", "cld")
188doc("It clears only the data, previously plotted, relative to the addressed figure, including its subplots, without clearing any other plot settings.")
190method("clear_color", "clc")
191doc("It clears only the color settings relative to the addressed figure, including its subplots, without clearing any other plot settings. The final rendering of this subplot will be colorless.")
194method("clear_terminal", "clt")
195doc("It clears the terminal screen and it is generally useful when plotting a continuous stream of data.\n\nNote that depending on the terminal shell used, few extra lines may be printed after the plot.")
196par("lines", "the optional number of terminal lines to be cleared. If None, the entire terminal will be cleared.", t.int, None)
199method("scatter")
200doc("It creates a scatter plot of coordinates given by the x and y lists provided.\n\nMultiple data sets can be plotted using consecutive plotting functions.")
201par("args", "The coordinates x and y (or just y) of the data points to be plotted; string dates are accepted.", t.xy)
202par("marker", "the marker used to identify the data points, which could be a single character or the available marker codes, accessible with the markers() method; a list of markers, one for each data point, could also be provided.", t.marker, 'hd')
203par("color", "the color code of the data points, accessible with the colors() method; a list of colors, one for each data point, could also be provided.", t.color_list, 'blue+')
204par("style", "the style of the data points, accessible with the styles() method; a list of styles, one for each data point, could also be provided.", t.marker, 'default')
205par("fillx", "if True, for each data point, a vertical line ending on the x axis (the level y = 0) will be printed; if a specific numerical value is provided, the line will stop at that y coordinate; if the string code 'internal' is provided, the line will stop when another data point is reached (if it exists); if False, no line will be printed.", t.bool_num_str, False)
206par("filly", "if True, for each data point, an horizontal line ending on the y axis (the level x = 0) will be printed; if a specific numerical value is provided, the line will stop at that x coordinate; if the string code 'internal' is provided, the line will stop when another data point is reached (if it exists); if False, no line will be printed.", t.bool_num_str, False)
207past("xside", "xlim")
208past("yside", "ylim")
209par("label", "the label of the current data set, which will appear in the legend menu at the top left corner of the plot canvas. If None, no label is added.", t.str, None)
212method("plot")
213doc("It creates a plot of lines between consecutive data points using the coordinates given by the x and y lists. \n\nMultiple data sets can be plotted using consecutive plotting functions.")
214past("args", "scatter")
215past("marker", "scatter")
216past("color", "scatter")
217past("style", "scatter")
218past("fillx", "scatter")
219past("filly", "scatter")
220past("xside", "scatter")
221past("yside", "scatter")
222past("label", "scatter")
225method("candlestick")
226doc("It creates a candlestick plot.")
227par("dates", "the list of strings, each representing a date time object; use the date_form() method to set the accepted date/time forms.", t.list_str())
228par("data", "the numerical data to be plotted.", t.dic)
229par("colors", "the two colors used to identify the positive and negative candlesticks; access the colors() method for the available color codes.", t.list_color(2), ['blue+', 'green+'])
230par("orientation", "the orientation of the plot which could be either 'vertical' (in short 'v', as by default) or 'horizontal' (in short 'h').", t.str, 'vertical')
231past("xside", "scatter")
232past("yside", "scatter")
233past("label", "scatter")
236method("bar")
237doc("It creates a bar plot using the x and y data provided.")
238par("args", "The coordinates x and y (or just y), of the bars; string labels or dates are accepted (but only as x values).", t.xy)
239par("marker", "the marker used to identify the bars, which could be a single character or the available marker codes, accessible with the markers() method.", t.str, 'sd')
240par("color", "the color code of the bars, accessible with the colors() method.", t.color, 'blue+')
241par("fill", "if True, the bars will be filled with the the given colored markers, otherwise only its borders would be printed.", t.bool, True)
242par("width", "the relative width of the bars, expressed as a float ranging from 0 to 1.", 'number', 4 / 5)
243past("orientation", "candlestick")
244par("minimum", "the minimum value of all the bars; this value could be easily tweaked, particularly when a logarithmic scale is chosen along the bars height.", 'number', 0)
245par("reset_ticks", "if True, the center coordinates at the base of each bar will be calculated (starting from 1) and printed automatically; otherwise the numerical ticks, along the base of the bars, will be calculated as for any other plot.", t.bool, True)
246past("xside", "scatter")
247past("yside", "scatter")
248past("label", "scatter")
251method("simple_bar")
252doc("It creates a simpler and sketchier version of an horizontal bar plot.\n\nNote that this plot cannot be fit into a matrix of subplots and any setting methods - like plot_size() or canvas_color() etc ... - will not have any effect on it.")
253past("args", "bar")
254past("marker", "bar")
255past("color", "bar")
256par("title", "the title of the plot. If None, no title will be added.", t.str, None)
257par("width", "sets the horizontal width of the plot; if None, the width will adapt to the terminal size.", t.int, None)
260method("multiple_bar")
261doc("It creates a bar plot where multiple bars are grouped together (along the bar width axis) and have the same bar label.")
262par("args", "The coordinates x and Y (or just Y), of the bars, where Y is a list of lists, each containing the bar heights of the correspondent bar plot; string labels or dates are accepted (but only as x values).", t.multiple_xy)
263par("marker", "the marker used to identify the bars, which could be a single character or the available marker codes, accessible with the markers() method; a list of markers (with same length as Y) could also be provided to separately set the marker of each bar", t.str_list, 'sd')
264par("color", "the list of colors (with same length as Y) used to identify each bar in a group of bars; access the colors() method for the available color codes.", t.list_color())
265past("fill", "bar")
266past("width", "bar")
267past("orientation", "bar")
268past("minimum", "bar")
269past("reset_ticks", "bar")
270past("xside", "scatter")
271past("yside", "scatter")
272par("labels", "the list of labels, one for each bar plot (with same length as Y), which will appear in the legend menu at the top left corner of the plot canvas.", t.list_str())
275method("simple_multiple_bar")
276doc("It creates a simpler and sketchier version of an horizontal multiple bar plot.\n\nNote that this plot cannot be fit into a matrix of subplots and any setting methods - like plot_size() or canvas_color() etc ... - will not have any effect on it.")
277past("args", "multiple_bar")
278past("marker", "multiple_bar")
279par("colors", "the list of colors (with same length as Y) used to identify each bar in a group of bars; access the colors() method for the available color codes.", t.list_color())
280past("title", "simple_bar")
281past("width", "simple_bar")
282past("labels", "multiple_bar")
285method("stacked_bar")
286doc("It creates a bar plot where multiple bars are stacked on top of each other (along the bar height axis) and have the same bar label.")
287past("args", "multiple_bar")
288past("marker", "multiple_bar")
289past("color", "multiple_bar")
290past("fill", "bar")
291past("width", "bar")
292past("orientation", "bar")
293past("minimum", "bar")
294past("reset_ticks", "bar")
295past("xside", "scatter")
296past("yside", "scatter")
297past("labels", "multiple_bar")
300method("simple_stacked_bar")
301doc("It creates a simpler and sketchier version of an horizontal stacked bar plot. \n\nNote that this plot cannot be fit into a matrix of subplots and any setting methods - like plot_size() or canvas_color() etc ... - will not have any effect on it.")
302past("args", "multiple_bar")
303past("marker", "multiple_bar")
304past("colors", "simple_multiple_bar")
305past("title", "simple_bar")
306past("width", "simple_bar")
307past("labels", "multiple_bar")
310method("hist")
311doc("It builds the histogram plot.")
312par("data", "the data to build an histogram upon.", t.list_num())
313par("bins", "the number of channels between the minimum and maximum values of the data set, used to count the data frequency.", t.int, 10)
314past("marker", "scatter")
315past("color", "scatter")
316past("fill", "bar")
317par("norm", "If true, each frequency count is normalized, such that the sum of all counts is 1 (instead of the length of the data set).", t.bool, False)
318past("width", "bar")
319past("orientation", "bar")
320past("minimum", "bar")
321past("xside", "scatter")
322past("yside", "scatter")
323past("label", "scatter")
326method("box")
327doc("It creates a box plot. Further development needed.")
328par("args", "The coordinates x and Y (or just Y), of the bars, where Y is a list of lists, one for each box element; string labels or dates are accepted (but only as x values).", t.multiple_xy)
329par("quintuples", "If True, the input data is an array of 5 elements, each representing the precomputed quantiles at levels 0, 25, 50, 75, 100 s, otherwise it's the original data.", t.bool, False)
330par("colors", "A list of two colors, one for the box body and the other for its inner lines", t.list_color(2), ['green', 'red'])
331past("fill", "bar")
332past("width", "bar")
333past("orientation", "bar")
334past("minimum", "bar")
335past("reset_ticks", "bar")
336past("xside", "scatter")
337past("yside", "scatter")
338past("label", "scatter")
341method("bar")
342doc("It creates a bar plot using the x and y data provided.")
343par("args", "The coordinates x and y (or just y), of the bars; string labels or dates are accepted (but only as x values).", t.xy)
344par("marker", "the marker used to identify the bars, which could be a single character or the available marker codes, accessible with the markers() method.", t.str, 'sd')
345par("color", "the color code of the bars, accessible with the colors() method.", t.color, 'blue+')
346par("fill", "if True, the bars will be filled with the the given colored markers, otherwise only its borders would be printed.", t.bool, True)
347par("width", "the relative width of the bars, expressed as a float ranging from 0 to 1.", 'number', 4 / 5)
348past("orientation", "candlestick")
349par("minimum", "the minimum value of all the bars; this value could be easily tweaked, particularly when a logarithmic scale is chosen along the bars height.", 'number', 0)
350par("reset_ticks", "if True, the center coordinates at the base of each bar will be calculated (starting from 1) and printed automatically; otherwise the numerical ticks, along the base of the bars, will be calculated as for any other plot.", t.bool, True)
351past("xside", "scatter")
352past("yside", "scatter")
353past("label", "scatter")
355method("error")
356doc("It build a scatter plot with error bars.\n\nNote that no marker parameter is needed, as the markers are automatically set to straight lines.")
357past("args", "scatter")
358par("xerr", "The errors relative to the x data.", t.list_num())
359par("yerr", "The errors relative to the y data.", t.list_num())
360past("color", "scatter")
361past("xside", "scatter")
362past("yside", "scatter")
363past("label", "scatter")
367method("event_plot", "eventplot")
368doc("It plots parallel lines at the coordinates provided.")
369par("data", "The list of coordinates identifying each line; string dates are also accepted.", t.x)
370past("marker", "scatter")
371past("color", "scatter")
372past("orientation", "bar")
373par("side", "It is used to identify on which axis to plot the data. It could be the 'lower' or 'upper' x axis (1 or 2 in short) for 'vertical' orientation, and 'left' or 'right' y axis (1 or 2 in short) for 'horizontal' orientation.", t.str_int, 'lower')
377method("vertical_line", "vline")
378doc("It plots a vertical line, spanning the entire canvas range, along the y axis.")
379par("coordinate", "the x coordinate where the vertical line should be placed; string dates are allowed.", t.str_num)
380par("color", "the color code of the line, accessible with the colors() method.", t.color, 'black')
381past("xside", "scatter")
384method("horizontal_line", "hline")
385doc("It plots an horizontal line, spanning the entire canvas range, along the y axis.")
386par("coordinate", "the y coordinate where the horizontal line should be placed; string dates are allowed.", t.str_num)
387past("color", "vertical_line")
388past("yside", "scatter")
391method("text")
392doc("It adds a text label to the plot at the given coordinate.")
393par("label", "The text to add to the plot; the new line character \\n will return multiple sub strings with the same alignment.", t.str)
394par("x", "the x coordinate of the text; date strings are accepted.", t.str_num)
395par("y", "the y coordinate of the text; date strings are accepted.", t.str_num)
396par("color", "the color code of the text, accessible with the colors() method.", t.color, 'green+')
397par("background", "the text background color code, accessible with the colors() method.", t.color, 'white')
398par("style", "the style code of the text, accessible with the styles() method.", t.str, 'default')
399past("orientation", "bar", 'horizontal')
400par("alignment", "the text alignment, which could be either 'left', 'center', and 'right' (for horizontal orientation) or 'top', 'center' and 'bottom' (for vertical orientation).", t.str, "center")
401past("xside", "scatter")
402past("yside", "scatter")
406method("rectangle")
407doc("It creates a rectangle with the given coordinates.")
408par("x", "the two x coordinates of the rectangle.", t.list_str(2))
409par("y", "the two y coordinates of the rectangle.", t.list_str(2))
410par("marker", "the marker used to identify the shape plotted, which could be a single character or the available marker codes, accessible with the markers() method,", t.marker, 'hd')
411par("color", "the color code of shape plotted, accessible with the colors() method", t.color, 'blue+')
412par("lines", "If True, the shape borders will be shown, otherwise just its vertices.", t.bool, True)
413par("fill" , "if True, the body of the shape will be filled with colored markers.", t.bool, True)
414past("xside", "scatter")
415past("yside", "scatter")
416past("label", "scatter")
419method("polygon")
420doc("It creates a polygon centered at the given coordinates.")
421par("x", "the polygon center x coordinate.")
422par("y", "the polygon center y coordinate.")
423par("radius", "the distance of the polygon vertices to the center; for a circle, it corresponds to its actual radius, hence the name.", 'number', 1)
424par("sides", "the number of sides of the polygon. To simulate a circle, input a high number (> 50).", t.int, 3)
425past("marker", "rectangle")
426past("color", "rectangle")
427past("lines", "rectangle")
428past("fill" , "rectangle")
429past("xside", "scatter")
430past("yside", "scatter")
431past("label", "scatter")
434method("confusion_matrix", "cmatrix")
435doc("It plots the confusion matrix correspondent to the actual and predicted data sets provided.")
436par("actual", "the real data", t.list_num_bool())
437par("predicted", "the predicted data, of same size as the 'actual' data", t.list_num_bool())
438par("color", "the color code of any writing on the plot, including the axes; this will affects the canvas colors, which are automatic levels of gray-scale; access the colors() method for the available color codes.", t.color, 'orange+')
439par("style", "the style code of any writing on the plot; access the styles() method for the available style codes.", t.str, 'bold')
440par("labels", "a list of labels, one for each unique and sorted data value; the labels will automatically appear on both axes.", t.list_str())
443method("indicator")
444doc("It creates a simple widget indicator, which occupies the entire plot and could be conveniently used in a matrix of subplots.")
445par("value", "the value to be displayed at the center of the plot.", t.str_num)
446par("label", "the label describing the value, appearing a plot title.", t.str)
447past("color", "confusion_matrix")
448past("style", "confusion_matrix")
451method("matrix_plot")
452doc("It creates a two dimensional plot of a matrix. The intensity of each element in the plot (a gray-scale level) is proportional to the correspondent element in the matrix (whiter for higher values). If a matrix of RGB colors is provided, each like (13, 45, 176), the color of each pixel will be the actual RGB color code provided.")
453par("matrix", "the matrix of data to be plotted", t.matrix)
454par("marker", "the marker used to identify the data points, which could be a single character or the available marker codes, accessible with the markers() method; note that higher resolution markers ('hd', 'fhd' and 'braille') will not result in an improved spatial resolution, as the color resolution is limited by a full character in all cases.", t.marker, 'sd')
455past("style", "scatter")
456par("fast", "if True, the plot will be rendered faster but most setting methods - like plot_size() or canvas_color() etc... - will not have any effect and the plot could not be nested in a matrix of subplots.",t.bool, False)
459method("image_plot")
460doc("It plots an image from file. \n\nIt is recommended to call the plot_size() method before this one, especially for larger images, to reduce the image size and so the computational load.")
461par("path", "the file path of the image", t.str)
462past("marker", "matrix_plot")
463past("style", "matrix_plot")
464past("fast", "matrix_plot")
465par("grayscale", "If True, the image will be rendered in gray-scale levels.", t.bool, False)
468method("play_gif")
469doc("It plays a GIF on terminal. The images will adapt to the screen size unless plot_size() method is used before.\n\nNote: this feature may require further development.")
470par("path", "image_plot")
473method("play_video")
474doc("It plays a video, with audio, from file. The frames will adapt to the screen size unless plot_size() is used before.\n\nNote: this feature may require further development.")
475par("path", "the file path of the video", t.str)
476par("from_youtube", "set this parameter to True, if the video was downloaded from YouTube.",t.bool, False)
479method("play_youtube")
480doc("It plays a YouTube video, with audio, from url.\n\nNote: this feature may require further development.")
481par("url", "the url link of the YouTube video", t.str)
484path_message = " If only the file name is provided, the parent folder will be automatically set to the user home directory."
486method("get_youtube")
487doc("It downloads a youtube video.")
488past("url", "play_youtube")
489par("path", "The location where the video should be saved." + path_message, t.str)
490par("log", "if True, a simple confirmation or warning message will appear on terminal.", t.bool, True)
493method("show")
494doc("It builds and prints the final figure on terminal.\n\nIf interactive(True) has been previously called, the show() method will not be necessary.")
496method("build")
497doc("It created and returns the final figure canvas in string form, without actually printing it.\n\nTo build and print, use the show() method instead.")
498out('The plot canvas in string form', t.str)
500method("sleep")
501doc("It adds a sleeping time to the computation and it is generally useful when plotting a continuous stream of data, in order to reduce undesired screen flickering effects. Manually tweak this value to reduce the flickering.")
502par("time", "The sleeping time, in seconds.", t.float, 0)
505method("time")
506doc("It returns the computational time of the latest show() or build() method called.\n\nNote that functions, such as matrix_plot() or image_plot(), add a non-negligible computational time before the show() or build() methods are called.")
507par("show", "If True, the time is also printed in an easier to read format.", t.bool, True)
508out('The computation time of the latest show() or build() method called (in seconds).', t.float)
511method("save_fig", "savefig")
512doc("It saves the plot canvas as text or html. \n\nIt is recommended to use it after the show() or build() method.")
513par("path", "The file path where the plot should be saved." + path_message, t.str)
514par("append", "If True, the final figure is appended to the text file, instead of replacing it.", t.bool, False)
515par("keep_colors", "If True, the ansi color codes will be preserved. Note that if the path file extension is '.html', the colors will be preserved automatically.", t.bool, False)
518method("from_matplotlib")
519doc("It takes a matplotlib figure and turns it into a plotext one.\n\nNote: this feature may require further development.")
520par("fig", 'The matplotlib figure to turn into a plotext one.', 'a matplotlib figure')
521past('marker', 'bar')
525iso_message = " It uses the standard Python ISO string forms, except '%' symbol is removed for simplicity. "
526global_message = "Use the date_form() method to set this parameter globally. "
529method("date_form")
530doc("It sets how to interpret string as datetime objects.\n\nNote that most methods that deal with string dates, have an internal 'input_form' or 'output_form' parameter for further flexibility.")
531par("input_form", "The string form used to interpret input strings as dates." + iso_message, t.str, 'd/m/Y')
532par("output_form", "The string form used to print dates as an output string. By default, it corresponds to the input one." + iso_message + global_message, t.str, 'd/m/Y')
535method("set_time0")
536doc("It sets the origin of time using the string provided. \n\nThis method is useful with logarithmic scale in date plots, in order to avoid 'hitting' the 0 timestamp.")
537par("string", "The string identifying the 0 time mark.", t.str, '01/01/1900')
538par("input_form", "The string form used to interpret the input string as a date." + iso_message + global_message, t.str, 'd/m/Y')
541method("today_datetime")
542doc("It returns today's date and time as a datetime object.")
543out("Today's date time.", t.datetime)
546method("today_string")
547doc("It returns today's date and time in string form.")
548par("output_form", "The string form used to print the today's date as an output string." + iso_message + global_message, t.str, 'd/m/Y')
549out("Today's date time.", t.str)
552method("datetime_to_string")
553doc("It turns a datetime object to a string.")
554par("datetime", "A datetime object.", t.datetime)
555par("output_form", "The string form used to print the datetime object as an output string." + iso_message + global_message, t.str, 'd/m/Y')
556out('the correspondent date time string', t.str)
559method("datetimes_to_strings")
560doc("It turns a list of datetime objects to a list of strings.")
561par("datetimes", "A list of datetime objects.", t.list_datetime)
562par("output_form", "The string form used to print the datetime objects as output strings." + iso_message + global_message, t.str, 'd/m/Y')
563out('A correspondent list of date time strings', t.list_str())
567method("string_to_datetime")
568doc("It turns a string into a datetime object.")
569par("string", "The string to convert to a datetime object.", t.str)
570past("input_form", "set_time0")
571out('The datetime object corresponded to the string provided.', t.datetime)
575method("script_folder")
576doc("It returns the parent folder (in string form) of the script where this method is run from.")
577out('The script folder', t.str)
580method("parent_folder")
581doc("It returns the parent folder of the path provided.")
582par("path", "The file path.")
583par("level", "The numbers of levels above the current one, in the folder structure, used to identify the parent folder.", int, 1)
584out('The parent folder', t.str)
586path_message = " Note that the symbol '~', is interpreted as the user home folder and if no folder is specified, the home folder is considered by default. "
589method("join_paths")
590doc("It turns a sequence of strings into a properly formatted file or folder path, dependent on the operating system used.\n\nFor example, the strings \"/\", \"home\" and \"file.txt\" would be properly joined into \"/home/file.txt\" in Unix systems.")
591par("args", "The list of strings to turn into a path." + path_message, t.list_str())
592out('The joined paths.', t.str)
596method("save_text")
597doc("It saves some text to file.")
598par("text", "The string to save", t.str)
599par("path", "The path location where the text should be saved." + path_message, t.str)
600past("log", "get_youtube")
603method("read_data")
604doc("It reads and properly interprets the tabular data from the path selected.")
605par("path", "The path location of the data." + path_message, t.str)
606par("delimiter", "The character used to separate data columns in the text file.", t.str, ' ')
607par("columns", 'The list of column indexes to consider (starting from 0); if None, all columns will be included.', t.list_int(), None)
608par("first_row", "The first row from which to acquire data (counting from 0).", t.int, 0)
609past("log", "save_text")
610out('The data read.', 'a matrix of numbers or strings')
613method("write_data")
614doc("It writes a tabular data to file.")
615par("data", "The data to write to file.", t.data)
616past("path", "save_text")
617past("delimiter", "read_data")
618past("columns", "read_data")
619past("log", "read_data")
622method("download")
623doc("It downloads an image/gif/video (or other) from the given URL to file.")
624par("url", "The URL to download.", t.str)
625par("path", "The path location where the content should be saved." + path_message, t.str)
626past("log", "read_data")
629method("delete_file")
630doc("It deletes the file selected, if it exists.")
631par("path", "The file path to delete." + path_message, t.str)
632past("log", "read_data")
635method("colorize")
636doc("It adds colors and styles to a string.")
637par("string", "The string to add colors and styles to", t.str)
638par("color", "the fullground color code: access the colors() method for the available codes.", t.color)
639par("style", "the style code: access the styles() method for the available codes.", t.str)
640par("background", "the background color code: access the colors() method for the available codes.", t.color)
641par("show", "If True, the string is also directly printed.", t.bool, False)
642out('The colorized and stylized string.', t.str)
645method("uncolorize")
646doc("It removes any coloring codes from a string.")
647par("string", "The string to remove color codes from.", t.str)
648out('The string with no color or style ansi codes.', t.str)
651method("terminal_size", "ts")
652doc("It returns the terminal size.")
653out('The terminal width and height (in character units)', t.list_int(2))
656method("terminal_width", "tw")
657doc("It returns the terminal width.")
658out('The terminal width (in character units)', t.int)
661method("terminal_height", "th")
662doc("It returns the terminal height.")
663out('The terminal height (in character units)', t.int)
666method("sin")
667doc("It returns a sinusoidal signal useful, for example, to quickly test some plotext plotting methods.")
668par("periods", "The number of periods in the signal.", t.float, 2)
669par("length", "The number of data points.", t.int, 200)
670par("amplitude", "The amplitude of the signal.", t.float, 1)
671par("phase", "The relative phase of the sinusoidal (in pi units); 0.5 returns a cosine signal, while 1 a negative sinusoidal.", t.float, 0)
672par("decay", "The relative decay rate of the signal, independent on the number of data points.", t.float, 0)
673out('the sinusoidal signal', t.list_num())
676method("square")
677doc("It returns a square wave signal useful, for example, to quickly test some plotext plotting methods.")
678past("periods", "sin")
679past("length", "sin")
680past("amplitude", "sin")
681out('the square signal', t.list_num())
684method("transpose")
685doc("It transposes a matrix of data.")
686past("data", "write_data")
687out('The transpose data', 'A list of lists')
690method("colors")
691doc("It displays the available string, integer and RGB color codes available in plotext.")
694method("styles")
695doc("It displays the available string style codes available in plotext.")
698method("markers")
699doc("It displays the available marker codes available in plotext. Note that any other single character is a valid marker.")
702method("themes")
703doc("It displays the available plot themes available in plotext.")
706method("test")
707doc("It builds a matrix of plots, useful to quickly test plotext after installation.")