# django-typomatic 
_A simple solution for generating Typescript interfaces from your [Django Rest Framework Serializers](https://www.django-rest-framework.org/api-guide/serializers/)._
Since I now require a simple package to generate Typescript interfaces for Django Rest Framework serializers, I've decided to port over my [Typemallow](https://github.com/adenh93/typemallow/) package for use with DRF serializers!
## Usage:
_Using django-typomatic is just as simple!_
First, install the package
`pip install django-typomatic`
### Option 1: Decorators
For your Django Rest Framework serializers that you wish to generate Typescript interfaces for, simply import `ts_interface` and `generate_ts` from the `django_typomatic` module, and add the `@ts_interface()` class decorator to your Django Rest Framework serializer class.
All that is required to generate your Typescript interfaces is to call the `generate_ts()` function, and provide a filepath as a parameter to output the result.
_main.py_
```python
from django_typomatic import ts_interface, generate_ts
from rest_framework import serializers
@ts_interface()
class Foo(serializers.Serializer):
some_field = serializers.CharField()
another_field = serializers.DateTimeField()
generate_ts('./output.ts')
```
_output.ts_
```typescript
export interface Foo {
some_field: string;
another_field: date;
}
```
Alternatively, you can call `get_ts()`, which will return the generated interfaces as a raw string, rather than writing the results to a file:
_main.py_
```python
from django_typomatic import ts_interface, get_ts
from rest_framework import serializers
@ts_interface()
class Foo(serializers.Serializer):
some_field = serializers.ListField(child=serializers.IntegerField())
another_field = serializers.CharField()
print(get_ts())
```
which outputs the following string:
`export interface Foo {\n some_field: number[];\n another_field: string;\n}\n\n`
_django-typomatic_ supports nested serializers, as well as list fields and other fields that act as lists (any field with many=True)
_main.py_
```python
from django_typomatic import ts_interface, generate_ts
from rest_framework import serializers
@ts_interface()
class Foo(serializers.Serializer):
some_field = serializers.ListField(child=serializers.IntegerField())
another_field = serializers.CharField()
@ts_interface()
class Bar(serializers.Serializer):
foo = Foo()
foos = Foo(many=True)
bar_field = serializers.CharField()
```
_output.ts_
```typescript
export interface Foo {
some_field: number[];
another_field: string;
}
export interface Bar {
foo: Foo;
foos: Foo[];
bar_field: string;
}
```
_django-typomatic_ also supports ChoiceField serializers, as well as any other serializer fields that makes use of choices.
_main.py_
```python
from django_typomatic import ts_interface
from rest_framework import serializers
from django.db import models
class ActionType(models.TextChoices):
ACTION1 = "Action1", ("Action1")
ACTION2 = "Action2", ("Action2")
ACTION3 = "Action3", ("Action3")
class NumberType(models.IntegerChoices):
LOW = 1
MEDIUM = 2
HIGH = 3
@ts_interface('choices')
class ChoiceSerializer(serializers.Serializer):
action = serializers.ChoiceField(choices=ActionType.choices)
num = serializers.ChoiceField(choices=NumberType.choices)
```
_output.ts_
```typescript
export interface ActionSerializer {
action: "Action1" | "Action2" | "Action3";
num: 1 | 2 | 3;
}
```
#### Extended Usage:
The `@ts_interface()` decorator function accepts an optional parameter, _context_, which defaults to... well... 'default'.
"_Why is this the case?_"
When a Serializer is identified with with `@ts_interface` decorator, it is added to a list in a dictionary of serializers, with the dictionary key being the value provided to the _context_ parameter. If you were to provide different contexts for each serializer, additional keys will be created if they do not exist, or the serializer will simply be appended to the list at the existing key.
This comes in handy, as the `generate_ts()` function _also_ accepts an optional _context_ parameter, which will filter only serializers in the dictionary at the specific key.
This is useful if you wish to output different contexts to different files, e.g.
_main.py_
```python
...
from django_typomatic import ts_interface, generate_ts
from rest_framework import serializers
@ts_interface(context='internal')
class Foo(serializers.Serializer):
foo = serializers.CharField()
@ts_interface(context='internal')
class Bar(serializers.Serializer):
bar = serializers.CharField()
@ts_interface(context='external')
class FooBar(serializers.Serializer):
foo_bar = serializers.CharField()
'''
we're telling django-typomatic that we only want to generate interfaces from serializers with
an 'internal' context to './internal.ts'
'''
generate_ts('./internal.ts', context='internal')
'''
only generate interfaces from serializers with an 'external' context to './external.ts'
'''
generate_ts('./external.ts', context='external')
```
_internal.ts_
```typescript
export interface Foo {
foo: string;
}
export interface Bar {
bar: string;
}
```
_external.ts_
```typescript
export interface FooBar {
foo_bar: string;
}
```
#### Camelize
You can use django dependencies that converts the response from `snake_casing` to `camelCasing`. The solution offered for this is camelize:
```python
from django_typomatic import ts_interface, generate_ts
from rest_framework import serializers
@ts_interface()
class Foo(serializers.Serializer):
some_field = serializers.CharField()
generate_ts('./output.ts', camelize=True)
```
Different from the main example. The interface attributes are now camel casing.
_output.ts_
```typescript
export interface Foo {
someField: string;
}
```
#### TypeScript enums from ChoiceFields
_django-typomatic_ also allows for generating an `enum` for a ChoiceField. The `enum` will follow the naming of `ModelFieldNameChoiceEnum` for a model field with the name `model_field_name`, note that the interface field still remains `model_field_name`.
_main.py_
```python
from django_typomatic import ts_interface
from rest_framework import serializers
from django.db import models
class ActionType(models.TextChoices):
ACTION1 = "Action1", ("Action1")
ACTION2 = "Action2", ("Action2")
ACTION3 = "Action3", ("Action3")
class NumberType(models.IntegerChoices):
LOW = 1
MEDIUM = 2
HIGH = 3
@ts_interface('enumChoices')
class ChoiceSerializer(serializers.Serializer):
action = serializers.ChoiceField(choices=ActionType.choices)
num = serializers.ChoiceField(choices=NumberType.choices)
```
_output.ts_
```typescript
export enum ActionChoiceEnum {
ACTION1 = 'Action1',
ACTION2 = 'Action2',
ACTION3 = 'Action3',
}
export enum NumChoiceEnum {
LOW = 1,
MEDIUM = 2,
HIGH = 3,
}
export interface EnumChoiceSerializer {
action: ActionChoiceEnum;
num: NumChoiceEnum;
}
```
## Option 2: CLI (Preferred)
Since version 2.1, you can now generate all interfaces via a CLI. This will be the preferred method going forward, as you will no longer need to decorate your serializers, or manually call the `generate_ts` function, resulting in less complexity overall.
**NOTE:** In order to use the CLI, you will need to add `django_typomatic` to `INSTALLED_APPS`.
Special thanks to @bigpe for brewing up the first version of this CLI!
### Usage
```
--serializers [SERIALIZERS ...], -s [SERIALIZERS ...]
Serializers enumeration formats: module_name.SerializerName | module_name
--all Generate TS types for all project serializers
--trim, -t Trim "serializer" from type name
--camelize, -c Camelize field names
--annotations, -a Add js doc annotations for validations (eg. for Zod)
--enum_choices, -ec Add choices to external enum type instead union
--enum_values, -ev Add enum to obtain display name for choices field
--enum_keys, -ev Add enum to obtain the choices field keys by values
```
Using the new `generate_ts` management command, you can fine tune the generation of your interfaces similarly to how you would via the decorator method, with some additional functionality. For example, you can call the command with the `--all` flag and get all the generated types to the folder specified (they will be grouped by the application name, all external applications will be excluded, only the project applications).
You can also generate modules separately, as an example, `-s user` will restrict generation to all serializers in the `user` application, and `-s user.UserSerializer` will restrict generation to just the `UserSerializer` serializer belonging to the `user` application.
### Examples
_Generate TS for `user` app_
`./manage.py generate_ts --app_name user`
_Generate TS for specific serializer from user app_
`./manage.py generate_ts -s user.UserSerializer`
_Generate TS for many apps or serializers_
`./manage.py generate_ts -s user.UserSerializer group role.RoleSerializer role.RoleListSerializer`
_Generate TS for user app with annotations, choices enums, trim serializer, camelize, enum values and custom output path_
`./manage.py generate_ts --app_name user -a -ec -t -c -ev -o "./custom_folder/"`
Raw data
{
"_id": null,
"home_page": "https://github.com/adenh93/django-typomatic",
"name": "django-typomatic",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Django, Django Rest Framework, DRF, Typescript, Python",
"author": "Aden Herold",
"author_email": "aden.herold1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9d/ba/862af1e6b3e80a3b118d26a1638367c73f0c262d8827456614ee11580b42/django_typomatic-2.5.2.tar.gz",
"platform": "any",
"description": "# django-typomatic \n\n_A simple solution for generating Typescript interfaces from your [Django Rest Framework Serializers](https://www.django-rest-framework.org/api-guide/serializers/)._\n\nSince I now require a simple package to generate Typescript interfaces for Django Rest Framework serializers, I've decided to port over my [Typemallow](https://github.com/adenh93/typemallow/) package for use with DRF serializers!\n\n## Usage:\n\n_Using django-typomatic is just as simple!_\n\nFirst, install the package\n`pip install django-typomatic`\n\n### Option 1: Decorators\n\nFor your Django Rest Framework serializers that you wish to generate Typescript interfaces for, simply import `ts_interface` and `generate_ts` from the `django_typomatic` module, and add the `@ts_interface()` class decorator to your Django Rest Framework serializer class.\n\nAll that is required to generate your Typescript interfaces is to call the `generate_ts()` function, and provide a filepath as a parameter to output the result.\n\n_main.py_\n\n```python\nfrom django_typomatic import ts_interface, generate_ts\nfrom rest_framework import serializers\n\n\n@ts_interface()\nclass Foo(serializers.Serializer):\n some_field = serializers.CharField()\n another_field = serializers.DateTimeField()\n\n\ngenerate_ts('./output.ts')\n```\n\n_output.ts_\n\n```typescript\nexport interface Foo {\n some_field: string;\n another_field: date;\n}\n```\n\nAlternatively, you can call `get_ts()`, which will return the generated interfaces as a raw string, rather than writing the results to a file:\n\n_main.py_\n\n```python\nfrom django_typomatic import ts_interface, get_ts\nfrom rest_framework import serializers\n\n\n@ts_interface()\nclass Foo(serializers.Serializer):\n some_field = serializers.ListField(child=serializers.IntegerField())\n another_field = serializers.CharField()\n\nprint(get_ts())\n```\n\nwhich outputs the following string:\n\n`export interface Foo {\\n some_field: number[];\\n another_field: string;\\n}\\n\\n`\n\n_django-typomatic_ supports nested serializers, as well as list fields and other fields that act as lists (any field with many=True)\n\n_main.py_\n\n```python\nfrom django_typomatic import ts_interface, generate_ts\nfrom rest_framework import serializers\n\n\n@ts_interface()\nclass Foo(serializers.Serializer):\n some_field = serializers.ListField(child=serializers.IntegerField())\n another_field = serializers.CharField()\n\n\n@ts_interface()\nclass Bar(serializers.Serializer):\n foo = Foo()\n foos = Foo(many=True)\n bar_field = serializers.CharField()\n```\n\n_output.ts_\n\n```typescript\nexport interface Foo {\n some_field: number[];\n another_field: string;\n}\n\nexport interface Bar {\n foo: Foo;\n foos: Foo[];\n bar_field: string;\n}\n```\n\n_django-typomatic_ also supports ChoiceField serializers, as well as any other serializer fields that makes use of choices.\n\n_main.py_\n\n```python\nfrom django_typomatic import ts_interface\nfrom rest_framework import serializers\nfrom django.db import models\n\n\nclass ActionType(models.TextChoices):\n ACTION1 = \"Action1\", (\"Action1\")\n ACTION2 = \"Action2\", (\"Action2\")\n ACTION3 = \"Action3\", (\"Action3\")\n\n\nclass NumberType(models.IntegerChoices):\n LOW = 1\n MEDIUM = 2\n HIGH = 3\n\n\n@ts_interface('choices')\nclass ChoiceSerializer(serializers.Serializer):\n action = serializers.ChoiceField(choices=ActionType.choices)\n num = serializers.ChoiceField(choices=NumberType.choices)\n\n```\n\n_output.ts_\n\n```typescript\nexport interface ActionSerializer {\n action: \"Action1\" | \"Action2\" | \"Action3\";\n num: 1 | 2 | 3;\n}\n```\n\n#### Extended Usage:\n\nThe `@ts_interface()` decorator function accepts an optional parameter, _context_, which defaults to... well... 'default'.\n\n\"_Why is this the case?_\"\n\nWhen a Serializer is identified with with `@ts_interface` decorator, it is added to a list in a dictionary of serializers, with the dictionary key being the value provided to the _context_ parameter. If you were to provide different contexts for each serializer, additional keys will be created if they do not exist, or the serializer will simply be appended to the list at the existing key.\n\nThis comes in handy, as the `generate_ts()` function _also_ accepts an optional _context_ parameter, which will filter only serializers in the dictionary at the specific key.\n\nThis is useful if you wish to output different contexts to different files, e.g.\n\n_main.py_\n\n```python\n...\nfrom django_typomatic import ts_interface, generate_ts\nfrom rest_framework import serializers\n\n\n@ts_interface(context='internal')\nclass Foo(serializers.Serializer):\n foo = serializers.CharField()\n\n\n@ts_interface(context='internal')\nclass Bar(serializers.Serializer):\n bar = serializers.CharField()\n\n\n@ts_interface(context='external')\nclass FooBar(serializers.Serializer):\n foo_bar = serializers.CharField()\n\n\n'''\nwe're telling django-typomatic that we only want to generate interfaces from serializers with\nan 'internal' context to './internal.ts'\n'''\ngenerate_ts('./internal.ts', context='internal')\n\n'''\nonly generate interfaces from serializers with an 'external' context to './external.ts'\n'''\ngenerate_ts('./external.ts', context='external')\n```\n\n_internal.ts_\n\n```typescript\nexport interface Foo {\n foo: string;\n}\n\nexport interface Bar {\n bar: string;\n}\n```\n\n_external.ts_\n\n```typescript\nexport interface FooBar {\n foo_bar: string;\n}\n```\n\n#### Camelize\n\nYou can use django dependencies that converts the response from `snake_casing` to `camelCasing`. The solution offered for this is camelize:\n\n```python\nfrom django_typomatic import ts_interface, generate_ts\nfrom rest_framework import serializers\n\n\n@ts_interface()\nclass Foo(serializers.Serializer):\n some_field = serializers.CharField()\n\n\ngenerate_ts('./output.ts', camelize=True)\n```\n\nDifferent from the main example. The interface attributes are now camel casing.\n\n_output.ts_\n\n```typescript\nexport interface Foo {\n someField: string;\n}\n```\n\n#### TypeScript enums from ChoiceFields\n_django-typomatic_ also allows for generating an `enum` for a ChoiceField. The `enum` will follow the naming of `ModelFieldNameChoiceEnum` for a model field with the name `model_field_name`, note that the interface field still remains `model_field_name`.\n\n_main.py_\n\n```python\nfrom django_typomatic import ts_interface\nfrom rest_framework import serializers\nfrom django.db import models\n\n\nclass ActionType(models.TextChoices):\n ACTION1 = \"Action1\", (\"Action1\")\n ACTION2 = \"Action2\", (\"Action2\")\n ACTION3 = \"Action3\", (\"Action3\")\n\n\nclass NumberType(models.IntegerChoices):\n LOW = 1\n MEDIUM = 2\n HIGH = 3\n\n\n@ts_interface('enumChoices')\nclass ChoiceSerializer(serializers.Serializer):\n action = serializers.ChoiceField(choices=ActionType.choices)\n num = serializers.ChoiceField(choices=NumberType.choices)\n\n```\n\n_output.ts_\n\n```typescript\nexport enum ActionChoiceEnum {\n ACTION1 = 'Action1',\n ACTION2 = 'Action2',\n ACTION3 = 'Action3',\n}\n\nexport enum NumChoiceEnum {\n LOW = 1,\n MEDIUM = 2,\n HIGH = 3,\n}\n\n\nexport interface EnumChoiceSerializer {\n action: ActionChoiceEnum;\n num: NumChoiceEnum;\n}\n```\n\n## Option 2: CLI (Preferred)\n\nSince version 2.1, you can now generate all interfaces via a CLI. This will be the preferred method going forward, as you will no longer need to decorate your serializers, or manually call the `generate_ts` function, resulting in less complexity overall.\n\n**NOTE:** In order to use the CLI, you will need to add `django_typomatic` to `INSTALLED_APPS`.\n\nSpecial thanks to @bigpe for brewing up the first version of this CLI!\n\n### Usage\n\n```\n--serializers [SERIALIZERS ...], -s [SERIALIZERS ...]\n Serializers enumeration formats: module_name.SerializerName | module_name\n --all Generate TS types for all project serializers\n --trim, -t Trim \"serializer\" from type name\n --camelize, -c Camelize field names\n --annotations, -a Add js doc annotations for validations (eg. for Zod)\n --enum_choices, -ec Add choices to external enum type instead union\n --enum_values, -ev Add enum to obtain display name for choices field\n --enum_keys, -ev Add enum to obtain the choices field keys by values\n```\n\nUsing the new `generate_ts` management command, you can fine tune the generation of your interfaces similarly to how you would via the decorator method, with some additional functionality. For example, you can call the command with the `--all` flag and get all the generated types to the folder specified (they will be grouped by the application name, all external applications will be excluded, only the project applications).\n\nYou can also generate modules separately, as an example, `-s user` will restrict generation to all serializers in the `user` application, and `-s user.UserSerializer` will restrict generation to just the `UserSerializer` serializer belonging to the `user` application.\n\n### Examples\n\n_Generate TS for `user` app_\n\n`./manage.py generate_ts --app_name user`\n\n_Generate TS for specific serializer from user app_\n\n`./manage.py generate_ts -s user.UserSerializer`\n\n_Generate TS for many apps or serializers_\n\n`./manage.py generate_ts -s user.UserSerializer group role.RoleSerializer role.RoleListSerializer`\n\n_Generate TS for user app with annotations, choices enums, trim serializer, camelize, enum values and custom output path_\n\n`./manage.py generate_ts --app_name user -a -ec -t -c -ev -o \"./custom_folder/\"`\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple solution for generating Typescript interfaces from your Django Rest Framework Serializers.",
"version": "2.5.2",
"project_urls": {
"Homepage": "https://github.com/adenh93/django-typomatic"
},
"split_keywords": [
"django",
" django rest framework",
" drf",
" typescript",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5fb365eee687447a49b6d59b21eafa7e1605b90126aa149d3987abfb1d9a05d9",
"md5": "153b757f85fee291af10dd9f31c3dd1b",
"sha256": "9b3a28fd5eb60f48aae0530e5db18d40d6a8c4b869dedb05f214de575a20d11c"
},
"downloads": -1,
"filename": "django_typomatic-2.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "153b757f85fee291af10dd9f31c3dd1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17307,
"upload_time": "2024-07-02T23:45:51",
"upload_time_iso_8601": "2024-07-02T23:45:51.466371Z",
"url": "https://files.pythonhosted.org/packages/5f/b3/65eee687447a49b6d59b21eafa7e1605b90126aa149d3987abfb1d9a05d9/django_typomatic-2.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9dba862af1e6b3e80a3b118d26a1638367c73f0c262d8827456614ee11580b42",
"md5": "b50732d2ed70a3320a75e6457c86ef19",
"sha256": "8d6a8b8d82e5782756a16b93b8c6004af4a6743b8cb38d520c3fd1588f0f5b82"
},
"downloads": -1,
"filename": "django_typomatic-2.5.2.tar.gz",
"has_sig": false,
"md5_digest": "b50732d2ed70a3320a75e6457c86ef19",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17357,
"upload_time": "2024-07-02T23:45:53",
"upload_time_iso_8601": "2024-07-02T23:45:53.182952Z",
"url": "https://files.pythonhosted.org/packages/9d/ba/862af1e6b3e80a3b118d26a1638367c73f0c262d8827456614ee11580b42/django_typomatic-2.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-02 23:45:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adenh93",
"github_project": "django-typomatic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "django-typomatic"
}
JSON
