| Name | df2img JSON |
| Version |
0.2.19
JSON |
| download |
| home_page | https://df2img.dev |
| Summary | Save a Pandas DataFrame as image |
| upload_time | 2024-04-27 12:56:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2022 Andreas Vester
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
pandas
dataframe
image
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# df2img: Save a Pandas DataFrame as image
## What is it all about?
Have you ever tried to save a ``pd.DataFrame`` into an image file? This is not a straightforward process at all. Unfortunately, ``pandas`` itself doesn't provide this functionality out of the box.
**df2img** tries to fill the gap. It is a Python library that greatly simplifies the process of saving a ``pd.DataFrame`` into an image file (e.g. ``png`` or ``jpg``).
It is a wrapper/convenience function in order to create a ``plotly`` Table. That is, one can use ``plotly``'s styling function to format the table.
## Dependencies
**df2img** has a limited number of dependencies, namely
- ``pandas``
- ``plotly``
- ``kaleido``
## Documentation
An extensive documentation is available at https://df2img.dev.
## Important note
The ``kaleido`` dependency is needed to save a ``pd.DataFrame``. Right now there is an
issue when using the latest version of ``kaleido``.
This project requires ``kaleido==v0.2.1`` when you are installing ``df2img`` on a
machine other than Windows.
However, when you're on a Windows machine, you must use ``kaleido==v0.1.0.post1``.
The dependency specification in the ``pyproject.toml`` file takes care of this.
Having said this, if you're not on Windows and using the
[pdm](https://pdm-project.org/en/stable/) package manager, ``kaleido`` won't get
installed at all due to a [bug](https://github.com/pdm-project/pdm/issues/46) in
[pdm](https://pdm-project.org/en/stable/). In that case the following workaround might
be helpful:
- activate your virtual environment: ``source .venv/bin/activate``
- use ``pip`` in order to install ``kaleido`` separately: ``pip install kaleido==0.2.1``
## Quickstart
You can install the package via ``pip``.
```bash
pip install df2img
```
Using ``poetry`` or ``pdm``?
```bash
poetry add df2img
pdm add df2img
```
Let's create a simple ``pd.DataFrame`` with some dummy data:
```python
import pandas as pd
import df2img
df = pd.DataFrame(
data=dict(
float_col=[1.4, float("NaN"), 250, 24.65],
str_col=("string1", "string2", float("NaN"), "string4"),
),
index=["row1", "row2", "row3", "row4"],
)
```
```python
float_col str_col
row1 1.40 string1
row2 NaN string2
row3 250.00 NaN
row4 24.65 string4
```
### Basics
Saving ``df`` into a png-file now takes just two lines of code including some styling out of the box.
* First, we create a ``plotly`` figure.
* Second, we save the figure to disk.
```python
fig = df2img.plot_dataframe(df, fig_size=(500, 140))
df2img.save_dataframe(fig=fig, filename="plot1.png")
```
### Formatting
You can control the settings for the header row via the ``tbl_header`` input argument. This accepts a regular ``dict``. This ``dict`` can comprise various key/value pairs that are also accepted by ``plotly``. All available key/value pairs can be seen at ``plotly``'s website at https://plotly.com/python/reference/table/#table-header.
Let's set the header row in a different color and size. Also, let's set the alignment to "left".
```python
fig = df2img.plot_dataframe(
df,
tbl_header=dict(
align="left",
fill_color="blue",
font_color="white",
font_size=14,
),
fig_size=(500, 140),
)
```
Controlling the table body (cells) is basically the same. Just use the ``tbl_cells`` input argument, which happens to be a ``dict``, too.
See https://plotly.com/python/reference/table/#table-cells for all the possible key/value pairs.
Let's print the table cell values in yellow on a green background and align them "right".
```python
fig = df2img.plot_dataframe(
df,
tbl_cells=dict(
align="right",
fill_color="green",
font_color="yellow",
),
fig_size=(500, 140),
)
```
You can alternate row colors for better readability by using the ``row_fill_color`` input argument. Using HEX colors is also possible:
```python
fig = df2img.plot_dataframe(
df,
row_fill_color=("#ffffff", "#d7d8d6"),
fig_size=(500, 140),
)
```
Setting the title will be controlled via the ``title`` input argument. You can find the relevant key/value pairs here: https://plotly.com/python/reference/layout/#layout-title.
Let's put the title in a different font and size. In addition, we can control the alignment via the ``x`` key/value pair. It sets the x (horizontal) position in normalized coordinates from "0" (left) to "1" (right).
```python
fig = df2img.plot_dataframe(
df,
title=dict(
font_color="darkred",
font_family="Times New Roman",
font_size=24,
text="This is a title starting at the x-value x=0.1",
x=0.1,
xanchor="left",
),
fig_size=(500, 140),
)
```
You can also control relative column width via the ``col_width`` argument. Let's set the first column's width triple the width of the third column and the second column's width double the width of the third column.
```python
fig = df2img.plot_dataframe(
df,
col_width=[3, 2, 1],
fig_size=(500, 140),
)
```
## Contributing to df2img
If you consider to contribute to **df2img**, please read the [Contributing to df2img](./CONTRIBUTING.md) section in the documentation. This document is supposed to guide you through the whole process.
Raw data
{
"_id": null,
"home_page": "https://df2img.dev",
"name": "df2img",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "pandas, dataframe, image",
"author": null,
"author_email": "Andreas Vester <info@df2img.dev>",
"download_url": "https://files.pythonhosted.org/packages/98/09/0d7194c2be9af57954c1d55d72555ae48acd05fae8bb9030ef72469deda9/df2img-0.2.19.tar.gz",
"platform": null,
"description": "# df2img: Save a Pandas DataFrame as image\n\n\n\n\n\n\n\n## What is it all about?\n\nHave you ever tried to save a ``pd.DataFrame`` into an image file? This is not a straightforward process at all. Unfortunately, ``pandas`` itself doesn't provide this functionality out of the box.\n\n**df2img** tries to fill the gap. It is a Python library that greatly simplifies the process of saving a ``pd.DataFrame`` into an image file (e.g. ``png`` or ``jpg``).\n\nIt is a wrapper/convenience function in order to create a ``plotly`` Table. That is, one can use ``plotly``'s styling function to format the table.\n\n\n## Dependencies\n\n**df2img** has a limited number of dependencies, namely\n\n- ``pandas``\n- ``plotly``\n- ``kaleido``\n\n\n## Documentation\n\nAn extensive documentation is available at https://df2img.dev.\n\n## Important note\nThe ``kaleido`` dependency is needed to save a ``pd.DataFrame``. Right now there is an\nissue when using the latest version of ``kaleido``.\nThis project requires ``kaleido==v0.2.1`` when you are installing ``df2img`` on a\nmachine other than Windows.\nHowever, when you're on a Windows machine, you must use ``kaleido==v0.1.0.post1``.\nThe dependency specification in the ``pyproject.toml`` file takes care of this.\n\nHaving said this, if you're not on Windows and using the\n[pdm](https://pdm-project.org/en/stable/) package manager, ``kaleido`` won't get\ninstalled at all due to a [bug](https://github.com/pdm-project/pdm/issues/46) in\n[pdm](https://pdm-project.org/en/stable/). In that case the following workaround might\nbe helpful:\n- activate your virtual environment: ``source .venv/bin/activate``\n- use ``pip`` in order to install ``kaleido`` separately: ``pip install kaleido==0.2.1``\n\n\n## Quickstart\n\nYou can install the package via ``pip``.\n\n```bash\npip install df2img\n```\n\nUsing ``poetry`` or ``pdm``?\n\n```bash\npoetry add df2img\npdm add df2img\n```\n\nLet's create a simple ``pd.DataFrame`` with some dummy data:\n\n```python\nimport pandas as pd\n\nimport df2img\n\ndf = pd.DataFrame(\n data=dict(\n float_col=[1.4, float(\"NaN\"), 250, 24.65],\n str_col=(\"string1\", \"string2\", float(\"NaN\"), \"string4\"),\n ),\n index=[\"row1\", \"row2\", \"row3\", \"row4\"],\n)\n```\n```python\n float_col str_col\nrow1 1.40 string1\nrow2 NaN string2\nrow3 250.00 NaN\nrow4 24.65 string4\n```\n\n### Basics\n\nSaving ``df`` into a png-file now takes just two lines of code including some styling out of the box.\n\n* First, we create a ``plotly`` figure.\n* Second, we save the figure to disk.\n\n```python\nfig = df2img.plot_dataframe(df, fig_size=(500, 140))\n\ndf2img.save_dataframe(fig=fig, filename=\"plot1.png\")\n```\n\n\n\n\n### Formatting\n\nYou can control the settings for the header row via the ``tbl_header`` input argument. This accepts a regular ``dict``. This ``dict`` can comprise various key/value pairs that are also accepted by ``plotly``. All available key/value pairs can be seen at ``plotly``'s website at https://plotly.com/python/reference/table/#table-header.\n\nLet's set the header row in a different color and size. Also, let's set the alignment to \"left\".\n\n```python\nfig = df2img.plot_dataframe(\n df,\n tbl_header=dict(\n align=\"left\",\n fill_color=\"blue\",\n font_color=\"white\",\n font_size=14,\n ),\n fig_size=(500, 140),\n)\n```\n\n\n\nControlling the table body (cells) is basically the same. Just use the ``tbl_cells`` input argument, which happens to be a ``dict``, too.\nSee https://plotly.com/python/reference/table/#table-cells for all the possible key/value pairs.\n\nLet's print the table cell values in yellow on a green background and align them \"right\".\n\n```python\nfig = df2img.plot_dataframe(\n df,\n tbl_cells=dict(\n align=\"right\",\n fill_color=\"green\",\n font_color=\"yellow\",\n ),\n fig_size=(500, 140),\n)\n```\n\n\n\n\nYou can alternate row colors for better readability by using the ``row_fill_color`` input argument. Using HEX colors is also possible:\n\n```python\nfig = df2img.plot_dataframe(\n df,\n row_fill_color=(\"#ffffff\", \"#d7d8d6\"),\n fig_size=(500, 140),\n)\n```\n\n\n\n\nSetting the title will be controlled via the ``title`` input argument. You can find the relevant key/value pairs here: https://plotly.com/python/reference/layout/#layout-title.\n\nLet's put the title in a different font and size. In addition, we can control the alignment via the ``x`` key/value pair. It sets the x (horizontal) position in normalized coordinates from \"0\" (left) to \"1\" (right).\n\n```python\n fig = df2img.plot_dataframe(\n df,\n title=dict(\n font_color=\"darkred\",\n font_family=\"Times New Roman\",\n font_size=24,\n text=\"This is a title starting at the x-value x=0.1\",\n x=0.1,\n xanchor=\"left\",\n ),\n fig_size=(500, 140),\n )\n ```\n\n\n\n\nYou can also control relative column width via the ``col_width`` argument. Let's set the first column's width triple the width of the third column and the second column's width double the width of the third column.\n\n```python\nfig = df2img.plot_dataframe(\n df,\n col_width=[3, 2, 1],\n fig_size=(500, 140),\n)\n```\n\n\n\n## Contributing to df2img\n\nIf you consider to contribute to **df2img**, please read the [Contributing to df2img](./CONTRIBUTING.md) section in the documentation. This document is supposed to guide you through the whole process.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2022 Andreas Vester\n \n Permission is hereby granted, free of charge, to any person obtaining\n a copy of this software and associated documentation files (the\n \"Software\"), to deal in the Software without restriction, including\n without limitation the rights to use, copy, modify, merge, publish,\n distribute, sublicense, and/or sell copies of the Software, and to\n permit persons to whom the Software is furnished to do so, subject to\n the following conditions:\n \n The above copyright notice and this permission notice shall be\n included in all copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\n EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\n NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\n LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\n OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\n WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Save a Pandas DataFrame as image",
"version": "0.2.19",
"project_urls": {
"Bugtracker": "https://github.com/andreas-vester/df2img/issues?q=label%3Abug+",
"Documentation": "https://df2img.dev",
"Homepage": "https://df2img.dev",
"Repository": "https://github.com/andreas-vester/df2img"
},
"split_keywords": [
"pandas",
" dataframe",
" image"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e588be7b36884521e3232b8d9f2471215d04d21e0333a7f87fc2bfc3b84e4a5",
"md5": "7c84f2b25512178413d457134d40faa2",
"sha256": "dc2f899b608fa7cbcb15f4856a91477bcb0d65b16631868894c04041fc85db36"
},
"downloads": -1,
"filename": "df2img-0.2.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c84f2b25512178413d457134d40faa2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15401,
"upload_time": "2024-04-27T12:56:37",
"upload_time_iso_8601": "2024-04-27T12:56:37.344775Z",
"url": "https://files.pythonhosted.org/packages/0e/58/8be7b36884521e3232b8d9f2471215d04d21e0333a7f87fc2bfc3b84e4a5/df2img-0.2.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "98090d7194c2be9af57954c1d55d72555ae48acd05fae8bb9030ef72469deda9",
"md5": "689d759639c1b3ed5e25226ba4d0dc13",
"sha256": "f18fe8c8452c7f300bb964beec8dd02ab0b7b880a9d8eb65b3a740fa35ba081e"
},
"downloads": -1,
"filename": "df2img-0.2.19.tar.gz",
"has_sig": false,
"md5_digest": "689d759639c1b3ed5e25226ba4d0dc13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19959,
"upload_time": "2024-04-27T12:56:39",
"upload_time_iso_8601": "2024-04-27T12:56:39.286090Z",
"url": "https://files.pythonhosted.org/packages/98/09/0d7194c2be9af57954c1d55d72555ae48acd05fae8bb9030ef72469deda9/df2img-0.2.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 12:56:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andreas-vester",
"github_project": "df2img",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "df2img"
}
