{"id":15065850,"url":"https://github.com/paduszyk/django-xlsx-serializer","last_synced_at":"2025-04-10T13:34:40.096Z","repository":{"id":244855727,"uuid":"804527501","full_name":"paduszyk/django-xlsx-serializer","owner":"paduszyk","description":"Load/dump Django models from/to Excel 2007+ workbooks.","archived":false,"fork":false,"pushed_at":"2024-12-20T19:36:08.000Z","size":94,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T03:03:59.406Z","etag":null,"topics":["django","django-application","excel","excel-export","excel-import","openpyxl","python"],"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/paduszyk.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","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":"2024-05-22T18:54:58.000Z","updated_at":"2025-02-17T11:39:33.000Z","dependencies_parsed_at":"2024-06-17T22:52:54.028Z","dependency_job_id":"d142408a-45e9-4737-b57d-1c29594101a1","html_url":"https://github.com/paduszyk/django-xlsx-serializer","commit_stats":null,"previous_names":["paduszyk/django-xlsx-serializer"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fdjango-xlsx-serializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fdjango-xlsx-serializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fdjango-xlsx-serializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paduszyk%2Fdjango-xlsx-serializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paduszyk","download_url":"https://codeload.github.com/paduszyk/django-xlsx-serializer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225870,"owners_count":21068078,"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":["django","django-application","excel","excel-export","excel-import","openpyxl","python"],"created_at":"2024-09-25T00:55:37.729Z","updated_at":"2025-04-10T13:34:40.058Z","avatar_url":"https://github.com/paduszyk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django-xlsx-serializer\n\n[![PyPI: Version](https://img.shields.io/pypi/v/django-xlsx-serializer?style=flat-square\u0026logo=pypi\u0026logoColor=white)][pypi]\n[![PyPI: Python](https://img.shields.io/pypi/pyversions/django-xlsx-serializer?style=flat-square\u0026logo=python\u0026logoColor=white)][pypi]\n[![PyPI: Django](https://img.shields.io/pypi/djversions/django-xlsx-serializer?style=flat-square\u0026color=0C4B33\u0026label=django\u0026logo=django)][pypi]\n[![PyPI: License](https://img.shields.io/pypi/l/django-xlsx-serializer?style=flat-square)][pypi]\n\n[![Pre-commit](https://img.shields.io/github/actions/workflow/status/paduszyk/django-xlsx-serializer/pre-commit-run.yml?style=flat-square\u0026label=pre-commit\u0026logo=pre-commit)][pre-commit]\n[![Python: CI](https://img.shields.io/github/actions/workflow/status/paduszyk/django-xlsx-serializer/python-ci.yml?style=flat-square\u0026logo=github\u0026label=CI)][python-ci]\n[![Codecov](https://img.shields.io/codecov/c/github/paduszyk/django-xlsx-serializer?style=flat-square\u0026logo=codecov)][codecov]\n\n[![Nox](https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg?style=flat-square)][nox]\n[![Ruff](https://img.shields.io/endpoint?style=flat-square\u0026url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)][ruff]\n[![Mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square\u0026logo=python)][mypy]\n[![Prettier](https://img.shields.io/badge/code%20style-prettier-1E2B33?style=flat-square\u0026logo=Prettier)][prettier]\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fa6673.svg?style=flat-square\u0026logo=conventional-commits)][conventional-commits]\n\n## Overview\n\n`django-xlsx-serializer` is a [Django][django] application designed to handle\nthe data serialization and deserialization between Django models and Microsoft\nExcel 2007+ workbooks. Utilizing the [OpenPyXL][openpyxl] engine, this tool\nprovides robust methods to export data from Django databases into XLSX files and\nimport data from the files back into the databases. This functionality is\nessential for applications that require data exchange between Django-based\nsystems and Excel, facilitating such tasks as data migration, reporting, and\nbackups.\n\n## Features\n\nThe app allows you to:\n\n- Export Django models from a database to an Excel workbook via the\n  [`dumpdata`][django-dumpdata] command.\n- Populate databases from Excel fixtures using the [`loaddata`][django-loaddata]\n  command.\n- Interact with Excel workbooks (either files or `openpyxl.Workbook` objects)\n  and the database using the Django's core [serialization][django-serialization]\n  utilities.\n\n## Requirements\n\n| Python | Django                       | Database engines    |\n| :----- | :--------------------------- | :------------------ |\n| 3.9    | 3.2, 4.0, 4.1, 4.2           | SQLite3, PostgreSQL |\n| 3.10   | 3.2, 4.0, 4.1, 4.2, 5.0, 5.1 | SQLite3, PostgreSQL |\n| 3.11   | 4.1, 4.2, 5.0, 5.1           | SQLite3, PostgreSQL |\n| 3.12   | 4.2, 5.0, 5.1                | SQLite3, PostgreSQL |\n\nAll setups require OpenPyXL \u003c 4.\n\n## Installation\n\nThe fastest way to add the package to your Python environment is to download and\ninstall it directly from [PyPI][pypi]. Use `pip`:\n\n```console\npip install django-xlsx-serializer\n```\n\nor any other dependency manager of your preference.\n\nAs soon as the installation is completed, all the app's functionalities can be\naccessed from the `xlsx_serializer` module:\n\n```python\nimport xlsx_serializer\n```\n\n\u003e The app is compatible with Excel 2007+ XLSX workbooks only. Adding support for\n\u003e the older XLS format is not planned.\n\n## Django Configuration\n\nThe app utilities can be incorporated into your Django project by following one\nof the approaches listed below:\n\n1. Installing the package as an app.\n2. Adding the package to serialization modules.\n3. Registering the app's serializers module from another app.\n\nAll of them associate the app's serializer with the `xlsx` format.\n\n### Install as an App\n\nIn your project settings module add `xlsx_serializers` to `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n    # ...\n    \"xlsx_serializer\",\n    # ...\n]\n```\n\n### Add to Serialization Modules\n\nIn your project settings module update the `SERIALIZATION_MODULES` dictionary:\n\n```python\nSERIALIZATION_MODULES = {\n    # ...\n    \"xlsx\": \"xlsx_serializer\",\n    # ...\n}\n```\n\n### Register from Another App\n\nIn any of the apps installed in your projects (let us call it `myapp`), register\nthe `xlsx_serializer` manually in the app's `ready` hook:\n\n```python\n# myapp/apps.py\n\nfrom django.apps import AppConfig\nfrom django.core import serializers\n\n\nclass MyAppConfig(AppConfig):\n    name = \"myapp\"\n\n    def ready(self) -\u003e None:\n        super().ready()\n\n        # ...\n\n        # Register serializers.\n        serializers.register_serializer(\"xlsx\", \"xlsx_serializer\")\n```\n\n\u003e There are many Django projects using a \"core\" app for defining project-wide\n\u003e utilities (e.g., custom commands, template tags, etc.). The configuration\n\u003e class of such an app is a good place to apply the code snippet above.\n\n## Usage\n\n### Excel Workbooks vs. Django Models\n\nThe app adopts quite intuitive correspondence between Excel workbooks (i.e., the\ncollections of worksheets) and Django models:\n\n- A Django model is represented by a single worksheet.\n- In an Excel workbook, the models are identified by worksheet names.\n- Within an Excel worksheet, model instances are represented by rows, while the\n  columns correspond to the model's fields.\n\n### Serialization\n\nSerialization can be run either by the built-in [`dumpdata`][django-dumpdata]\nDjango management command:\n\n```console\npython manage.py dumpdata --format xlsx --output dump.xlsx\n```\n\nor from Django interactive shell:\n\n```python\n\u003e\u003e\u003e from django.core import serializers\n\u003e\u003e\u003e from polls.models import Question\n\u003e\u003e\u003e serializers.serialize(\"xlsx\", Question.objects.all(), output=\"dump.xlsx\")\n# Prints: \u003copenpyxl.workbook.workbook.Workbook object at ...\u003e\n```\n\nBoth the command and expression shown above save `dump.xlsx` workbook file. The\nlatter additionally returns an `openpyxl.Workbook` object, which can be used\nlater if necessary (e.g., in development or maintenance scripts).\n\nWhen serializing, the app creates worksheets named using fully qualified model\nlabels. For example, the `Question` model defined in the `polls` app is\nserialized to the \"polls.Question\" worksheet. Excel does not accept worksheet\nnames longer than 31 characters. If the model's label is longer, it's truncated.\nA useful feature allowing you to circumvent this issue is that the output\nworksheet names can be customized using the `model_sheet_names` option. So, the\ncommand:\n\n```python\n\u003e\u003e\u003e workbook = serialize(\n        \"xlsx\",\n        Question.objects.all(),\n        model_sheet_names={\"polls.Question\": \"Questions\"},\n    )\n\u003e\u003e\u003e workbook\n# Prints: \u003copenpyxl.workbook.workbook.Workbook object at ...\u003e\n```\n\nresults in the `polls.Question` model data serialized in the \"Questions\"\nworksheet. Note that this option is not available when using the app via the\n`dumpdata` command.\n\n\u003e The app inspects each key and value of the `model_sheet_names` dictionary. For\n\u003e the keys, it validates whether they represent valid model identifiers. The\n\u003e values, in turn, are checked to see if they are unique, are not too long, and\n\u003e do not contain invalid characters (`?`, `*`, `:`, `\\`, `/`, `[`, `]`).\n\nOther key points:\n\n- `DateField`, `DateTimeField`, and `TimeField` values are serialized as\n  ISO 8601 strings.\n- `JSONField` values are serialized as JSON strings returned by the respective\n  field's encoders.\n- `ManyToManyField` values are serialized as stringified lists of foreign keys.\n- The app supports serialization by using natural keys. If it is triggered (by\n  applying the `--natural-primary`/`--natural-foreign` flags), the natural keys\n  are serialized as stringified tuples (or their lists in the case of\n  many-to-many relations).\n\n### Deserialization\n\nThe recommended way of employing the app to load the model data from an Excel\nfixture to the database is to call it via the [`loaddata`][django-loaddata]\ncommand:\n\n```console\npython manage.py loaddata fixture.xlsx\n```\n\nDeserialization requires the input workbook's worksheets to have names that are\neither the fully qualified labels or model names (case-insensitive). The latter\ncan be applied if the model name is unique. For example, if the project uses\nmodels `polls.Question` and `exams.Question`, the worksheet named \"Question\"\nwill not be deserialized.\n\nWithin a worksheet, ensure that the column headers correspond to the field names\nof the respective model. The app ignores a column if it does not represent\na field. Empty rows and columns surrounding the data range are ignored as well.\nHowever, the app does not check the data for the missing or invalid values.\n\nOther key points:\n\n- Populating `DateField`, `DateTimeField`, and `TimeField` with timezone support\n  enabled in Django settings requires date/time values to be saved as ISO 8601\n  strings (date/time type values in Excel don't store timezone information).\n- Deserializing `JSONfield` requires values in a format compatible with the JSON\n  decoder of the respective field.\n- In the case of `ManyToManyField` provide string representations of Python\n  lists containing the primary (or natural, see the next bullet) keys of the\n  related objects.\n- The app handles deserialization from natural keys by using `ast.literal_eval`.\n  Make sure to provide the keys that are valid string representations of the\n  corresponding values (i.e., tuples of primitive Python literals; in most\n  cases, they are strings \u0026mdash; if so, use single quotes as text delimiters).\n\n## Contributing\n\nThis is an open-source project that embraces contributions of all types. We\nrequire all contributors to adhere to our [Code of Conduct][code-of-conduct].\nFor comprehensive instructions on how to contribute to the project, please refer\nto our [Contributing Guide][contributing].\n\n## Authors\n\nCreated and maintained by Kamil Paduszyński ([@paduszyk][paduszyk]).\n\n## License\n\nReleased under the [MIT license][license].\n\n[code-of-conduct]: https://github.com/paduszyk/django-xlsx-serializer/blob/main/docs/CODE_OF_CONDUCT.md\n[codecov]: https://app.codecov.io/gh/paduszyk/django-xlsx-serializer\n[contributing]: https://github.com/paduszyk/django-xlsx-serializer/blob/main/docs/CONTRIBUTING.md\n[conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/\n[django-dumpdata]: https://docs.djangoproject.com/en/5.0/ref/django-admin/#dumpdata\n[django-loaddata]: https://docs.djangoproject.com/en/5.0/ref/django-admin/#loaddata\n[django-serialization]: https://docs.djangoproject.com/en/5.0/topics/serialization/\n[django]: https://www.djangoproject.com\n[license]: https://github.com/paduszyk/django-xlsx-serializer/blob/main/LICENSE\n[mypy]: https://mypy.readthedocs.io\n[nox]: https://github.com/wntrblm/nox\n[openpyxl]: https://openpyxl.readthedocs.io/en/stable/\n[paduszyk]: https://github.com/paduszyk\n[pre-commit]: https://github.com/paduszyk/django-xlsx-serializer/actions/workflows/pre-commit-run.yml\n[prettier]: https://prettier.io\n[pypi]: https://pypi.org/project/django-xlsx-serializer/\n[python-ci]: https://github.com/paduszyk/django-xlsx-serializer/actions/workflows/python-ci.yml\n[ruff]: https://docs.astral.sh/ruff/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaduszyk%2Fdjango-xlsx-serializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaduszyk%2Fdjango-xlsx-serializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaduszyk%2Fdjango-xlsx-serializer/lists"}