CINXE.COM

<!DOCTYPE html> <html lang="en" data-content_root="../"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Class-based Views — Flask Documentation (3.1.x)</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=6625fa76" /> <link rel="stylesheet" type="text/css" href="../_static/flask.css?v=b87c8d14" /> <script src="../_static/documentation_options.js?v=d71c4578"></script> <script src="../_static/doctools.js?v=9bcbadda"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <link rel="canonical" href="https://flask.palletsprojects.com/en/stable/views/" /> <link rel="icon" href="../_static/shortcut-icon.png"/> <link rel="index" title="Index" href="../genindex/" /> <link rel="search" title="Search" href="../search/" /> <link rel="next" title="Application Structure and Lifecycle" href="../lifecycle/" /> <link rel="prev" title="Signals" href="../signals/" /> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="flask" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/views/" /><meta name="readthedocs-http-status" content="200" /></head><body> <div class="related" role="navigation" aria-label="Related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex/" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex/" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="../lifecycle/" title="Application Structure and Lifecycle" accesskey="N">next</a> |</li> <li class="right" > <a href="../signals/" title="Signals" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../">Flask Documentation (3.1.x)</a> »</li> <li class="nav-item nav-item-this"><a href="">Class-based Views</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="class-based-views"> <h1>Class-based Views<a class="headerlink" href="#class-based-views" title="Link to this heading">露</a></h1> This page introduces using the <a class="reference internal" href="../api/#flask.views.View" title="flask.views.View"><code class="xref py py-class docutils literal notranslate">View</code></a> and <a class="reference internal" href="../api/#flask.views.MethodView" title="flask.views.MethodView"><code class="xref py py-class docutils literal notranslate">MethodView</code></a> classes to write class-based views. A class-based view is a class that acts as a view function. Because it is a class, different instances of the class can be created with different arguments, to change the behavior of the view. This is also known as generic, reusable, or pluggable views. An example of where this is useful is defining a class that creates an API based on the database model it is initialized with. For more complex API behavior and customization, look into the various API extensions for Flask. <section id="basic-reusable-view"> <h2>Basic Reusable View<a class="headerlink" href="#basic-reusable-view" title="Link to this heading">露</a></h2> Let鈥檚 walk through an example converting a view function to a view class. We start with a view function that queries a list of users then renders a template to show the list. <div class="highlight-python notranslate"><div class="highlight"><pre>@app.route("/users/") def user_list(): users = User.query.all() return render_template("users.html", users=users) </pre></div> </div> This works for the user model, but let鈥檚 say you also had more models that needed list pages. You鈥檇 need to write another view function for each model, even though the only thing that would change is the model and template name. Instead, you can write a <a class="reference internal" href="../api/#flask.views.View" title="flask.views.View"><code class="xref py py-class docutils literal notranslate">View</code></a> subclass that will query a model and render a template. As the first step, we鈥檒l convert the view to a class without any customization. <div class="highlight-python notranslate"><div class="highlight"><pre>from flask.views import View class UserList(View): def dispatch_request(self): users = User.query.all() return render_template("users.html", objects=users) app.add_url_rule("/users/", view_func=UserList.as_view("user_list")) </pre></div> </div> The <a class="reference internal" href="../api/#flask.views.View.dispatch_request" title="flask.views.View.dispatch_request"><code class="xref py py-meth docutils literal notranslate">View.dispatch_request()</code></a> method is the equivalent of the view function. Calling <a class="reference internal" href="../api/#flask.views.View.as_view" title="flask.views.View.as_view"><code class="xref py py-meth docutils literal notranslate">View.as_view()</code></a> method will create a view function that can be registered on the app with its <a class="reference internal" href="../api/#flask.Flask.add_url_rule" title="flask.Flask.add_url_rule"><code class="xref py py-meth docutils literal notranslate">add_url_rule()</code></a> method. The first argument to <code class="docutils literal notranslate">as_view</code> is the name to use to refer to the view with <a class="reference internal" href="../api/#flask.url_for" title="flask.url_for"><code class="xref py py-func docutils literal notranslate">url_for()</code></a>. <div class="admonition note"> Note You can鈥檛 decorate the class with <code class="docutils literal notranslate">@app.route()</code> the way you鈥檇 do with a basic view function. </div> Next, we need to be able to register the same view class for different models and templates, to make it more useful than the original function. The class will take two arguments, the model and template, and store them on <code class="docutils literal notranslate">self</code>. Then <code class="docutils literal notranslate">dispatch_request</code> can reference these instead of hard-coded values. <div class="highlight-python notranslate"><div class="highlight"><pre>class ListView(View): def __init__(self, model, template): self.model = model self.template = template def dispatch_request(self): items = self.model.query.all() return render_template(self.template, items=items) </pre></div> </div> Remember, we create the view function with <code class="docutils literal notranslate">View.as_view()</code> instead of creating the class directly. Any extra arguments passed to <code class="docutils literal notranslate">as_view</code> are then passed when creating the class. Now we can register the same view to handle multiple models. <div class="highlight-python notranslate"><div class="highlight"><pre>app.add_url_rule( "/users/", view_func=ListView.as_view("user_list", User, "users.html"), ) app.add_url_rule( "/stories/", view_func=ListView.as_view("story_list", Story, "stories.html"), ) </pre></div> </div> </section> <section id="url-variables"> <h2>URL Variables<a class="headerlink" href="#url-variables" title="Link to this heading">露</a></h2> Any variables captured by the URL are passed as keyword arguments to the <code class="docutils literal notranslate">dispatch_request</code> method, as they would be for a regular view function. <div class="highlight-python notranslate"><div class="highlight"><pre>class DetailView(View): def __init__(self, model): self.model = model self.template = f"{model.__name__.lower()}/detail.html" def dispatch_request(self, id) item = self.model.query.get_or_404(id) return render_template(self.template, item=item) app.add_url_rule( "/users/<int:id>", view_func=DetailView.as_view("user_detail", User) ) </pre></div> </div> </section> <section id="view-lifetime-and-self"> <h2>View Lifetime and <code class="docutils literal notranslate">self</code><a class="headerlink" href="#view-lifetime-and-self" title="Link to this heading">露</a></h2> By default, a new instance of the view class is created every time a request is handled. This means that it is safe to write other data to <code class="docutils literal notranslate">self</code> during the request, since the next request will not see it, unlike other forms of global state. However, if your view class needs to do a lot of complex initialization, doing it for every request is unnecessary and can be inefficient. To avoid this, set <a class="reference internal" href="../api/#flask.views.View.init_every_request" title="flask.views.View.init_every_request"><code class="xref py py-attr docutils literal notranslate">View.init_every_request</code></a> to <code class="docutils literal notranslate">False</code>, which will only create one instance of the class and use it for every request. In this case, writing to <code class="docutils literal notranslate">self</code> is not safe. If you need to store data during the request, use <a class="reference internal" href="../api/#flask.g" title="flask.g"><code class="xref py py-data docutils literal notranslate">g</code></a> instead. In the <code class="docutils literal notranslate">ListView</code> example, nothing writes to <code class="docutils literal notranslate">self</code> during the request, so it is more efficient to create a single instance. <div class="highlight-python notranslate"><div class="highlight"><pre>class ListView(View): init_every_request = False def __init__(self, model, template): self.model = model self.template = template def dispatch_request(self): items = self.model.query.all() return render_template(self.template, items=items) </pre></div> </div> Different instances will still be created each for each <code class="docutils literal notranslate">as_view</code> call, but not for each request to those views. </section> <section id="view-decorators"> <h2>View Decorators<a class="headerlink" href="#view-decorators" title="Link to this heading">露</a></h2> The view class itself is not the view function. View decorators need to be applied to the view function returned by <code class="docutils literal notranslate">as_view</code>, not the class itself. Set <a class="reference internal" href="../api/#flask.views.View.decorators" title="flask.views.View.decorators"><code class="xref py py-attr docutils literal notranslate">View.decorators</code></a> to a list of decorators to apply. <div class="highlight-python notranslate"><div class="highlight"><pre>class UserList(View): decorators = [cache(minutes=2), login_required] app.add_url_rule('/users/', view_func=UserList.as_view()) </pre></div> </div> If you didn鈥檛 set <code class="docutils literal notranslate">decorators</code>, you could apply them manually instead. This is equivalent to: <div class="highlight-python notranslate"><div class="highlight"><pre>view = UserList.as_view("users_list") view = cache(minutes=2)(view) view = login_required(view) app.add_url_rule('/users/', view_func=view) </pre></div> </div> Keep in mind that order matters. If you鈥檙e used to <code class="docutils literal notranslate">@decorator</code> style, this is equivalent to: <div class="highlight-python notranslate"><div class="highlight"><pre>@app.route("/users/") @login_required @cache(minutes=2) def user_list(): ... </pre></div> </div> </section> <section id="method-hints"> <h2>Method Hints<a class="headerlink" href="#method-hints" title="Link to this heading">露</a></h2> A common pattern is to register a view with <code class="docutils literal notranslate">methods=["GET", "POST"]</code>, then check <code class="docutils literal notranslate">request.method == "POST"</code> to decide what to do. Setting <a class="reference internal" href="../api/#flask.views.View.methods" title="flask.views.View.methods"><code class="xref py py-attr docutils literal notranslate">View.methods</code></a> is equivalent to passing the list of methods to <code class="docutils literal notranslate">add_url_rule</code> or <code class="docutils literal notranslate">route</code>. <div class="highlight-python notranslate"><div class="highlight"><pre>class MyView(View): methods = ["GET", "POST"] def dispatch_request(self): if request.method == "POST": ... ... app.add_url_rule('/my-view', view_func=MyView.as_view('my-view')) </pre></div> </div> This is equivalent to the following, except further subclasses can inherit or change the methods. <div class="highlight-python notranslate"><div class="highlight"><pre>app.add_url_rule( "/my-view", view_func=MyView.as_view("my-view"), methods=["GET", "POST"], ) </pre></div> </div> </section> <section id="method-dispatching-and-apis"> <h2>Method Dispatching and APIs<a class="headerlink" href="#method-dispatching-and-apis" title="Link to this heading">露</a></h2> For APIs it can be helpful to use a different function for each HTTP method. <a class="reference internal" href="../api/#flask.views.MethodView" title="flask.views.MethodView"><code class="xref py py-class docutils literal notranslate">MethodView</code></a> extends the basic <a class="reference internal" href="../api/#flask.views.View" title="flask.views.View"><code class="xref py py-class docutils literal notranslate">View</code></a> to dispatch to different methods of the class based on the request method. Each HTTP method maps to a method of the class with the same (lowercase) name. <a class="reference internal" href="../api/#flask.views.MethodView" title="flask.views.MethodView"><code class="xref py py-class docutils literal notranslate">MethodView</code></a> automatically sets <a class="reference internal" href="../api/#flask.views.View.methods" title="flask.views.View.methods"><code class="xref py py-attr docutils literal notranslate">View.methods</code></a> based on the methods defined by the class. It even knows how to handle subclasses that override or define other methods. We can make a generic <code class="docutils literal notranslate">ItemAPI</code> class that provides get (detail), patch (edit), and delete methods for a given model. A <code class="docutils literal notranslate">GroupAPI</code> can provide get (list) and post (create) methods. <div class="highlight-python notranslate"><div class="highlight"><pre>from flask.views import MethodView class ItemAPI(MethodView): init_every_request = False def __init__(self, model): self.model = model self.validator = generate_validator(model) def _get_item(self, id): return self.model.query.get_or_404(id) def get(self, id): item = self._get_item(id) return jsonify(item.to_json()) def patch(self, id): item = self._get_item(id) errors = self.validator.validate(item, request.json) if errors: return jsonify(errors), 400 item.update_from_json(request.json) db.session.commit() return jsonify(item.to_json()) def delete(self, id): item = self._get_item(id) db.session.delete(item) db.session.commit() return "", 204 class GroupAPI(MethodView): init_every_request = False def __init__(self, model): self.model = model self.validator = generate_validator(model, create=True) def get(self): items = self.model.query.all() return jsonify([item.to_json() for item in items]) def post(self): errors = self.validator.validate(request.json) if errors: return jsonify(errors), 400 db.session.add(self.model.from_json(request.json)) db.session.commit() return jsonify(item.to_json()) def register_api(app, model, name): item = ItemAPI.as_view(f"{name}-item", model) group = GroupAPI.as_view(f"{name}-group", model) app.add_url_rule(f"/{name}/<int:id>", view_func=item) app.add_url_rule(f"/{name}/", view_func=group) register_api(app, User, "users") register_api(app, Story, "stories") </pre></div> </div> This produces the following views, a standard REST API! <table class="docutils align-default"> <tbody> <tr class="row-odd"><td>URL</td> <td>Method</td> <td>Description</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">/users/</code></td> <td><code class="docutils literal notranslate">GET</code></td> <td>List all users</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">/users/</code></td> <td><code class="docutils literal notranslate">POST</code></td> <td>Create a new user</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">/users/<id></code></td> <td><code class="docutils literal notranslate">GET</code></td> <td>Show a single user</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">/users/<id></code></td> <td><code class="docutils literal notranslate">PATCH</code></td> <td>Update a user</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">/users/<id></code></td> <td><code class="docutils literal notranslate">DELETE</code></td> <td>Delete a user</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">/stories/</code></td> <td><code class="docutils literal notranslate">GET</code></td> <td>List all stories</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">/stories/</code></td> <td><code class="docutils literal notranslate">POST</code></td> <td>Create a new story</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">/stories/<id></code></td> <td><code class="docutils literal notranslate">GET</code></td> <td>Show a single story</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">/stories/<id></code></td> <td><code class="docutils literal notranslate">PATCH</code></td> <td>Update a story</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">/stories/<id></code></td> <td><code class="docutils literal notranslate">DELETE</code></td> <td>Delete a story</td> </tr> </tbody> </table> </section> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="Main"> <div class="sphinxsidebarwrapper"> <a href="../"> <img class="logo" src="../_static/flask-vertical.png" alt="Logo of Flask"/> </a> <h3>Contents</h3> <ul> <li><a class="reference internal" href="#">Class-based Views</a><ul> <li><a class="reference internal" href="#basic-reusable-view">Basic Reusable View</a></li> <li><a class="reference internal" href="#url-variables">URL Variables</a></li> <li><a class="reference internal" href="#view-lifetime-and-self">View Lifetime and <code class="docutils literal notranslate">self</code></a></li> <li><a class="reference internal" href="#view-decorators">View Decorators</a></li> <li><a class="reference internal" href="#method-hints">Method Hints</a></li> <li><a class="reference internal" href="#method-dispatching-and-apis">Method Dispatching and APIs</a></li> </ul> </li> </ul> <h3>Navigation</h3> <ul> <li><a href="../">Overview</a> <ul> <li>Previous: <a href="../signals/" title="previous chapter">Signals</a> <li>Next: <a href="../lifecycle/" title="next chapter">Application Structure and Lifecycle</a> </ul> </li> </ul> <search id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search/" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </search> <script>document.getElementById('searchbox').style.display = "block"</script><div id="ethical-ad-placement"></div> </div> </div> <div class="clearer"></div> </div> <div class="footer" role="contentinfo"> © Copyright 2010 Pallets. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3. </div> </body> </html>