plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/forms/forms.py

@@ -2,21 +2,37 @@
 Form classes
 """
 
+from __future__ import annotations
+
 import copy
 from functools import cached_property
+from typing import TYPE_CHECKING, Any
 
 from plain.exceptions import NON_FIELD_ERRORS
+from plain.internal import internalcode
+from plain.utils.datastructures import MultiValueDict
 
 from .exceptions import ValidationError
 from .fields import Field, FileField
 
+if TYPE_CHECKING:
+    from plain.http import Request
+
+    from .boundfield import BoundField
+
 __all__ = ("BaseForm", "Form")
 
 
+@internalcode
 class DeclarativeFieldsMetaclass(type):
     """Collect Fields declared on the base classes."""
 
-    def __new__(mcs, name, bases, attrs):
+    def __new__(
+        mcs: type[DeclarativeFieldsMetaclass],
+        name: str,
+        bases: tuple[type, ...],
+        attrs: dict[str, Any],
+    ) -> type:
         # Collect fields from current class and remove them from attrs.
         attrs["declared_fields"] = {
             key: attrs.pop(key)
@@ -27,19 +43,19 @@ class DeclarativeFieldsMetaclass(type):
         new_class = super().__new__(mcs, name, bases, attrs)
 
         # Walk through the MRO.
-        declared_fields = {}
+        declared_fields: dict[str, Field] = {}
         for base in reversed(new_class.__mro__):
             # Collect fields from base class.
             if hasattr(base, "declared_fields"):
-                declared_fields.update(base.declared_fields)
+                declared_fields.update(getattr(base, "declared_fields"))
 
             # Field shadowing.
             for attr, value in base.__dict__.items():
                 if value is None and attr in declared_fields:
                     declared_fields.pop(attr)
 
-        new_class.base_fields = declared_fields
-        new_class.declared_fields = declared_fields
+        setattr(new_class, "base_fields", declared_fields)
+        setattr(new_class, "declared_fields", declared_fields)
 
         return new_class
 
@@ -52,22 +68,29 @@ class BaseForm:
     class.
     """
 
-    prefix = None
+    # Set by DeclarativeFieldsMetaclass
+    base_fields: dict[str, Field]
+
+    prefix: str | None = None
 
     def __init__(
         self,
         *,
-        request,
-        auto_id="id_%s",
-        prefix=None,
-        initial=None,
+        request: Request,
+        auto_id: str | bool = "id_%s",
+        prefix: str | None = None,
+        initial: dict[str, Any] | None = None,
     ):
-        self.data = request.data
-        self.files = request.files
-
+        # Forms can handle both JSON and form data
         self.is_json_request = request.headers.get("Content-Type", "").startswith(
             "application/json"
         )
+        if self.is_json_request:
+            self.data = request.json_data
+            self.files = MultiValueDict()
+        else:
+            self.data = request.form_data
+            self.files = request.files
 
         self.is_bound = bool(self.data or self.files)
 
@@ -75,17 +98,19 @@ class BaseForm:
         if prefix is not None:
             self.prefix = prefix
         self.initial = initial or {}
-        self._errors = None  # Stores the errors after clean() has been called.
+        self._errors: dict[str, list[str]] | None = (
+            None  # Stores the errors after clean() has been called.
+        )
 
         # The base_fields class attribute is the *class-wide* definition of
         # fields. Because a particular *instance* of the class might want to
         # alter self.fields, we create self.fields here by copying base_fields.
         # Instances should always modify self.fields; they should not modify
         # self.base_fields.
-        self.fields = copy.deepcopy(self.base_fields)
-        self._bound_fields_cache = {}
+        self.fields: dict[str, Field] = copy.deepcopy(self.base_fields)
+        self._bound_fields_cache: dict[str, BoundField] = {}
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         if self._errors is None:
             is_valid = "Unknown"
         else:
@@ -97,17 +122,17 @@ class BaseForm:
             fields=";".join(self.fields),
         )
 
-    def _bound_items(self):
+    def _bound_items(self) -> Any:
         """Yield (name, bf) pairs, where bf is a BoundField object."""
         for name in self.fields:
             yield name, self[name]
 
-    def __iter__(self):
+    def __iter__(self) -> Any:
         """Yield the form's fields as BoundField objects."""
         for name in self.fields:
             yield self[name]
 
-    def __getitem__(self, name):
+    def __getitem__(self, name: str) -> BoundField:
         """Return a BoundField with the given name."""
         try:
             field = self.fields[name]
@@ -124,17 +149,18 @@ class BaseForm:
         return self._bound_fields_cache[name]
 
     @property
-    def errors(self):
+    def errors(self) -> dict[str, list[str]]:
         """Return an error dict for the data provided for the form."""
         if self._errors is None:
             self.full_clean()
+        assert self._errors is not None, "full_clean should initialize _errors"
         return self._errors
 
-    def is_valid(self):
+    def is_valid(self) -> bool:
         """Return True if the form has no errors, or False otherwise."""
         return self.is_bound and not self.errors
 
-    def add_prefix(self, field_name):
+    def add_prefix(self, field_name: str) -> str:
         """
         Return the field name with a prefix appended, if this Form has a
         prefix set.
@@ -144,7 +170,7 @@ class BaseForm:
         return f"{self.prefix}-{field_name}" if self.prefix else field_name
 
     @property
-    def non_field_errors(self):
+    def non_field_errors(self) -> list[str]:
         """
         Return a list of errors that aren't associated with a particular
         field -- i.e., from Form.clean(). Return an empty list if there
@@ -155,7 +181,7 @@ class BaseForm:
             [],
         )
 
-    def add_error(self, field, error):
+    def add_error(self, field: str | None, error: ValidationError) -> None:
         """
         Update the content of `self._errors`.
 
@@ -179,6 +205,7 @@ class BaseForm:
                 f"`ValidationError`, not `{type(error).__name__}`."
             )
 
+        error_dict: dict[str, Any]
         if hasattr(error, "error_dict"):
             if field is not None:
                 raise TypeError(
@@ -186,45 +213,48 @@ class BaseForm:
                     "argument contains errors for multiple fields."
                 )
             else:
-                error = error.error_dict
+                error_dict = error.error_dict
         else:
-            error = {field or NON_FIELD_ERRORS: error.error_list}
+            error_dict = {field or NON_FIELD_ERRORS: error.error_list}
 
         class ValidationErrors(list):
-            def __iter__(self):
+            def __iter__(self) -> Any:
                 for err in super().__iter__():
                     # TODO make sure this works...
                     yield next(iter(err))
 
-        for field, error_list in error.items():
-            if field not in self.errors:
-                if field != NON_FIELD_ERRORS and field not in self.fields:
+        for field_key, error_list in error_dict.items():
+            # Accessing self.errors ensures _errors is initialized
+            if field_key not in self.errors:
+                if field_key != NON_FIELD_ERRORS and field_key not in self.fields:
                     raise ValueError(
-                        f"'{self.__class__.__name__}' has no field named '{field}'."
+                        f"'{self.__class__.__name__}' has no field named '{field_key}'."
                     )
-                self._errors[field] = ValidationErrors()
+                assert self._errors is not None, "errors property initializes _errors"
+                self._errors[field_key] = ValidationErrors()
 
-            self._errors[field].extend(error_list)
+            assert self._errors is not None, "errors property initializes _errors"
+            self._errors[field_key].extend(error_list)
 
             # The field had an error, so removed it from the final data
             # (we use getattr here so errors can be added to uncleaned forms)
-            if field in getattr(self, "cleaned_data", {}):
-                del self.cleaned_data[field]
+            if field_key in getattr(self, "cleaned_data", {}):
+                del self.cleaned_data[field_key]
 
-    def full_clean(self):
+    def full_clean(self) -> None:
         """
         Clean all of self.data and populate self._errors and self.cleaned_data.
         """
         self._errors = {}
         if not self.is_bound:  # Stop further processing.
-            return
+            return None
         self.cleaned_data = {}
 
         self._clean_fields()
         self._clean_form()
         self._post_clean()
 
-    def _field_data_value(self, field, html_name):
+    def _field_data_value(self, field: Field, html_name: str) -> Any:
         if hasattr(self, f"parse_{html_name}"):
             # Allow custom parsing from form data/files at the form level
             return getattr(self, f"parse_{html_name}")()
@@ -234,7 +264,7 @@ class BaseForm:
         else:
             return field.value_from_form_data(self.data, self.files, html_name)
 
-    def _clean_fields(self):
+    def _clean_fields(self) -> None:
         for name, bf in self._bound_items():
             field = bf.field
 
@@ -252,7 +282,7 @@ class BaseForm:
             except ValidationError as e:
                 self.add_error(name, e)
 
-    def _clean_form(self):
+    def _clean_form(self) -> None:
         try:
             cleaned_data = self.clean()
         except ValidationError as e:
@@ -261,14 +291,14 @@ class BaseForm:
             if cleaned_data is not None:
                 self.cleaned_data = cleaned_data
 
-    def _post_clean(self):
+    def _post_clean(self) -> None:
         """
         An internal hook for performing additional cleaning after form cleaning
         is complete. Used for model validation in model forms.
         """
         pass
 
-    def clean(self):
+    def clean(self) -> dict[str, Any]:
         """
         Hook for doing any extra form-wide cleaning after Field.clean() has been
         called on every field. Any ValidationError raised by this method will
@@ -278,10 +308,10 @@ class BaseForm:
         return self.cleaned_data
 
     @cached_property
-    def changed_data(self):
+    def changed_data(self) -> list[str]:
         return [name for name, bf in self._bound_items() if bf._has_changed()]
 
-    def get_initial_for_field(self, field, field_name):
+    def get_initial_for_field(self, field: Field, field_name: str) -> Any:
         """
         Return initial data for field on form. Use initial data from the form
         or the field, in that order. Evaluate callable values.

plain/http/README.md

@@ -1,12 +1,27 @@
 # HTTP
 
-**HTTP request and response handling.**
+**Request and response handling for Plain applications.**
 
 - [Overview](#overview)
+- [Request](#request)
+    - [Headers](#headers)
+    - [Query parameters](#query-parameters)
+    - [Body data](#body-data)
+    - [Content negotiation](#content-negotiation)
+    - [Cookies](#cookies)
+- [Response](#response)
+    - [Response types](#response-types)
+    - [Setting cookies](#setting-cookies)
+    - [Default response headers](#default-response-headers)
+- [Content Security Policy (CSP)](#content-security-policy-csp)
+- [Middleware](#middleware)
+- [Exceptions](#exceptions)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-Typically you will interact with [request](request.py#HttpRequest) and [response](response.py#ResponseBase) objects in your views and middleware.
+You interact with [`Request`](./request.py#Request) and [`Response`](./response.py#Response) objects in your views and middleware.
 
 ```python
 from plain.views import View
@@ -14,17 +29,349 @@ from plain.http import Response
 
 class ExampleView(View):
     def get(self):
-        # Accessing a request header
-        print(self.request.headers.get("Example-Header"))
+        # Access a request header
+        user_agent = self.request.headers.get("User-Agent")
 
-        # Accessing a query parameter
-        print(self.request.query_params.get("example"))
+        # Access a query parameter
+        page = self.request.query_params.get("page", "1")
 
-        # Creating a response
+        # Create and return a response
         response = Response("Hello, world!", status_code=200)
+        response.headers["X-Custom-Header"] = "Custom Value"
+        return response
+```
+
+## Request
+
+The [`Request`](./request.py#Request) object provides access to all incoming HTTP request data.
+
+### Headers
+
+Access request headers through the `headers` property. Header names are case-insensitive.
+
+```python
+content_type = self.request.headers.get("Content-Type")
+auth = self.request.headers.get("authorization")  # Case-insensitive
+```
+
+### Query parameters
+
+Query string parameters are available as a [`QueryDict`](./request.py#QueryDict) through `query_params`.
+
+```python
+# URL: /search?q=plain&page=2
+query = self.request.query_params.get("q")  # "plain"
+page = self.request.query_params.get("page", "1")  # "2"
+
+# For parameters with multiple values (?tags=python&tags=web)
+tags = self.request.query_params.getlist("tags")  # ["python", "web"]
+```
+
+### Body data
+
+Access request body data based on the content type.
+
+**JSON data:**
+
+```python
+# Returns dict, raises BadRequestError400 for invalid JSON
+data = self.request.json_data
+name = data.get("name")
+```
+
+**Form data:**
+
+```python
+# For application/x-www-form-urlencoded or multipart/form-data
+form = self.request.form_data
+email = form.get("email")
+```
+
+**File uploads:**
+
+```python
+# For multipart/form-data requests
+uploaded_file = self.request.files.get("document")
+if uploaded_file:
+    content = uploaded_file.read()
+```
+
+**Raw body:**
+
+```python
+raw_bytes = self.request.body
+```
+
+### Content negotiation
+
+Check what content types the client accepts.
+
+```python
+# Check if client accepts JSON
+if self.request.accepts("application/json"):
+    return JsonResponse({"message": "Hello"})
+
+# Get preferred type from options
+preferred = self.request.get_preferred_type("text/html", "application/json")
+```
+
+### Cookies
+
+Read cookies from the request.
+
+```python
+session_id = self.request.cookies.get("session_id")
+
+# Read a signed cookie (returns None if signature is invalid)
+user_id = self.request.get_signed_cookie("user_id", default=None)
+```
+
+## Response
+
+The [`Response`](./response.py#Response) class creates HTTP responses with string or bytes content.
+
+```python
+from plain.http import Response
+
+# Basic response
+response = Response("Hello, world!")
+
+# With status code and headers
+response = Response(
+    content="Created!",
+    status_code=201,
+    headers={"X-Custom": "value"},
+)
+
+# Set content type
+response = Response("<h1>Hello</h1>", content_type="text/html")
+```
+
+### Response types
+
+Plain provides specialized response classes for common use cases.
+
+**JSON responses:**
+
+```python
+from plain.http import JsonResponse
+
+return JsonResponse({"name": "Plain", "version": "1.0"})
+```
+
+**Redirects:**
+
+```python
+from plain.http import RedirectResponse
+
+return RedirectResponse("/new-location")
+```
+
+**File downloads:**
+
+```python
+from plain.http import FileResponse
+
+# Serve a file
+return FileResponse(open("report.pdf", "rb"))
+
+# Force download with custom filename
+return FileResponse(
+    open("report.pdf", "rb"),
+    as_attachment=True,
+    filename="monthly-report.pdf",
+)
+```
+
+**Streaming responses:**
+
+```python
+from plain.http import StreamingResponse
+
+def generate_data():
+    for i in range(1000):
+        yield f"Line {i}\n"
+
+return StreamingResponse(generate_data(), content_type="text/plain")
+```
+
+Other response types include [`NotModifiedResponse`](./response.py#NotModifiedResponse) (304) and [`NotAllowedResponse`](./response.py#NotAllowedResponse) (405).
 
-        # Setting a response header
-        response.headers["Example-Header"] = "Example Value"
+### Setting cookies
 
+Set cookies on the response.
+
+```python
+response = Response("Welcome!")
+response.set_cookie("session_id", "abc123", httponly=True, secure=True)
+
+# With expiration
+response.set_cookie("remember_me", "yes", max_age=86400 * 30)  # 30 days
+
+# Signed cookie (tamper-proof)
+response.set_signed_cookie("user_id", "42", httponly=True)
+
+# Delete a cookie
+response.delete_cookie("old_cookie")
+```
+
+### Default response headers
+
+Plain applies default headers from `DEFAULT_RESPONSE_HEADERS` in settings to all responses. You can customize these per-view.
+
+**Override a default header:**
+
+```python
+response = Response("content")
+response.headers["X-Frame-Options"] = "SAMEORIGIN"
+```
+
+**Remove a default header:**
+
+```python
+response = Response("content")
+response.headers["X-Frame-Options"] = None  # Removes the header
+```
+
+**Extend a default header:**
+
+```python
+from plain.runtime import settings
+
+if csp := settings.DEFAULT_RESPONSE_HEADERS.get("Content-Security-Policy"):
+    csp = csp.format(request=self.request)
+    response.headers["Content-Security-Policy"] = f"{csp}; script-src https://cdn.example.com"
+```
+
+## Content Security Policy (CSP)
+
+Plain includes built-in support for Content Security Policy through nonces. Each request generates a unique cryptographically secure nonce available via `request.csp_nonce`.
+
+**Configure CSP in settings:**
+
+```python
+# app/settings.py
+DEFAULT_RESPONSE_HEADERS = {
+    "Content-Security-Policy": (
+        "default-src 'self'; "
+        "script-src 'self' 'nonce-{request.csp_nonce}'; "
+        "style-src 'self' 'nonce-{request.csp_nonce}'; "
+        "img-src 'self' data:; "
+        "font-src 'self'; "
+        "connect-src 'self'; "
+        "frame-ancestors 'self'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    ),
+    "X-Frame-Options": "DENY",
+}
+```
+
+The `{request.csp_nonce}` placeholder is replaced with a unique nonce for each request.
+
+**Use nonces in templates:**
+
+```html
+<script nonce="{{ request.csp_nonce }}">
+    console.log("This script is allowed by CSP");
+</script>
+
+<style nonce="{{ request.csp_nonce }}">
+    .example { color: red; }
+</style>
+```
+
+External scripts and stylesheets loaded from `'self'` don't need nonces:
+
+```html
+<script src="/assets/app.js"></script>
+<link rel="stylesheet" href="/assets/app.css">
+```
+
+Use [Google's CSP Evaluator](https://csp-evaluator.withgoogle.com/) to analyze your CSP policy.
+
+## Middleware
+
+Create custom middleware by subclassing [`HttpMiddleware`](./middleware.py#HttpMiddleware).
+
+```python
+from plain.http import HttpMiddleware, Request, Response
+
+class TimingMiddleware(HttpMiddleware):
+    def process_request(self, request: Request) -> Response:
+        import time
+        start = time.time()
+
+        response = self.get_response(request)
+
+        duration = time.time() - start
+        response.headers["X-Request-Duration"] = f"{duration:.3f}s"
         return response
 ```
+
+## Exceptions
+
+Raise exceptions to return specific HTTP error responses.
+
+```python
+from plain.http import NotFoundError404, ForbiddenError403, BadRequestError400
+
+# Return 404
+raise NotFoundError404("Page not found")
+
+# Return 403
+raise ForbiddenError403("Access denied")
+
+# Return 400
+raise BadRequestError400("Invalid input")
+```
+
+Additional exceptions include [`SuspiciousOperationError400`](./exceptions.py#SuspiciousOperationError400), [`TooManyFieldsSentError400`](./exceptions.py#TooManyFieldsSentError400), [`TooManyFilesSentError400`](./exceptions.py#TooManyFilesSentError400), and [`RequestDataTooBigError400`](./exceptions.py#RequestDataTooBigError400).
+
+## FAQs
+
+#### How do I access the client's IP address?
+
+Use `request.client_ip`. If you're behind a proxy, enable `HTTP_X_FORWARDED_FOR` in settings.
+
+```python
+ip = self.request.client_ip
+```
+
+#### How do I build an absolute URL?
+
+Use `request.build_absolute_uri()`.
+
+```python
+# Current page
+url = self.request.build_absolute_uri()
+
+# Specific path
+url = self.request.build_absolute_uri("/api/users")
+```
+
+#### How do I check if the request is HTTPS?
+
+Use `request.is_https()` or check `request.scheme`.
+
+```python
+if self.request.is_https():
+    # Secure connection
+    pass
+```
+
+#### What's the difference between QueryDict and a regular dict?
+
+[`QueryDict`](./request.py#QueryDict) handles multiple values for the same key (common in query strings and form data). Use `get()` for a single value or `getlist()` for all values.
+
+#### How do I handle large file uploads?
+
+Configure `DATA_UPLOAD_MAX_MEMORY_SIZE` in settings. For very large files, consider streaming the upload instead of loading it into memory.
+
+## Installation
+
+The `plain.http` module is included with Plain by default. No additional installation is required.
+
+```python
+from plain.http import Request, Response, JsonResponse
+```