Skip to main content

A simple package to convert a Django QuerySet to a CSV file through an HttpResponse object.

Project description

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

pip install django-qs2csv

Full

pip install django-qs2csv[pd]

Note: this will install pandas, 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

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:

...

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 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 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 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 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 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 file for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_qs2csv-0.3.5.tar.gz (7.8 kB view details)

Uploaded Source

Built Distribution

django_qs2csv-0.3.5-py3-none-any.whl (8.4 kB view details)

Uploaded Python 3

File details

Details for the file django_qs2csv-0.3.5.tar.gz.

File metadata

  • Download URL: django_qs2csv-0.3.5.tar.gz
  • Upload date:
  • Size: 7.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.3

File hashes

Hashes for django_qs2csv-0.3.5.tar.gz
Algorithm Hash digest
SHA256 59bd3a62b302ef40e151f78d9517bc37e9ac8ef3a6c503bb693bbd0f64128136
MD5 08d055fceb728fd648c738c62df07da8
BLAKE2b-256 cd0dcd8b5f9d11519ce65c9a8acc65cb1d9f8039060b27c541f4b51b07b72ad3

See more details on using hashes here.

File details

Details for the file django_qs2csv-0.3.5-py3-none-any.whl.

File metadata

File hashes

Hashes for django_qs2csv-0.3.5-py3-none-any.whl
Algorithm Hash digest
SHA256 02710373cd097928547f60f85cbcdb55e7ae5dbc73bcee573fbc55af4a027aef
MD5 4df38dced5170fc2e49cac0e92d5fe6b
BLAKE2b-256 67522fd55b9fd76348c466c736a1699175790375636f46c28cc54322d5efbc70

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page