{"id":27976387,"url":"https://github.com/litestar-org/litestar-django","last_synced_at":"2025-08-09T01:53:00.481Z","repository":{"id":291718909,"uuid":"976797172","full_name":"litestar-org/litestar-django","owner":"litestar-org","description":"Django model support for Litestar.","archived":false,"fork":false,"pushed_at":"2025-05-19T12:33:15.000Z","size":200,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-08T09:07:59.668Z","etag":null,"topics":["django","litestar","openapi"],"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/litestar-org.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,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["litestar-org"],"open_collective":"litestar","polar":"litestar-org"}},"created_at":"2025-05-02T19:10:37.000Z","updated_at":"2025-06-03T23:00:33.000Z","dependencies_parsed_at":"2025-06-07T11:07:54.834Z","dependency_job_id":"a160d6bd-0941-42b0-b7bc-ac97d2e7c23b","html_url":"https://github.com/litestar-org/litestar-django","commit_stats":null,"previous_names":["litestar-org/litestar-django"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/litestar-org/litestar-django","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-django","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-django/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-django/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-django/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/litestar-org","download_url":"https://codeload.github.com/litestar-org/litestar-django/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-django/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269518567,"owners_count":24430637,"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","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","litestar","openapi"],"created_at":"2025-05-08T01:26:07.645Z","updated_at":"2025-08-09T01:53:00.469Z","avatar_url":"https://github.com/litestar-org.png","language":"Python","funding_links":["https://github.com/sponsors/litestar-org","https://opencollective.com/litestar","https://polar.sh/litestar-org"],"categories":[],"sub_categories":[],"readme":"# Litestar-Django\n\nDjango model support for Litestar, implemented via Litestar [DTOs](https://docs.litestar.dev/latest/usage/dto/index.html).\n\n```python\nfrom litestar import get, Litestar\nfrom litestar_django import DjangoModelPlugin\nfrom django.db import models\n\nclass Author(models.Model):\n    name = models.CharField(max_length=100)\n\n\nclass Genre(models.Model):\n    name = models.CharField(max_length=50)\n\n\nclass Book(models.Model):\n    name = models.CharField()\n    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name=\"books\")\n    genres = models.ManyToManyField(Genre, related_name=\"books\")\n\n\n@get(\"/{author_id:int}\")\nasync def handler(author_id: int) -\u003e Author:\n    return await Author.objects.prefetch_related(\"books\").aget(id=author_id)\n\n\napp = Litestar([handler], plugins=[DjangoModelPlugin()])\n```\n\nThis minimal setup will provide serialization of Django objects returned from handlers,\ncomplete with OpenAPI schema generation.\n\n## Installation\n\n```bash\npip install litestar-django\n```\n\n## Usage\n\n### Directly constructing a DTO\n\n```python\nfrom litestar import get\nfrom litestar_django import DjangoModelDTO\nfrom app.models import Author\n\n@get(\"/{author_id:int}\", dto=DjangoModelDTO[Author])\nasync def handler(author_id: int) -\u003e Author:\n    return await Author.objects.prefetch_related(\"books\").aget(id=author_id)\n```\n\n### Automatically creating DTOs via the plugin\n\n```python\nfrom litestar import get\nfrom litestar_django import DjangoModelPlugin\nfrom app.models import Author\n\n@get(\"/{author_id:int}\")\nasync def handler(author_id: int) -\u003e Author:\n    return await Author.objects.prefetch_related(\"books\").aget(id=author_id)\n\napp = Litestar([handler], plugins=[DjangoModelPlugin()])\n```\n\n### Creating a model instance from a DTO\n\n```python\nfrom typing import Annotated\nfrom litestar import post\nfrom litestar.dto import DTOConfig\nfrom litestar_django import DjangoModelDTO\nfrom app.models import Author\n\n@post(\n    \"/\",\n    sync_to_thread=True,\n    dto=DjangoModelDTO[\n       Annotated[\n          Author,\n          # exclude primary key and relationship fields\n          DTOConfig(exclude={\"id\", \"books\"})\n       ]\n    ],\n    return_dto=DjangoModelDTO[Author],\n)\nasync def handler(data: Author) -\u003e Author:\n    await data.asave()\n    return data\n```\n\n## OpenAPI\n\nFull OpenAPI schemas are generated from models based on their field types:\n\n### Type map\n\n| Field                  | OpenAPI type | OpenAPI format |\n|------------------------|--------------|----------------|\n| `models.JSONField`     | `{}`         |                |\n| `models.DecimalField`  | `number`     |                |\n| `models.DateTimeField` | `string`     | `date-time`    |\n| `models.DateField`     | `string`     | `date`         |\n| `models.TimeField`     | `string`     | `duration`     |\n| `models.DurationField` | `string`     | `duration`     |\n| `models.FileField`     | `string`     |                |\n| `models.FilePathField` | `string`     |                |\n| `models.UUIDField`     | `string`     | `uuid`         |\n| `models.IntegerField`  | `integer`    |                |\n| `models.FloatField`    | `number`     |                |\n| `models.BooleanField`  | `boolean`    |                |\n| `models.CharField`     | `string`     |                |\n| `models.TextField`     | `string`     |                |\n| `models.BinaryField`   | `string`     | `byte`         |\n\n### Additional properties\n\nThe following properties are extracted from fields, in addition to its type:\n\n\n| OpenAPI property   | From                 |\n|--------------------|----------------------|\n| `title`            | `Field.verbose_name` |\n| `description`      | `Field.help_text`    |\n| `enum`             | `Field.choices`      |\n| `exclusiveMinimum` | `MinValueValidator`  |\n| `exclusiveMaximum` | `MaxValueValidator`  |\n| `minLength`        | `MinLengthValidator` |\n| `maxLength`        | `MaxLengthValidator` |\n\n### Relationships\n\nRelationships will be represented as individual components, referenced in the schema.\n\n\n## Lazy loading\n\n\u003e [!IMPORTANT]\n\u003e Since lazy-loading is not supported in an async context, you must ensure to always\n\u003e load everything consumed by the DTO. Not doing so will result in a\n\u003e [`SynchronousOnlyOperation`](https://docs.djangoproject.com/en/5.2/ref/exceptions/#django.core.exceptions.SynchronousOnlyOperation)\n\u003e exception being raised by Django\n\nThis can be mitigated by:\n\n1. Setting `include` or `exclude` rules to only include necessary fields ([docs](https://docs.litestar.dev/latest/usage/dto/1-abstract-dto.html#excluding-fields))\n2. Configuring nested relationships with an appropriate `max_nexted_depth`\n   ([docs](https://docs.litestar.dev/latest/usage/dto/1-abstract-dto.html#nested-fields))\n3. Using [`select_related`](https://docs.djangoproject.com/en/5.2/ref/models/querysets/#select-related)\n   and [`prefetch_related`](https://docs.djangoproject.com/en/5.2/ref/models/querysets/#prefetch-related)\n   to ensure relationships are fully loaded\n\n## Foreign keys\n\nWhen defining a `ForeignKey` field, Django will implicitly generate another field on the\nmodel with an `_id` suffix, to store the actual foreign key value. The DTO will include\nthese implicit fields.\n\n```python\nclass Author(models.Model):\n    name = models.CharField(max_length=100)\n\nclass Book(models.Model):\n    name = models.CharField(max_length=100)\n    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name=\"books\")\n```\n\nIn this example, the DTO for `Book` includes the field definitions\n- `id: int`\n- `name: str`\n- `author_id: int`\n- `author: Author`\n\n\n## Serialization / validation of 3rd party field types\n\nAdditionally, the following 3rd party fields / types are supported if the\n`DjangoModelPlugin` is installed:\n\n- `django-enumfields`\n- `django-enumfields2`\n\n\n## Contributing\n\nAll [Litestar Organization][litestar-org] projects are open for contributions of any\nsize and form.\n\nIf you have any questions, reach out to us on [Discord][discord] or our org-wide\n[GitHub discussions][litestar-discussions] page.\n\n\u003c!-- markdownlint-disable --\u003e\n\u003chr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003c!-- github-banner-start --\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/litestar-org/branding/main/assets/Branding%20-%20SVG%20-%20Transparent/Organization%20Project%20-%20Banner%20-%20Inline%20-%20Dark.svg\" alt=\"Litestar Logo - Light\" width=\"40%\" height=\"auto\" /\u003e\n  \u003cbr\u003eAn official \u003ca href=\"https://github.com/litestar-org\"\u003eLitestar Organization\u003c/a\u003e Project\n  \u003c!-- github-banner-end --\u003e\n\u003c/p\u003e\n\n[litestar-org]: https://github.com/litestar-org\n[discord]: https://discord.gg/litestar\n[litestar-discussions]: https://github.com/orgs/litestar-org/discussions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitestar-org%2Flitestar-django","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flitestar-org%2Flitestar-django","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitestar-org%2Flitestar-django/lists"}