akiyoko blog

akiyoko の IT技術系ブログです

Django パッケージ利用実態調査アンケート(2022年12月)について

この投稿は 「Calendar for Django | Advent Calendar 2022 - Qiita」 4日目の記事です。


Django Advent Calendar のネタ探しをしていて、ふと 「どんな Djangoパッケージがどれくらい使われているの?🤔」 という利用実態調査みたいな記事なら自分もぜひ読んでみたいと思ったので、アンケートを採ってみることにしました。


ということで、ぜひアンケートにご協力よろしくお願いします 🙇‍♂️🙇‍♂️🙇‍♂️(回答者の情報は収集していません)

docs.google.com



アンケートの回答〆切は 12/15 23:59 までとさせていただき、12/16 以降の Django Advent Calendar のどこかで発表する予定です。


なお、Q2. の Django パッケージの選択肢を以下に列挙しますが、これは 2022 Django Developers Survey というワールドワイドな Django 開発者向けアンケートの「お気に入りのサードパーティ Django パッケージは?」という質問の選択肢をそのまま利用しました(なぜこの選択肢になったのかは私にも分かりません)。


Django パッケージ 説明文
dj-database-url Django を使用したアプリケーションで、データベースの接続文字列を簡単に扱うためのライブラリです。このライブラリを使うことで、データベースの接続情報を環境変数や設定ファイルから読み取り、Django の設定に渡すことができます。その結果、Django アプリケーションのデプロイやテストを容易に行うことができるようになります。また、dj-database-url は、様々なデータベース管理システムをサポートしているため、どのようなデータベースを使用しているかに関係なく利用できます。
dj-rest-knox Django の REST フレームワークである Django REST framework にて、トークンベースの認証を提供するためのものです。このパッケージを使用することで、Django アプリケーションでトークンベースの認証を実装することができます。また、dj-rest-knox は Django REST framework の上に構築されており、Django のログイン認証システムを使用している場合は、すぐに使用することができます。
dj-rest-auth Django の REST フレームワークである Django REST framework にて、ユーザー認証を提供するためのものです。このパッケージを使用することで、Django アプリケーションで簡単にユーザー認証を実装することができます。また、dj-rest-auth は Django のログイン認証システムを拡張しているため、既存の Django アプリケーションでも簡単に導入することができます。
django-allauth Django にて、多要素認証を提供するためのものです。このパッケージを使用することで、Django アプリケーションで簡単に多要素認証を実装することができます。また、django-allauth は Django のログイン認証システムを拡張しており、既存の Django アプリケーションでも簡単に導入することができます。また、django-allauth は様々な外部サービス(Facebook、Google、Twitter など)との連携もサポートしています。
django-braces Django にて、様々な拡張機能を提供するためのものです。このパッケージを使用することで、Django アプリケーションで簡単にビューやミックスインなどの拡張機能を実装することができます。また、django-braces は他の Django パッケージとも組み合わせて使用することができ、Django プロジェクトで様々な拡張機能を組み合わせることができます。
django-celery Web フレームワークである Django と、Python のタスク駆動フレームワークである Celery を組み合わせるためのものです。このパッケージを使用することで、Django アプリケーション内で Celery を利用して、非同期タスクを管理することができます。
django-celery-beat Django フレームワークと Celery というタスクキューライブラリを組み合わせて使用するためのツールを提供します。Celery は、バックグラウンドで処理を行うタスクを管理するためのライブラリです。django-celery-beat を使うことで、Django プロジェクトで Celery のスケジュール処理をより簡単に利用することができます。また、django-celery-beat には、Django のデータベースを使って Celery のスケジュールを管理するためのツールが提供されているため、Django プロジェクトで定期的なタスクを実行するためのインフラストラクチャを構築することができます。
django-channels Django にて、WebSocket や Server-Sent Events(SSE)を扱うためのものです。このパッケージを使用することで、Django アプリケーションで WebSocket や SSE を利用した通信を実装することができます。
django-click Python の Webフレームワークである Django を使用したアプリケーションで、コマンドラインインターフェース(CLI)を簡単に構築するためのライブラリです。その結果、Django アプリケーションの管理や操作を、より便利でスムーズに行うことができるようになります。
django-compressor Django にて、JavaScript や CSS のファイルを圧縮するためのものです。このパッケージを使用することで、Django アプリケーションで簡単に JavaScript や CSS のファイルを圧縮することができます。
django-configurations Django にて、複数の環境に対応した設定を管理するためのものです。このパッケージを使用することで、Django アプリケーションで簡単に複数の環境(開発環境、本番環境、ステージング環境など)に対応した設定を管理することができます。
django-cors-headers Django にて、クロスオリジンリソースシェアリング(CORS)を扱うためのものです。CORS は、異なるオリジン(ドメイン)間での Web ページのやり取りを許可する仕組みです。
django-crispyforms このパッケージを使用することで、Django アプリケーションで簡単にフォームを美しくレンダリングすることができます。また、django-crispy-forms は Bootstrap を使用したフォームのレンダリングをサポートしています。
django-dbbackup このパッケージを使用することで、Django アプリケーションで簡単にデータベースのバックアップを管理することができます。また、django-dbbackup は様々なクラウドストレージサービス(Amazon S3、Dropbox、Google Cloud Storage など)との連携もサポートしています。
django-debug-toolbar Django にて、開発時にデバッグを行うためのものです。このパッケージを使用することで、Django アプリケーションの開発時に、リクエストやレスポンスなどの詳細情報を表示することができます。
django-environ Django アプリケーションで環境変数を簡単に使用できるようにするためのライブラリです。このライブラリを使用することで、アプリケーションの設定値を環境変数から取得することができます。これにより、アプリケーションの設定値を外部から安全かつ簡単に管理することができます。
django-extensions Django フレームワークのためのサポートライブラリです。このライブラリには、Django アプリケーションを開発するためのさまざまな便利な機能が含まれています。例えば、コマンドラインから Django プロジェクトを作成するためのツール、データベースのスキーマを表示するためのツール、データベースのデータをダンプするためのツールなどがあります。このライブラリを使用することで、Django アプリケーションの開発プロセスをよりスムーズかつ効率的に行うことができます。
django-filter Django アプリケーションでクエリセットをフィルタリングするためのライブラリです。このライブラリを使用することで、クエリセットを簡単に様々な条件でフィルタリングし、特定の条件にマッチするデータのみを取得することができます。 django-filter を使用することで、データベースからデータを抽出する際に、より細かいフィルタリングを行うことができるため、データをより正確かつ効率的に取得することができます。
django-import-export Djangoフレームワークでのデータのインポートおよびエクスポートを簡単に行うためのライブラリです。このライブラリを使用することで、Djangoのモデルデータを様々な形式のファイル(CSV、JSON、Excelなど)とやりとりすることができます。django-import-export を使用することで、データのインポートおよびエクスポート操作を管理画面から直接実行することができます。
django-lifecycle Python の Web フレームワークである Django を使用したアプリケーションで、モデルの作成や更新時に実行される処理を定義するためのライブラリです。このライブラリを使うことで、Django のモデルを作成、更新する際に、特定の処理を自動的に実行することができます。例えば、モデルが作成されるときに、特定のメールを送信する処理や、モデルが更新されるときに、特定のログを記録する処理などを定義することができます。これにより、Django アプリケーションの動作をより自動化し、処理の追加や変更を容易に行うことができるようになります。
django-model-utils Django フレームワークでモデルを定義する際に便利なユーティリティクラスを提供するライブラリです。このライブラリを使用することで、モデルの作成やカスタマイズがより簡単かつ効率的に行えます。
django-money Djangoフレームワークで組み込みの「Money」フィールドを提供するライブラリです。このライブラリを使用することで、データベース内での金額を貨幣単位を考慮した形で保存することができます。django-moneyを使用することで、金額を扱うアプリケーションを作成する際に、正確かつ柔軟な金額処理が行えるようになります。また、django-moneyは、様々な通貨をサポートしており、通貨の相互変換も可能です。
django-redis Django フレームワークで Redis を使用するためのライブラリです。Redis は、速度が非常に速いキー/値型のデータベースです。django-redis を使用することで、Django アプリケーションで Redis を使用してデータを保存することができます。これにより、Djangoアプリケーションのデータ保存や取得が高速化されます。また、django-redis は、Django のキャッシュフレームワークと組み合わせて使用することで、アプリケーションのパフォーマンスをさらに向上させることができます。
django-rest-swagger Django フレームワークで作成された RESTful API に Swagger を組み込むためのライブラリです。Swagger は、RESTful API を文書化して公開するためのツールです。django-rest-swagger を使用することで、Django アプリケーションで作成した RESTful API を Swagger を使用して文書化することができます。これにより、API を使用する開発者が API の仕様や使用方法を簡単に理解することができるようになります。また、django-rest-swagger を使用することで、API のテストやモックを作成することができます。
django-storages Django フレームワークでさまざまなクラウドストレージサービスを使用するためのライブラリです。このライブラリを使用することで、Django アプリケーションで Amazon S3 や Google Cloud Storage などのクラウドストレージサービスを簡単に使用することができます。 django-storages を使用することで、Django アプリケーションで保存されるデータや画像などのファイルをクラウドストレージ上に保存することができます。これにより、アプリケーションのデータを安全かつスケーラブルな方法で保存することができるようになります。
django-silk Django フレームワークでリクエストとレスポンスをモニタリングするためのライブラリです。このライブラリを使用することで、Djangoアプリケーションで発生するHTTPリクエストとレスポンスを管理画面から簡単に閲覧することができます。django-silkを使用することで、アプリケーションのパフォーマンスやエラーを把握することができるため、デバッグやトラブルシューティングがより容易に行えます。また、django-silkは、リクエストとレスポンスの中身を表示するだけでなく、リクエストを再現したり、リクエストやレスポンスを検索したりすることができます。
django-taggit Django フレームワークでタグを扱うためのライブラリです。このライブラリを使用することで、Djangoアプリケーションでタグを作成したり、タグを付けられたオブジェクトを取得したりすることができます。django-taggit を使用することで、アプリケーションにタグ付け機能を簡単に実装することができます。また、django-taggit は、既存の Django モデルにタグを追加することもできます。これにより、タグを使用してデータを管理したり、検索したりすることができます。
django-test-plus Django フレームワークでのユニットテストを実行するためのライブラリです。このライブラリを使用することで、Django アプリケーションのユニットテストをより簡単かつ効率的に行うことができます。 django-test-plus には、ユニットテストを実行する際に便利なユーティリティ関数やアサーションが含まれています。例えば、ビューやURLのテストを行うためのヘルパー関数、フォームやモデルのテストを行うためのアサーションなどがあります。これらの機能を使用することで、Djangoアプリケーションのユニットテストをよりスムーズかつ効率的に実行することができます。
djangorestframework Django フレームワークで RESTful な Web API を作成するためのライブラリです。このライブラリを使用することで、Django アプリケーションを通じて RESTful な Web API を提供することができます。 djangorestframework には、API のエンドポイントやリクエストとレスポンスのシリアライザ、API の認証や権限管理など、RESTful な Web API を実装するための必要な機能がすべて提供されています。このライブラリを使用することで、Django アプリケーションから RESTful な Web API を提供することができるようになります。
djangorestframework-simplejwt django-rest-framework を使用した RESTful な Web API にJSON Web Tokens(JWT)を使用した認証を実装するためのライブラリです。JWT は、トークンベースの認証方式の一種です。djangorestframework-simplejwt を使用することで、django-rest-framework で作成した RESTful な Web API に JWT を使用した認証を実装することができます。これにより、API を利用するアプリケーションがAPIに対してアクセスする際に、トークンを使用して認証を行うことができるようになります。
Djoser Django フレームワークで作成された RESTful な Web API にユーザー管理機能を実装するためのライブラリです。このライブラリを使用することで、Djangoアプリケーションにユーザー登録、ユーザー情報の管理、パスワードの変更などの機能を簡単に実装することができます。また、Djoser は、JSON Web Tokens(JWT)を使用した認証をサポートしているため、JWT を使用した API の認証も実装することができます。Djoser を使用することで、Django アプリケーションにRESTful な API を作成し、ユーザー管理や認証を実装することができるようになります。
model-bakery Django プロジェクトで使用されるモデルを生成するための Python パッケージです。model-bakery は、モデルを生成し、操作し、評価するためのツールを提供します。
pylint-django pylint-django は、Django フレームワークで作成された Python コードを検証するための Pylint プラグインです。Pylint は、Python のコード品質を測定するツールです。pylint-django を使用することで、Django フレームワークを使用した Python コードに対して、Pylint が提供する様々な品質指標を適用することができます。これにより、Django フレームワークを使用した Python コードの品質を向上させることができます。また、pylint-django は、Django フレームワーク固有の構文や API を理解しており、Django フレームワークを使用した Python コードをより正確かつ効率的に検証することができます。
pytest-django Python のテストフレームワークである pytest を用いて Django Web アプリケーションのテストを実行するためのプラグインです。このプラグインを使うことで、Django アプリケーションのテストを簡単に実行し、結果を比較することができます。また、pytest-django は、Django アプリケーションのデータベースを自動的にセットアップ・クリーンアップするため、データベースのテストも容易に行うことができます。
Wagtail Wagtail は、Django フレームワークを使用した CMS(Content Management System)です。このCMSを使用することで、WebサイトやWebアプリケーションのコンテンツの管理をより簡単かつスムーズに行うことができます。 Wagtail には、ページやブログ記事の管理、メディアライブラリ、ページのテンプレートやカスタマイズ、検索、ユーザー管理などの機能が備わっています。これらの機能を使用することで、WebサイトやWebアプリケーションのコンテンツを効率的に管理することができます。また、Wagtail はオープンソースであるため、カスタマイズや拡張も容易に行うことができます。


ちなみに、説明文は最近話題の「ChatGPT」の回答を使わせていただきました(なのでしれっと間違っている可能性もあるかもしれません)。冗長な説明があったのを削除して調整しましたが、スゴイですねこれ。

Django のビューから Django コマンドを実行する方法

この投稿は 「Calendar for Django | Advent Calendar 2022 - Qiita」 3日目の記事です。

小ネタです。


Django のビューから直接 Djangoコマンドを実行するには、django.core.management.call_command を使えば簡単 です。*1


こんな感じで使います。

api/views.py

from django.core import management
from rest_framework.response import Response
from rest_framework.views import APIView


class CallCommandView(APIView):
    def post(self, request, *args, **kwargs):
        # Djangoコマンドを実行
        management.call_command('loaddata', 'test_data', verbosity=0)
        # レスポンスオブジェクトを作成して返す
        return Response({'success': True})


これは Django REST Framework(通称 DRF)を使用したビューの実装例ですが、Django 単体でも同じように利用することが可能です。



config/urls.py

from django.urls import path

from api import views

urlpatterns = [
    path('call-command/', views.CallCommandView.as_view()),
]


実行結果





ちなみに、Django コマンドの「--no-input」オプションは call_command() に「interactive=False」を指定することで利用可能です。

management.call_command('flush', verbosity=0, interactive=False)


標準出力をファイルに書き込むこともできます。*2

with open('/path/to/command_output', 'w') as f:
    management.call_command('dumpdata', stdout=f)


cron などで定期実行している Django コマンドを、API で呼び出すなどといった利用方法が考えられますね。

*1:ビューからでなくても、モデルでもどこでも実行可能です。

*2:https://docs.djangoproject.com/ja/3.2/ref/django-admin/#output-redirection

既存テーブルに単一の主キーがない場合に Django モデルを使いたい場合の解決案(Django で複合主キーを使う方法)

この投稿は 「Calendar for Django | Advent Calendar 2022 - Qiita」 2日目の記事です。

最近こんなの見つけたよという緩い内容になっているので、「こんなのもあるんだな」という軽い気持ちで読んでいただければと思います。そしてもし、「現場で使ってるよ」という方がいれば教えていただければありがたいです。

課題

まず大前提ですが、Django モデルの仕様として、それぞれのモデルごとに単一の主キーを持たせる必要があり(「primary=True」オプションを持つフィールドをモデルに明示的に含めるか、さもなくば「id」という名前のフィールドが自動的にモデルに追加され、それに対応したカラムがテーブルに作成される)、複合主キー(composite primary key)はサポートされていません。 *1


そのため、例えば、単一の主キーを持たない(が複合主キーを持っている)既存のテーブルを Django モデルで扱うことは困難です。



ところで Django で複合主キーっぽいことをしたければ通常は、「id」という名前のサロゲートキーを主キーとして別に用意しつつ、複合ユニーク制約を利用しますよね。具体的には、Django 2.2 から追加された UniqueConstraint を利用して次のように実装します。


models.py

from django.db import models


class Employee(models.Model):
    """従業員モデル"""

    class Meta:
        db_table = 'employee'
        verbose_name = verbose_name_plural = '従業員'
        constraints = [
            models.UniqueConstraint(fields=['branch_code', 'employee_code'], name='unique_employee')
        ]

    branch_code = models.CharField('支店コード', max_length=3)
    employee_code = models.CharField('従業員コード', max_length=5)
    name = models.CharField('従業員名', max_length=255)

    def __str__(self):
        return f'{self.branch_code}-{self.employee_code}'


この従業員テーブルの仕様としては、支店ごとに従業員コードが振られていて、従業員コードはレコード全体としてはユニークになっていない(支店コードと従業員コードを合わせるとユニークになる)という想定です。

ちなみに複合ユニーク制約を実現するには unique_together を使うことも可能ですが、将来的に非推奨になる可能性があり、UniqueConstraint の方が多機能なので、UniqueConstraint の利用が推奨されます。



 

解決策

最近見つけたのですが、(次期リリースではありますが)「Viewflow」というライブラリの「CompositeKey」を使えば、既存テーブルに主キーがないテーブルを Django モデルで扱うことが可能になります。

使い方は次の通りです。

pip install django-viewflow --pre

# or

pip install django-viewflow==2.0.0a2


models.py

from django.db import models
from viewflow.fields import CompositeKey


class Employee(models.Model):
    """従業員モデル"""

    class Meta:
        db_table = 'employee'
        managed = False
        verbose_name = verbose_name_plural = '従業員'

    id = CompositeKey(columns=['branch_code', 'employee_code'])
    branch_code = models.CharField('支店コード', max_length=3)
    employee_code = models.CharField('従業員コード', max_length=5)
    name = models.CharField('従業員名', max_length=255)

    def __str__(self):
        return f'{self.branch_code}-{self.employee_code}'


これで、CompositeKey の columns で指定した複数のフィールドの値を「{'branch_code': '001', 'employee_code': '00001'}」のような JSON 文字列で保持する「id」という名前の 仮想フィールド を持つことができます。

「managed = False」*2 を指定しないとマイグレーションで「id」カラムが作成されてしまうのですが、CompositeKey が威力を発揮するのは「managed = False」を指定してモデルをマイグレーションの対象外にした場合で、主キーを持たない既存のテーブルに影響を及ぼさずに Django モデルを用意することができます。事例としては、次のように複合主キーを持った既存テーブルから Django ORM を使ってレコードを抽出(読み取り専用)したいというニーズに応えることができます。


Django 管理サイトでも動作するというのも高評価です。

*1:Django で複合主キーをサポートするかどうかは、17年前から議論が続いています… #373 (Add support for multiple-column primary keys) – Django

*2:https://docs.djangoproject.com/ja/3.2/ref/models/options/#managed

Django REST Framework はじめの一歩 〜押さえておきたい3つのポイント〜

この投稿は 「Calendar for Django | Advent Calendar 2022 - Qiita」 1日目の記事です。


この記事では、11月に「みんなのPython勉強会#87」で発表したトーク 「Django REST Framework はじめの一歩 〜押さえておきたい3つのポイント〜」の内容を詳しく説明したいと思います。トークの目的は「Django REST Framework(通称 DRF)がどんなものかをざっくり理解する」です。 DRF はよく分からないけど、Django なら何となく分かるという DRF 初心者の方を理想のトーク対象者として想定しています(もちろん Django を知らなくてもウェルカム!)。

ちなみに、各種バージョンは

  • Django : 3.2 LTS(現時点での最新 LTS)
  • DRF : 3.14(現時点での最新バージョン)

で動作確認をしています。



 

はじめに



今回のトークに先立って事前に Twitter でアンケートを取ったところ、約73%の方が「DRF を使っている」と回答していた のですが、私の予想を遥かに超えて DRF が使われていることに驚きました(正直半々くらいかなと思っていました…)。

ここで、アンケートにご協力いただいた皆さまにこの場を借りて感謝申し上げたいと思います。ご協力ありがとうございました。





また、「Django Developers Community Survey 2021」という7000名を超える開発者アンケートでは、「好きな Django パッケージは何ですか?(複数回答ありで5つまで回答可)」という質問に対して、DRF が第1位に選出されていました。2位の「django-celery」と比較してもダブルスコアというぶっちぎりの結果になっていますね。



 

DRF とは?



本題に入る前にまず、DRF とは何か?を説明したいと思います。一言でいえば、DRF は「REST API を作成する際の多彩なニーズに応えるための超ド定番 Django パッケージ」です。 Django 単体では不足しているさまざまな機能を、DRF で補完してくれているというイメージになります。特に、Django 開発者なら理解しやすい作りになっているというのが、Django 開発者にとってうれしい特徴です。






続いて、REST API の概要についても説明します。
REST API はスマホや SPA のバックエンドとして よく利用されています(左図)。そして、REST API は、URI でリソースを特定し、HTTP メソッドでそのリソースへの操作を表すという直感的に理解しやすいシンプルな設計になっています(右図)。そんな共通の枠組みに則ったデータを介すことで、フロントエンドとバックエンドが疎結合化、すなわち、お互いのプログラミング言語やアーキテクチャを意識することなくデータをやり取りすることができるのです。なお、REST API はリソース中心の設計となっているので、モデル中心の Django と親和性が高いというのも DRF を使うメリットになるかと思います。






DRF が一番得意なのは、単一リソースの CRUD を処理する REST API です。上の表に示したように、単一リソースの CRUD を処理する REST API は、「GET」「POST」「PUT」「PATCH」「DELETE」という HTTPメソッドそれぞれに意味を持たせ、リソースを表す URI と組み合わせて、「リソース一覧の取得」「リソース詳細の取得」「リソースの登録」「リソースの更新」「リソースの一部更新」「リソースの削除」といった API を構成します。これを DRF で実装するのはすごく簡単で、モデル除けば最短20行くらいで書くことができます(コード例については後ほど紹介します)。






ここで、DRF についてよくある「誤解」を紹介します。
よくある誤解その①「DRF では単一リソースを扱う API 以外は作れない」は「✕」です。先に説明した 単一リソースを扱う REST API 以外にも、上の表に示したような、リソースがネストした API、独自アクションを追加した API、リソースに紐付いていない API なども DRF で作成することができます。





よくある誤解その②「DRF なしでは JSON のやり取りができない」も「✕」です。Django 単体でも(やろうと思えば)JSON データを受け取って JSON データを返すことができます。下の例を見てください。

api/views.py

import json
from django.forms.models import model_to_dict
from django.http.response import JsonResponse
from django.views import View
from shop.models import Book


class BookCreateView(View):
    """本モデルの登録APIクラス"""

    def post(self, request, *args, **kwargs):
        """本モデルの登録APIに対応するハンドラメソッド"""
        data = json.loads(request.body)
        # バリデーションを実行
        if not data.get('title'):
            return JsonResponse({'message': 'タイトルは必須です。'}, status=400)
        # モデルオブジェクトを登録
        book = Book(**data)
        book.save()
        # レスポンスオブジェクトを作成して返す
        return JsonResponse(model_to_dict(book), status=201)

入力パラメータとなる JSON データは request.body に入っているのでそれをパースして、(この例ではめちゃくちゃ適当ですが)バリデーションを適宜実行して、モデルオブジェクトにデータを詰め替えて永続化して、最後に JsonResponse オブジェクトを作成して返しています。でもこんなことを毎回するのは大変ですよね。できれば Django っぽい書き方で、こういった処理を共通化したいというニーズから DRF が誕生したんじゃないかなと思います。






次は、DRF を使うメリットについて。
まず、Django のノウハウやエコシステムが活用できるというのが、DRF を使う大きなメリットになります。 むしろこれがほとんどすべてと言っても過言ではありません。DRF プロジェクトのベースはあくまでも Django なので、ORM やマイグレーションを始めとする多くの機能をフル活用できたり、いつも使っている Django パッケージが使えたりといったように、Django のノウハウやエコシステムをほぼそのまま使うことができます。

そして次に、人気があって枯れていることもメリットです。DRF は Django で REST API を作るとなった場合にほぼ一択になるほど人気で、特に英語圏での情報がたくさんあります。 公式ドキュメントやチュートリアルも(英語になりますが)かなり充実しています。

機能が充実していることも DRF ならではのメリットです。 例えば、Cookie認証、トークン認証、JWT認証などの API でよく利用される認証を簡単に利用する ことができます。また、アクセス権制御をするための「パーミッション」機能、クエリ文字列による検索をするための「フィルタリング」機能、「ページネーション」機能、APIの利用回数制限をするための「スロットリング」機能などが用意されており、それぞれが差し替えできるようになっています。さらに、画面で API を実行確認できる「Browsable API」と呼ばれるテストクライアントがすぐに使えたり、OpenAPI に準拠した API ドキュメントを出力 したりすることもできます。こういった REST API を作成するのに必要な機能がたいてい揃っていて、簡単な設定をするだけで幅広いニーズを満たすことができるというのが大きな特徴になります。






逆に、DRF にはどんなデメリットがあるのでしょうか。

ズバリ… 複雑です。

Django だけでも十分複雑なのに、そこに DRF が加わったらさらに複雑になってしまいますよね。






そこでここからは、DRF 初心者が押さえておきたい次の3つのポイントを解説していきたいと思います。

  • ポイント①:全体像を把握しよう
  • ポイント②:シリアライザはフォームっぽく使える
  • ポイント③:起点は DRF 用ビュー

この3つについてそれぞれ詳しく説明していきます。



 

ポイント①:全体像を把握しよう

ポイント①「全体像を把握しよう」について。



まず比較のために、Django プロジェクトの全体像と登場人物について説明します。図の左側から来たリクエストを、URLディスパッチャと呼ばれる Django のコアコンポーネントがハンドリングし、URLconf で登録したビュー関数を呼び出して、ビューの中でフォームやモデル、テンプレートを使って、レスポンスを作成して返し、URLディスパッチャがレスポンスを処理するという流れになっています。ミドルウェアは、ビューが呼び出される前や後で何らかの処理をするために利用されます。






REST API を構築するための DRF プロジェクトでは、(HTML のフォーム要素を扱わないし、レスポンスとして画面をレンダリングした HTML を返さないので)基本的にフォームとテンプレートは使いません(後述しますが、Django を共存させる場合にはその限りではありません)。その代わり、DRF では「シリアライザ」というコンポーネントを使います。 シリアライザは入出力の JSON(およびモデルとの連携)定義とバリデーションを担当します。ポイント②で詳しく説明しますが、シリアライザはフォームに似せて作られていて、フォームと同じように使うことができます。

そしてビューは、DRF用のビューを使います。これもポイント③で説明しますが、図を見ると分かるように、DRF の起点となるのは「DRF 用ビュー」です。図では「✕」で示していますが、通常の Django のビューを URLconf に登録しておくことも可能です。

それ以外のモデル、URLconf、ミドルウェアは通常の Django と同じように使います。






ポイント①のまとめです。DRF では、DRF用のビュー を作成して URLconf に登録します。そしてシリアライザというコンポーネントを使い、フォームとテンプレートは使いません。ただし、Django と DRF のビューをそれぞれ登録することができるので、そういった共存をさせる場合にはフォームもテンプレートも使うことになるので誤解のないようにしてください。それ以外は通常の Django とだいたい同じように使います。こういった全体像を押さえておくのが第一のポイントです。




 

ポイント②:シリアライザはフォームっぽく使える

ポイントその②「シリアライザはフォームっぽく使える」について。



その前にまず、DRF の独自コンポーネントである「シリアライザ」の使いどころを説明します。シリアライザが担当する役目は、

  • 入力データのバリデーション
  • モデルオブジェクトの永続化
  • 出力データの作成

です。上の図はどこでシリアライザを使うかを示しているのですが、登録API、更新API、取得API のそれぞれでシリアライザの使いどころが異なります(削除API のようにシリアライザを使わない場合もあります)。例えば登録 API だと、リクエストされた JSON データを元にしてシリアライザオブジェクトを作成し、シリアライザオブジェクトのバリデーションメソッドを実行し、シリアライザの永続化メソッドを実行して、最後にレスポンスオブジェクトの引数にシリアライザのデータを渡すという流れになります。このように、ほとんどの場合でシリアライザを使うことになるため、DRF を使うときにはシリアライザは避けて通ることができません。






さて、本題です。シリアライザはフォームっぽく使えるということについて説明します。リソース(すなわちモデル)と紐付いた REST API の場合は「ModelSerializer」を使うのが基本なのですが、ModelSerializer の使い方は(フォームで特定のモデルを扱うための)ModelForm とほぼ同じです。 ModelSerializer と ModelForm の引数や属性、バリデーション、永続化の流れを上の図に並べて示したのですが、仕組みがほぼ同じになっています。バリデーションメソッドは「is_valid」、永続化メソッドは「save」でこちらも同じです。ただし、バリデーション済みのデータは「validated_data」となっていて、ModelForm(親クラスの Form も同様)と変数名が異なるので注意してください。






シリアライザの実装イメージは次のようになります。

api/serializers.py

from rest_framework import serializers

from shop.models import Book


class BookSerializer(serializers.ModelSerializer):
    """本モデル用シリアライザ"""

    class Meta:
        model = Book
        fields = ['id', 'title', 'price']

ModelSerializer を継承したシリアライザクラスを用意して、Metaクラスの「model」属性に連携させるモデルクラス、「fields」属性に JSONの入出力フィールドとして利用するモデルのフィールド名を指定します。フィールドは、fields 属性以外に、除外するフィールドを excludes 属性で指定することもできます。

使い方は ModelFormとほぼ同じで、引数「data」にリクエストのパラメータ(DRF では JSON データ)、更新時には引数「instance」にモデルオブジェクトを指定します。バリデーションをおこなたいときは is_valid()、モデルオブジェクトを永続化したいときは save() メソッドを実行します。

>>> from api.serializers import BookSerializer
>>> serializer = BookSerializer(data={'title': 'DRFの本', 'price': 1000})
>>> serializer.is_valid()
True
>>> serializer.validated_data
OrderedDict([('title', 'DRFの本'), ('price', 1000)])
>>> book = serializer.save()

>>> serializer = BookSerializer(instance=book, data={'price': 2000}, partial=True)
>>> serializer.is_valid()
True
>>> serializer.save()
<Book: DRFの本>




ポイント②のまとめです。モデルと紐付いた REST API の場合は ModelSerializer を使うのが簡単で、その使い方は ModelForm とほぼ同じです。




 

ポイント③:起点は DRF 用ビュー

最後のポイント「起点は DRF 用ビュー」について。



DRF には「rest_framework.views.APIView」というクラスが用意されているのですが、「APIView」は DRF の起点となる基底ビュークラスで、これを継承することで、さまざまな前処理と後処理をやってくれます。

1. リクエストオブジェクトを DRF 用に変換
2. レンダラクラスとメディアタイプを決定
3. バージョニング
4. 認証チェック
5. パーミッションチェック
6. スロットリング
7. 例外ハンドリング

これらの処理は差し替え可能です。2. 〜 6. には代表的な処理クラスがいくつか用意されていて、デフォルトの設定を設定ファイル(settings.py)の「REST_FRAMEWORK」で上書きして全体的な設定をしたり、クラス変数をオーバーライドしてビュークラス単位での個別設定をしたりすることができます。






DRF 用のビューは大きく分けて3種類あり、用途に応じて

1)rest_framework.views.APIView
2)rest_framework.generics.CreateAPIView などの 汎用 APIView
3)rest_framework.viewsets.ModelViewSet 系ビュー

のいずれかを継承して作成します。 どれを選択するかによってそれぞれカスタム性やコード量が異なってきますが、この後で具体的な実装を見ながら説明していきます(コードがたくさん出てきますが、雰囲気を理解してもらえれば大丈夫です)。

ちなみに下の図で示すように、2) と 3) のビューは「APIView」の子クラスで、APIView は「基本汎用ビュー」と呼ばれる Django の「View」クラスの子クラスです。







まず、1)の APIView を継承したビューの書き方について説明します。

例えば、更新 API で呼び出される post メソッドでは、モデルオブジェクトと入力データからシリアライザオブジェクトを作成し、is_valid() で入力データのバリデーションをおこない、save() でモデルオブジェクトを更新して、最後にシリアライザの data 属性の値を使ってレスポンスオブジェクトを作成して返しています。

api/views.py

from rest_framework import status, views
from rest_framework.generics import get_object_or_404
from rest_framework.response import Response

from shop.models import Book
from .serializers import BookSerializer


class BookRetrieveUpdateAPIView(views.APIView):
    """本モデルの取得(詳細)・更新APIクラス"""

    def get(self, request, pk, *args, **kwargs):
        """本モデルの取得(詳細)APIに対応するハンドラメソッド"""

        # モデルオブジェクトを取得
        book = get_object_or_404(Book, pk=pk)
        # シリアライザオブジェクトを作成
        serializer = BookSerializer(instance=book)
        return Response(serializer.data, status.HTTP_200_OK)

    def put(self, request, pk, *args, **kwargs):
        """本モデルの更新APIに対応するハンドラメソッド"""

        # モデルオブジェクトを取得
        book = get_object_or_404(Book, pk=pk)
        # シリアライザオブジェクトを作成
        serializer = BookSerializer(instance=book, data=request.data)
        # バリデーションを実行
        serializer.is_valid(raise_exception=True)
        # モデルオブジェクトを更新
        serializer.save()
        # レスポンスオブジェクトを作成して返す
        return Response(serializer.data, status.HTTP_200_OK)

コードは長くなりますが、好きなように書くことができます。しかし、単一リソースの CRUD 処理をする場合、モデルとシリアライザだけが違うビューを追加する場合に同じようなコードを何度も書くのはさすがに冗長ですよね。






そんな場合に利用したいのが、2)の「汎用 APIView」です。上の表に示したように、対応アクションごとにいろいろな汎用 APIView が用意されているので、用途に合わせてどれかを継承して、モデルオブジェクトを取得するためのクエリを指定するための「queryset」とシリアライザクラスを指定するための「serializer_class」をクラス変数を加えるだけです。

これでだいぶ短く書くことができますが、単一モデルのCRUD処理をするというのを逸脱した API を作ろうとすると、親クラスのメソッドをオーバーライドして拡張する必要があります。


api/views.py

from rest_framework import generics

from shop.models import Book
from .serializers import BookSerializer


class BookListCreateAPIView(generics.ListCreateAPIView):
    """本モデルの取得(一覧)・登録APIクラス"""

    queryset = Book.objects.all()
    serializer_class = BookSerializer


class BookRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
    """本モデルの取得(詳細)・更新・一部更新・削除APIクラス"""

    queryset = Book.objects.all()
    serializer_class = BookSerializer

config/urls.py

from django.urls import path
from api import views

urlpatterns = [
    path('api/books/', views.BookListCreateAPIView.as_view()),
    path('api/books/<pk>/', views.BookRetrieveUpdateDestroyAPIView.as_view()),
]




最後に、3)ModelViewSet 系ビューを継承したビューの書き方です。冒頭で「単一リソースの CRUD を処理する REST API なら超簡単」で「20行くらいで API が全部書ける」と言っていたのはこちらです。

上の表に書いたように ModelViewSet は「一覧」「詳細」「登録」「更新」「一部更新」「削除」という6つの API を全部網羅しています。 実装は、下に示したように ModelViewSet を継承して、「serializer_class」と「queryset」の指定をするだけです。

api/views.py

from rest_framework import viewsets

from shop.models import Book
from .serializers import BookSerializer


class BookViewSet(viewsets.ModelViewSet):
    """本モデルのCRUD用APIクラス"""

    serializer_class = BookSerializer
    queryset = Book.objects.all()


あとは、ViewSet 用の SimpleRouter(または DefaultRouter)を利用して URL パターンを URLconf に追加してあげれば、これで API の実装は完了です。シリアライザを含めて最短20行ほどで書くことができます。

config/urls.py

from django.urls import include, path
from rest_framework import routers
from api import views

router = routers.DefaultRouter()
router.register('books', api.BookViewSet)

urlpatterns = [
    # すべてのアクション(一覧・詳細・登録・更新・一部更新・削除)をまとめて追加
    path('api/', include(router.urls)),
]

なので、単一モデルの CRUD を処理する REST API をまるっと実装したいというニーズには「ModelViewSet」が一番最速で実装できる ということになります。






ポイント③のまとめです。単一モデルの CRUD を処理する REST API をまるっと実装したい場合は ModelViewSet 系ビューを使うのが一番簡単で、複雑なことがしたい場合は APIView(または GenericAPIView)を継承したビュークラスを使うのがよいでしょう。



 

まとめ

最後のまとめです。



DRFを使う場合、Django に DRF の要素、コンポーネントが加わることになるので複雑になります。なのでまずは、全体像を把握しましょう。一見複雑にみえますが、新しい要素は「シリアライザ」と「DRF用ビュー」です。

「シリアライザ」は入力データのバリデーション、内部に保持したモデルオブジェクトの永続化、出力データの作成を担当するクラスで、Django のフォームと同じような使い方ができます。

「DRF用ビュー」は大きく3種類あり、まるっと API 全部を実装できてしまうものもあれば、複雑なカスタム API にも対応できるものもあるので、用途に合わせて親クラスと書き方を使い分けてください。


さてこれで、DRF がどんなものか完全に理解できたでしょうか。もっと DRF のことを深く知りたいという方は、「現場で使える Django REST Framework の教科書」という 220ページ以上まるまる DRF について書かれた素敵な本があるので、そちらを読んでみてください。ここで説明した内容をもっとディープに解説しています。そして何と、今月この本が改訂予定です。Django 3.2 LTS、DRF 3.14 対応で、Vue 3(+ Vite)と Vuetify 3 でチュートリアルを刷新しています。




トークのスライドはこちらにアップしています。

speakerdeck.com




 

宣伝

Django の技術同人誌をこれまでに4冊出しました。開発のお供にどうぞ。



現場で使える Django の教科書《基礎編》

「現場で使える Django の教科書」シリーズ第1弾となる Django の技術同人誌。Django を現場で使うための基礎知識やベストプラクティスについて、初心者・初級者向けに解説した本です。B5・本文192ページ。最新の Django 3.2 LTS に対応。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django の教科書《実践編》

《基礎編》の続編にあたる「現場で使える Django の教科書」シリーズの第2弾。認証まわり、ファイルアップロード、ユニットテスト、デプロイ、セキュリティ、高速化など、さらに実践的な内容に踏み込んでいます。現場で Django を本格的に活用したい、あるいはすでに活用している方にピッタリの一冊。B5・本文180ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django REST Framework の教科書

Django で REST API を構築する際の鉄板ライブラリである「Django REST Framework」(通称「DRF」)にフォーカスした、「現場で使える Django の教科書」シリーズの第3弾。B5・本文220ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django 管理サイトのつくり方

Django の管理サイト(Django Admin)だけに特化した、ニッチでオンリーワンな一冊。管理サイトをカスタマイズする前に絶対に読んでほしい本です。B5・本文152ページ。


★ Amazon(電子版)


★ BOOTH(紙の本)

Django 組み込みのパスワード再設定(パスワードリセット)の仕組み

この投稿は 「Calendar for Django | Advent Calendar 2021 - Qiita」 1日目の記事です。


akiyoko です。
この記事では、Django 組み込みで提供されているパスワード再設定(パスワードリセット)の仕組みを深掘りします。 Django のパスワード再設定機能に関しては、利用方法についてはさまざまな記事で紹介されていたりするのですが、その内部仕様について詳しく紹介した記事をあまり見かけたことがなかったので、自分のメモがてら残しておこうと思い、ほぼ一年ぶりに筆を執りました。何かのお役に立てば幸いです。




検証環境

  • Django 3.2


 

はじめに

Django は Webアプリケーションを作成するために必要な機能が何でも揃っているフルスタックフレームワークで、ユーザー認証まわりの機能(ユーザーモデル、パーミッション、ユーザーセッションなど)などの便利な機能がデフォルトで用意されています。そしてあまりよく知られていませんが、パスワード再設定(パスワードリセット)機能(で利用できるビューやフォーム)もユーザー認証まわりの機能の一部として「django.contrib.auth(認証システム)」パッケージに含まれています。

なお、「django.contrib.admin(管理サイト)」パッケージにはパスワード再設定系のテンプレートが用意されているので、管理サイト内でパスワード再設定機能を利用するのは非常に簡単です。


 

管理サイトでのパスワード再設定機能の利用方法

管理サイトではパスワード再設定系の機能はデフォルトでオフになっているため、利用するには次のように URLconf にパスワード再設定用の4つの URLパターンを追加しなければいけません(詳しくは公式ドキュメント *1 を参照)。

config/urls.py(URLconf)

from django.contrib import admin
from django.contrib.auth import views as auth_views
from django.urls import path

urlpatterns = [
    path('admin/password_reset/', auth_views.PasswordResetView.as_view(), name='admin_password_reset'),
    path('admin/password_reset/done/', auth_views.PasswordResetDoneView.as_view(), name='password_reset_done'),
    path('reset/<uidb64>/<token>/', auth_views.PasswordResetConfirmView.as_view(), name='password_reset_confirm'),
    path('reset/done/', auth_views.PasswordResetCompleteView.as_view(), name='password_reset_complete'),
    path('admin/', admin.site.urls),
]


上で示した「admin_password_reset」というURLパターンが登録されていれば、管理サイトのログイン画面に、次のように「パスワードまたはユーザー名を忘れましたか?」というリンクが表示されるようになります。


f:id:akiyoko:20211127070253p:plain:w350


この追加設定により、次のような画面遷移ができます。

f:id:akiyoko:20211128090512p:plain


それぞれの挙動は参考情報に示したビューやフォームを読めば分かるのですが、ちょっと理解しずらいのが「パスワード再設定メール」の仕組みです。


パスワード再設定メールの仕組み


f:id:akiyoko:20211128100012p:plain:w450

パスワード再設定メール送信画面で「パスワードをリセット」ボタンを押下すると、django.contrib.auth.views.PasswordResetView がリクエストを受け取り、入力したメールアドレスに紐付くアクティブ(is_active が True)なユーザーが存在する場合にのみパスワード再設定用のメールが送信されます。

例えばホストが「127.0.0.1:8000」の場合のパスワード再設定メールは次のようになります。

Subject: 127.0.0.1:8000 のパスワードリセット
From: webmaster@localhost
To: admin@example.com
Date: Fri, 26 Nov 2021 21:47:26 -0000
Message-ID: 
 <163796324660.443.3589748126282107509@1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa>
このメールは 127.0.0.1:8000 で、あなたのアカウントのパスワードリセットが要求されたため、送信されました。
次のページで新しいパスワードを選んでください:
http://127.0.0.1:8000/reset/MQ/awrev2-3a07a0471392cfbc3b885b713b2846d5/
あなたのユーザー名 (もし忘れていたら): admin
ご利用ありがとうございました!
 127.0.0.1:8000 チーム

メール本文にはパスワード再設定画面に遷移するためのリンクが含まれており、リンクの有効期限はデフォルトでは3日間となっています。*2


このリンクの URL は、「password_reset_confirm」という URL パターンで URLconf に登録されている「reset/<uidb64>/<token>/」に相当します。<uidb64>の部分、すなわち上のメールの例の「MQ」は、Base64 でエンコードされたユーザーの PK で、Base64 でデコードすると「1」になります。

<token>の「-」の左側の部分(上の例では「awrev2」)は、メール送信時のタイムスタンプ(2001/1/1 00:00:00 からの経過秒数)を Base34 でエンコードしたもので、リンクの有効期限をチェックするために使われます。残りの右側の部分(上の例では「3a07a0471392cfbc3b885b713b2846d5」)は改ざん防止のためのハッシュです。*3


django.contrib.auth.views.PasswordResetConfirmView では、パスワード再設定URL のリクエストを受け取ると、URL の妥当性(ユーザーが存在するかどうか、URL が改ざんされていないかどうか、有効期限を過ぎていないか)が検証され、「/reset/<uidb64>/set-password/」にリダイレクトされてパスワード再設定画面が表示されます。


f:id:akiyoko:20211128111830p:plain:w450

ちなみに、URL の<token>は(ハッシュ化された)パスワード文字列などから生成されているため(下記参照)、パスワード再設定によってパスワードが変更された後は同じ URL は利用できなくなります。

django.contrib.auth.tokens.PasswordResetTokenGenerator._make_hash_value

    def _make_hash_value(self, user, timestamp):
        """
        Hash the user's primary key, email (if available), and some user state
        that's sure to change after a password reset to produce a token that is
        invalidated when it's used:
        1. The password field will change upon a password reset (even if the
           same password is chosen, due to password salting).
        2. The last_login field will usually be updated very shortly after
           a password reset.
        Failing those things, settings.PASSWORD_RESET_TIMEOUT eventually
        invalidates the token.

        Running this data through salted_hmac() prevents password cracking
        attempts using the reset token, provided the secret isn't compromised.
        """
        # Truncate microseconds so that tokens are consistent even if the
        # database doesn't support microseconds.
        login_timestamp = '' if user.last_login is None else user.last_login.replace(microsecond=0, tzinfo=None)
        email_field = user.get_email_field_name()
        email = getattr(user, email_field, '') or ''
        return f'{user.pk}{user.password}{login_timestamp}{timestamp}{email}'


f:id:akiyoko:20211128111923p:plain:w450


 

まとめ

Django はパスワード再設定(パスワードリセット)機能を組み込みで提供しており、管理サイト内でパスワード再設定機能を利用するのは非常に簡単です。管理サイト外でパスワード再設定を利用する場合は、「django.contrib.auth(認証システム)」パッケージのビューやフォームを使用し、「django.contrib.admin(管理サイト)」パッケージのテンプレートを参考にすればよいでしょう。

パスワード再設定系のビューやフォーム、テンプレートについては次の参考情報をご確認ください。


 

参考情報

パスワード再設定系のビュー・フォーム

  • django.contrib.auth.views.PasswordResetView
  • django.contrib.auth.views.PasswordResetDoneView
  • django.contrib.auth.views.PasswordResetConfirmView
  • django.contrib.auth.views.PasswordResetCompleteView
  • django.contrib.auth.forms.PasswordResetForm
  • django.contrib.auth.forms.SetPasswordForm

パスワード再設定系のテンプレート

  • django/contrib/admin/templates/registration/password_reset_form.html
  • django/contrib/admin/templates/registration/password_reset_done.html
  • django/contrib/admin/templates/registration/password_reset_confirm.html
  • django/contrib/admin/templates/registration/password_reset_complete.html

(メールタイトル・本文のテンプレート)

  • django/contrib/auth/templates/registration/password_reset_subject.txt
  • django/contrib/admin/templates/registration/password_reset_email.html


 

宣伝

Django の技術同人誌をこれまでに4冊出しました。開発のお供にどうぞ。



現場で使える Django の教科書《基礎編》

「現場で使える Django の教科書」シリーズ第1弾となる Django の技術同人誌。Django を現場で使うための基礎知識やベストプラクティスについて、初心者・初級者向けに解説した本です。B5・本文192ページ。最新の Django 3.2 LTS に対応。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django の教科書《実践編》

《基礎編》の続編にあたる「現場で使える Django の教科書」シリーズの第2弾。認証まわり、ファイルアップロード、ユニットテスト、デプロイ、セキュリティ、高速化など、さらに実践的な内容に踏み込んでいます。現場で Django を本格的に活用したい、あるいはすでに活用している方にピッタリの一冊。B5・本文180ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django REST Framework の教科書

Django で REST API を構築する際の鉄板ライブラリである「Django REST Framework」(通称「DRF」)にフォーカスした、「現場で使える Django の教科書」シリーズの第3弾。B5・本文220ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django 管理サイトのつくり方

Django の管理サイト(Django Admin)だけに特化した、ニッチでオンリーワンな一冊。管理サイトをカスタマイズする前に絶対に読んでほしい本です。B5・本文152ページ。


★ Amazon(電子版)


★ BOOTH(紙の本)

*1:https://docs.djangoproject.com/ja/3.2/ref/contrib/admin/#adding-a-password-reset-feature

*2:有効期限をデフォルトの3日間から変更したい場合は、「PASSWORD_RESET_TIMEOUT」を設定ファイルに定義することで変更可能です。なお、Django 2.2 以前で利用されていた「PASSWORD_RESET_TIMEOUT_DAYS」は非推奨になっており、Django 4.0 で削除される予定です。https://docs.djangoproject.com/en/3.2/internals/deprecation/#deprecation-removed-in-4-0

*3:ハッシュ化アルゴリズムには Django 3.1 以降でデフォルトになった「sha256」が使われています。

Django REST Framework で API ドキュメンテーション機能を利用する方法(DRF 3.12 最新版)

この投稿は 「Django Advent Calendar 2020 - Qiita」 8日目の記事です。


akiyoko です。
この記事では、Django REST Framework(通称「DRF」)で API スキーマを自動生成する「API ドキュメンテーション」機能を簡単に利用する方法について説明します。


f:id:akiyoko:20201208093319p:plain:w600




検証環境

  • Windows 10 Home
  • Django 3.1
  • Django REST Framework 3.12



 

はじめに

Django REST Framework には、API スキーマ(どのような URL にどのようなリクエストを送ればどのようなレスポンスが返ってくるかという API の定義を記述したもの)を出力してくれる「API ドキュメンテーション」機能が備わっています。



DRF 公式ドキュメント


API スキーマの仕様は「OpenAPI 3.0」に準拠しています。「OpenAPI 3.0」は、REST API インタフェース記述の標準化を目指して Swagger 2.0 を統合して策定された仕様です。

swagger.io


OpenAPI スキーマファイル(YAML形式)の例を次に示します。

openapi: "3.0.0"
info:
  title: Simple API overview
  version: 2.0.0
paths:
  /:
    get:
      operationId: listVersionsv2
      summary: List API versions
      responses:
        '200':
          description: |-
            200 response
          content:
            application/json:
              examples: 
                foo:
                  value:
                    {
                      "versions": [
                        {
                            "status": "CURRENT",
                            "updated": "2011-01-21T11:33:21Z",
                            "id": "v2.0",
                            "links": [
                                {
                                    "href": "http://127.0.0.1:8774/v2/",
                                    "rel": "self"
                                }
                            ]
                        },
                        {
                            "status": "EXPERIMENTAL",
                            "updated": "2013-07-23T11:33:21Z",
                            "id": "v3.0",
                            "links": [
                                {
                                    "href": "http://127.0.0.1:8774/v3/",
                                    "rel": "self"
                                }
                            ]
                        }
                      ]
                    }

...(略)...

https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/api-with-examples.yaml より引用



 

DRF 3.12 の状況

現在の最新バージョンの DRF 3.12 で OpenAPI 3.0 に準拠した API スキーマを出力する方法として、筆者は次の二つの方法を推奨します。ひとつは DRF 標準の generateschema コマンドを使って OpenAPIスキーマファイルを出力する方法、もうひとつは 「drf-spectacular」というサードパーティ製パッケージを使う方法 です。 *1



ちなみに、DRF で API スキーマを出力するにはこれまで「CoreAPI」ベースの「rest_framework.schemas.coreapi.AutoSchema」を使うのがデフォルトだったのですが、これは DRF 3.10 で非推奨になり、DRF 3.12 以降で削除予定となっています。*2
なおこの記事を書いている時点ではまだ削除はされていないようですが、今後いつ削除されるとも分かりません。

Django REST Framework v3.10 でネイティブな OpenAPI ベースのスキーマ生成が導入されたことにより、CoreAPI ベースのスキーマの使用は非推奨となりました。

Django REST Framework v3.12 で CoreAPI 関連のコードはすべて削除されます。それまでに OpenAPI スキーマに切り替えてください。

https://www.django-rest-framework.org/coreapi/ の内容を抜粋して翻訳)



本記事では、DRF 3.12 で OpenAPI 3.0 に準拠した API スキーマを出力する方法として

  • 【方法1】generateschema コマンドを使って OpenAPIスキーマファイルを出力する方法
  • 【方法2】drf-spectacular を利用する方法

について紹介します。


 

【方法1】DRF 標準の generateschema コマンドを使ってスキーマファイルを出力する

DRF 標準の generateschema コマンドを使って OpenAPI スキーマファイルを出力するには、PyYAML パッケージと uritemplate パッケージが必要です。


そこで、次のようにして PyYAML と uritemplate をそれぞれインストールします。

(venv) > pip install PyYAML==5.3.* uritemplate==3.0.*


次のように generateschema コマンドを実行すれば、OpenAPI 3.0 に対応した YAML形式のスキーマファイルを出力することができます。ちなみに format オプションで「openapi-json」を指定すれば、JSON 形式のファイルを出力することも可能です。

(venv) > python manage.py generateschema --file schema.yml


コマンドを実行すると、次のようなスキーマファイルが出力されます。

openapi: 3.0.2
info:
  title: ''
  version: ''
paths:
  /api/v0/books/:
    get:
      operationId: listBookListCreates
      description: "\u672C\u30E2\u30C7\u30EB\u306E\u53D6\u5F97\uFF08\u4E00\u89A7\uFF09\
        API\u306B\u5BFE\u5FDC\u3059\u308B\u30CF\u30F3\u30C9\u30E9\u30E1\u30BD\u30C3\
        \u30C9"
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items: {}
          description: ''
      tags:
      - api

      ...(略)...



出力したスキーマファイルを、OpenAPI に対応した Swagger EditorSwagger Inspector などのツールに読み込ませて、ツール上で API の定義を確認したり、API クライアント(API へのリクエストを実行できるツール)として利用したりすることができます。



オンライン API ドキュメントエディタ Swagger Editor の画面例


f:id:akiyoko:20201202234527p:plain:w500


Swagger Inspector の画面例


f:id:akiyoko:20201202234559p:plain:w500


このほかにも OpenAPI スキーマファイルが利用できるツールは多数存在します。

openapi.tools


公式ドキュメント では、URLconf やテンプレートの準備をして Swagger UI と ReDoc の二種類の API ドキュメント画面を表示させる方法を紹介していますが、次に示す drf-spectacular を利用する方が簡単なので筆者はそちらを推します(公式ドキュメントでも代替案として drf-spectacular を紹介しています)。



 

【方法2】drf-spectacular を利用する

これまで DRF で標準になっていた CoreAPI ベースの「AutoSchema」を使えば、次のような API ドキュメント画面を簡単に構築することができました。*3


f:id:akiyoko:20201204000317p:plain:w450

しかし先述のように、CoreAPI ベースの「AutoSchema」の利用は非推奨になってしまいました。そこで、代わりに「drf-spectacular」を利用すれば、OpenAPI 3.0 準拠の API スキーマファイルを出力できるのに加えて、Swagger UI 形式と ReDoc 形式の二種類の API ドキュメント画面を自動生成することができます。

 

導入方法

導入方法はほぼ 公式ドキュメント に書いてある通りです。


まず、drf-spectacular をインストールします。*4

(venv) > pip install drf-spectacular==0.12.*


次に、設定ファイルの「INSTALLED_APPS」に「drf_spectacular」を追加し、「REST_FRAMEWORK」の「DEFAULT_SCHEMA_CLASS」に「drf_spectacular.openapi.AutoSchema」を設定します。


config/settings.py(設定ファイル)

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # 3rd party apps
    'drf_spectacular',  # 追加

    ...
]

...

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',  # 追加
}


OpenAPI スキーマファイルを出力するだけなら設定はここまでで OK です。コマンドプロンプトから spectacular コマンドを使えば、API スキーマファイルを出力することができます。

(venv) > python manage.py spectacular --file schema.yml



APIドキュメント画面を自動生成したいのであれば、続けて URLconf に次の設定を書き加えます。ちなみに、DEBUG が False の場合にのみ APIドキュメント画面を表示できるようにしています。


config/urls.py(URLconf)

from django.urls import include, path
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView  # 追加

urlpatterns = [
    ...(略)...
]

if settings.DEBUG:
    urlpatterns += [
        path('api/schema/', SpectacularAPIView.as_view(), name='schema'),                                      # 追加
        path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),  # 追加
        path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),              # 追加
    ]


 

Swagger UI 形式の APIドキュメント画面

設定完了後に runserver を起動し、(起動 URL が「127.0.0.1:8000」の場合)ブラウザで「http://127.0.0.1:8000/api/schema/swagger-ui/」にアクセスすれば、Swagger UI 形式の APIドキュメント画面が表示できます。


f:id:akiyoko:20201202231159p:plain:w550


API ごとの「Try it out」ボタンをクリックして、「Parameters」を適宜入力して「Execute」ボタンをクリックすることでリクエストを送信することができるので、API クライアントとしても利用することができます。



 

ReDoc 形式の APIドキュメント画面

ReDoc 形式の APIドキュメント画面(http://127.0.0.1:8000/api/schema/redoc/)は次のようになります。


f:id:akiyoko:20201202232040p:plain:w550




 

カスタマイズ

これでよいかと思いきや、ちょっとしたカスタマイズが必要な箇所もあります。

例えば、ListAPIView や RetrieveAPIView などの汎用 APIView 系ビューや ModelViewSet 系ビューなど(クラス変数 serializer_class を指定するもの)は入出力のパラメータが自動判定されるのですが、APIView を継承しているビューではドキュメンテーションが不完全になります。その場合は、extend_schema でドキュメンテーション用の追加設定をしてあげる必要があります。


apiv0/views.py(ビュー)

from drf_spectacular.utils import extend_schema
from rest_framework import status, views
from rest_framework.response import Response

from shop.models import Book
from .serializers import BookSerializer


class BookListCreateAPIView(views.APIView):
    """本モデルの取得(一覧)・登録APIクラス"""

    @extend_schema(
        responses={200: BookSerializer},
    )
    def get(self, request, *args, **kwargs):
        """本モデルの取得(一覧)APIに対応するハンドラメソッド"""

        ...(略)...

        return Response(serializer.data, status.HTTP_200_OK)

    @extend_schema(
        request=BookSerializer,
        responses={201: BookSerializer},
    )
    def post(self, request, *args, **kwargs):
        """本モデルの登録APIに対応するハンドラメソッド"""

        ...(略)...

        return Response(serializer.data, status.HTTP_201_CREATED)


他にもいろいろ追加設定ができますが、詳細については公式ドキュメントを参照してください。

Settings — drf-spectacular documentation





 

まとめ

Django REST Framework(DRF)にはデフォルトで OpenAPI 3.0 に対応した API スキーマを出力してくれる「API ドキュメンテーション」機能が備わっています。利用方法は簡単で、generateschema コマンドでスキーマファイルを出力するだけです(ただし、PyYAML と uritemplate のインストールが必要)。


API スキーマをリアルタイムに反映した API ドキュメント画面を表示したいのであれば、drf-spectacular パッケージを利用するのが簡単です。なお、DRF 3.12 以降は、DRF 3.10 までで標準だった CoreAPI ベースの APIドキュメント画面が利用できなくなるので注意が必要です。



 

宣伝

Django の技術同人誌をこれまでに4冊出しました。開発のお供にどうぞ。



現場で使える Django の教科書《基礎編》

「現場で使える Django の教科書」シリーズ第1弾となる Django の技術同人誌。Django を現場で使うための基礎知識やベストプラクティスについて、初心者・初級者向けに解説した本です。B5・本文192ページ。最新の Django 3.2 LTS に対応。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django の教科書《実践編》

《基礎編》の続編にあたる「現場で使える Django の教科書」シリーズの第2弾。認証まわり、ファイルアップロード、ユニットテスト、デプロイ、セキュリティ、高速化など、さらに実践的な内容に踏み込んでいます。現場で Django を本格的に活用したい、あるいはすでに活用している方にピッタリの一冊。B5・本文180ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django REST Framework の教科書

Django で REST API を構築する際の鉄板ライブラリである「Django REST Framework」(通称「DRF」)にフォーカスした、「現場で使える Django の教科書」シリーズの第3弾。B5・本文220ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django 管理サイトのつくり方

Django の管理サイト(Django Admin)だけに特化した、ニッチでオンリーワンな一冊。管理サイトをカスタマイズする前に絶対に読んでほしい本です。B5・本文152ページ。


★ Amazon(電子版)


★ BOOTH(紙の本)

*1:サードパーティ製パッケージとしては「drf-yasg」も有名ですが、README にも書かれている通り、OpenAPI 3.0 には当分対応しないとのことなので検討を除外しています。

*2:DRF 3.10 以降はデフォルトで OpenAPI ベースの「rest_framework.schemas.openapi.AutoSchema」を使う設定になっているので、追加設定は特に必要ありません。

*3:https://www.django-rest-framework.org/coreapi/

*4:依存パッケージの PyYAML と uritemplate もインストールされます。

Django でデータベースビューを扱う方法(初級者向け)

この投稿は 「Django Advent Calendar 2020 - Qiita」 5日目の記事です。


akiyoko です。
この記事では、Django でデータベースビューを扱う方法について説明します。「Django のコンポーネントとしてのビュー(View)」ではなく、「データベースのビュー」の話です。本記事では区別のために「データベースビュー」と表記することにします。



f:id:akiyoko:20201205082412p:plain:w350




検証環境

  • Windows 10 Home
  • Django 3.1
  • PostgreSQL 13.1



 

はじめに

あまり知られていないかもしれませんが、Django でもデータベースビューを扱うことができます。 具体的には、データベースビューに対応するモデルを用意することで、データベースビューのレコードをモデルオブジェクトとして取り扱うことができます(しかし当然ながら、データベースビューへのレコードの登録や更新、削除はできませんのでご注意を)。



ところで、データベースビューを使うと何が嬉しいのでしょうか?

例えば、テーブルの結果を 集計 したり、サブクエリ を使ったり、複数のテーブルを UNION したりするには、Django ORM の API を使って実現できないこともありませんが、コードが複雑になり、思わぬバグが混入する可能性が高くなってしまいます。それならいっそのこと SQL で書いてしまう方が早くて確実だというケースもあるでしょう。そんなときにデータベースビューを使えば、モデル側のコードをすっきりさせることができるのです。 *1




 

データベースビューに対応するモデル

通常のモデルとの違いは、Meta に「managed = False」を指定するだけです。これで、モデルをマイグレーションの対象外にすることができます。 *2


次の例を見てください。

sales/models.py(モデル)

from django.db import models


class SalesResultPerMonth(models.Model):
    class Meta:
        managed = False
        db_table = 'sales_result_per_month'
        verbose_name = verbose_name_plural = '月別合計売上金額'

    sales_month = models.DateField('売上月')
    total_amount = models.PositiveIntegerField('合計売上金額')
    target_amount = models.PositiveIntegerField('目標売上金額')


モデルの Meta クラスに「managed = False」を指定しています。ちなみにデータベースビューに対応したモデルには「null=True」や「blank=True」などのフィールドオプションは付ける必要はありません。データベースビューには登録や更新ができないため、付けてもあまり意味がないからです。



モデルをマイグレーションの対象外にすると、マイグレーション(migrate)コマンドを実行したときにマイグレーションファイルの内容がデータベースのテーブルに反映されず、テーブルが新たに作成されたり、テーブル構造が変更されたりすることがなくなります。


f:id:akiyoko:20201205100932p:plain:w550



 

具体例

簡単な例として、売上実績テーブルから月次の売上金額の合計を集計して、売上目標テーブルの売上目標金額と比較することを取り上げてみます。これをデータベースビューとして利用するイメージは次のようになります。


f:id:akiyoko:20201201094402p:plain


通常のモデルを作成する

まず、sales アプリケーションに「売上目標モデル」と「売上実績モデル」を次のように定義します。これらはマイグレーション対象となる通常のモデルです。

sales/models.py(モデル)

from django.db import models


class SalesTarget(models.Model):
    """売上目標モデル"""

    class Meta:
        db_table = 'sales_target'
        verbose_name = verbose_name_plural = '売上目標'

    sales_month = models.DateField('売上月')
    amount = models.PositiveIntegerField('目標金額')
    created_at = models.DateTimeField('登録日時', auto_now_add=True)

    def __str__(self):
        return f'{self.sales_month:%Y年%m月}'


class SalesResult(models.Model):
    """売上実績モデル"""

    class Meta:
        db_table = 'sales_result'
        verbose_name = verbose_name_plural = '売上実績'

    sales_date = models.DateField('売上日')
    amount = models.PositiveIntegerField('売上金額')
    subject = models.CharField('件名', max_length=255)
    created_at = models.DateTimeField('登録日時', auto_now_add=True)

    def __str__(self):
        return f'{self.sales_date:%Y年%m月%d日} - {self.subject}'


makemigrations コマンドでマイグレーションファイルを作成して、migrate コマンドでマイグレーションを実行すると、次のようなテーブルが作成されます。

(venv) > python manage.py makemigrations sales
(venv) > python manage.py migrate sales


f:id:akiyoko:20201201094218p:plain


データベースビュー作成用の DDL をマイグレーションファイルに書く

データベースビューを作成するための DDL は、マイグレーションファイルに書くのがよいでしょう。次のように「--empty」オプションを付けて makemigrations コマンドを実行すると、空のマイグレーションファイルを作成することができます。

(venv) $ python manage.py makemigrations sales --empty


上記のコマンドを実行すると、次のようなマイグレーションファイルが「sales/migrations」ディレクトリの下に生成されます。


sales/migrations/0002_auto_20201204_2134.py(マイグレーションファイル)

# Generated by Django 3.1.3 on 2020-12-04 12:34

from django.db import migrations


class Migration(migrations.Migration):

    dependencies = [
        ('sales', '0001_initial'),
    ]

    operations = [
    ]


このひな型ファイルを次のように編集して、sales_result_per_month ビューを作成する DDL を書き加えます。

# Generated by Django 3.1.3 on 2020-12-04 12:34

from django.db import migrations


class Migration(migrations.Migration):

    dependencies = [
        ('sales', '0001_initial'),
    ]

    sql = """
        CREATE VIEW sales_result_per_month AS
            SELECT
                ROW_NUMBER() OVER() AS id,
                t.sales_month,
                t.amount AS target_amount,
                SUM(r.amount) AS total_amount
            FROM
                sales_target t
            LEFT OUTER JOIN
                sales_result r
            ON
                TO_CHAR(t.sales_month, 'YYYY-MM') = TO_CHAR(r.sales_date, 'YYYY-MM')
            GROUP BY
                t.sales_month, t.amount
            ORDER BY
                t.sales_month;
    """

    reverse_sql = """
        DROP VIEW IF EXISTS sales_result_per_month;
    """

    operations = [
        migrations.RunSQL(sql, reverse_sql),
    ]

RunSQL の第一引数には migrate コマンドが実行されたときに発行する SQL を、第二引数には特定のバージョンのマイグレーションの状態に戻す *3 ときに発行する SQL を指定します(第二引数は省略可)。ちなみにこの SQL は PostgreSQL 向けのものです。


マイグレーションファイルを手動で書くやり方については、次の記事を参考にしてみてください。

参考



マイグレーションを実行すると、データベースビューが作成されます。

(venv) $ python manage.py migrate sales


pgAdmin 4 上で確認すると、このようになっています。


f:id:akiyoko:20201201114913p:plain



ビューに対応するモデルを作成する

sales_result_per_month ビューに対応するモデルを作成します。ここで Meta クラスに「managed = False」を指定します。繰り返しになりますが、これでマイグレーションの対象から外れます。


sales/models.py(モデル)

from django.db import models


class SalesTarget(models.Model):
    """売上目標モデル"""
    ...(略)...


class SalesResult(models.Model):
    """売上実績モデル"""
    ...(略)...


class SalesResultPerMonth(models.Model):  # 追加
    """月別合計売上金額モデル"""

    class Meta:
        managed = False
        db_table = 'sales_result_per_month'
        verbose_name = verbose_name_plural = '月別合計売上金額'

    sales_month = models.DateField('売上月')
    total_amount = models.PositiveIntegerField('合計売上金額')
    target_amount = models.PositiveIntegerField('目標売上金額')



モデルを作成する際には、次のように

(venv) > python manage.py inspectdb sales_result_per_month

inspectdb という既存のテーブルからモデルを自動生成する Django コマンドを実行した結果を参考にするとよいでしょう。


(出力結果例)

# This is an auto-generated Django model module.
# You'll have to do the following manually to clean this up:
#   * Rearrange models' order
#   * Make sure each model has one field with primary_key=True
#   * Make sure each ForeignKey and OneToOneField has `on_delete` set to the desired behavior
#   * Remove `managed = False` lines if you wish to allow Django to create, modify, and delete the table
# Feel free to rename the models, but don't rename db_table values or field names.
from django.db import models


class SalesResultPerMonth(models.Model):
    id = models.BigIntegerField(blank=True, null=True)
    sales_month = models.DateField(blank=True, null=True)
    target_amount = models.IntegerField(blank=True, null=True)
    total_amount = models.BigIntegerField(blank=True, null=True)

    class Meta:
        managed = False  # Created from a view. Don't remove.
        db_table = 'sales_result_per_month'



 

管理サイトでデータベースビューの内容を確認する

最後に、このデータベースビューの内容を管理サイト上で確認できるようにしてみましょう。sales/admin.py を次のように編集します。


sales/admin.py(管理サイト用モジュール)

from django.contrib import admin

from common.helpers.admin_helper import format_yen, format_yyyy_nen_mm_gatsu
from .models import SalesResult, SalesResultPerMonth, SalesTarget


class SalesResultAdmin(admin.ModelAdmin):
    """売上実績モデル用 ModelAdmin"""

    ###############################
    # モデル一覧画面のカスタマイズ
    ###############################
    list_display = ('sales_date', 'format_amount', 'subject')
    ordering = ('sales_date', 'created_at')

    def format_amount(self, obj):
        return format_yen(obj.amount)

    format_amount.short_description = '売上金額'
    format_amount.admin_order_field = 'amount'

    ###############################
    # モデル追加・変更画面のカスタマイズ
    ###############################
    readonly_fields = ('id', 'created_at')


class SalesTargetAdmin(admin.ModelAdmin):
    """売上目標モデル用 ModelAdmin"""

    ###############################
    # モデル一覧画面のカスタマイズ
    ###############################
    list_display = ('format_sales_month', 'format_amount')
    ordering = ('sales_month',)

    def format_sales_month(self, obj):
        return format_yyyy_nen_mm_gatsu(obj.sales_month)

    format_sales_month.short_description = '売上月'
    format_sales_month.admin_order_field = 'sales_month'

    def format_amount(self, obj):
        return format_yen(obj.amount)

    format_amount.short_description = '目標金額'
    format_amount.admin_order_field = 'amount'

    ###############################
    # モデル追加・変更画面のカスタマイズ
    ###############################
    readonly_fields = ('id', 'created_at')


class SalesResultPerMonthAdmin(admin.ModelAdmin):
    """月別合計売上金額モデル用 ModelAdmin"""

    ###############################
    # モデル一覧画面のカスタマイズ
    ###############################
    list_display = ('format_sales_month', 'format_target_amount', 'format_total_amount')
    ordering = ('sales_month',)

    def format_sales_month(self, obj):
        return format_yyyy_nen_mm_gatsu(obj.sales_month)

    format_sales_month.short_description = '売上月'
    format_sales_month.admin_order_field = 'sales_month'

    def format_target_amount(self, obj):
        return format_yen(obj.target_amount)

    format_target_amount.short_description = '目標売上金額'
    format_target_amount.admin_order_field = 'target_amount'

    def format_total_amount(self, obj):
        return format_yen(obj.total_amount)

    format_total_amount.short_description = '合計売上金額'
    format_total_amount.admin_order_field = 'total_amount'

    ###############################
    # その他のカスタマイズ
    ###############################
    def has_add_permission(self, request):
        return False

    def has_change_permission(self, request, obj=None):
        return False

    def has_delete_permission(self, request, obj=None):
        return False


admin.site.register(SalesTarget, SalesTargetAdmin)
admin.site.register(SalesResult, SalesResultAdmin)
admin.site.register(SalesResultPerMonth, SalesResultPerMonthAdmin)



管理サイトの月別合計売上金額モデルの一覧画面はこのように表示されます。


f:id:akiyoko:20201202105916p:plain:w500


何がどうなっているのか?が気になる方は、拙著『現場で使える Django 管理サイトのつくり方』にいろいろと書いてあるので、ぜひお手に取ってご確認くださいませ 🙇

akiyoko.hatenablog.jp



 

(おまけ)マイグレーションファイルの SQL を複数種類のデータベースに対応させる方法

例示したマイグレーションファイルの SQL は PostgreSQL だけにしか使えません。PostgreSQL を使うだけならこれでもよいのですが、ローカルでは SQLite を使って、本番環境では PostgreSQL を使って・・といったケースには対応できません。そのような場合は、RunPython を使って次のように書き分けることができます。

# Generated by Django 3.1.3 on 2020-12-04 12:34

from django.db import migrations
from django.db.migrations import exceptions


def code(apps, schema_editor):
    if schema_editor.connection.vendor == 'sqlite':
        schema_editor.execute("""
            CREATE VIEW sales_result_per_month AS
                SELECT
                    ROW_NUMBER() OVER() AS id,
                    t.sales_month,
                    t.amount AS target_amount,
                    SUM(r.amount) AS total_amount
                FROM
                    sales_target t
                LEFT OUTER JOIN
                    sales_result r
                ON
                    STRFTIME('%Y-%m', t.sales_month) = STRFTIME('%Y-%m', r.sales_date)
                GROUP BY
                    t.sales_month
                ORDER BY
                    sales_month;
        """)
    elif schema_editor.connection.vendor == 'postgresql':
        schema_editor.execute("""
            CREATE VIEW sales_result_per_month AS
                SELECT
                    ROW_NUMBER() OVER() AS id,
                    t.sales_month,
                    t.amount AS target_amount,
                    SUM(r.amount) AS total_amount
                FROM
                    sales_target t
                LEFT OUTER JOIN
                    sales_result r
                ON
                    TO_CHAR(t.sales_month, 'YYYY-MM') = TO_CHAR(r.sales_date, 'YYYY-MM')
                GROUP BY
                    t.sales_month, t.amount
                ORDER BY
                    t.sales_month;
        """)
    elif schema_editor.connection.vendor == 'mysql':
        schema_editor.execute("""
            CREATE VIEW sales_result_per_month AS
                SELECT
                    ROW_NUMBER() OVER() AS id,
                    t.sales_month,
                    t.amount AS target_amount,
                    SUM(r.amount) AS total_amount
                FROM
                    sales_target t
                LEFT OUTER JOIN
                    sales_result r
                ON
                    DATE_FORMAT(t.sales_month, '%Y-%m') = DATE_FORMAT(r.sales_date, '%Y-%m')
                GROUP BY
                    t.sales_month;
                ORDER BY
                    t.sales_month;
            """, params=None)
    else:
        raise exceptions.BadMigrationError(
            'Database vendor should be SQLite, PostgreSQL, or MySQL.')


def reverse_code(apps, schema_editor):
    schema_editor.execute('DROP VIEW IF EXISTS sales_result_per_month;')


class Migration(migrations.Migration):
    dependencies = [
        ('sales', '0001_initial'),
    ]

    operations = [
        migrations.RunPython(code, reverse_code, atomic=False)
    ]


 

まとめ

モデルの Meta クラスに「managed = False」を指定すると、マイグレーションの対象から外すことができるため、データベースビューに対応するモデルを作成することができます。


またこの方法を利用すれば、すでにあるテーブルに対応するモデルを作成することも可能です。いろいろ便利に使えそうですね!



 

宣伝

Django の技術同人誌をこれまでに4冊出しました。開発のお供にどうぞ。



現場で使える Django の教科書《基礎編》

「現場で使える Django の教科書」シリーズ第1弾となる Django の技術同人誌。Django を現場で使うための基礎知識やベストプラクティスについて、初心者・初級者向けに解説した本です。B5・本文192ページ。最新の Django 3.2 LTS に対応。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django の教科書《実践編》

《基礎編》の続編にあたる「現場で使える Django の教科書」シリーズの第2弾。認証まわり、ファイルアップロード、ユニットテスト、デプロイ、セキュリティ、高速化など、さらに実践的な内容に踏み込んでいます。現場で Django を本格的に活用したい、あるいはすでに活用している方にピッタリの一冊。B5・本文180ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django REST Framework の教科書

Django で REST API を構築する際の鉄板ライブラリである「Django REST Framework」(通称「DRF」)にフォーカスした、「現場で使える Django の教科書」シリーズの第3弾。B5・本文220ページ。


★ Amazon(電子版/ペーパーバック)


★ BOOTH(紙の本)



現場で使える Django 管理サイトのつくり方

Django の管理サイト(Django Admin)だけに特化した、ニッチでオンリーワンな一冊。管理サイトをカスタマイズする前に絶対に読んでほしい本です。B5・本文152ページ。


★ Amazon(電子版)


★ BOOTH(紙の本)

*1:モデルマネージャの raw() や django.db.connection.cursor オブジェクトの execute() を使えば、生の SQL を書くことも可能です。

*2:https://docs.djangoproject.com/ja/3.1/ref/models/options/#managed

*3:マイグレーション | Django ドキュメント | Django