Big cleanup

Author: jpsca

Makefile

@@ -11,6 +11,10 @@ lint:
 	uv run ruff check src tests
 	uv run ty check
 
+.PHONY: lintfix
+lintfix:
+	uv run ruff check src tests --fix
+
 .PHONY: coverage
 coverage:
 	uv run pytest --cov=formidable --cov-config=pyproject.toml --cov-report=html tests

docs/content/fields/form.md

@@ -5,6 +5,7 @@ title: FormField
 ::: api formidable.FormField
 :show_members: false
 :::
+
 ----
 
 This is a form field that contains another form as its value. For example:
@@ -28,22 +29,22 @@ class Profile(f.Form):
 
 To the user, this will probably look as part of the same form, why bother then? Well, this field isn't about showing the form, it's about how the data is saved.
 
-When saving a form with a `FormField`, the contents of it comes encapsulated in their own object or dictionary:
+When saving a form with a `FormField`, the contents of it come encapsulated in their own object or dictionary:
 
 ```python
 print(form.save())
 
 {
   "name": "My name",
   "settings": {
-    "locale": "en_us"
+    "locale": "en_us",
     "timezone": "utc",
     "email_notifications": True,
   },
 }
 ```
 
-This field is useful when you want to store those group of fields separated, for example:
+This field is useful when you want to store that group of fields separated, for example:
 
 In a different model with a one-to-one relationship to the main model
 

docs/content/forms.md

@@ -196,7 +196,7 @@ print(product.user_id)  # 123
 
 If you add an `after_validate` method to the form, it will be called at the end of the validation process, after the individual field validations.
 
-You can use it to validate the relation between fields, for example in a update password scenario, or to modify the field values before saving.
+You can use it to validate the relation between fields, for example in an update password scenario, or to modify the field values before saving.
 
 ```python {hl_lines="11"}
 import formidable as f

docs/content/messages.md

@@ -26,30 +26,30 @@ You can see the full (short) default dictionary of error messages in `formidable
 
 ```python
 MESSAGES = {
-    "invalid": "Invalid value",
-    "required": "Field is required",
-    "one_of": "Must be one of {one_of}",
-    "gt": "Must be greater than {gt}",
-    "gte": "Must be greater or equal than {gte}",
-    "lt": "Must be less than {lt}",
-    "lte": "Must be less or equal than {lte}",
-    "multiple_of": "Must multiple of {multiple_of}",
-    "min_items": "Must have at least {min_length} items",
-    "max_items": "Must have at most {max_length} items",
-    "min_length": "Must have at least {min_length} characters",
-    "max_length": "Must have at most {max_length} characters",
-    "pattern": "Invalid format",
-    "past_date": "Must be a date in the past",
-    "future_date": "Must be a date in the future",
-    "after_date": "Must be after {after_date}",
-    "before_date": "Must be before {before_date}",
-    "after_time": "Must be after {after_time}",
-    "before_time": "Must be before {before_time}",
-    "past_time": "Must be a time in the past",
-    "future_time": "Must be a time in the future",
-    "invalid_url": "Doesn't seem to be a valid URL",
-    "invalid_email": "Doesn't seem to be a valid email address",
-    "invalid_slug": "A valid “slug” can only have a-z letters, numbers, underscores, or hyphens",
+    “invalid”: “Invalid value”,
+    “required”: “Field is required”,
+    “one_of”: “Must be one of {one_of}”,
+    “gt”: “Must be greater than {gt}”,
+    “gte”: “Must be greater than or equal to {gte}”,
+    “lt”: “Must be less than {lt}”,
+    “lte”: “Must be less than or equal to {lte}”,
+    “multiple_of”: “Must be a multiple of {multiple_of}”,
+    “min_items”: “Must have at least {min_items} items”,
+    “max_items”: “Must have at most {max_items} items”,
+    “min_length”: “Must have at least {min_length} characters”,
+    “max_length”: “Must have at most {max_length} characters”,
+    “pattern”: “Invalid format”,
+    “past_date”: “Must be a date in the past”,
+    “future_date”: “Must be a date in the future”,
+    “after_date”: “Must be after {after_date}”,
+    “before_date”: “Must be before {before_date}”,
+    “after_time”: “Must be after {after_time}”,
+    “before_time”: “Must be before {before_time}”,
+    “past_time”: “Must be a time in the past”,
+    “future_time”: “Must be a time in the future”,
+    “invalid_url”: “Doesn't seem to be a valid URL”,
+    “invalid_email”: “Doesn't seem to be a valid email address”,
+    “invalid_slug”: “A valid 'slug' can only have a-z letters, numbers, underscores, or hyphens”,
 }
 ```
 :::
@@ -142,7 +142,7 @@ class NewPasswordForm(f.Form):
 
     def validate_password(self, value):
         if "&" not in value:
-            raise ValueError("must_contain", char="&")
+            raise ValueError("must_contain", {"char": "&"})
         return value
 
 

docs/content/nested.md

@@ -196,7 +196,7 @@ for example, to the `static/js/` folder.
 
 Then, add this to the header of your base template:
 
-```html {hk_lines="4-8"}
+```html {hl_lines="4-8"}
 <html>
   <head>
     ...
@@ -219,7 +219,7 @@ class TodoListForm(f.Form):
     todo = f.NestedForms(TodoForm, allow_delete=True)
 ```
 
-... and a template. I'm using a macro to render the `TodoForm` (because later we are going to need to render it more than once:
+... and a template. I'm using a macro to render the `TodoForm` (because later we are going to need to render it more than once):
 
 ```html+jinja
 {% macro render_todo(form, label) -%}
@@ -301,7 +301,7 @@ The JS script needs something to clone so it can add a new nested form, let's ad
 </form>
 ```
 
-**Note that we call the macro using `form.todo.empty_form`**. This is a special attribute of a `NestedForms` field that generates an empty instance of a nested form, excatly for using it for this cases.
+**Note that we call the macro using `form.todo.empty_form`**. This is a special attribute of a `NestedForms` field that generates an empty instance of a nested form, exactly for using it for these cases.
 
 It's important to put it *inside* the element with the `data-nestedform` attribute (the form tag in our example).
 

docs/content/orm.md

@@ -31,12 +31,16 @@ After calling `form.save()`, you only need to commit the changes to the database
 
 ### SQLAlchemy and SQLModel
 
-Because these ORMs work with a session pattern, you must add these two methods to a base form:
+Because these ORMs work with a session pattern, Formidable's default `ObjectManager` needs to be extended. There are two ways to do this:
 
-```python {title="forms/base.py"}
-import formidable as f
+#### Option A: Add methods to a model base class
 
-class BaseForm(f.Form):
+Formidable's `ObjectManager` calls `orm_cls.create(**data)` when creating new objects and `object.delete()` when deleting them. You can add these methods to a shared model base class:
+
+```python {title="models/base.py"}
+from sqlalchemy.orm import DeclarativeBase
+
+class Base(DeclarativeBase):
     @classmethod
     def create(cls, **kwargs):
         instance = cls(**kwargs)
@@ -49,7 +53,40 @@ class BaseForm(f.Form):
 
 ```
 
-and make all your forms inherit from it:
+Then use `Base` as the base for all your models:
+
+```python {title="models/page.py"}
+class Page(Base):
+    __tablename__ = "pages"
+    title: Mapped[str]
+    content: Mapped[str]
+
+```
+
+#### Option B: Provide a custom ObjectManager
+
+Alternatively, you can subclass `ObjectManager` to handle the session directly:
+
+```python {title="forms/base.py"}
+import formidable as f
+from formidable.wrappers import ObjectManager
+
+class SAObjectManager(ObjectManager):
+    def create(self, data):
+        instance = self.orm_cls(**data)
+        db_session.add(instance)
+        return instance
+
+    # Only needed for NestedForms fields
+    def delete(self):
+        db_session.delete(self.object)
+
+class BaseForm(f.Form):
+    _ObjectManager = SAObjectManager
+
+```
+
+Then make all your forms inherit from it:
 
 ```python {title="forms/page.py", hl_lines="5"}
 import formidable as f

src/formidable/errors.py

@@ -63,5 +63,5 @@
 
     INVALID_URL: "Doesn't seem to be a valid URL",
     INVALID_EMAIL: "Doesn't seem to be a valid email address",
-    INVALID_SLUG: "A valid “slug” can only have a-z letters, numbers, underscores, or hyphens"
+    INVALID_SLUG: "A valid 'slug' can only have a-z letters, numbers, underscores, or hyphens"
 }

src/formidable/fields/__init__.py

@@ -5,8 +5,8 @@
 from .email import EmailField  # noqa
 from .file import FileField  # noqa
 from .formfield import FormField  # noqa
-from .nested import NestedForms  # noqa
 from .list import ListField  # noqa
+from .nested import NestedForms  # noqa
 from .number import FloatField, IntegerField  # noqa
 from .slug import SlugField  # noqa
 from .text import TextField  # noqa

src/formidable/fields/base.py

@@ -180,6 +180,11 @@ def _custom_filter(self, value: t.Any) -> t.Any:
     def _custom_validator(self, value: t.Any) -> t.Any:
         return value
 
+    def _str_value(self) -> str:
+        if hasattr(self.value, "isoformat"):
+            return self.value.isoformat()
+        return str(self.value)
+
     # Helper methods for rendering HTML forms
 
     def label(self, text: str | None = None, **attrs: t.Any) -> str:
@@ -372,16 +377,17 @@ def select(
         attributes.update(attrs)
         attr_str = self._render_html_attrs(attributes)
 
-        options_html = ""
         values = self.value if self.multiple else [self.value]
 
+        option_tags = []
         for value, display in options:
             selected_attr = " selected" if value in values else ""
             escaped_value = Markup.escape(value)
             escaped_display = Markup.escape(display)
-            options_html += f'<option value="{escaped_value}"{selected_attr}>{escaped_display}</option>\n'
+            option_tags.append(f'<option value="{escaped_value}"{selected_attr}>{escaped_display}</option>')
 
-        return Markup(f"<select {attr_str}>\n{options_html}</select>")
+        options_html = "\n".join(option_tags)
+        return Markup(f"<select {attr_str}>\n{options_html}\n</select>")
 
     def checkbox(self, **attrs: t.Any) -> str:
         """
@@ -491,7 +497,7 @@ def _input(self, input_type: str = "text", **attrs: t.Any) -> str:
             "type": input_type,
             "id": self.id,
             "name": self.name,
-            "value": False if self.value is None else str(self.value),
+            "value": False if self.value is None else self._str_value(),
             "required": self.required,
         }
         if self.error:
@@ -529,7 +535,7 @@ def hidden_input(self, **attrs: t.Any) -> str:
         attributes = {
             "type": "hidden",
             "name": self.name,
-            "value": False if self.value is None else str(self.value),
+            "value": False if self.value is None else self._str_value(),
             **attrs,
         }
         attr_str = self._render_html_attrs(attributes)

src/formidable/fields/date.py

@@ -112,7 +112,7 @@ def validate_value(self) -> bool:
         """
         Validate the field value against the defined constraints.
         """
-        if not self.value:
+        if self.value is None:
             return True
 
         if self.after_date and self.value <= self.after_date: