{"id":13936825,"url":"https://github.com/DeepSpace2/StyleFrame","last_synced_at":"2025-07-19T22:32:37.532Z","repository":{"id":2052660,"uuid":"41303032","full_name":"DeepSpace2/StyleFrame","owner":"DeepSpace2","description":"A library that wraps pandas and openpyxl and allows easy styling of dataframes in excel","archived":false,"fork":false,"pushed_at":"2024-04-22T04:34:26.000Z","size":585,"stargazers_count":379,"open_issues_count":9,"forks_count":54,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-07-03T05:19:50.900Z","etag":null,"topics":["data-frame","dataframe","excel","openpyxl","pandas"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepSpace2.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-24T12:56:57.000Z","updated_at":"2025-07-02T03:24:39.000Z","dependencies_parsed_at":"2023-11-11T20:25:50.593Z","dependency_job_id":"076400fd-5e77-439e-a984-825710a49bf0","html_url":"https://github.com/DeepSpace2/StyleFrame","commit_stats":{"total_commits":514,"total_committers":12,"mean_commits":"42.833333333333336","dds":0.6420233463035019,"last_synced_commit":"c8a11172d84d4af6eab7c75e7563a00926267765"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/DeepSpace2/StyleFrame","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSpace2%2FStyleFrame","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSpace2%2FStyleFrame/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSpace2%2FStyleFrame/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSpace2%2FStyleFrame/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepSpace2","download_url":"https://codeload.github.com/DeepSpace2/StyleFrame/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepSpace2%2FStyleFrame/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266031483,"owners_count":23866766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-frame","dataframe","excel","openpyxl","pandas"],"created_at":"2024-08-07T23:03:02.010Z","updated_at":"2025-07-19T22:32:37.257Z","avatar_url":"https://github.com/DeepSpace2.png","language":"Python","funding_links":["https://www.buymeacoffee.com/deepspace","https://img.buymeacoffee.com/button-api/?text=Buy"],"categories":["Python"],"sub_categories":[],"readme":"[![codecov](https://codecov.io/gh/DeepSpace2/StyleFrame/branch/master/graph/badge.svg?token=f4Q048ZOwC)](https://codecov.io/gh/DeepSpace2/StyleFrame)\n[![GitHub Actions](https://img.shields.io/github/checks-status/deepspace2/styleframe/master?label=Tests\u0026logo=github\u0026style=plastic)](https://github.com/DeepSpace2/StyleFrame/actions/workflows/test.yml?query=branch%3Amaster)\n[![PyPI](https://img.shields.io/pypi/v/styleframe.svg?style=plastic)](https://pypi.org/project/styleframe/)\n![PyPI](https://img.shields.io/pypi/pyversions/StyleFrame.svg?style=plastic)\n[![Downloads](http://pepy.tech/badge/styleframe)](https://pepy.tech/project/styleframe)\n[![Documentation Status](https://readthedocs.org/projects/styleframe/badge/?version=latest\u0026style=plastic)](https://styleframe.readthedocs.io/en/latest/?badge=latest)\n\n# StyleFrame\n_Exporting DataFrames to a styled Excel file has never been so easy_\n\nA library that wraps pandas and openpyxl and allows easy styling of dataframes in Excel.\n\n- [Documentation](http://styleframe.readthedocs.org/en/latest/)\n- [Changelog](CHANGELOG.md)\n- [How to contribute](.github/CONTRIBUTING.md)\n\n---\n\n## Contents\n1. [Rationale](#rationale)\n2. [Installation](#installation)\n3. [Basics](#basics)\n4. [Usage Examples](#usage-examples)    \n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;- [Simple Example](#simple-example)    \n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;- [Advance Example](#advance-example)   \n5. [Commandline Interface](#commandline-interface)\n6. [Buy me a Pizza](#buy-me-a-pizza)\n\n\n## Rationale\n\nPandas's DataFrame is great.   \nDealing with a lot of data is not easy and DataFrame helps us to manage it in the best way possible.   \n \nThere are many ways to present the output and one of them is excel files.   \nExcel files are easy to understand, can be viewed offline, can be sent over the email\nand a large percentage of the population familiar with it.   \nThat is why many times we would choose excel files as our output.   \n\nStyleFrame package allows us to design the excel file on the data in a similar way to DataFrame api.   \nIt saves us the trouble of working with excel workbook and the suffering of trying to match it with the data stored in our DataFrame.\n\n\n## Installation\n```\n$ pip install styleframe\n```\n\n## Basics\n\n* ***Styler***:\nThe `Styler` class represents a style of a cell.   \n\n* ***utils***:\nThe `utils` module contains helper classes for frequently used styling elements,\nsuch as number and date formats, colors and border types.\n\n* ***Container***: \nThe `Container` class represents a cell, a value/style pair.\n\n* ***StyleFrame***:\nThe `StyleFrame` is the main interaction point you will have. \nIt wraps the `DataFrame` object you will be styling.\n\n## Usage Examples\n\n### Simple Example\n\n```python\nimport pandas as pd\nfrom styleframe import StyleFrame, Styler, utils   \n   \ndf = pd.DataFrame({\n    'Time': [1.496728e+09, 1.496728e+09, 1.496728e+09, 1.496728e+09, 1.496728e+09],\n    'Expect': ['Hey', 'how', 'are', 'you', 'today?'],\n    'Actual': ['Hello', 'how', 'are', 'u', 'today?'],\n    'Pass/Fail': ['Failed', 'Passed', 'Passed', 'Failed', 'Passed']\n    },\n    columns=['Time', 'Expect', 'Actual', 'Pass/Fail'])\n   \n\"\"\"Our DataFrame looks like this:\n\n           Time  Expect  Actual Pass/Fail\n0  1.496728e+09     Hey   Hello    Failed\n1  1.496728e+09     how     how    Passed\n2  1.496728e+09     are     are    Passed\n3  1.496728e+09     you       u    Failed\n4  1.496728e+09  today?  today?    Passed\n\n\"\"\"\n   \n# Create StyleFrame object that wrap our DataFrame and assign default style.\ndefault_style = Styler(font=utils.fonts.aharoni, font_size=14)\nsf = StyleFrame(df, styler_obj=default_style)\n   \n# Style the headers of the table\nheader_style = Styler(bold=True, font_size=18)\nsf.apply_headers_style(styler_obj=header_style)\n   \n# Set the background color to green where the test marked as 'passed'\npassed_style = Styler(bg_color=utils.colors.green, font_color=utils.colors.white)\nsf.apply_style_by_indexes(indexes_to_style=sf[sf['Pass/Fail'] == 'Passed'],\n                          cols_to_style='Pass/Fail',\n                          styler_obj=passed_style,\n                          overwrite_default_style=False)\n   \n# Set the background color to red where the test marked as 'failed'\nfailed_style = Styler(bg_color=utils.colors.red, font_color=utils.colors.white)\nsf.apply_style_by_indexes(indexes_to_style=sf[sf['Pass/Fail'] == 'Failed'],\n                          cols_to_style='Pass/Fail',\n                          styler_obj=failed_style,\n                          overwrite_default_style=False)\n   \n# Change the columns width and the rows height\nsf.set_column_width(columns=sf.columns, width=20)\nsf.set_row_height(rows=sf.row_indexes, height=25)\n\nwriter = sf.to_excel('output.xlsx',\n                     # Add filters in row 0 to each column.\n                     row_to_add_filters=0, \n                     # Freeze the columns before column 'A' (=None)\n                     # and rows above '2' (=1).\n                     columns_and_rows_to_freeze='A2')\n\nwriter.close()\n```    \nThe final output saved under output.xlsx:    \n![Example 1](readme-images/example1.PNG?raw=true)\n\n\n### Advance Example\n\nFirst, let us create a DataFrame that contains data we would like to export to an .xlsx file \n```python\nfrom datetime import date\nimport pandas as pd\n   \n   \ncolumns = ['Date', 'Col A', 'Col B', 'Col C', 'Percentage']\ndf = pd.DataFrame(data={'Date': [date(1995, 9, 5), date(1947, 11, 29), date(2000, 1, 15)],\n                        'Col A': [1, 2004, -3],\n                        'Col B': [15, 3, 116],\n                        'Col C': [33, -6, 9],\n                        'Percentage': [0.113, 0.504, 0.005]},\n                  columns=columns)\n\nonly_values_df = df[columns[1:-1]]\n\nrows_max_value = only_values_df.idxmax(axis=1)\n\ndf['Sum'] = only_values_df.sum(axis=1)\ndf['Mean'] = only_values_df.mean(axis=1)\n\n\"\"\"Our DataFrame looks like this:\n\n         Date  Col A  Col B  Col C  Percentage   Sum        Mean\n0  1995-09-05      1     15     33       0.113    49   16.333333\n1  1947-11-29   2004      3     -6       0.504  2001  667.000000\n2  2000-01-15     -3    116      9       0.005   122   40.666667\n\n\"\"\"\n```\n\nNow, once we have the DataFrame ready, lets create a StyleFrame object\n```python\nfrom styleframe import StyleFrame\n\nsf = StyleFrame(df)\n# it is also possible to directly initiate StyleFrame\nsf = StyleFrame({'Date': [date(1995, 9, 5), date(1947, 11, 29), date(2000, 1, 15)],\n                 'Col A': [1, 2004, -3],\n                 'Col B': [15, 3, 116],\n                 'Col C': [33, -6, 9],\n                 'Percentage': [0.113, 0.504, 0.005],\n                 'Sum': [49, 2001, 122],\n                 'Mean': [16.333333, 667.000000, 40.666667]})\n```\n\nThe StyleFrame object will auto-adjust the columns width and the rows height\nbut they can be changed manually\n```python\nsf.set_column_width_dict(col_width_dict={\n    ('Col A', 'Col B', 'Col C'): 15.3,\n    ('Sum', 'Mean'): 30,\n    ('Percentage', ): 12\n})\n\n# excel rows starts from 1\n# row number 1 is the headers\n# len of StyleFrame (same as DataFrame) does not count the headers row\nall_rows = sf.row_indexes\nsf.set_row_height_dict(row_height_dict={\n    all_rows[0]: 45,  # headers row\n    all_rows[1:]: 25\n})\n```\n\nApplying number formats\n```python\nfrom styleframe import Styler, utils\n\n\nsf.apply_column_style(cols_to_style='Date',\n                      styler_obj=Styler(date_format=utils.number_formats.date,\n                                        font=utils.fonts.calibri,\n                                        bold=True))\n\nsf.apply_column_style(cols_to_style='Percentage',\n                      styler_obj=Styler(number_format=utils.number_formats.percent))\n\nsf.apply_column_style(cols_to_style=['Col A', 'Col B', 'Col C'],\n                      styler_obj=Styler(number_format=utils.number_formats.thousands_comma_sep))                     \n```\n\nNext, let's change the background color of the maximum values to red and the font to white  \nwe will also protect those cells and prevent the ability to change their value\n```python\nstyle = Styler(bg_color=utils.colors.red,\n               bold=True,\n               font_color=utils.colors.white,\n               protection=True,\n               underline=utils.underline.double,\n               number_format=utils.number_formats.thousands_comma_sep).to_openpyxl_style()\n        \nfor row_index, col_name in rows_max_value.iteritems():\n    sf[col_name][row_index].style = style\n```\n\nAnd change the font and the font size of Sum and Mean columns\n```python\nsf.apply_column_style(cols_to_style=['Sum', 'Mean'],\n                      style_header=True,\n                      styler_obj=Styler(font_color='#40B5BF',\n                                        font_size=18,\n                                        bold=True))\n```\n\nChange the background of all rows where the date is after 14/1/2000 to green\n```python                 \nsf.apply_style_by_indexes(indexes_to_style=sf[sf['Date'] \u003e date(2000, 1, 14)],\n                          cols_to_style='Date',\n                          styler_obj=Styler(bg_color=utils.colors.green,\n                                            date_format=utils.number_formats.date,\n                                            bold=True))\n```\n\nFinally, let's export to Excel but not before we use more of StyleFrame's features:\n- Change the page writing side\n- Freeze rows and columns\n- Add filters to headers\n\n```python\new = StyleFrame.ExcelWriter('sf tutorial.xlsx')\nsf.to_excel(excel_writer=ew,\n            sheet_name='1',\n            right_to_left=False,\n            columns_and_rows_to_freeze='B2', # will freeze the rows above 2 (=row 1 only) and columns that before column 'B' (=col A only)\n            row_to_add_filters=0,\n            allow_protection=True)\n```\n\nAdding another excel sheet\n```python\nother_sheet_sf = StyleFrame({'Dates': [date(2016, 10, 20), date(2016, 10, 21), date(2016, 10, 22)]},\n                            styler_obj=Styler(date_format=utils.number_formats.date))\n                            \nother_sheet_sf.to_excel(excel_writer=ew, sheet_name='2')\n```\n\nDon't forget to save\n```python\new.close()\n```\n\n**_the result:_**\nSheet 1:\n\n![Example 2 sheet 1](readme-images/example2-sheet-1.PNG?raw=true)\n\nSheet 2:\n\n![Example 2 sheet 2](readme-images/example2-sheet-2.PNG?raw=true)\n\nNote that Sheet 1 is protected:\n\n![Example 2 sheets](readme-images/example2-sheets.PNG?raw=true)\n\n## Commandline Interface\n#### General Information\n\nStarting with version 1.1 StyleFrame offers a commandline interface\nthat lets you create an xlsx file from a json file.\n\n#### Usage\n\n`-v` Displays the installed versions of StyleFrame and its dependencies.\n\n`--json_path` Path to the json file.\n\n`--output_path` Path to the output xlsx file. If not provided defaults to `output.xlsx`.\n\n***Usage Examples:***\n\n`$ styleframe --json_path data.json --output_path data.xlsx`\n\n#### JSON Format\n\nThe input JSON should be thought of as an hierarchy of predefined entities,\nsome of which correspond to a Python class used by StyleFrame.\nThe top-most level should be a list of `sheet` entities (see below).\n\nAn example JSON is available \u003ca href=\"examples/json_example.json\" target=\"_blank\"\u003ehere\u003c/a\u003e.\n\n* ***style:***\n\nCorresponds to: Styler class.\n\nThis entity uses the arguments of `Styler.__init__()` as keys.\nAny missing keys in the JSON will be given the same default values.\n\n`\"style\": {\"bg_color\": \"yellow\", \"bold\": true}`\n\n* ***cell***\n\nThis entity represents a single cell in the sheet.\n\nRequired keys:\n\n`\"value\"` - The cell's value.\n\nOptional keys:\n\n`\"style\"` - The `style` entity for this cell. \nIf not provided, the `style` provided to the `coloumn` entity will be used.\nIf that was not provided as well, the default `Styler.__init__()` values will be used.  \n\n`{\"value\": 42, \"style\": {\"border\": \"double\"}}`\n\n* ***column***\n\nThis entity represents a column in the sheet.\n\nRequired keys:\n\n`\"col_name\"` - The column name.\n\n`\"cells\"` - A list of `cell` entities.\n\nOptional keys:\n\n`\"style\"` - A style used for the entire column. If not provided the default `Styler.__init__()` values will be used. \n\n`\"width\"` - The column's width. If not provided Excel's default column width will be used.\n\n* ***sheet***\n\nThis entity represents the whole sheet.\n\nRequired keys:\n\n`\"sheet_name\"` - The sheet's name.\n\n`\"columns\"` - A list of `column` entities.\n\nOptional keys:\n\n`\"default_styles\"` - A JSON object with items as keys and `style` entities as values.\nCurrently only `headers` is supported as an item.\n\n`\"default_styles\": {\"headers\": {\"bg_color\": \"blue\"}}`\n \n`\"row_heights\"` - A JSON object with rows indexes as keys and heights as value.\n\n`\"extra_features\"` - A JSON that contains the same arguments as the\n`to_excel` method, such as `\"row_to_add_filters\"`, `\"columns_and_rows_to_freeze\"`,\n`\"columns_to_hide\"`, `\"right_to_left\"` and `\"allow_protection\"`. \nYou can also use other arguments that Pandas' `\"to_excel\"` accepts.\n\nRefer to the \u003ca href=\"http://styleframe.readthedocs.org/en/latest/\" target=\"_blank\"\u003edocumentation\u003c/a\u003e\nfor more information.\n\n## Buy me a Pizza\n\nYou made it all the way down here, cool! If you love StyleFrame and want to show your appreciation, consider buying me a slice of Pizza (or even just drop a comment). Anything will be greatly appreciated 🙂\n\n\u003ca href=\"https://www.buymeacoffee.com/deepspace\"\u003e\u003cimg src=\"https://img.buymeacoffee.com/button-api/?text=Buy me a Pizza\u0026emoji=🍕\u0026slug=deepspace\u0026button_colour=5F7FFF\u0026font_colour=ffffff\u0026font_family=Comic\u0026outline_colour=000000\u0026coffee_colour=FFDD00\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeepSpace2%2FStyleFrame","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDeepSpace2%2FStyleFrame","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeepSpace2%2FStyleFrame/lists"}