{"id":13671391,"url":"https://github.com/SundayWindy/ExcelAlchemy","last_synced_at":"2025-04-27T18:31:14.839Z","repository":{"id":80009241,"uuid":"605894799","full_name":"SundayWindy/ExcelAlchemy","owner":"SundayWindy","description":"A Python Library for Reading and Writing Excel Files.","archived":false,"fork":false,"pushed_at":"2023-06-28T02:11:52.000Z","size":449,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-23T22:20:43.514Z","etag":null,"topics":["excel-export","minio","openpyxl","pandas","pydantic","pydantic-models","python3"],"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/SundayWindy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2023-02-24T06:01:14.000Z","updated_at":"2025-04-04T16:29:12.000Z","dependencies_parsed_at":"2023-07-17T07:15:08.566Z","dependency_job_id":null,"html_url":"https://github.com/SundayWindy/ExcelAlchemy","commit_stats":{"total_commits":44,"total_committers":3,"mean_commits":"14.666666666666666","dds":"0.11363636363636365","last_synced_commit":"f93b0518a6f9cd148a98b6f1ec9212725b8e97b9"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SundayWindy%2FExcelAlchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SundayWindy%2FExcelAlchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SundayWindy%2FExcelAlchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SundayWindy%2FExcelAlchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SundayWindy","download_url":"https://codeload.github.com/SundayWindy/ExcelAlchemy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251187095,"owners_count":21549581,"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":["excel-export","minio","openpyxl","pandas","pydantic","pydantic-models","python3"],"created_at":"2024-08-02T09:01:08.328Z","updated_at":"2025-04-27T18:31:14.166Z","avatar_url":"https://github.com/SundayWindy.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003e [中文](https://github.com/SundayWindy/ExcelAlchemy/blob/main/README_cn.md) | English\n\u003e\n\n\n# ExcelAlchemy User Guide\n# 📊 ExcelAlchemy [![codecov](https://codecov.io/gh/SundayWindy/ExcelAlchemy/branch/main/graph/badge.svg?token=F6QVKL37XH)](https://codecov.io/gh/SundayWindy/ExcelAlchemy)    [![](https://tokei.rs/b1/github.com/SundayWindy/ExcelAlchemy?category=lines)](https://github.com/SundayWindy/ExcelAlchemy)\nExcelAlchemy is a Python library that allows you to download Excel files from Minio, parse user inputs, and generate corresponding Pydantic classes. It also allows you to generate Excel files based on Pydantic classes for easy user downloads.\n\n## Installation\n\nUse pip to install:\n\n```\npip install ExcelAlchemy\n```\n\n## Usage\n\n### Generate Excel template from Pydantic class\n\n```python\nfrom excelalchemy import ExcelAlchemy, FieldMeta, ImporterConfig, Number, String\nfrom pydantic import BaseModel\n\nclass Importer(BaseModel):\n    age: Number = FieldMeta(label='Age', order=1)\n    name: String = FieldMeta(label='Name', order=2)\n    phone: String | None = FieldMeta(label='Phone', order=3)\n    address: String | None = FieldMeta(label='Address', order=4)\n\nalchemy = ExcelAlchemy(ImporterConfig(Importer))\nbase64content = alchemy.download_template()\nprint(base64content)\n\n```\n* The above is a simple example of generating an Excel template from a Pydantic class. The Excel template will have a sheet named \"Sheet1\" with four columns: \"Age\", \"Name\", \"Phone\", and \"Address\". \"Age\" and \"Name\" are required fields, while \"Phone\" and \"Address\" are optional.\n* The method returns a base64-encoded string that represents the Excel file. You can directly use the window.open method to open the Excel file in the front-end, or download it by typing the base64 content in the browser's address bar.\n* When downloading a template, you can also specify some default values, for example:\n\n```python\nfrom excelalchemy import ExcelAlchemy, FieldMeta, ImporterConfig, Number, String\nfrom pydantic import BaseModel\n\nclass Importer(BaseModel):\n    age: Number = FieldMeta(label='Age', order=1)\n    name: String = FieldMeta(label='Name', order=2)\n    phone: String | None = FieldMeta(label='Phone', order=3)\n    address: String | None = FieldMeta(label='Address', order=4)\n\nalchemy = ExcelAlchemy(ImporterConfig(Importer))\n\nsample = [\n    {'age': 18, 'name': 'Bob', 'phone': '12345678901', 'address': 'New York'},\n    {'age': 19, 'name': 'Alice', 'address': 'Shanghai'},\n    {'age': 20, 'name': 'John', 'phone': '12345678901'},\n]\nbase64content = alchemy.download_template(sample)\nprint(base64content)\n```\nIn the above example, we specify a sample, which is a list of dictionaries. Each dictionary represents a row in the Excel sheet, and the keys represent column names. The method returns an Excel template with default values filled in. If a field doesn't have a default value, it will be empty. For example:\n* ![image](https://github.com/SundayWindy/ExcelAlchemy/raw/main/images/001_sample_template.png)\n\n### Parse a Pydantic class from an Excel file and create data\n\n```python\nimport asyncio\nfrom typing import Any\n\nfrom excelalchemy import ExcelAlchemy, FieldMeta, ImporterConfig, Number, String\nfrom minio import Minio\nfrom pydantic import BaseModel\n\n\nclass Importer(BaseModel):\n    age: Number = FieldMeta(label='Age', order=1)\n    name: String = FieldMeta(label='Name', order=2)\n    phone: String | None = FieldMeta(label='Phone', order=3)\n    address: String | None = FieldMeta(label='Address', order=4)\n\n\ndef data_converter(data: dict[str, Any]) -\u003e dict[str, Any]:\n    \"\"\"Custom data converter, here you can modify the result of Importer.dict()\"\"\"\n    data['age'] = data['age'] + 1\n    data['name'] = {\"phone\": data['phone']}\n    return data\n\n\nasync def create_func(data: dict[str, Any], context: None) -\u003e Any:\n    \"\"\"Your defined creation function\"\"\"\n    # do something to create data\n    return True\n\n\nasync def main():\n    alchemy = ExcelAlchemy(\n        ImporterConfig(\n            create_importer_model=Importer,\n            creator=create_func,\n            data_converter=data_converter,\n            minio=Minio(endpoint=''),  # reachable minio address\n            bucket_name='excel',\n            url_expires=3600,\n        )\n    )\n    result = await alchemy.import_data(input_excel_name='test.xlsx', output_excel_name=\"test.xlsx\")\n    print(result)\n\n\nasyncio.run(main())\n```\n\n* The importing function is based on `Minio`, so you need to install Minio and create a bucket to use this functionality for storing the Excel files.\n\n* The imported Excel file must be generated by the `download_template()` method, otherwise, it will produce a parsing error.\n* In the above example, we define a `data_converter` function, which is used to modify the result of `Importer.dict().` The final result of `data_converter` function will be the parameter of the create_func function. This function is optional if you don't need to modify the data.\n* The `create_func` function is used to create data, and the parameter is the result of the data_converter function, and context is None. You can create data, for example, by storing the data in a database.\n* The `input_excel_name` parameter of the `import_data()` method is the name of the Excel file in Minio, and the `output_excel_name` parameter is the name of the Excel file with the parsing result in Minio. This file contains all the input data, and if any data fails the parsing, the first column of that data has an error message, and the error-producing cell is highlighted in red.\n* The method returns an `ImportResult` type result. You can see the definition of this class in the code. This class contains all the information about the parsing result, such as the number of successfully imported data, the number of failed data, the failed data, etc.\n* An example of the importing result is shown in the following image:\n![image](https://github.com/SundayWindy/ExcelAlchemy/raw/main/images/002_import_result.png)\n\n\n### Contributing\nIf you have any questions or suggestions regarding the ExcelAlchemy library, please raise an issue in [GitHub Issues](https://github.com/SundayWindy/ExcelAlchemy/issues). We also welcome you to submit a pull request to contribute your code.\n\n### License\nExcelAlchemy is licensed under the MIT license. For more information, please see the [LICENSE](https://github.com/SundayWindy/ExcelAlchemy/blob/main/LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSundayWindy%2FExcelAlchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSundayWindy%2FExcelAlchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSundayWindy%2FExcelAlchemy/lists"}