diff --git a/CHANGELOG.md b/CHANGELOG.md index f0fc013..a60a427 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,16 +1,19 @@ # Changelog -## 1.0.0 (2023-09-02) +## 1.0.0 (2023-09-11) -- Updated to newer versions of optional dependencies. -- Created documentation at readthedocs. - Added new text elements `div()` and `span()`. Added new parameters to HTML elements - in particular `cl` and `attrs`. -- Deprecated `print_html()` function. New `print()` should be used instead. -- Deprecated `print_code()` function. New `print_source_code()` should be used instead. +- Replaced `print_html()` function with `print()`. +- Replaced `print_code()` function with `print_source_code()`. +- Replaced `plot_graph()` with `print_figure()`. +- Removed `plot_multi_graph`. - Replaced code-prettify with highlight.js for code blocks. - `print_h1`, ..., `print_h6` functions can now take a `Reference` object. - Added `--config-path` CLI option, changed how `pyreball-generate-config` command works and how the config paths are handled. +- Updated CLI arguments and config parameters for tables and figures. +- Updated to newer versions of 3rd party dependencies for example. +- Created documentation at readthedocs. ## 0.1.1 (2021-09-14) diff --git a/README.md b/README.md index 03aa08d..af0fb21 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ pb.print_table(df, caption="A data table.") fig, ax = plt.subplots() sns.lineplot(x="x", y="y", ax=ax, data=df) ax.set(xlabel="x", ylabel="y") -pb.plot_graph(fig, caption="The first plot.") +pb.print_figure(fig, caption="The first plot.") ``` In this particular example, we are using a few 3rd party packages, so let's install them too: diff --git a/docs/configuration.md b/docs/configuration.md index 4688561..8a65365 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -110,27 +110,27 @@ parameters. The following table shows the parameter alternatives between these t of given function. For example, instead of values `yes` and `no`, the functions usually use Boolean values `True` and `False`. -| `config.ini` key | CLI argument | Function argument | Description | -|---------------------------|-----------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `toc` | `--toc ` | _N/A_ | Include table of contents. It is included only when there are any headings. Allowed values: `yes`, `no`. | -| `align-tables` | `--align-tables` | `align` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Horizontal alignment of tables. Allowed values: `left`, `center`, `right`. | -| `table-captions-position` | `--table-captions-position` | `caption_position` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Caption position. Allowed values: `top`, `bottom`. | -| `numbered-tables` | `--numbered-tables` | `numbered` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to number tables. Allowed values: `yes`, `no`. | -| `tables-display-option` | `--tables-display-option` | `display_option` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | How to display table. This option is useful for long tables, which should not be displayed fully. Allowed values are: `full` (show the full table), `scrolling` (show the table in scrolling mode on y-axis), `paging` (show the table in paging mode). | -| `tables-paging-sizes` | `--tables-paging-sizes` | `paging_sizes` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | The paging sizes that can be selected. Ignored when `tables-display-option` is not `paging`. Allowed values are integers and string `all` (no matter the case of letters), written as a non-empty comma-separated list. | -| `tables-scroll-y-height` | `--tables-scroll-y-height` | `scroll_y_height` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Height of the tables when `tables-display-option` is set to `scrolling`. Any string compatible with CSS sizing can be used, e.g. `300px`, `20em`, etc. | -| `tables-scroll-x` | `--tables-scroll-x` | `scroll_x` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to allow scrolling on the x-axis. If turned off, a wide table is allowed to overflow the main container. It is recommended to turn this on. Allowed values: `yes`, `no`. | -| `sortable-tables` | `--sortable-tables` | `sortable` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to make columns in tables sortable. Allowed values: `yes`, `no`. | -| `tables-search-box` | `--tables-search-box` | `show_search_box` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to show the search box for the tables. Allowed values: `yes`, `no`. | -| `tables-datatables-style` | `--tables-datatables-style` | `datatables_style` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Datatables class(es) that affect the tables styling. If multiple classes are provided, separate them either with commas or spaces. See [DataTables documentation](https://datatables.net/manual/styling/classes) with the possible values. | -| `align-plots` | `--align-plots` | `align` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Horizontal alignment of plots. Allowed values: `left`, `center`, `right`. | -| `plot-captions-position` | `--plot-captions-position` | `caption_position` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Caption position. Allowed values: `top`, `bottom`. | -| `numbered-plots` | `--numbered-plots` | `numbered` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to number plots. Allowed values: `yes`, `no`. | -| `matplotlib-format` | `--matplotlib-format` | `matplotlib_format` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Format of matplotlib (and thus also seaborn) plots. Allowed values: `png`, `svg`. | -| `matplotlib-embedded` | `--matplotlib-embedded` | `embedded` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to embedded matplotlib (and thus also seaborn) plots directly into HTML. Only for svg format. Allowed values: `yes`, `no`. | -| `numbered-headings` | `--numbered-headings` | _N/A_ | Whether to number headings. Allowed values: `yes`, `no`. | -| `page-width` | `--page-width` | _N/A_ | Width of the page container in percentage. Allowed values: An integer in the range 40..100. | -| `keep-stdout` | `--keep-stdout` | _N/A_ | Whether to print the output to stdout too: `yes`, `no`. | +| `config.ini` key | CLI argument | Function argument | Description | +|----------------------------|------------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `toc` | `--toc ` | _N/A_ | Include table of contents. It is included only when there are any headings. Allowed values: `yes`, `no`. | +| `align-tables` | `--align-tables` | `align` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Horizontal alignment of tables. Allowed values: `left`, `center`, `right`. | +| `table-captions-position` | `--table-captions-position` | `caption_position` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Caption position. Allowed values: `top`, `bottom`. | +| `numbered-tables` | `--numbered-tables` | `numbered` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to number tables. Allowed values: `yes`, `no`. | +| `tables-display-option` | `--tables-display-option` | `display_option` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | How to display table. This option is useful for long tables, which should not be displayed fully. Allowed values are: `full` (show the full table), `scrolling` (show the table in scrolling mode on y-axis), `paging` (show the table in paging mode). | +| `tables-paging-sizes` | `--tables-paging-sizes` | `paging_sizes` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | The paging sizes that can be selected. Ignored when `tables-display-option` is not `paging`. Allowed values are integers and string `all` (no matter the case of letters), written as a non-empty comma-separated list. | +| `tables-scroll-y-height` | `--tables-scroll-y-height` | `scroll_y_height` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Height of the tables when `tables-display-option` is set to `scrolling`. Any string compatible with CSS sizing can be used, e.g. `300px`, `20em`, etc. | +| `tables-scroll-x` | `--tables-scroll-x` | `scroll_x` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to allow scrolling on the x-axis. If turned off, a wide table is allowed to overflow the main container. It is recommended to turn this on. Allowed values: `yes`, `no`. | +| `sortable-tables` | `--sortable-tables` | `sortable` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to make columns in tables sortable. Allowed values: `yes`, `no`. | +| `tables-search-box` | `--tables-search-box` | `show_search_box` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to show the search box for the tables. Allowed values: `yes`, `no`. | +| `tables-datatables-style` | `--tables-datatables-style` | `datatables_style` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Datatables class(es) that affect the tables styling. If multiple classes are provided, separate them either with commas or spaces. See [DataTables documentation](https://datatables.net/manual/styling/classes) with the possible values. | +| `align-figures` | `--align-figures` | `align` in [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure) | Horizontal alignment of figures. Allowed values: `left`, `center`, `right`. | +| `figure-captions-position` | `--figure-captions-position` | `caption_position` in [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure) | Caption position. Allowed values: `top`, `bottom`. | +| `numbered-figures` | `--numbered-figures` | `numbered` in [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure) | Whether to number figures. Allowed values: `yes`, `no`. | +| `matplotlib-format` | `--matplotlib-format` | `matplotlib_format` in [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure) | Format of matplotlib (and thus also seaborn) figures. Allowed values: `png`, `svg`. | +| `matplotlib-embedded` | `--matplotlib-embedded` | `embedded` in [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure) | Whether to embedded matplotlib (and thus also seaborn) figures directly into HTML. Only for svg format. Allowed values: `yes`, `no`. | +| `numbered-headings` | `--numbered-headings` | _N/A_ | Whether to number headings. Allowed values: `yes`, `no`. | +| `page-width` | `--page-width` | _N/A_ | Width of the page container in percentage. Allowed values: An integer in the range 40..100. | +| `keep-stdout` | `--keep-stdout` | _N/A_ | Whether to print the output to stdout too: `yes`, `no`. | The reason for having multiple options for setting these values is to allow the user to set some properties globally, while others locally as needed for particular scripts. diff --git a/docs/examples/example_init.py b/docs/examples/example_init.py index ee8a0c0..cbd83af 100644 --- a/docs/examples/example_init.py +++ b/docs/examples/example_init.py @@ -5,7 +5,7 @@ pb.print_div( "Pyreball has many features, among others:", pb.ulist( - "Creating plots.", + "Creating charts.", "Sortable and scrollable tables.", f'Basic text formatting such as {pb.em("emphasis")}.', f'Also {pb.link("hyperlinks", "https://www.python.org/")}.', diff --git a/docs/examples/example_init_deps.py b/docs/examples/example_init_deps.py index 83b3dce..612814d 100644 --- a/docs/examples/example_init_deps.py +++ b/docs/examples/example_init_deps.py @@ -3,14 +3,12 @@ import pyreball as pb import seaborn as sns -pb.set_title("Tables and Plots") +pb.set_title("Tables and Figures") -# Print a table df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 6, 5]}) pb.print_table(df, caption="A data table.") -# Plot a graph fig, ax = plt.subplots() sns.lineplot(x="x", y="y", ax=ax, data=df) ax.set(xlabel="x", ylabel="y") -pb.plot_graph(fig, caption="A line plot.") +pb.print_figure(fig, caption="A line chart.") diff --git a/docs/examples/plotting_bokeh.py b/docs/examples/plotting_bokeh.py index d0ff05f..6b545ab 100644 --- a/docs/examples/plotting_bokeh.py +++ b/docs/examples/plotting_bokeh.py @@ -8,4 +8,4 @@ fig = figure(x_range=df["x"]) fig.vbar(x="x", top="y", width=0.9, source=ColumnDataSource(data=df)) fig.add_tools(HoverTool(tooltips=[("x", "@x"), ("y", "@y")])) -pb.plot_graph(fig, caption="Bokeh barchart.") +pb.print_figure(fig, caption="Bokeh barchart.") diff --git a/docs/examples/plotting_matplotlib_png.py b/docs/examples/plotting_matplotlib_png.py index d940dd0..34197f5 100644 --- a/docs/examples/plotting_matplotlib_png.py +++ b/docs/examples/plotting_matplotlib_png.py @@ -5,7 +5,7 @@ plt.bar([1, 2, 3], [4, 3, 6]) plt.xlabel("x") plt.ylabel("y") -pb.plot_graph( +pb.print_figure( fig, caption="Matplotlib barchart as png.", matplotlib_format="png", diff --git a/docs/examples/plotting_matplotlib_svg.py b/docs/examples/plotting_matplotlib_svg.py index b6d8f4d..9dd5a68 100644 --- a/docs/examples/plotting_matplotlib_svg.py +++ b/docs/examples/plotting_matplotlib_svg.py @@ -5,7 +5,7 @@ plt.bar([1, 2, 3], [4, 3, 6]) plt.xlabel("x") plt.ylabel("y") -pb.plot_graph( +pb.print_figure( fig, caption="Matplotlib barchart as svg.", matplotlib_format="svg", diff --git a/docs/examples/plotting_plotly.py b/docs/examples/plotting_plotly.py index c560c71..78f19e6 100644 --- a/docs/examples/plotting_plotly.py +++ b/docs/examples/plotting_plotly.py @@ -5,4 +5,4 @@ df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 3, 6]}) fig = px.bar(df, x="x", y="y") -pb.plot_graph(fig, caption="Plotly graph.") +pb.print_figure(fig, caption="Plotly chart.") diff --git a/docs/examples/plotting_seaborn.py b/docs/examples/plotting_seaborn.py index cf6c323..2b3496a 100644 --- a/docs/examples/plotting_seaborn.py +++ b/docs/examples/plotting_seaborn.py @@ -8,7 +8,7 @@ fig, ax = plt.subplots() sns.barplot(x="x", y="y", data=df, ax=ax, color=sns.xkcd_rgb["windows blue"]) ax.set(xlabel="x", ylabel="y") -pb.plot_graph( +pb.print_figure( fig, caption="Seaborn barchart as png.", matplotlib_format="png", diff --git a/docs/examples/plotting_vega_altair.py b/docs/examples/plotting_vega_altair.py index 481cd83..9a24927 100644 --- a/docs/examples/plotting_vega_altair.py +++ b/docs/examples/plotting_vega_altair.py @@ -23,4 +23,4 @@ height=400, ) ) -pb.plot_graph(fig, caption="Vega-Altair barchart.") +pb.print_figure(fig, caption="Vega-Altair barchart.") diff --git a/docs/examples/references.py b/docs/examples/references.py index 168b87e..cd9dbf9 100644 --- a/docs/examples/references.py +++ b/docs/examples/references.py @@ -5,7 +5,7 @@ import pyreball as pb import seaborn as sns -pb.set_title("References to Plots and Tables") +pb.set_title("References to Figures and Tables") ref_ch_1 = pb.Reference() @@ -47,7 +47,7 @@ fig, ax = plt.subplots() sns.scatterplot(x="x", y="y", ax=ax, data=df) ax.set(xlabel="x", ylabel="y") -pb.plot_graph(fig, caption="A plot with a reference.", reference=img_reference) +pb.print_figure(fig, caption="A figure with a reference.", reference=img_reference) pb.print_div( f"Note that you can use the references in your text multiple times, " diff --git a/docs/examples/references_simple.py b/docs/examples/references_simple.py index 07e8598..204a90a 100644 --- a/docs/examples/references_simple.py +++ b/docs/examples/references_simple.py @@ -4,6 +4,6 @@ ref = pb.Reference("My Table") pb.print(f"It is possible to create a link {ref} before the target...") -pb.print_table(pd.DataFrame({'a': [1, 2], 'b': [3, 4]}), reference=ref) +pb.print_table(pd.DataFrame({"a": [1, 2], "b": [3, 4]}), reference=ref) pb.print(f"and also link {ref} after the target.") pb.print(f"It is also possible to create {ref('link with custom text')}.") diff --git a/docs/examples/text_utils_formatting.py b/docs/examples/text_utils_formatting.py index 20ab2db..3bf61ff 100644 --- a/docs/examples/text_utils_formatting.py +++ b/docs/examples/text_utils_formatting.py @@ -1,6 +1,5 @@ import pyreball as pb pb.print( - f"This sentence contains both {pb.bold('bold')} " - f"and {pb.em('emphasized')} text." + f"This sentence contains both {pb.bold('bold')} " f"and {pb.em('emphasized')} text." ) diff --git a/docs/index.md b/docs/index.md index 7975ca4..1326434 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ Pyreball is a Python reporting tool that generates HTML reports from Python scri Main features: -- Plots in [Vega-Altair](https://altair-viz.github.io/index.html), [Plotly](https://plotly.com/), [Bokeh](https://bokeh.org/), and [Matplotlib](https://matplotlib.org/) (and thus also [Seaborn](https://seaborn.pydata.org/) etc.). +- Charts in [Vega-Altair](https://altair-viz.github.io/index.html), [Plotly](https://plotly.com/), [Bokeh](https://bokeh.org/), and [Matplotlib](https://matplotlib.org/) (and thus also [Seaborn](https://seaborn.pydata.org/) etc.). - Interactive tables based on [DataTables](https://datatables.net/) library and created from [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html). - Basic text formatting such as headings, emphasis, and lists. - Hyperlinks, references and table of contents. @@ -39,13 +39,13 @@ pyreball report.py -## Adding Tables and Plots +## Adding Tables and Figures The core functionality of `pyreball` does not require any 3rd party dependencies. However, it is possible to generate other types of elements with the help of libraries such as [pandas](https://pandas.pydata.org/) or [seaborn](https://seaborn.pydata.org/). -Let's create another python script called `report_plot.py`: +Let's create another python script called `report_chart.py`: {{ inline_source("docs/examples/example_init_deps.py") }} @@ -53,9 +53,9 @@ Install `pandas` and `seaborn`, then run `pyreball`: ``` pip install pandas seaborn -pyreball report_plot.py +pyreball report_chart.py ``` -`report_plot.html` should look like this: +`report_chart.html` should look like this: diff --git a/docs/plotting.md b/docs/plotting.md index 11b8812..f8aa45a 100644 --- a/docs/plotting.md +++ b/docs/plotting.md @@ -4,23 +4,23 @@ Pyreball currently supports plotting figures created by [Matplotlib](https://matplotlib.org/), [Seaborn](https://seaborn.pydata.org/), [Vega-Altair](https://altair-viz.github.io/index.html), [Plotly](https://plotly.com/), and [Bokeh](https://bokeh.org/). -There is a single function [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) for all these libraries. +There is a single function [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure) for all these libraries. Similarly to [`print_table()`](../api/pyreball_html/#pyreball.html.print_table), it uses parameters `caption`, `align`, `caption_position` and `numbered` with the same meaning. -In contrast to table captions, the default position of plot captions is `bottom`. +In contrast to table captions, the default position of figure captions is `bottom`. ## Matplotlib When plotting with Matplotlib, it is necessary to create a figure object and pass it -to [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph). +to [`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure). -In case of Matplotlib, a user can select the format of the plot via `matplotlib_format` parameter: either `"png"` +In case of Matplotlib, a user can select the format of the figure via `matplotlib_format` parameter: either `"png"` or `"svg"`. -In case of `"svg"`, it is also possible to choose whether the plot should be embedded into the HTML file or saved into a -separate file and referenced in the HTML file by setting `embedded` accordingly. -Plots in `"png"` format cannot be embedded into the HTML file. +In case of `"svg"`, it is also possible to choose whether the figure should be embedded into the HTML file +or saved into a separate file and referenced in the HTML file by setting `embedded` accordingly. +Figures in `"png"` format cannot be embedded into the HTML file. -When the plot is stored into a file, the file is saved in a directory with name equal to the filename stem of the HTML +When the figure is stored into a file, the file is saved in a directory with name equal to the filename stem of the HTML file. For example, for HTML file `report.html`, the image file will be stored in directory `report`. The following code shows an example of a bar chart created with Matplotlib and stored in a `"png"` format. @@ -29,7 +29,7 @@ The following code shows an example of a bar chart created with Matplotlib and s -The next example shows the same plot, but embedded directly into the HTML document in `"svg"` format. +The next example shows the same chart, but embedded directly into the HTML document in `"svg"` format. {{ inline_source("docs/examples/plotting_matplotlib_svg.py") }} @@ -58,7 +58,7 @@ e.g. `altair.ConcatChart`, `altair.HConcatChart`. ## Plotly -Pyreball supports interactive plots created by Plotly, too. +Pyreball supports interactive charts created by Plotly, too. {{ inline_source("docs/examples/plotting_plotly.py") }} @@ -66,7 +66,7 @@ Pyreball supports interactive plots created by Plotly, too. ## Bokeh -Another library for plotting interactive plots supported by Pyreball is Bokeh. +Another library for plotting interactive charts supported by Pyreball is Bokeh. {{ inline_source("docs/examples/plotting_bokeh.py") }} diff --git a/docs/references.md b/docs/references.md index 3d06f4d..bf74af4 100644 --- a/docs/references.md +++ b/docs/references.md @@ -7,7 +7,7 @@ class. Specifically, one can create a reference object by calling `pb.Reference()`. This object can be then passed to a function that creates a table ([`print_table()`](../api/pyreball_html/#pyreball.html.print_table)), -a plot ([`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph)), or +a figure ([`print_figure()`](../api/pyreball_html/#pyreball.html.print_figure)), or a heading ([`print_h1()`](../api/pyreball_html/#pyreball.html.print_h1), ..., [`print_h6()`](../api/pyreball_html/#pyreball.html.print_h6)). Each such function then creates a target for the link. @@ -31,8 +31,8 @@ a parameter that is used to override the default link text. When default link text is not provided through the constructor, Pyreball uses table numbers as texts for links pointing -to tables. The same is applied for links pointing to plots. In case of headings, the default link text would be the text -of the heading itself. +to tables. The same is applied for links pointing to figures. +In case of headings, the default link text would be the text of the heading itself. The artificial example below demonstrates some of these features. diff --git a/examples/large_table_report.html b/examples/large_table_report.html deleted file mode 100644 index db07175..0000000 --- a/examples/large_table_report.html +++ /dev/null @@ -1,189 +0,0 @@ - - - -Large Tables Report - - - - - - - - - - - - - - - - - - - - - -
-

Large Tables Report

-1  Illustration of full_table parameter.
-

1  Illustration of full_table parameter.

-
Note that the second table is not shown whole and is therefore scrollable.
-
- - - \ No newline at end of file diff --git a/examples/large_table_report.py b/examples/large_table_report.py deleted file mode 100644 index 16dd393..0000000 --- a/examples/large_table_report.py +++ /dev/null @@ -1,31 +0,0 @@ -"""This report shows how to work with larger tables.""" -import numpy as np -import pandas as pd - -import pyreball as pb - -pb.set_title("Large Tables Report") - -# Print headers -pb.print_h1(f"Illustration of {pb.code('full_table')} parameter.") - -pb.print_div( - "Note that the second table is not shown whole and is therefore scrollable." -) - -# Print a table -df = pd.DataFrame({"x": np.arange(0, 20), "y": np.arange(100, 120)}) - -pb.print_table(df, caption="Data table with full_table=True.", full_table=True) - -pb.print_table(df, caption="Data table with full_table=False.", full_table=False) - -small_df = pd.DataFrame({"x": np.arange(0, 10), "y": np.arange(100, 110)}) - -pb.print_table( - small_df, caption="Small data table with full_table=True.", full_table=True -) - -pb.print_table( - small_df, caption="Small data table with full_table=False.", full_table=False -) diff --git a/examples/longer_report.html b/examples/longer_report.html index 66c6728..00386b6 100644 --- a/examples/longer_report.html +++ b/examples/longer_report.html @@ -181,7 +181,6 @@

Sample Report2  Inspecting Data

1  Displaying Texts

We can always start inserting custom raw HTML code.
@@ -267,1256 +266,6 @@

2.1  Tables and Plots -
- - - - - - - 2023-09-07T08:56:02.303305 - image/svg+xml - - - Matplotlib v3.7.2, https://matplotlib.org/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Figure 1: The first plot. -
-
-

2.2  References to Plots and Tables

-
It is also possible to create references to tables and figures. For example Table 2 shows sortable columns and Fig. 2 displays a scatterplot.
-
-
-
-Table 2: A sortable table with a reference -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
xy
15.155267
24.676778
35.740878
43.817809
56.512470
63.109550
75.681870
84.669219
95.234759
103.561548
-
-
- -
-
-
-Table 3: A table sorted by y column -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
xy
15.155267
24.676778
35.740878
43.817809
56.512470
63.109550
75.681870
84.669219
95.234759
103.561548
-
-
- -
- - - - - - - 2023-09-07T08:56:02.329851 - image/svg+xml - - - Matplotlib v3.7.2, https://matplotlib.org/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Figure 2: A plot with a reference. -
-
-
Note that you can use the references in your text multiple times, see again the reference to Table 2 and Fig. 2. Of course, we cannot use a single reference for multiple tables or figures.
-
+
@@ -220,7 +220,7 @@

2  Tables and Plots - 2023-09-07T08:56:01.582977 + 2023-09-11T08:16:07.294369 image/svg+xml @@ -256,12 +256,12 @@

2  Tables and Plots - - + @@ -321,7 +321,7 @@

2  Tables and Plots - + @@ -388,7 +388,7 @@

2  Tables and Plots - + @@ -404,7 +404,7 @@

2  Tables and Plots - + @@ -432,7 +432,7 @@

2  Tables and Plots - + @@ -448,7 +448,7 @@

2  Tables and Plots - + @@ -464,7 +464,7 @@

2  Tables and Plots - + @@ -480,7 +480,7 @@

2  Tables and Plots - + @@ -496,7 +496,7 @@

2  Tables and Plots - + @@ -571,12 +571,12 @@

2  Tables and Plots - - + @@ -613,7 +613,7 @@

2  Tables and Plots - + @@ -629,7 +629,7 @@

2  Tables and Plots - + @@ -645,7 +645,7 @@

2  Tables and Plots - + @@ -661,7 +661,7 @@

2  Tables and Plots - + @@ -677,7 +677,7 @@

2  Tables and Plots - + @@ -693,7 +693,7 @@

2  Tables and Plots - + @@ -709,7 +709,7 @@

2  Tables and Plots - + @@ -725,7 +725,7 @@

2  Tables and Plots - + @@ -800,7 +800,7 @@

2  Tables and Plots +" clip-path="url(#p4d836f0802)" style="fill: none; stroke: #1f77b4; stroke-width: 1.5; stroke-linecap: square"/> 2  Tables and Plots - +
-Figure 1: The first plot. +The first figure.

diff --git a/examples/report.py b/examples/report.py index dd29389..6a6640c 100644 --- a/examples/report.py +++ b/examples/report.py @@ -11,21 +11,19 @@ pb.print_div( "Pyreball has many features, among others:", pb.ulist( - "Plots in altair, plotly, bokeh, and matplotlib (and thus also seaborn etc.).", + "Charts in altair, plotly, bokeh, and matplotlib (and thus also seaborn etc.).", "Sortable and scrollable tables from pandas DataFrame.", f'Basic text formatting such as {pb.bold("headings")}, {pb.em("emphasis")}, and {pb.code("lists")}.', f'{pb.link("hyperlinks", "https://www.python.org/")}, references and table of contents.', ), ) -pb.print_h1("Tables and Plots") +pb.print_h1("Tables and Figures") -# Print a table df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 6, 5]}) pb.print_table(df, caption="A data table.") -# Plot a graph fig, ax = plt.subplots() sns.lineplot(x="x", y="y", ax=ax, data=df) ax.set(xlabel="x", ylabel="y") -pb.plot_graph(fig, caption="The first plot.") +pb.print_figure(fig, caption="The first figure.") diff --git a/examples/sample_plots.html b/examples/sample_plots.html index 20187e0..0a17820 100644 --- a/examples/sample_plots.html +++ b/examples/sample_plots.html @@ -208,597 +208,6 @@

Sample Plots -
-
- - - - - - - 2023-09-07T08:56:00.804558 - image/svg+xml - - - Matplotlib v3.7.2, https://matplotlib.org/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Figure 2: Seaborn barchart as embedded svg. -
-
-
-
-Figure 3: Altair barchart. -
-
-
-
-Figure 4: Plotly graph. -
-
-
-
-
-Figure 5: Bokeh barchart. -
-

" ) - assert _prepare_altair_plot_element(fig, 326) == expected_result + assert _prepare_altair_image_element(fig, 326) == expected_result -def test__prepare_plotly_plot_element(): +def test__prepare_plotly_image_element(): fig = mock.Mock() fig.to_html.return_value = "fig_html" - result = _prepare_plotly_plot_element(fig) + result = _prepare_plotly_image_element(fig) assert result == "fig_html" fig.to_html.assert_called_with(full_html=False, include_plotlyjs=False) -def test__prepare_bokeh_plot_element(): +def test__prepare_bokeh_image_element(): with mock.patch("bokeh.embed.components", side_effect=lambda x: x): - result = _prepare_bokeh_plot_element(("a", "b")) + result = _prepare_bokeh_image_element(("a", "b")) assert result == "
ba
" @@ -1353,42 +1353,42 @@ def test__prepare_image_element__unknown_figure_type(): fig = list() with pytest.raises(ValueError) as excinfo: _prepare_image_element( - fig=fig, plot_index=3, matplotlib_format="svg", embedded=True + fig=fig, fig_index=3, matplotlib_format="svg", embedded=True ) assert "Unknown figure type" in str(excinfo.value) @mock.patch( - "pyreball.html._prepare_matplotlib_plot_element", return_value="img_element" + "pyreball.html._prepare_matplotlib_image_element", return_value="img_element" ) -def test__prepare_image_element__matplotlib(_prepare_matplotlib_plot_element_mock): +def test__prepare_image_element__matplotlib(_prepare_matplotlib_image_element_mock): fig, _ = plt.subplots() result = _prepare_image_element( - fig=fig, plot_index=3, matplotlib_format="svg", embedded=True + fig=fig, fig_index=3, matplotlib_format="svg", embedded=True ) - _prepare_matplotlib_plot_element_mock.assert_called_with( - fig=fig, l_plot_index=3, plot_format="svg", embedded=True + _prepare_matplotlib_image_element_mock.assert_called_with( + fig=fig, fig_index=3, image_format="svg", embedded=True ) assert result == "img_element" @mock.patch( - "pyreball.html._prepare_matplotlib_plot_element", return_value="img_element" + "pyreball.html._prepare_matplotlib_image_element", return_value="img_element" ) def test__prepare_image_element__seaborn( - _prepare_matplotlib_plot_element_mock, simple_dataframe + _prepare_matplotlib_image_element_mock, simple_dataframe ): fig = sns.PairGrid(simple_dataframe) result = _prepare_image_element( - fig=fig, plot_index=3, matplotlib_format="svg", embedded=True + fig=fig, fig_index=3, matplotlib_format="svg", embedded=True ) - _prepare_matplotlib_plot_element_mock.assert_called_with( - fig=fig, l_plot_index=3, plot_format="svg", embedded=True + _prepare_matplotlib_image_element_mock.assert_called_with( + fig=fig, fig_index=3, image_format="svg", embedded=True ) assert result == "img_element" -@mock.patch("pyreball.html._prepare_altair_plot_element", return_value="img_element") +@mock.patch("pyreball.html._prepare_altair_image_element", return_value="img_element") @pytest.mark.parametrize( "fig", [ @@ -1401,39 +1401,39 @@ def test__prepare_image_element__seaborn( alt.VConcatChart(get_simple_dataframe()), ], ) -def test__prepare_image_element__altair(_prepare_altair_plot_element_mock, fig): +def test__prepare_image_element__altair(_prepare_altair_image_element_mock, fig): result = _prepare_image_element( - fig=fig, plot_index=3, matplotlib_format="svg", embedded=True + fig=fig, fig_index=3, matplotlib_format="svg", embedded=True ) - _prepare_altair_plot_element_mock.assert_called_with(fig=fig, l_plot_index=3) + _prepare_altair_image_element_mock.assert_called_with(fig=fig, fig_index=3) assert result == "img_element" -@mock.patch("pyreball.html._prepare_plotly_plot_element", return_value="img_element") +@mock.patch("pyreball.html._prepare_plotly_image_element", return_value="img_element") def test__prepare_image_element__plotly( - _prepare_plotly_plot_element_mock, simple_dataframe + _prepare_plotly_image_element_mock, simple_dataframe ): fig = px.bar(simple_dataframe, x="x1", y="x2") result = _prepare_image_element( - fig=fig, plot_index=3, matplotlib_format="svg", embedded=True + fig=fig, fig_index=3, matplotlib_format="svg", embedded=True ) - _prepare_plotly_plot_element_mock.assert_called_with(fig=fig) + _prepare_plotly_image_element_mock.assert_called_with(fig=fig) assert result == "img_element" -@mock.patch("pyreball.html._prepare_bokeh_plot_element", return_value="img_element") +@mock.patch("pyreball.html._prepare_bokeh_image_element", return_value="img_element") def test__prepare_image_element__bokeh( - _prepare_bokeh_plot_element_mock, simple_dataframe + _prepare_bokeh_image_element_mock, simple_dataframe ): fig = bokeh_figure(x_range=simple_dataframe["x2"]) result = _prepare_image_element( - fig=fig, plot_index=3, matplotlib_format="svg", embedded=True + fig=fig, fig_index=3, matplotlib_format="svg", embedded=True ) - _prepare_bokeh_plot_element_mock.assert_called_with(fig=fig) + _prepare_bokeh_image_element_mock.assert_called_with(fig=fig) assert result == "img_element" -def test__plot_graph__stdout__bokeh(simple_dataframe): +def test__print_figure__stdout__bokeh(simple_dataframe): def fake_get_parameter_value(key): return key == "keep_stdout" @@ -1450,7 +1450,7 @@ def fake_get_parameter_value_different(key): with mock.patch( "pyreball.html.get_parameter_value", side_effect=fake_get_parameter_value ): - _plot_graph(fig) + _print_figure(fig) show_mock.assert_called_once_with(fig) # when keep_stdout is set off, but we don't have html file either @@ -1458,11 +1458,11 @@ def fake_get_parameter_value_different(key): "pyreball.html.get_parameter_value", side_effect=fake_get_parameter_value_different, ): - _plot_graph(fig) + _print_figure(fig) assert show_mock.call_count == 2 -def test__plot_graph__stdout__not_bokeh(simple_dataframe): +def test__print_figure__stdout__not_bokeh(simple_dataframe): def fake_get_parameter_value(key): return key == "keep_stdout" @@ -1478,7 +1478,7 @@ def fake_get_parameter_value_different(key): with mock.patch( "pyreball.html.get_parameter_value", side_effect=fake_get_parameter_value ): - _plot_graph(fig) + _print_figure(fig) show_mock.assert_called_once() # when keep_stdout is set off, but we don't have html file either @@ -1486,16 +1486,16 @@ def fake_get_parameter_value_different(key): "pyreball.html.get_parameter_value", side_effect=fake_get_parameter_value_different, ): - _plot_graph(fig) + _print_figure(fig) assert show_mock.call_count == 2 @pytest.mark.parametrize("caption_position", ["top", "bottom"]) -def test__plot_graph__file_output( +def test__print_figure__file_output( caption_position, simple_html_file, simple_dataframe, - pre_test_plot_graph_cleanup, + pre_test_print_figure_cleanup, pre_test_check_and_mark_reference_cleanup, ): # just test one fig to go through the pipeline @@ -1512,7 +1512,7 @@ def fake_get_parameter_value(key): fig = alt.Chart(simple_dataframe).mark_bar().encode(x="x2", y="x1") ref = Reference() ref.id = "id123" - _plot_graph( + _print_figure( fig=fig, caption="cap", reference=ref, @@ -1525,9 +1525,9 @@ def fake_get_parameter_value(key): ) _write_to_html_mock.assert_called_once() - assert _graph_memory["plot_index"] == 2 + assert _graph_memory["fig_index"] == 2 - _plot_graph( + _print_figure( fig=fig, caption="cap", reference=Reference(), @@ -1538,11 +1538,11 @@ def fake_get_parameter_value(key): embedded=True, hidden=True, ) - assert _graph_memory["plot_index"] == 3 + assert _graph_memory["fig_index"] == 3 # try with the same reference one more time with pytest.raises(ValueError) as excinfo: - _plot_graph( + _print_figure( fig=fig, caption="cap", reference=ref, @@ -1578,7 +1578,7 @@ def fake_get_parameter_value(key): (None, False, False), ], ) -def test_plot_graph( +def test_print_figure( align, param_align, expected_used_align, @@ -1593,11 +1593,11 @@ def test_plot_graph( def fake_get_parameter_value(key): if key == "html_file_path": return simple_html_file - elif key == "align_plots": + elif key == "align_figures": return param_align - elif key == "plot_captions_position": + elif key == "figure_captions_position": return param_caption_position - elif key == "numbered_plots": + elif key == "numbered_figures": return param_numbered else: return None @@ -1605,10 +1605,10 @@ def fake_get_parameter_value(key): with mock.patch( "pyreball.html.get_parameter_value", side_effect=fake_get_parameter_value ): - with mock.patch("pyreball.html._plot_graph") as _plot_graph_mock: + with mock.patch("pyreball.html._print_figure") as _print_figure_mock: ref = Reference() fig = alt.Chart(simple_dataframe).mark_bar().encode(x="x2", y="x1") - plot_graph( + print_figure( fig, caption="cap", reference=ref, @@ -1619,7 +1619,7 @@ def fake_get_parameter_value(key): embedded=True, ) - _plot_graph_mock.assert_called_with( + _print_figure_mock.assert_called_with( fig=fig, caption="cap", reference=ref, @@ -1630,56 +1630,3 @@ def fake_get_parameter_value(key): embedded=True, hidden=False, ) - - -@pytest.mark.parametrize( - "align,param_align,expected_used_align", - [ - ("left", "center", "left"), - (None, "right", "right"), - ], -) -@pytest.mark.parametrize( - "numbered,param_numbered,expected_used_numbered", - [ - (True, False, True), - (None, True, True), - (None, False, False), - ], -) -def test_plot_multi_graph( - align, - param_align, - expected_used_align, - numbered, - param_numbered, - expected_used_numbered, - simple_dataframe, - pre_test_plot_multi_graph_cleanup, -): - def fake_get_parameter_value(key): - if key == "html_file_path": - return simple_html_file - elif key == "align_plots": - return param_align - elif key == "numbered_plots": - return param_numbered - else: - return None - - with mock.patch( - "pyreball.html.get_parameter_value", side_effect=fake_get_parameter_value - ): - with mock.patch("pyreball.html._plot_graph") as _plot_graph_mock: - with mock.patch("pyreball.html._write_to_html") as _write_to_html_mock: - fig = alt.Chart(simple_dataframe).mark_bar().encode(x="x2", y="x1") - figs = [fig, fig, fig] - plot_multi_graph( - figs, - captions=["cap1", "cap2", "cap3"], - align=align, - numbered=numbered, - ) - - assert _plot_graph_mock.call_count == 3 - assert _multi_graph_memory["multi_plot_index"] == 2 diff --git a/tests/test_main.py b/tests/test_main.py index c8fbc8d..e74e0b3 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -389,7 +389,7 @@ def test__get_output_dir_and_file_stem__valid_inputs( # Empty string as input_path [""], # wrong param value - ["--numbered-plots", "hello", "scripts/report.py"], + ["--numbered-figures", "hello", "scripts/report.py"], # empty string for path option # white-space string for path option ["--output-path", "\n \n", "scripts/report.py"], @@ -495,9 +495,9 @@ def test_parse_arguments__valid_arguments(args, expected_non_empty_result): "tables_paging_sizes": None, "tables_search_box": None, "tables_datatables_style": None, - "align_plots": None, - "plot_captions_position": None, - "numbered_plots": None, + "align_figures": None, + "figure_captions_position": None, + "numbered_figures": None, "matplotlib_format": None, "matplotlib_embedded": None, "numbered_headings": None,