# django-qs2csv
A simple package to convert a Django QuerySet to a CSV file through an HttpResponse object.
## Getting started
### Prerequisites
* Python >= 3.9
* Django >= 3.2
### Optional Dependencies
* pandas >= 1.5
### Installation
Recommended
```console
pip install django-qs2csv
```
Full
```console
pip install django-qs2csv[pd]
```
Note: this will install [pandas](https://pandas.pydata.org/), which is used with ``queryset_to_csv_pd()``. It is not recommended to install the pandas library unless you will use this function or already use pandas. Using ``queryset_to_csv_pd()`` will likely increase the export speed of large QuerySets (2M+ results) and decrease file size for all QuerySets.
## Usage
views.py
```python
from qs2csv import qs_to_csv
from .models import SampleModel
...
def export_csv(request):
...
my_queryset = SampleModel.objects.all()
response = qs_to_csv(
my_queryset,
filename="all_sample_models",
)
return response
```
### Return type
All functions return a `django.http.HttpResponse` with the `Content-Type` and `Content-Disposition` headers. Additional headers can be added to the response before returning:
```python
...
response = qs_to_csv(my_queryset)
response["Another-Header"] = "This is another header for the HttpResponse."
...
```
### Parameters
#### Universal
`qs : QuerySet` - **Required**. The QuerySet to be exported as a CSV file. This can be passed as QuerySet\[object], QuerySet\[dict] (values()), or QuerySet\[list\[tuple]] (values_list()). See the note in the [Limitations](#limitations) about QuerySet evaluation.
`filename : str` - The name of the exported CSV file. You do not need to include .csv, it will be added once the filename is evaluated. File names can not end in a period, include the symbols (< > : " / \\ | ? *), or be longer than 251 characters (255 w/ ".csv"). **Default: "export"**
`only : list[str]` - List the field names that you would like to include in the exported file. An empty list will include all fields, other than those in `defer`. Field names listed in both `only` and `defer` will not be included. See the note in the [Limitations](#limitations) section for details how this works with a QuerySet that calls only(), defer(), values(), or values_list(). **Default: []**
`defer : list[str]` - List the field names that you do not want to include in the exported file. An empty list will include all fields, or just those mentioned in `only`. Field names listed in both `only` and `defer` will not be included. See the note in the [Limitations](#limitations) section for details how this works with a QuerySet that calls only(), defer(), values(), or values_list(). **Default: []**
`header : bool` - Include a header row with field names. **Default: False**
`verbose : bool` - Determine if the header row uses the fields' `verbose_name` or just the field names. This only applies when `header=True`. **Default: True**
#### qs_to_csv() and qs_to_csv_pd()
`values : bool` - Only enable this if your QuerySet was already evaluated (no longer lazy) and called values(). You must ensure your fields are properly selected in the original QuerySet, because this will skip applying the `only` and `defer` parameters. **Default: False**
#### qs_to_csv_rel_str()
`values : bool` - Only enable this if the QuerySet is passed to the function after calling values() or values_list(). This will convert the QuerySet back to a list of model objects, instead of a list of dicts/lists. See note in [Limitations](#limitations) for an _IMPORTANT WARNING_ about performance. **Default: False**
### Limitations
If the QuerySet was already evaluated before being passed to `qs_to_csv` then it will be re-evaluated by the function. Depending on the size of the QuerySet, complexity of the query and the database setup, this may add a noticeable delay. It is recommended to monitor the impact of database queries using `django.db.connection.queries` or [django-debug-toolbar](https://django-debug-toolbar.readthedocs.io/en/latest/index.html) during development. If the QuerySet must be evaluated before the function is called, it would be most efficient to use values() with the QuerySet (if possible) then pass `values=True` to `qs_to_csv`.
If your QuerySet uses only() / defer() then you must include those same fields in the `only` / `defer` parameters when calling `qs_to_csv`. The function transforms all QuerySets into a list of dicts using values(), which is incompatible with only() and defer().
`ForeignKey` and `OneToOneField` will always return the primary key, because the function uses `values()`.
`ManyToManyField` is not supported.
Passing ``values=True`` to ``qs_to_csv_rel_str()`` will create a new query, checking for primary keys (PKs) that are in a list of all PKs from your original QuerySet. **This will add significant time if your QuerySet is large and will potentially not work**, depending on the size of your QuerySet and your database's capabilities. It is recommended to avoid this by not using values() or values_list() when calling this function. It would be more efficient to create a brand new QuerySet than to do use this. Note: if you make this change, ensure `values` is False or the issue will remain.
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-qs2csv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "django, csv, export, httpresponse, http response, pandas",
"author": null,
"author_email": "Jer-Pha <pharesoft@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/0d/cd8b5f9d11519ce65c9a8acc65cb1d9f8039060b27c541f4b51b07b72ad3/django_qs2csv-0.3.5.tar.gz",
"platform": null,
"description": "# django-qs2csv\r\n\r\nA simple package to convert a Django QuerySet to a CSV file through an HttpResponse object.\r\n\r\n## Getting started\r\n\r\n### Prerequisites\r\n\r\n* Python >= 3.9\r\n* Django >= 3.2\r\n\r\n### Optional Dependencies\r\n\r\n* pandas >= 1.5\r\n\r\n### Installation\r\n\r\nRecommended\r\n```console\r\npip install django-qs2csv\r\n```\r\n\r\nFull\r\n```console\r\npip install django-qs2csv[pd]\r\n```\r\nNote: this will install [pandas](https://pandas.pydata.org/), which is used with ``queryset_to_csv_pd()``. It is not recommended to install the pandas library unless you will use this function or already use pandas. Using ``queryset_to_csv_pd()`` will likely increase the export speed of large QuerySets (2M+ results) and decrease file size for all QuerySets.\r\n\r\n## Usage\r\n\r\nviews.py\r\n\r\n```python\r\nfrom qs2csv import qs_to_csv\r\n\r\nfrom .models import SampleModel\r\n\r\n...\r\n\r\ndef export_csv(request):\r\n ...\r\n\r\n my_queryset = SampleModel.objects.all()\r\n\r\n response = qs_to_csv(\r\n my_queryset,\r\n filename=\"all_sample_models\",\r\n )\r\n\r\n return response\r\n```\r\n\r\n### Return type\r\n\r\nAll functions return a `django.http.HttpResponse` with the `Content-Type` and `Content-Disposition` headers. Additional headers can be added to the response before returning:\r\n\r\n```python\r\n...\r\n\r\nresponse = qs_to_csv(my_queryset)\r\nresponse[\"Another-Header\"] = \"This is another header for the HttpResponse.\"\r\n\r\n...\r\n```\r\n\r\n### Parameters\r\n\r\n#### Universal\r\n\r\n`qs : QuerySet` - **Required**. The QuerySet to be exported as a CSV file. This can be passed as QuerySet\\[object], QuerySet\\[dict] (values()), or QuerySet\\[list\\[tuple]] (values_list()). See the note in the [Limitations](#limitations) about QuerySet evaluation.\r\n\r\n`filename : str` - The name of the exported CSV file. You do not need to include .csv, it will be added once the filename is evaluated. File names can not end in a period, include the symbols (< > : \" / \\\\ | ? *), or be longer than 251 characters (255 w/ \".csv\"). **Default: \"export\"**\r\n\r\n`only : list[str]` - List the field names that you would like to include in the exported file. An empty list will include all fields, other than those in `defer`. Field names listed in both `only` and `defer` will not be included. See the note in the [Limitations](#limitations) section for details how this works with a QuerySet that calls only(), defer(), values(), or values_list(). **Default: []**\r\n\r\n`defer : list[str]` - List the field names that you do not want to include in the exported file. An empty list will include all fields, or just those mentioned in `only`. Field names listed in both `only` and `defer` will not be included. See the note in the [Limitations](#limitations) section for details how this works with a QuerySet that calls only(), defer(), values(), or values_list(). **Default: []**\r\n\r\n`header : bool` - Include a header row with field names. **Default: False**\r\n\r\n`verbose : bool` - Determine if the header row uses the fields' `verbose_name` or just the field names. This only applies when `header=True`. **Default: True**\r\n\r\n#### qs_to_csv() and qs_to_csv_pd()\r\n\r\n`values : bool` - Only enable this if your QuerySet was already evaluated (no longer lazy) and called values(). You must ensure your fields are properly selected in the original QuerySet, because this will skip applying the `only` and `defer` parameters. **Default: False**\r\n\r\n#### qs_to_csv_rel_str()\r\n`values : bool` - Only enable this if the QuerySet is passed to the function after calling values() or values_list(). This will convert the QuerySet back to a list of model objects, instead of a list of dicts/lists. See note in [Limitations](#limitations) for an _IMPORTANT WARNING_ about performance. **Default: False**\r\n\r\n### Limitations\r\n\r\nIf the QuerySet was already evaluated before being passed to `qs_to_csv` then it will be re-evaluated by the function. Depending on the size of the QuerySet, complexity of the query and the database setup, this may add a noticeable delay. It is recommended to monitor the impact of database queries using `django.db.connection.queries` or [django-debug-toolbar](https://django-debug-toolbar.readthedocs.io/en/latest/index.html) during development. If the QuerySet must be evaluated before the function is called, it would be most efficient to use values() with the QuerySet (if possible) then pass `values=True` to `qs_to_csv`.\r\n\r\nIf your QuerySet uses only() / defer() then you must include those same fields in the `only` / `defer` parameters when calling `qs_to_csv`. The function transforms all QuerySets into a list of dicts using values(), which is incompatible with only() and defer().\r\n\r\n`ForeignKey` and `OneToOneField` will always return the primary key, because the function uses `values()`.\r\n\r\n`ManyToManyField` is not supported.\r\n\r\nPassing ``values=True`` to ``qs_to_csv_rel_str()`` will create a new query, checking for primary keys (PKs) that are in a list of all PKs from your original QuerySet. **This will add significant time if your QuerySet is large and will potentially not work**, depending on the size of your QuerySet and your database's capabilities. It is recommended to avoid this by not using values() or values_list() when calling this function. It would be more efficient to create a brand new QuerySet than to do use this. Note: if you make this change, ensure `values` is False or the issue will remain.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple package to convert a Django QuerySet to a CSV file through an HttpResponse object.",
"version": "0.3.5",
"project_urls": {
"Homepage": "https://github.com/Jer-Pha/django-qs2csv",
"Issues": "https://github.com/Jer-Pha/django-qs2csv/issues"
},
"split_keywords": [
"django",
" csv",
" export",
" httpresponse",
" http response",
" pandas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "67522fd55b9fd76348c466c736a1699175790375636f46c28cc54322d5efbc70",
"md5": "4df38dced5170fc2e49cac0e92d5fe6b",
"sha256": "02710373cd097928547f60f85cbcdb55e7ae5dbc73bcee573fbc55af4a027aef"
},
"downloads": -1,
"filename": "django_qs2csv-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4df38dced5170fc2e49cac0e92d5fe6b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8362,
"upload_time": "2024-06-09T03:54:01",
"upload_time_iso_8601": "2024-06-09T03:54:01.025153Z",
"url": "https://files.pythonhosted.org/packages/67/52/2fd55b9fd76348c466c736a1699175790375636f46c28cc54322d5efbc70/django_qs2csv-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd0dcd8b5f9d11519ce65c9a8acc65cb1d9f8039060b27c541f4b51b07b72ad3",
"md5": "08d055fceb728fd648c738c62df07da8",
"sha256": "59bd3a62b302ef40e151f78d9517bc37e9ac8ef3a6c503bb693bbd0f64128136"
},
"downloads": -1,
"filename": "django_qs2csv-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "08d055fceb728fd648c738c62df07da8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7808,
"upload_time": "2024-06-09T03:54:02",
"upload_time_iso_8601": "2024-06-09T03:54:02.877975Z",
"url": "https://files.pythonhosted.org/packages/cd/0d/cd8b5f9d11519ce65c9a8acc65cb1d9f8039060b27c541f4b51b07b72ad3/django_qs2csv-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-09 03:54:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jer-Pha",
"github_project": "django-qs2csv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"3.2"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.5"
]
]
},
{
"name": "coverage",
"specs": [
[
">=",
"7.5"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"24.4"
]
]
},
{
"name": "pre-commit",
"specs": [
[
">=",
"3.7"
]
]
},
{
"name": "tox",
"specs": [
[
">=",
"4.0"
]
]
}
],
"tox": true,
"lcname": "django-qs2csv"
}
JSON
