numdaplot 0.1.0__py3-none-any.whl

numdaplot/plots/figure/placement.py

@@ -0,0 +1,150 @@
+"""
+A Plot placed in the grid of a Figure, and the checks of its place.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.cell_out_of_range_error import CellOutOfRangeError
+from numdaplot.errors.occupied_cell_error import OccupiedCellError
+from numdaplot.plots.figure.cell import Cell
+from numdaplot.plots.figure.layout import Layout
+from numdaplot.plots.plot import Plot
+
+
+@dataclass(frozen=True, eq=False)
+class Placement:
+	"""
+	A Plot and the cells it covers in a Figure.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	plot
+		The Plot placed.
+	cell
+		Its first cell and the number of cells it spans.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.figure.placement import Placement
+	>>> plot = ndp.Plot.line(ndp.Array.from_list([12.0, 15.5]))
+	>>> Placement(plot, ndp.Cell(row=0, column=1)).cell.column
+	1
+	"""
+
+	plot: Plot
+	cell: Cell
+
+
+def require_cell_inside(cell: Cell, layout: Layout) -> None:
+	"""
+	Check that every cell a Plot covers is inside the grid of a Figure.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	cell
+		The first cell and the spans of the Plot.
+	layout
+		The grid of the Figure.
+
+	Raises
+	------
+	CellOutOfRangeError
+		When a cell it spans is after the last row or column. ``Cell`` already refuses a negative row or column.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.figure.placement import require_cell_inside
+	>>> try:
+	... 	require_cell_inside(ndp.Cell(row=1, column=0, column_span=3), ndp.Layout(rows=2, columns=2))
+	... except ndp.CellOutOfRangeError as error:
+	... 	print(error)
+	Cell (1, 0) is outside a Layout of 2 rows and 2 columns.
+	"""
+	row_end = cell.row + cell.row_span
+	column_end = cell.column + cell.column_span
+	is_outside = row_end > layout.rows or column_end > layout.columns
+	if is_outside:
+		raise CellOutOfRangeError(cell.row, cell.column, layout.rows, layout.columns)
+
+
+def require_free_cells(cell: Cell, placements: list[Placement]) -> None:
+	"""
+	Check that no cell a Plot covers already holds another Plot.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	cell
+		The first cell and the spans of the Plot placed.
+	placements
+		The Plots already in the Figure.
+
+	Raises
+	------
+	OccupiedCellError
+		At the first cell, row by row, already covered by another Plot.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.figure.placement import Placement, require_free_cells
+	>>> plot = ndp.Plot.line(ndp.Array.from_list([12.0, 15.5]))
+	>>> wide_placement = Placement(plot, ndp.Cell(row=0, column=0, column_span=2))
+	>>> try:
+	... 	require_free_cells(ndp.Cell(row=0, column=1), [wide_placement])
+	... except ndp.OccupiedCellError as error:
+	... 	print(error)
+	Cell (0, 1) already holds a Plot.
+	"""
+	covered_cells = set[tuple[int, int]]()
+
+	for placement in placements:
+		placement_cells = list_covered_cells(placement.cell)
+		covered_cells.update(placement_cells)
+
+	new_cells = list_covered_cells(cell)
+
+	for row, column in new_cells:
+		if (row, column) in covered_cells:
+			raise OccupiedCellError(row, column)
+
+
+def list_covered_cells(cell: Cell) -> list[tuple[int, int]]:
+	"""
+	Return the row and the column of every cell a Plot covers, row by row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	cell
+		The first cell and the spans of the Plot.
+
+	Returns
+	-------
+	list[tuple[int, int]]
+		The covered cells.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.figure.placement import list_covered_cells
+	>>> list_covered_cells(ndp.Cell(row=1, column=0, column_span=2))
+	[(1, 0), (1, 1)]
+	"""
+	row_end = cell.row + cell.row_span
+	column_end = cell.column + cell.column_span
+	rows = range(cell.row, row_end)
+	columns = range(cell.column, column_end)
+	covered_cells = [(row, column) for row in rows for column in columns]
+
+	return covered_cells

numdaplot/plots/layer_reading.py

@@ -0,0 +1,166 @@
+"""
+Reading of the charts a Plot draws on its axes: lines, bars and points.
+
+``Plot.line``, ``Plot.bar`` and ``Plot.scatter`` read their first chart with these functions, and
+``Plot.add_line``, ``Plot.add_bar`` and ``Plot.add_scatter`` the charts they add.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.arrays.array import Array
+from numdaplot.plots.chart_layer import ChartLayer
+from numdaplot.plots.charts.bar_chart import BarChart
+from numdaplot.plots.charts.line_chart import LineChart
+from numdaplot.plots.charts.scatter_chart import ScatterChart
+from numdaplot.plots.data.array_values import read_array_values
+from numdaplot.plots.data.chart_data import read_chart_values, require_column_setting, require_no_column_settings
+from numdaplot.plots.data.point_values import hide_missing_points, read_point_values, require_scale_on_numbers
+from numdaplot.plots.data.table_values import read_table_values
+from numdaplot.plots.drawing.series_colors import require_color_count
+from numdaplot.tables.table import Table
+
+LINE_NAME = "LineChart"
+BAR_NAME = "BarChart"
+SCATTER_NAME = "ScatterChart"
+X_SETTING = "x"
+Y_SETTING = "y"
+COLOR_BY_SETTING = "color_by"
+SIZE_BY_SETTING = "size_by"
+
+
+def read_line_layer(data: Table | Array, chart: LineChart) -> ChartLayer:
+	"""
+	Return a LineChart with the values it draws from a Table or an Array.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data
+		The Table or the Array drawn.
+	chart
+		The columns drawn and the look of the lines.
+
+	Returns
+	-------
+	ChartLayer
+		The chart and its values.
+
+	Raises
+	------
+	InvalidChartDataError
+		When a Table has no ``y`` columns, or an Array has ``x`` or ``y`` columns.
+	InvalidColorCountError
+		When the colors of the chart are not one per line.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.layer_reading import read_line_layer
+	>>> grid = ndp.Array.from_list([[1.0, 2.0], [3.0, 4.0]])
+	>>> len(read_line_layer(grid, ndp.LineChart()).values.series)
+	2
+	"""
+	values = read_chart_values(data, chart.x, chart.y, LINE_NAME)
+	series_count = len(values.series)
+	require_color_count(chart.colors, series_count)
+	layer = ChartLayer(chart, values)
+
+	return layer
+
+
+def read_bar_layer(data: Table | Array, chart: BarChart) -> ChartLayer:
+	"""
+	Return a BarChart with the values it draws from a Table or an Array.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data
+		The Table or the Array drawn.
+	chart
+		The columns drawn and the look of the bars.
+
+	Returns
+	-------
+	ChartLayer
+		The chart and its values.
+
+	Raises
+	------
+	InvalidChartDataError
+		When a Table has no ``y`` columns, or an Array has ``x`` or ``y`` columns.
+	InvalidColorCountError
+		When the colors of the chart are not one per series.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.layer_reading import read_bar_layer
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> read_bar_layer(prices, ndp.BarChart()).values.series[0].values
+	array([12. , 15.5])
+	"""
+	values = read_chart_values(data, chart.x, chart.y, BAR_NAME)
+	series_count = len(values.series)
+	require_color_count(chart.colors, series_count)
+	layer = ChartLayer(chart, values)
+
+	return layer
+
+
+def read_scatter_layer(data: Table | Array, chart: ScatterChart) -> ChartLayer:
+	"""
+	Return a ScatterChart with the values it draws from a Table or an Array.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data
+		The Table or the Array drawn.
+	chart
+		The columns drawn and the look of the points.
+
+	Returns
+	-------
+	ChartLayer
+		The chart, its values, and for a Table the values coloring and sizing its points.
+
+	Raises
+	------
+	InvalidChartDataError
+		When a Table has no ``y`` column, or an Array has a column setting.
+	InvalidColorCountError
+		When ``color`` is given for an Array of several columns.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.layer_reading import read_scatter_layer
+	>>> grid = ndp.Array.from_list([[1.0, 2.0], [3.0, 4.0]])
+	>>> len(read_scatter_layer(grid, ndp.ScatterChart()).values.series)
+	2
+	"""
+	if isinstance(data, Array):
+		column_settings = dict[str, object](
+			{X_SETTING: chart.x, Y_SETTING: chart.y, COLOR_BY_SETTING: chart.color_by, SIZE_BY_SETTING: chart.size_by}
+		)
+		require_no_column_settings(SCATTER_NAME, column_settings)
+		array_values = read_array_values(data, SCATTER_NAME)
+		series_count = len(array_values.series)
+		if chart.color is not None:
+			require_color_count([chart.color], series_count)
+
+		array_layer = ChartLayer(chart, array_values)
+		return array_layer
+
+	y_name = require_column_setting(SCATTER_NAME, Y_SETTING, chart.y)
+	table_values = read_table_values(data, chart.x, [y_name], SCATTER_NAME)
+	point_values = read_point_values(data, chart.color_by, chart.size_by, table_values.rows)
+	require_scale_on_numbers(chart.scale, point_values.colors)
+	shown_values = hide_missing_points(table_values, point_values)
+	table_layer = ChartLayer(chart, shown_values, point_values)
+
+	return table_layer

numdaplot/plots/output/__init__.py

@@ -0,0 +1,5 @@
+"""
+Image files and display of Plots.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/plots/output/image_saving.py

@@ -0,0 +1,187 @@
+"""
+Image files of a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+from pathlib import Path
+
+from matplotlib.figure import Figure
+
+from numdaplot.errors.refused_setting_error import RefusedSettingError
+from numdaplot.errors.unsupported_image_format_error import UnsupportedImageFormatError
+from numdaplot.plots.drawing.plot_drawing import FigureDrawing, build_figure
+from numdaplot.plots.style.image_options import DEFAULT_DPI, ImageOptions
+from numdaplot.tables.conflict import Conflict
+from numdaplot.tables.files.file_access import WRITE_OPERATION, FileAccessErrors
+from numdaplot.tables.files.file_paths import FilePath, require_free_path
+
+IMAGE_FORMATS = {".png": "png", ".svg": "svg", ".pdf": "pdf"}
+RESOLUTION_EXTENSION = ".png"
+OPTIONS_NAME = "ImageOptions"
+IMAGE_OWNER = "A {extension} image"
+
+
+def find_image_format(path: Path) -> str:
+	"""
+	Return the image format named by the extension of a path.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of the image, ending with ``.png``, ``.svg`` or ``.pdf`` in lowercase or uppercase.
+
+	Returns
+	-------
+	str
+		The matplotlib name of the format: ``png``, ``svg`` or ``pdf``.
+
+	Raises
+	------
+	UnsupportedImageFormatError
+		When the path has another extension or none.
+
+	Examples
+	--------
+	>>> from pathlib import Path
+	>>> from numdaplot.plots.output.image_saving import find_image_format
+	>>> find_image_format(Path("sales.SVG"))
+	'svg'
+	"""
+	extension = path.suffix.lower()
+	if extension not in IMAGE_FORMATS:
+		raise UnsupportedImageFormatError(path.suffix)
+
+	image_format = IMAGE_FORMATS[extension]
+
+	return image_format
+
+
+def choose_resolution(path: Path, options: ImageOptions | None) -> int:
+	"""
+	Return the number of dots per inch an image is saved with.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of the image, with a supported extension.
+	options
+		The settings of a PNG image, or None.
+
+	Returns
+	-------
+	int
+		The resolution of the options, 100 without them.
+
+	Raises
+	------
+	RefusedSettingError
+		When options are given for an SVG or PDF image, which has no resolution.
+
+	Examples
+	--------
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.output.image_saving import choose_resolution
+	>>> try:
+	... 	choose_resolution(Path("sales.svg"), ndp.ImageOptions(dpi=200))
+	... except ndp.RefusedSettingError as error:
+	... 	print(error)
+	A .svg image does not accept ImageOptions.
+	"""
+	if options is None:
+		return DEFAULT_DPI
+
+	extension = path.suffix.lower()
+	if extension != RESOLUTION_EXTENSION:
+		image_name = IMAGE_OWNER.format(extension=extension)
+		raise RefusedSettingError(OPTIONS_NAME, image_name)
+
+	return options.dpi
+
+
+def save_figure(figure: Figure, path: Path, image_format: str, resolution: int) -> None:
+	"""
+	Save a matplotlib figure as an image.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	figure
+		The figure to save.
+	path
+		The path of the image.
+	image_format
+		The matplotlib name of the format, as ``find_image_format`` gives it.
+	resolution
+		The number of dots per inch, as ``choose_resolution`` gives it.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> from matplotlib.figure import Figure
+	>>> from numdaplot.plots.output.image_saving import save_figure
+	>>> path = Path(tempfile.mkdtemp()) / "empty.pdf"
+	>>> save_figure(Figure(), path, "pdf", 100)
+	>>> path.read_bytes()[:4]
+	b'%PDF'
+	"""
+	with FileAccessErrors(WRITE_OPERATION, path):
+		figure.savefig(path, format=image_format, dpi=resolution)
+
+
+def write_image(drawing: FigureDrawing, path: FilePath, options: ImageOptions | None, on_conflict: Conflict) -> None:
+	"""
+	Save what a Plot or a Figure draws as an image, in the format named by the extension of the path.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	drawing
+		What is drawn, and the size of the image.
+	path
+		The path of the image, ending with ``.png``, ``.svg`` or ``.pdf``.
+	options
+		The resolution of a PNG image, 100 dots per inch when omitted. SVG and PDF images take none.
+	on_conflict
+		``ERROR`` refuses to overwrite an existing file, ``REPLACE`` overwrites it.
+
+	Raises
+	------
+	UnsupportedImageFormatError
+		When the path does not end with ``.png``, ``.svg`` or ``.pdf``.
+	RefusedSettingError
+		When options are given for an SVG or PDF image.
+	FileExistsError
+		When a file exists at the path and ``on_conflict`` is ``ERROR``.
+	FileAccessError
+		When the file system refuses the file: missing folder, missing permission and so on.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.drawing.plot_drawing import FigureDrawing
+	>>> from numdaplot.plots.output.image_saving import write_image
+	>>> path = Path(tempfile.mkdtemp()) / "title.svg"
+	>>> write_image(FigureDrawing(lambda target: target.suptitle("Sales"), (3.0, 2.0)), path, None, ndp.Conflict.ERROR)
+	>>> path.read_text().startswith("<?xml")
+	True
+	"""
+	file_path = Path(path)
+	image_format = find_image_format(file_path)
+	resolution = choose_resolution(file_path, options)
+	require_free_path(file_path, on_conflict)
+	figure = build_figure(drawing)
+	save_figure(figure, file_path, image_format, resolution)

numdaplot/plots/output/plot_display.py

@@ -0,0 +1,181 @@
+"""
+Display of a Plot or a Figure in a Jupyter notebook or in a matplotlib window.
+
+.. versionadded:: 0.1.0
+"""
+
+# The matplotlib stubs leave the keyword arguments of most drawing methods untyped.
+# pyright: reportUnknownMemberType=false
+
+import warnings
+from importlib import import_module
+from io import BytesIO
+
+from matplotlib.backends.registry import BackendFilter, backend_registry
+from matplotlib.figure import Figure
+
+from numdaplot.arrays.operations.float_errors import INTERNAL_FILES
+from numdaplot.errors.display_warning import DisplayWarning
+from numdaplot.plots.drawing.plot_drawing import FIGURE_LAYOUT, FigureDrawing, build_figure
+from numdaplot.plots.output.shown_object import ShownObject
+from numdaplot.plots.style.image_options import DEFAULT_DPI
+from numdaplot.tables.preview.notebook_display import is_notebook
+
+IPYTHON_DISPLAY_MODULE = "IPython.display"
+PNG_FORMAT = "png"
+NO_WINDOW_MESSAGE = (
+	"No window can be opened, matplotlib has no graphical backend here. Install tkinter (python3-tk on Debian and "
+	"Ubuntu) to see the {object_name}, or save it with {class_name}.save."
+)
+
+
+def show_drawing(drawing: FigureDrawing, shown_object: ShownObject) -> None:
+	"""
+	Show what a Plot or a Figure draws: as an image in a Jupyter notebook, in a matplotlib window anywhere else.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	drawing
+		What is drawn, and the size of the figure.
+	shown_object
+		Whether a Plot or a Figure is shown, named by the warning emitted when no window can be opened.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.plot_drawing import FigureDrawing
+	>>> from numdaplot.plots.output.plot_display import show_drawing
+	>>> from numdaplot.plots.output.shown_object import ShownObject
+	>>> show_drawing(FigureDrawing(lambda target: target.suptitle("Sales"), (3.0, 2.0)), ShownObject.PLOT)
+	"""
+	runs_in_notebook = is_notebook()
+	if not runs_in_notebook:
+		show_drawing_in_window(drawing, shown_object)
+		return
+
+	figure = build_figure(drawing)
+	show_figure_in_notebook(figure)
+
+
+def show_figure_in_notebook(figure: Figure) -> None:
+	"""
+	Show a matplotlib figure as a PNG image in the output of a Jupyter notebook cell.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	figure
+		The figure to show.
+	"""
+	image_buffer = BytesIO()
+	figure.savefig(image_buffer, format=PNG_FORMAT, dpi=DEFAULT_DPI)
+	image_bytes = image_buffer.getvalue()
+	display_module = import_module(IPYTHON_DISPLAY_MODULE)
+	image = display_module.Image(data=image_bytes)
+	display_module.display(image)
+
+
+def show_drawing_in_window(drawing: FigureDrawing, shown_object: ShownObject) -> None:
+	"""
+	Show what a Plot or a Figure draws in a matplotlib window.
+
+	The call waits until the window is closed, unless matplotlib runs interactively. With a matplotlib backend
+	that opens no window, such as the one of a server, nothing is drawn and a ``DisplayWarning`` is emitted.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	drawing
+		What is drawn, and the size of the figure.
+	shown_object
+		Whether a Plot or a Figure is shown, named by the warning emitted when no window can be opened.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.drawing.plot_drawing import FigureDrawing
+	>>> from numdaplot.plots.output.plot_display import show_drawing_in_window
+	>>> from numdaplot.plots.output.shown_object import ShownObject
+	>>> drawing = FigureDrawing(lambda target: target.suptitle("Sales"), (3.0, 2.0))
+	>>> show_drawing_in_window(drawing, ShownObject.FIGURE)
+	"""
+	# pyplot chooses a matplotlib backend when imported, so it is only imported to open a window.
+	from matplotlib import pyplot
+
+	backend_name = pyplot.get_backend()
+	can_open_window = is_window_backend(backend_name)
+	if not can_open_window:
+		warn_without_window(shown_object)
+		return
+
+	figure = pyplot.figure(figsize=drawing.size_inches, dpi=DEFAULT_DPI, layout=FIGURE_LAYOUT)
+	drawing.draw_on(figure)
+	pyplot.show()
+	is_interactive = pyplot.isinteractive()
+	if not is_interactive:
+		pyplot.close(figure)
+
+
+def is_window_backend(backend_name: str) -> bool:
+	"""
+	Return whether a matplotlib backend opens windows.
+
+	Only the backends matplotlib lists as non-interactive, such as ``agg`` chosen when no window can be opened,
+	are refused: a backend added by another package is trusted.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	backend_name
+		The name matplotlib gives to its backend, such as ``tkagg`` or ``agg``, in any case.
+
+	Returns
+	-------
+	bool
+		False for a matplotlib backend without window, True otherwise.
+
+	Examples
+	--------
+	>>> from numdaplot.plots.output.plot_display import is_window_backend
+	>>> is_window_backend("Agg")
+	False
+	>>> is_window_backend("TkAgg")
+	True
+	"""
+	lowered_name = backend_name.lower()
+	non_interactive_names = backend_registry.list_builtin(BackendFilter.NON_INTERACTIVE)
+	is_window = lowered_name not in non_interactive_names
+
+	return is_window
+
+
+def warn_without_window(shown_object: ShownObject) -> None:
+	"""
+	Emit a ``DisplayWarning`` pointing at the line of the calling code that asked to show a Plot or a Figure.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	shown_object
+		Whether a Plot or a Figure could not be shown.
+
+	Examples
+	--------
+	>>> import warnings
+	>>> from numdaplot.plots.output.plot_display import warn_without_window
+	>>> from numdaplot.plots.output.shown_object import ShownObject
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	warn_without_window(ShownObject.FIGURE)
+	>>> print(caught_warnings[0].message)
+	No window can be opened, matplotlib has no graphical backend here. Install tkinter (python3-tk on Debian and
+	Ubuntu) to see the figure, or save it with Figure.save.
+	"""
+	class_name = shown_object.value
+	object_name = class_name.lower()
+	message = NO_WINDOW_MESSAGE.format(object_name=object_name, class_name=class_name)
+	warnings.warn(message, DisplayWarning, skip_file_prefixes=INTERNAL_FILES)