plain 0.1.0__py3-none-any.whl

plain/views/README.md

@@ -0,0 +1,268 @@
+# Views
+
+Take a request, return a response.
+
+Plain views are written as classes,
+with a straightforward API that keeps simple views simple,
+but gives you the power of a full class to handle more complex cases.
+
+```python
+from plain.views import View
+
+
+class ExampleView(View):
+    def get(self):
+        return "Hello, world!"
+```
+
+## HTTP methods -> class methods
+
+The HTTP methd of the request will map to a class method of the same name on the view.
+
+If a request comes in and there isn't a matching method on the view,
+Plain will return a `405 Method Not Allowed` response.
+
+```python
+from plain.views import View
+
+
+class ExampleView(View):
+    def get(self):
+        pass
+
+    def post(self):
+        pass
+
+    def put(self):
+        pass
+
+    def patch(self):
+        pass
+
+    def delete(self):
+        pass
+
+    def trace(self):
+        pass
+```
+
+The [base `View` class](./base.py) defines default `options` and `head` behavior,
+but you can override these too.
+
+## Return types
+
+For simple plain text and JSON responses,
+you don't need to instantiate a `Response` object.
+
+```python
+class TextView(View):
+    def get(self):
+        return "Hello, world!"
+
+
+class JsonView(View):
+    def get(self):
+        return {"message": "Hello, world!"}
+```
+
+## Template views
+
+The most common behavior for a view is to render a template.
+
+```python
+from plain.views import TemplateView
+
+
+class ExampleView(TemplateView):
+    template_name = "example.html"
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["message"] = "Hello, world!"
+        return context
+```
+
+The `TemplateView` is also the base class for *most* of the other built-in view classes.
+
+## Form views
+
+Standard [forms](../forms) can be rendered and processed by a `FormView`.
+
+```python
+from plain.views import FormView
+from .forms import ExampleForm
+
+
+class ExampleView(FormView):
+    template_name = "example.html"
+    form_class = ExampleForm
+    success_url = "."  # Redirect to the same page
+
+    def form_valid(self, form):
+        # Do other successfull form processing here
+        return super().form_valid(form)
+```
+
+Rendering forms is done directly in the HTML.
+
+```html
+{% extends "base.html" %}
+
+{% block content %}
+
+<form method="post">
+    {{ csrf_input }}
+
+    <!-- Render general form errors -->
+    {% for error in form.non_field_errors %}
+    <div>{{ error }}</div>
+    {% endfor %}
+
+    <!-- Render form fields individually (or with Jinja helps or other concepts) -->
+    <label for="{{ form.email.html_id }}">Email</label>
+    <input
+        type="email"
+        name="{{ form.email.html_name }}"
+        id="{{ form.email.html_id }}"
+        value="{{ form.email.value() or '' }}"
+        autocomplete="email"
+        autofocus
+        required>
+    {% if form.email.errors %}
+    <div>{{ form.email.errors|join(', ') }}</div>
+    {% endif %}
+
+    <button type="submit">Save</button>
+</form>
+
+{% endblock %}
+```
+
+## Object views
+
+The object views support the standard CRUD (create, read/detail, update, delete) operations, plus a list view.
+
+```python
+from plain.views import DetailView, CreateView, UpdateView, DeleteView, ListView
+
+
+class ExampleDetailView(DetailView):
+    template_name = "detail.html"
+
+    def get_object(self):
+        return MyObjectClass.objects.get(
+            pk=self.url_kwargs["pk"],
+            user=self.request.user,  # Limit access
+        )
+
+
+class ExampleCreateView(CreateView):
+    template_name = "create.html"
+    form_class = CustomCreateForm
+    success_url = "."
+
+
+class ExampleUpdateView(UpdateView):
+    template_name = "update.html"
+    form_class = CustomUpdateForm
+    success_url = "."
+
+    def get_object(self):
+        return MyObjectClass.objects.get(
+            pk=self.url_kwargs["pk"],
+            user=self.request.user,  # Limit access
+        )
+
+
+class ExampleDeleteView(DeleteView):
+    template_name = "delete.html"
+    success_url = "."
+
+    # No form class necessary.
+    # Just POST to this view to delete the object.
+
+    def get_object(self):
+        return MyObjectClass.objects.get(
+            pk=self.url_kwargs["pk"],
+            user=self.request.user,  # Limit access
+        )
+
+
+class ExampleListView(ListView):
+    template_name = "list.html"
+
+    def get_objects(self):
+        return MyObjectClass.objects.filter(
+            user=self.request.user,  # Limit access
+        )
+```
+
+## Response exceptions
+
+At any point in the request handling,
+a view can raise a `ResponseException` to immediately exit and return the wrapped response.
+
+This isn't always necessary, but can be useful for raising rate limits or authorization errors when you're a couple layers deep in the view handling or helper functions.
+
+```python
+from plain.views import DetailView
+from plain.views.exceptions import ResponseException
+from plain.http import Response
+
+
+class ExampleView(DetailView):
+    def get_object(self):
+        if self.request.user.exceeds_rate_limit:
+            raise ResponseException(
+                Response("Rate limit exceeded", status=429)
+            )
+
+        return AnExpensiveObject()
+```
+
+## Error views
+
+By default, HTTP errors will be rendered by `templates/<status_code>.html` or `templates/error.html`.
+
+You can define your own error views by pointing the `HTTP_ERROR_VIEWS` setting to a dictionary of status codes and view classes.
+
+```python
+# app/settings.py
+HTTP_ERROR_VIEWS = {
+    404: "errors.NotFoundView",
+}
+```
+
+```python
+# app/errors.py
+from plain.views import View
+
+
+class NotFoundView(View):
+    def get(self):
+        # A custom implementation or error view handling
+        pass
+```
+
+## Redirect views
+
+```python
+from plain.views import RedirectView
+
+
+class ExampleRedirectView(RedirectView):
+    url = "/new-location/"
+    permanent = True
+```
+
+## CSRF exemption
+
+```python
+from plain.views import View
+from plain.views.csrf import CsrfExemptViewMixin
+
+
+class ExemptView(CsrfExemptViewMixin, View):
+    def post(self):
+        return "Hello, world!"
+```

plain/views/__init__.py

@@ -0,0 +1,18 @@
+from .base import View
+from .forms import FormView
+from .objects import CreateView, DeleteView, DetailView, ListView, UpdateView
+from .redirect import RedirectView
+from .templates import TemplateView
+
+__all__ = [
+    "View",
+    "TemplateView",
+    "RedirectView",
+    "FormView",
+    "DetailView",
+    "CreateView",
+    "UpdateView",
+    "DeleteView",
+    "ListView",
+    "AuthViewMixin",
+]

plain/views/base.py

@@ -0,0 +1,107 @@
+import logging
+
+from plain.http import (
+    HttpRequest,
+    JsonResponse,
+    Response,
+    ResponseBase,
+    ResponseNotAllowed,
+)
+from plain.utils.decorators import classonlymethod
+
+from .exceptions import ResponseException
+
+logger = logging.getLogger("plain.request")
+
+
+class View:
+    def __init__(self, *args, **kwargs) -> None:
+        # Views can customize their init, which receives
+        # the args and kwargs from as_view()
+        pass
+
+    def setup(self, request: HttpRequest, *args, **kwargs) -> None:
+        if hasattr(self, "get") and not hasattr(self, "head"):
+            self.head = self.get
+
+        self.request = request
+        self.url_args = args
+        self.url_kwargs = kwargs
+
+    @classonlymethod
+    def as_view(cls, *init_args, **init_kwargs):
+        def view(request, *args, **kwargs):
+            v = cls(*init_args, **init_kwargs)
+            v.setup(request, *args, **kwargs)
+            try:
+                return v.get_response()
+            except ResponseException as e:
+                return e.response
+
+        # Copy possible attributes set by decorators, e.g. @csrf_exempt, from
+        # the dispatch method.
+        view.__dict__.update(cls.get_response.__dict__)
+        view.view_class = cls
+
+        return view
+
+    def get_request_handler(self) -> callable:
+        """Return the handler for the current request method."""
+
+        if not self.request.method:
+            raise AttributeError("HTTP method is not set")
+
+        handler = getattr(self, self.request.method.lower(), None)
+
+        if not handler:
+            logger.warning(
+                "Method Not Allowed (%s): %s",
+                self.request.method,
+                self.request.path,
+                extra={"status_code": 405, "request": self.request},
+            )
+            raise ResponseException(ResponseNotAllowed(self._allowed_methods()))
+
+        return handler
+
+    def get_response(self) -> ResponseBase:
+        handler = self.get_request_handler()
+
+        result = handler()
+
+        if isinstance(result, ResponseBase):
+            return result
+
+        # Allow return of an int (status code)
+        # or tuple (status code, content)?
+
+        if isinstance(result, str):
+            return Response(result)
+
+        if isinstance(result, list):
+            return JsonResponse(result, safe=False)
+
+        if isinstance(result, dict):
+            return JsonResponse(result)
+
+        raise ValueError(f"Unexpected view return type: {type(result)}")
+
+    def options(self) -> Response:
+        """Handle responding to requests for the OPTIONS HTTP verb."""
+        response = Response()
+        response.headers["Allow"] = ", ".join(self._allowed_methods())
+        response.headers["Content-Length"] = "0"
+        return response
+
+    def _allowed_methods(self) -> list[str]:
+        known_http_method_names = [
+            "get",
+            "post",
+            "put",
+            "patch",
+            "delete",
+            "head",
+            "options",
+            "trace",
+        ]
+        return [m.upper() for m in known_http_method_names if hasattr(self, m)]

plain/views/csrf.py

@@ -0,0 +1,24 @@
+from functools import wraps
+
+from plain.utils.decorators import method_decorator
+
+
+def csrf_exempt(view_func):
+    """Mark a view function as being exempt from the CSRF view protection."""
+
+    # view_func.csrf_exempt = True would also work, but decorators are nicer
+    # if they don't have side effects, so return a new function.
+    @wraps(view_func)
+    def wrapper_view(*args, **kwargs):
+        return view_func(*args, **kwargs)
+
+    wrapper_view.csrf_exempt = True
+    return wrapper_view
+
+
+@method_decorator(csrf_exempt, name="get_response")
+class CsrfExemptViewMixin:
+    """CsrfExemptViewMixin needs to come before View in the class definition"""
+
+    def get_response(self):
+        return super().get_response()

plain/views/errors.py

@@ -0,0 +1,25 @@
+from plain.http import ResponseBase
+
+from .templates import TemplateView
+
+
+class ErrorView(TemplateView):
+    status_code: int
+
+    def __init__(self, status_code=None) -> None:
+        # Allow creating an ErrorView with a status code
+        # e.g. ErrorView.as_view(status_code=404)
+        if status_code is not None:
+            self.status_code = status_code
+
+    def get_template_names(self) -> list[str]:
+        return [f"{self.status_code}.html", "error.html"]
+
+    def get_request_handler(self):
+        return self.get  # All methods (post, patch, etc.) will use the get()
+
+    def get_response(self) -> ResponseBase:
+        response = super().get_response()
+        # Set the status code we want
+        response.status_code = self.status_code
+        return response

plain/views/exceptions.py

@@ -0,0 +1,4 @@
+class ResponseException(Exception):
+    def __init__(self, response):
+        self.response = response
+        super().__init__(response)

plain/views/forms.py

@@ -0,0 +1,76 @@
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from plain.exceptions import ImproperlyConfigured
+from plain.http import Response, ResponseRedirect
+
+from .templates import TemplateView
+
+if TYPE_CHECKING:
+    from plain.forms import BaseForm
+
+
+class FormView(TemplateView):
+    """A view for displaying a form and rendering a template response."""
+
+    form_class: type["BaseForm"] | None = None
+    success_url: Callable | str | None = None
+
+    def get_form(self) -> "BaseForm":
+        """Return an instance of the form to be used in this view."""
+        if not self.form_class:
+            raise ImproperlyConfigured(
+                "No form class provided. Define {cls}.form_class or override "
+                "{cls}.get_form().".format(cls=self.__class__.__name__)
+            )
+        return self.form_class(**self.get_form_kwargs())
+
+    def get_form_kwargs(self) -> dict:
+        """Return the keyword arguments for instantiating the form."""
+        kwargs: dict = {
+            "initial": {},  # Make it easier to set keys in subclasses
+        }
+
+        if hasattr(self, "request") and self.request.method in ("POST", "PUT"):
+            kwargs.update(
+                {
+                    "data": self.request.POST,
+                    "files": self.request.FILES,
+                }
+            )
+        return kwargs
+
+    def get_success_url(self) -> str:
+        """Return the URL to redirect to after processing a valid form."""
+        if not self.success_url:
+            raise ImproperlyConfigured("No URL to redirect to. Provide a success_url.")
+        return str(self.success_url)  # success_url may be lazy
+
+    def form_valid(self, form: "BaseForm") -> Response:
+        """If the form is valid, redirect to the supplied URL."""
+        return ResponseRedirect(self.get_success_url())
+
+    def form_invalid(self, form: "BaseForm") -> Response:
+        """If the form is invalid, render the invalid form."""
+        context = {
+            **self.get_template_context(),
+            "form": form,
+        }
+        return self.get_template().render(context)
+
+    def get_template_context(self) -> dict:
+        """Insert the form into the context dict."""
+        context = super().get_template_context()
+        context["form"] = self.get_form()
+        return context
+
+    def post(self) -> Response:
+        """
+        Handle POST requests: instantiate a form instance with the passed
+        POST variables and then check if it's valid.
+        """
+        form = self.get_form()
+        if form.is_valid():
+            return self.form_valid(form)
+        else:
+            return self.form_invalid(form)