plain.models 0.39.2__py3-none-any.whl → 0.40.0__py3-none-any.whl

plain/models/CHANGELOG.md

@@ -1,5 +1,21 @@
 # plain-models changelog
 
+## [0.40.0](https://github.com/dropseed/plain/releases/plain-models@0.40.0) (2025-08-05)
+
+### What's changed
+
+- Foreign key fields now accept lazy objects (like `SimpleLazyObject` used for `request.user`) by automatically evaluating them ([eb78dcc76d](https://github.com/dropseed/plain/commit/eb78dcc76d))
+- Added `--no-input` option to `plain migrate` command to skip user prompts ([0bdaf0409e](https://github.com/dropseed/plain/commit/0bdaf0409e))
+- Removed the `plain models optimize-migration` command ([6e4131ab29](https://github.com/dropseed/plain/commit/6e4131ab29))
+- Removed the `--fake-initial` option from `plain migrate` command ([6506a8bfb9](https://github.com/dropseed/plain/commit/6506a8bfb9))
+- Fixed CLI help text to reference `plain` commands instead of `manage.py` ([8071854d61](https://github.com/dropseed/plain/commit/8071854d61))
+
+### Upgrade instructions
+
+- Remove any usage of `plain models optimize-migration` command - it is no longer available
+- Remove any usage of `--fake-initial` option from `plain migrate` commands - it is no longer supported
+- It is no longer necessary to do `user=request.user or None`, for example, when setting foreign key fields with a lazy object like `request.user`. These will now be automatically evaluated.
+
 ## [0.39.2](https://github.com/dropseed/plain/releases/plain-models@0.39.2) (2025-07-25)
 
 ### What's changed

plain/models/README.md

@@ -2,6 +2,20 @@
 
 **Model your data and store it in a database.**
 
+- [Overview](#overview)
+- [Database connection](#database-connection)
+- [Querying](#querying)
+- [Migrations](#migrations)
+- [Fields](#fields)
+- [Validation](#validation)
+- [Indexes and constraints](#indexes-and-constraints)
+- [Managers](#managers)
+- [Forms](#forms)
+- [Sharing fields across models](#sharing-fields-across-models)
+- [Installation](#installation)
+
+## Overview
+
 ```python
 # app/users/models.py
 from plain import models
@@ -45,25 +59,15 @@ user.delete()
 admin_users = User.objects.filter(is_admin=True)
 ```
 
-## Installation
-
-Install `plain.models` from PyPI, then add it to your `INSTALLED_PACKAGES`.
-
-```python
-# app/settings.py
-INSTALLED_PACKAGES = [
-    ...
-    "plain.models",
-]
-```
+## Database connection
 
-To connect to a database, you can provide a `DATABASE_URL` environment variable.
+To connect to a database, you can provide a `DATABASE_URL` environment variable:
 
 ```sh
 DATABASE_URL=postgresql://user:password@localhost:5432/dbname
 ```
 
-Or you can manually define the `DATABASE` setting.
+Or you can manually define the `DATABASE` setting:
 
 ```python
 # app/settings.py
@@ -81,31 +85,174 @@ Multiple backends are supported, including Postgres, MySQL, and SQLite.
 
 ## Querying
 
-TODO
+Models come with a powerful query API through their [`Manager`](./manager.py#Manager) interface:
+
+```python
+# Get all users
+all_users = User.objects.all()
+
+# Filter users
+admin_users = User.objects.filter(is_admin=True)
+recent_users = User.objects.filter(created_at__gte=datetime.now() - timedelta(days=7))
+
+# Get a single user
+user = User.objects.get(email="test@example.com")
+
+# Complex queries with Q objects
+from plain.models import Q
+users = User.objects.filter(
+    Q(is_admin=True) | Q(email__endswith="@example.com")
+)
+
+# Ordering
+users = User.objects.order_by("-created_at")
+
+# Limiting results
+first_10_users = User.objects.all()[:10]
+```
+
+For more advanced querying options, see the [`QuerySet`](./query.py#QuerySet) class.
 
 ## Migrations
 
-TODO
+Migrations track changes to your models and update the database schema accordingly:
+
+```bash
+# Create migrations for model changes
+plain makemigrations
+
+# Apply migrations to the database
+plain migrate
+
+# See migration status
+plain models show-migrations
+```
+
+Migrations are Python files that describe database schema changes. They're stored in your app's `migrations/` directory.
 
 ## Fields
 
-TODO
+Plain provides many field types for different data:
+
+```python
+from plain import models
+
+class Product(models.Model):
+    # Text fields
+    name = models.CharField(max_length=200)
+    description = models.TextField()
+
+    # Numeric fields
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+    quantity = models.IntegerField(default=0)
+
+    # Boolean fields
+    is_active = models.BooleanField(default=True)
+
+    # Date and time fields
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    # Relationships
+    category = models.ForeignKey("Category", on_delete=models.CASCADE)
+    tags = models.ManyToManyField("Tag")
+```
+
+Common field types include:
+
+- [`CharField`](./fields/__init__.py#CharField)
+- [`TextField`](./fields/__init__.py#TextField)
+- [`IntegerField`](./fields/__init__.py#IntegerField)
+- [`DecimalField`](./fields/__init__.py#DecimalField)
+- [`BooleanField`](./fields/__init__.py#BooleanField)
+- [`DateTimeField`](./fields/__init__.py#DateTimeField)
+- [`EmailField`](./fields/__init__.py#EmailField)
+- [`URLField`](./fields/__init__.py#URLField)
+- [`UUIDField`](./fields/__init__.py#UUIDField)
 
 ## Validation
 
-TODO
+Models can be validated before saving:
+
+```python
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    age = models.IntegerField()
+
+    def clean(self):
+        if self.age < 18:
+            raise ValidationError("User must be 18 or older")
+
+    def save(self, *args, **kwargs):
+        self.full_clean()  # Runs validation
+        super().save(*args, **kwargs)
+```
+
+Field-level validation happens automatically based on field types and constraints.
 
 ## Indexes and constraints
 
-TODO
+Optimize queries and ensure data integrity with indexes and constraints:
+
+```python
+class User(models.Model):
+    email = models.EmailField()
+    username = models.CharField(max_length=150)
+    age = models.IntegerField()
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["email"]),
+            models.Index(fields=["-created_at"], name="user_created_idx"),
+        ]
+        constraints = [
+            models.UniqueConstraint(fields=["email", "username"], name="unique_user"),
+            models.CheckConstraint(check=models.Q(age__gte=0), name="age_positive"),
+        ]
+```
 
 ## Managers
 
-TODO
+[`Manager`](./manager.py#Manager) objects provide the interface for querying models:
+
+```python
+class PublishedManager(models.Manager):
+    def get_queryset(self):
+        return super().get_queryset().filter(status="published")
+
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    status = models.CharField(max_length=20)
+
+    # Default manager
+    objects = models.Manager()
+
+    # Custom manager
+    published = PublishedManager()
+
+# Usage
+all_articles = Article.objects.all()
+published_articles = Article.published.all()
+```
 
 ## Forms
 
-TODO
+Models integrate with Plain's form system:
+
+```python
+from plain import forms
+from .models import User
+
+class UserForm(forms.ModelForm):
+    class Meta:
+        model = User
+        fields = ["email", "is_admin"]
+
+# Usage
+form = UserForm(data=request.data)
+if form.is_valid():
+    user = form.save()
+```
 
 ## Sharing fields across models
 
@@ -134,3 +281,21 @@ class Note(TimestampedMixin, models.Model):
     content = models.TextField(max_length=1024)
     liked = models.BooleanField(default=False)
 ```
+
+## Installation
+
+Install the `plain.models` package from [PyPI](https://pypi.org/project/plain.models/):
+
+```bash
+uv add plain.models
+```
+
+Then add to your `INSTALLED_PACKAGES`:
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    ...
+    "plain.models",
+]
+```

plain/models/backends/base/creation.py

@@ -53,11 +53,11 @@ class BaseDatabaseCreation:
             package_label=None,
             migration_name=None,
             fake=False,
-            fake_initial=False,
             plan=False,
             check_unapplied=False,
             backup=False,
             prune=False,
+            no_input=True,
             verbosity=max(verbosity - 1, 0),
         )
 

plain/models/cli.py

@@ -325,11 +325,6 @@ def makemigrations(package_labels, dry_run, empty, no_input, name, check, verbos
 @click.option(
     "--fake", is_flag=True, help="Mark migrations as run without actually running them."
 )
-@click.option(
-    "--fake-initial",
-    is_flag=True,
-    help="Detect if tables already exist and fake-apply initial migrations if so. Make sure that the current database schema matches your initial migration before using this flag. Plain will only check for an existing table name.",
-)
 @click.option(
     "--plan",
     is_flag=True,
@@ -353,6 +348,13 @@ def makemigrations(package_labels, dry_run, empty, no_input, name, check, verbos
     is_flag=True,
     help="Delete nonexistent migrations from the plainmigrations table.",
 )
+@click.option(
+    "--no-input",
+    "--noinput",
+    "no_input",
+    is_flag=True,
+    help="Tells Plain to NOT prompt the user for input of any kind.",
+)
 @click.option(
     "-v",
     "--verbosity",
@@ -364,11 +366,11 @@ def migrate(
     package_label,
     migration_name,
     fake,
-    fake_initial,
     plan,
     check_unapplied,
     backup,
     prune,
+    no_input,
     verbosity,
 ):
     """Updates database schema. Manages both packages with migrations and those without."""
@@ -500,7 +502,7 @@ def migrate(
                 click.echo(f"    {package}.{name}")
             click.echo(
                 click.style(
-                    "  Re-run 'manage.py migrate' if they are not marked as "
+                    "  Re-run `plain migrate` if they are not marked as "
                     "applied, and remove 'replaces' attributes in their "
                     "Migration classes.",
                     fg="yellow",
@@ -576,9 +578,12 @@ def migrate(
         if backup or (
             backup is None
             and settings.DEBUG
-            and click.confirm(
-                "\nYou are in DEBUG mode. Would you like to make a database backup before running migrations?",
-                default=True,
+            and (
+                no_input
+                or click.confirm(
+                    "\nYou are in DEBUG mode. Would you like to make a database backup before running migrations?",
+                    default=True,
+                )
             )
         ):
             backup_name = f"migrate_{time.strftime('%Y%m%d_%H%M%S')}"
@@ -600,7 +605,6 @@ def migrate(
             plan=migration_plan,
             state=pre_migrate_state.clone(),
             fake=fake,
-            fake_initial=fake_initial,
         )
         # post_migrate signals have access to all models. Ensure that all models
         # are reloaded in case any are delayed.
@@ -642,117 +646,14 @@ def migrate(
             )
             click.echo(
                 click.style(
-                    "  Run 'manage.py makemigrations' to make new "
-                    "migrations, and then re-run 'manage.py migrate' to "
+                    "  Run `plain makemigrations` to make new "
+                    "migrations, and then re-run `plain migrate` to "
                     "apply them.",
                     fg="yellow",
                 )
             )
 
 
-@cli.command()
-@click.argument("package_label")
-@click.argument("migration_name")
-@click.option(
-    "--check",
-    is_flag=True,
-    help="Exit with a non-zero status if the migration can be optimized.",
-)
-@click.option(
-    "-v",
-    "--verbosity",
-    type=int,
-    default=1,
-    help="Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output",
-)
-def optimize_migration(package_label, migration_name, check, verbosity):
-    """Optimizes the operations for the named migration."""
-    try:
-        packages_registry.get_package_config(package_label)
-    except LookupError as err:
-        raise click.ClickException(str(err))
-
-    # Load the current graph state.
-    loader = MigrationLoader(None)
-    if package_label not in loader.migrated_packages:
-        raise click.ClickException(
-            f"Package '{package_label}' does not have migrations."
-        )
-
-    # Find a migration.
-    try:
-        migration = loader.get_migration_by_prefix(package_label, migration_name)
-    except AmbiguityError:
-        raise click.ClickException(
-            f"More than one migration matches '{migration_name}' in package "
-            f"'{package_label}'. Please be more specific."
-        )
-    except KeyError:
-        raise click.ClickException(
-            f"Cannot find a migration matching '{migration_name}' from package "
-            f"'{package_label}'."
-        )
-
-    # Optimize the migration.
-    optimizer = MigrationOptimizer()
-    new_operations = optimizer.optimize(migration.operations, migration.package_label)
-    if len(migration.operations) == len(new_operations):
-        if verbosity > 0:
-            click.echo("No optimizations possible.")
-        return
-    else:
-        if verbosity > 0:
-            click.echo(
-                f"Optimizing from {len(migration.operations)} operations to {len(new_operations)} operations."
-            )
-        if check:
-            sys.exit(1)
-
-    # Set the new migration optimizations.
-    migration.operations = new_operations
-
-    # Write out the optimized migration file.
-    writer = MigrationWriter(migration)
-    migration_file_string = writer.as_string()
-    if writer.needs_manual_porting:
-        if migration.replaces:
-            raise click.ClickException(
-                "Migration will require manual porting but is already a squashed "
-                "migration.\nTransition to a normal migration first."
-            )
-        # Make a new migration with those operations.
-        subclass = type(
-            "Migration",
-            (migrations.Migration,),
-            {
-                "dependencies": migration.dependencies,
-                "operations": new_operations,
-                "replaces": [(migration.package_label, migration.name)],
-            },
-        )
-        optimized_migration_name = f"{migration.name}_optimized"
-        optimized_migration = subclass(optimized_migration_name, package_label)
-        writer = MigrationWriter(optimized_migration)
-        migration_file_string = writer.as_string()
-        if verbosity > 0:
-            click.echo(click.style("Manual porting required", fg="yellow", bold=True))
-            click.echo(
-                "  Your migrations contained functions that must be manually "
-                "copied over,\n"
-                "  as we could not safely copy their implementation.\n"
-                "  See the comment at the top of the optimized migration for "
-                "details."
-            )
-
-    with open(writer.path, "w", encoding="utf-8") as fh:
-        fh.write(migration_file_string)
-
-    if verbosity > 0:
-        click.echo(
-            click.style(f"Optimized migration {writer.path}", fg="green", bold=True)
-        )
-
-
 @cli.command()
 @click.argument("package_labels", nargs=-1)
 @click.option(
@@ -817,7 +718,7 @@ def show_migrations(package_labels, format, verbosity):
                             if plan_node in recorded_migrations:
                                 output = f" [X] {title}"
                             else:
-                                title += " Run 'manage.py migrate' to finish recording."
+                                title += " Run `plain migrate` to finish recording."
                                 output = f" [-] {title}"
                             if verbosity >= 2 and hasattr(applied_migration, "applied"):
                                 output += f" (applied at {applied_migration.applied.strftime('%Y-%m-%d %H:%M:%S')})"
@@ -997,7 +898,7 @@ def squash_migrations(
                 f"The migration '{start_migration}' cannot be found. Maybe it comes after "
                 f"the migration '{migration}'?\n"
                 f"Have a look at:\n"
-                f"  python manage.py showmigrations {package_label}\n"
+                f"  plain models show-migrations {package_label}\n"
                 f"to debug this issue."
             )
 

plain/models/fields/related_descriptors.py

@@ -60,6 +60,7 @@ from plain.models.lookups import GreaterThan, LessThanOrEqual
 from plain.models.query import QuerySet
 from plain.models.query_utils import DeferredAttribute, Q
 from plain.models.utils import resolve_callables
+from plain.utils.functional import LazyObject
 
 
 class ForeignKeyDeferredAttribute(DeferredAttribute):
@@ -222,6 +223,14 @@ class ForwardManyToOneDescriptor:
         - ``instance`` is the ``child`` instance
         - ``value`` is the ``parent`` instance on the right of the equal sign
         """
+        # If value is a LazyObject (like SimpleLazyObject used for request.user),
+        # force its evaluation. For ForeignKey fields, the value should only be
+        # None or a model instance, never a boolean or other type.
+        if isinstance(value, LazyObject):
+            # This forces evaluation: if it's None, value becomes None;
+            # if it's a User instance, value becomes that instance.
+            value = value if value else None
+
         # An object must be an instance of the related class.
         if value is not None and not isinstance(
             value, self.field.remote_field.model._meta.concrete_model

plain/models/migrations/executor.py

@@ -1,5 +1,3 @@
-from plain.models import migrations
-
 from .loader import MigrationLoader
 from .recorder import MigrationRecorder
 from .state import ProjectState
@@ -54,7 +52,7 @@ class MigrationExecutor:
                     migration.mutate_state(state, preserve=False)
         return state
 
-    def migrate(self, targets, plan=None, state=None, fake=False, fake_initial=False):
+    def migrate(self, targets, plan=None, state=None, fake=False):
         """
         Migrate the database up to the given targets.
 
@@ -84,15 +82,13 @@ class MigrationExecutor:
             if state is None:
                 # The resulting state should still include applied migrations.
                 state = self._create_project_state(with_applied_migrations=True)
-            state = self._migrate_all_forwards(
-                state, plan, full_plan, fake=fake, fake_initial=fake_initial
-            )
+            state = self._migrate_all_forwards(state, plan, full_plan, fake=fake)
 
         self.check_replacements()
 
         return state
 
-    def _migrate_all_forwards(self, state, plan, full_plan, fake, fake_initial):
+    def _migrate_all_forwards(self, state, plan, full_plan, fake):
         """
         Take a list of 2-tuples of the form (migration instance, False) and
         apply them in the order they occur in the full_plan.
@@ -112,33 +108,25 @@ class MigrationExecutor:
                     state.models_registry  # Render all -- performance critical
                     if self.progress_callback:
                         self.progress_callback("render_success")
-                state = self.apply_migration(
-                    state, migration, fake=fake, fake_initial=fake_initial
-                )
+                state = self.apply_migration(state, migration, fake=fake)
                 migrations_to_run.remove(migration)
 
         return state
 
-    def apply_migration(self, state, migration, fake=False, fake_initial=False):
+    def apply_migration(self, state, migration, fake=False):
         """Run a migration forwards."""
         migration_recorded = False
         if self.progress_callback:
             self.progress_callback("apply_start", migration, fake)
         if not fake:
-            if fake_initial:
-                # Test to see if this is an already-applied initial migration
-                applied, state = self.detect_soft_applied(state, migration)
-                if applied:
-                    fake = True
-            if not fake:
-                # Alright, do it normally
-                with self.connection.schema_editor(
-                    atomic=migration.atomic
-                ) as schema_editor:
-                    state = migration.apply(state, schema_editor)
-                    if not schema_editor.deferred_sql:
-                        self.record_migration(migration)
-                        migration_recorded = True
+            # Alright, do it normally
+            with self.connection.schema_editor(
+                atomic=migration.atomic
+            ) as schema_editor:
+                state = migration.apply(state, schema_editor)
+                if not schema_editor.deferred_sql:
+                    self.record_migration(migration)
+                    migration_recorded = True
         if not migration_recorded:
             self.record_migration(migration)
         # Report progress
@@ -170,88 +158,3 @@ class MigrationExecutor:
             all_applied = all(m in applied for m in migration.replaces)
             if all_applied and key not in applied:
                 self.recorder.record_applied(*key)
-
-    def detect_soft_applied(self, project_state, migration):
-        """
-        Test whether a migration has been implicitly applied - that the
-        tables or columns it would create exist. This is intended only for use
-        on initial migrations (as it only looks for CreateModel and AddField).
-        """
-
-        if migration.initial is None:
-            # Bail if the migration isn't the first one in its app
-            if any(
-                app == migration.package_label for app, name in migration.dependencies
-            ):
-                return False, project_state
-        elif migration.initial is False:
-            # Bail if it's NOT an initial migration
-            return False, project_state
-
-        if project_state is None:
-            after_state = self.loader.project_state(
-                (migration.package_label, migration.name), at_end=True
-            )
-        else:
-            after_state = migration.mutate_state(project_state)
-        models_registry = after_state.models_registry
-        found_create_model_migration = False
-        found_add_field_migration = False
-        fold_identifier_case = self.connection.features.ignores_table_name_case
-        with self.connection.cursor() as cursor:
-            existing_table_names = set(
-                self.connection.introspection.table_names(cursor)
-            )
-            if fold_identifier_case:
-                existing_table_names = {
-                    name.casefold() for name in existing_table_names
-                }
-        # Make sure all create model and add field operations are done
-        for operation in migration.operations:
-            if isinstance(operation, migrations.CreateModel):
-                model = models_registry.get_model(
-                    migration.package_label, operation.name
-                )
-
-                db_table = model._meta.db_table
-                if fold_identifier_case:
-                    db_table = db_table.casefold()
-                if db_table not in existing_table_names:
-                    return False, project_state
-                found_create_model_migration = True
-            elif isinstance(operation, migrations.AddField):
-                model = models_registry.get_model(
-                    migration.package_label, operation.model_name
-                )
-
-                table = model._meta.db_table
-                field = model._meta.get_field(operation.name)
-
-                # Handle implicit many-to-many tables created by AddField.
-                if field.many_to_many:
-                    through_db_table = field.remote_field.through._meta.db_table
-                    if fold_identifier_case:
-                        through_db_table = through_db_table.casefold()
-                    if through_db_table not in existing_table_names:
-                        return False, project_state
-                    else:
-                        found_add_field_migration = True
-                        continue
-                with self.connection.cursor() as cursor:
-                    columns = self.connection.introspection.get_table_description(
-                        cursor, table
-                    )
-                for column in columns:
-                    field_column = field.column
-                    column_name = column.name
-                    if fold_identifier_case:
-                        column_name = column_name.casefold()
-                        field_column = field_column.casefold()
-                    if column_name == field_column:
-                        found_add_field_migration = True
-                        break
-                else:
-                    return False, project_state
-        # If we get this far and we found at least one CreateModel or AddField
-        # migration, the migration is considered implicitly applied.
-        return (found_create_model_migration or found_add_field_migration), after_state

plain_models-0.40.0.dist-info/METADATA

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: plain.models
+Version: 0.40.0
+Summary: Model your data and store it in a database.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: plain<1.0.0
+Requires-Dist: sqlparse>=0.3.1
+Description-Content-Type: text/markdown
+
+# plain.models
+
+**Model your data and store it in a database.**
+
+- [Overview](#overview)
+- [Database connection](#database-connection)
+- [Querying](#querying)
+- [Migrations](#migrations)
+- [Fields](#fields)
+- [Validation](#validation)
+- [Indexes and constraints](#indexes-and-constraints)
+- [Managers](#managers)
+- [Forms](#forms)
+- [Sharing fields across models](#sharing-fields-across-models)
+- [Installation](#installation)
+
+## Overview
+
+```python
+# app/users/models.py
+from plain import models
+from plain.passwords.models import PasswordField
+
+
+@models.register_model
+class User(models.Model):
+    email = models.EmailField()
+    password = PasswordField()
+    is_admin = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.email
+```
+
+Every model automatically includes an `id` field which serves as the primary
+key. The name `id` is reserved and can't be used for other fields.
+
+Create, update, and delete instances of your models:
+
+```python
+from .models import User
+
+
+# Create a new user
+user = User.objects.create(
+    email="test@example.com",
+    password="password",
+)
+
+# Update a user
+user.email = "new@example.com"
+user.save()
+
+# Delete a user
+user.delete()
+
+# Query for users
+admin_users = User.objects.filter(is_admin=True)
+```
+
+## Database connection
+
+To connect to a database, you can provide a `DATABASE_URL` environment variable:
+
+```sh
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+```
+
+Or you can manually define the `DATABASE` setting:
+
+```python
+# app/settings.py
+DATABASE = {
+    "ENGINE": "plain.models.backends.postgresql",
+    "NAME": "dbname",
+    "USER": "user",
+    "PASSWORD": "password",
+    "HOST": "localhost",
+    "PORT": "5432",
+}
+```
+
+Multiple backends are supported, including Postgres, MySQL, and SQLite.
+
+## Querying
+
+Models come with a powerful query API through their [`Manager`](./manager.py#Manager) interface:
+
+```python
+# Get all users
+all_users = User.objects.all()
+
+# Filter users
+admin_users = User.objects.filter(is_admin=True)
+recent_users = User.objects.filter(created_at__gte=datetime.now() - timedelta(days=7))
+
+# Get a single user
+user = User.objects.get(email="test@example.com")
+
+# Complex queries with Q objects
+from plain.models import Q
+users = User.objects.filter(
+    Q(is_admin=True) | Q(email__endswith="@example.com")
+)
+
+# Ordering
+users = User.objects.order_by("-created_at")
+
+# Limiting results
+first_10_users = User.objects.all()[:10]
+```
+
+For more advanced querying options, see the [`QuerySet`](./query.py#QuerySet) class.
+
+## Migrations
+
+Migrations track changes to your models and update the database schema accordingly:
+
+```bash
+# Create migrations for model changes
+plain makemigrations
+
+# Apply migrations to the database
+plain migrate
+
+# See migration status
+plain models show-migrations
+```
+
+Migrations are Python files that describe database schema changes. They're stored in your app's `migrations/` directory.
+
+## Fields
+
+Plain provides many field types for different data:
+
+```python
+from plain import models
+
+class Product(models.Model):
+    # Text fields
+    name = models.CharField(max_length=200)
+    description = models.TextField()
+
+    # Numeric fields
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+    quantity = models.IntegerField(default=0)
+
+    # Boolean fields
+    is_active = models.BooleanField(default=True)
+
+    # Date and time fields
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    # Relationships
+    category = models.ForeignKey("Category", on_delete=models.CASCADE)
+    tags = models.ManyToManyField("Tag")
+```
+
+Common field types include:
+
+- [`CharField`](./fields/__init__.py#CharField)
+- [`TextField`](./fields/__init__.py#TextField)
+- [`IntegerField`](./fields/__init__.py#IntegerField)
+- [`DecimalField`](./fields/__init__.py#DecimalField)
+- [`BooleanField`](./fields/__init__.py#BooleanField)
+- [`DateTimeField`](./fields/__init__.py#DateTimeField)
+- [`EmailField`](./fields/__init__.py#EmailField)
+- [`URLField`](./fields/__init__.py#URLField)
+- [`UUIDField`](./fields/__init__.py#UUIDField)
+
+## Validation
+
+Models can be validated before saving:
+
+```python
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    age = models.IntegerField()
+
+    def clean(self):
+        if self.age < 18:
+            raise ValidationError("User must be 18 or older")
+
+    def save(self, *args, **kwargs):
+        self.full_clean()  # Runs validation
+        super().save(*args, **kwargs)
+```
+
+Field-level validation happens automatically based on field types and constraints.
+
+## Indexes and constraints
+
+Optimize queries and ensure data integrity with indexes and constraints:
+
+```python
+class User(models.Model):
+    email = models.EmailField()
+    username = models.CharField(max_length=150)
+    age = models.IntegerField()
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["email"]),
+            models.Index(fields=["-created_at"], name="user_created_idx"),
+        ]
+        constraints = [
+            models.UniqueConstraint(fields=["email", "username"], name="unique_user"),
+            models.CheckConstraint(check=models.Q(age__gte=0), name="age_positive"),
+        ]
+```
+
+## Managers
+
+[`Manager`](./manager.py#Manager) objects provide the interface for querying models:
+
+```python
+class PublishedManager(models.Manager):
+    def get_queryset(self):
+        return super().get_queryset().filter(status="published")
+
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    status = models.CharField(max_length=20)
+
+    # Default manager
+    objects = models.Manager()
+
+    # Custom manager
+    published = PublishedManager()
+
+# Usage
+all_articles = Article.objects.all()
+published_articles = Article.published.all()
+```
+
+## Forms
+
+Models integrate with Plain's form system:
+
+```python
+from plain import forms
+from .models import User
+
+class UserForm(forms.ModelForm):
+    class Meta:
+        model = User
+        fields = ["email", "is_admin"]
+
+# Usage
+form = UserForm(data=request.data)
+if form.is_valid():
+    user = form.save()
+```
+
+## Sharing fields across models
+
+To share common fields across multiple models, use Python classes as mixins. The final, registered model must inherit directly from `models.Model` and the mixins should not.
+
+```python
+from plain import models
+
+
+# Regular Python class for shared fields
+class TimestampedMixin:
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+
+# Models inherit from the mixin AND models.Model
+@models.register_model
+class User(TimestampedMixin, models.Model):
+    email = models.EmailField()
+    password = PasswordField()
+    is_admin = models.BooleanField(default=False)
+
+
+@models.register_model
+class Note(TimestampedMixin, models.Model):
+    content = models.TextField(max_length=1024)
+    liked = models.BooleanField(default=False)
+```
+
+## Installation
+
+Install the `plain.models` package from [PyPI](https://pypi.org/project/plain.models/):
+
+```bash
+uv add plain.models
+```
+
+Then add to your `INSTALLED_PACKAGES`:
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    ...
+    "plain.models",
+]
+```

{plain_models-0.39.2.dist-info → plain_models-0.40.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
-plain/models/CHANGELOG.md,sha256=sZMW5wLHmFJ3v1aZeUHsVI3QX8tnKhpivshBn7sNlJs,8028
-plain/models/README.md,sha256=c5Z7YHxsS72mBS9SZuVoJhudwuAQJDm7tYBeh5fwib0,2591
+plain/models/CHANGELOG.md,sha256=aNi4zsWMbFRKdV1O5x9Du-fKepQl3jj6x7Ksu3rcIXI,9295
+plain/models/README.md,sha256=uibhtLwH-JUGzpW3tCFUrQo19i2RAvet1EkpyItdFxM,7269
 plain/models/__init__.py,sha256=LJhlJauhTfUySY2hTJ9qBhCbEKMxTDKpeVrjYXZnsCw,2964
 plain/models/aggregates.py,sha256=P0mhsMl1VZt2CVHMuCHnNI8SxZ9citjDLEgioN6NOpo,7240
 plain/models/base.py,sha256=FJlWJ_LUdjk3Bizi45R4IsYzcuLAoiUHS-R3FxxNmWk,66857
-plain/models/cli.py,sha256=f303FCV4HWJMVHCW-bK3CUOblXblpCknGjgvgnnbs-U,40409
+plain/models/cli.py,sha256=f6VF49l4wWtPn8feTF6IL6qIrcYxk3x9nTf03BOWSp4,36564
 plain/models/config.py,sha256=OF7eIEtXNZyGwgc3eMEpb5uEAup5RXeT-0um60dfBeU,636
 plain/models/connections.py,sha256=RBNa2FZ0x3C9un6PaYL-IYzH_OesRSpdHNGKvYHGiOM,2276
 plain/models/constants.py,sha256=ndnj9TOTKW0p4YcIPLOLEbsH6mOgFi6B1-rIzr_iwwU,210
@@ -34,7 +34,7 @@ plain/models/backends/utils.py,sha256=VN9b_hnGeLqndVAcCx00X7KhFC6jY2Tn6J3E62HqDE
 plain/models/backends/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/backends/base/base.py,sha256=I5040pUAe7-yNTb9wfMNOYjeiFQLZ5dcRI4rtmVKJ04,26457
 plain/models/backends/base/client.py,sha256=90Ffs6zZYCli3tJjwsPH8TItZ8tz1Pp-zhQa-EpsNqc,937
-plain/models/backends/base/creation.py,sha256=i0QQXPAiPrPxsmJhgaxTXavOJXzmpy1UhEmkwvaVsdI,9337
+plain/models/backends/base/creation.py,sha256=H-xx667pLediQ19HDmE_mP-b03tDKQriBmWPKigJ5t0,9332
 plain/models/backends/base/features.py,sha256=1AehdhpeC7VobhggwpeXIt7HJNY2EWY700j4gYX8Xjs,7856
 plain/models/backends/base/introspection.py,sha256=8icKf9h8y4kobmyrbo8JWTDcpQIAt4oS_4FtCnY7FqQ,6815
 plain/models/backends/base/operations.py,sha256=tzuw7AgVb3aZn2RHamReGNco7wIt4UBkAHx8HebDZ_s,25652
@@ -75,7 +75,7 @@ plain/models/fields/__init__.py,sha256=PcricU7Z5qxIw-RIJhVZlMgHWWSJStJjuzU6l0P82
 plain/models/fields/json.py,sha256=OdGW4EYBSHQgkuugB-EiIXOqGstUqcMKUvOTOVUHqEQ,18049
 plain/models/fields/mixins.py,sha256=K_ocrSbb6pPuGwYZeqgzoZskwCIMFIB6IV3T5CrU5J0,1805
 plain/models/fields/related.py,sha256=7Zbpz17zzmMwg9jBQhwPH-dyAW01ClaQGJMMwbArWCM,51027
-plain/models/fields/related_descriptors.py,sha256=4LdV6bLxXsbpYrmD8tnyphE_aX4k0TngUE9bLL6yAEA,38591
+plain/models/fields/related_descriptors.py,sha256=VRWNdR4ptXwxQ0jyBajPV9h2Gv5jc5lzBDl9XZgT4Xk,39094
 plain/models/fields/related_lookups.py,sha256=rtDTS-GvN4goka7CP36dMg1ayUyOEAE39VKXyRMV5g0,7785
 plain/models/fields/reverse_related.py,sha256=AqHPSx1tZ6uj9rESyy1tN1qT415N7eifkgKZHJZWH2k,10767
 plain/models/functions/__init__.py,sha256=aglCm_JtzDYk2KmxubDN_78CGG3JCfRWnfJ74Oj5YJ4,2658
@@ -88,7 +88,7 @@ plain/models/functions/window.py,sha256=3S0QIZc_pIVcWpE5Qq-OxixmtATLb8rZrWkvCfVt
 plain/models/migrations/__init__.py,sha256=ZAQUGrfr_OxYMIO7vUBIHLs_M3oZ4iQSjDzCHRFUdtI,96
 plain/models/migrations/autodetector.py,sha256=8GpvNHdtTshKB05YiP2AWy4Vw5a2ClAm0peA4K7_-WE,61780
 plain/models/migrations/exceptions.py,sha256=_bGjIMaBP2Py9ePUxUhiH0p1zXrQM4JhJO4lWfyF8-g,1044
-plain/models/migrations/executor.py,sha256=0xvduDwB_6KuCFMXsArhmlkEQkTigoMJFptwUTqPOoc,11204
+plain/models/migrations/executor.py,sha256=2_1bWM7Dp3s8z6PADAEN-Y0KnIiRzAqsUkn_nRQl5TA,6757
 plain/models/migrations/graph.py,sha256=nrztu_8dU0wAUSxKUqqFWpvZcSQxGEqE6dXWkPytmCU,12570
 plain/models/migrations/loader.py,sha256=qUTmaEYI1_mV6goQPQYZKjSz8rMbE6G1wqvrAsmuGwA,16464
 plain/models/migrations/migration.py,sha256=22YwRHnaRnCkBpW5p7K89tAU6h4QSsG5yiq-o7W-cSI,6505
@@ -114,8 +114,8 @@ plain/models/sql/where.py,sha256=ezE9Clt2BmKo-I7ARsgqZ_aVA-1UdayCwr6ULSWZL6c,126
 plain/models/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/test/pytest.py,sha256=KD5-mxonBxOYIhUh9Ql5uJOIiC9R4t-LYfb6sjA0UdE,3486
 plain/models/test/utils.py,sha256=S3d6zf3OFWDxB_kBJr0tDvwn51bjwDVWKPumv37N-p8,467
-plain_models-0.39.2.dist-info/METADATA,sha256=Qa0gXCRQ59--VybcXoc-dOsLzVn-FCNST50xAqPk4w0,2886
-plain_models-0.39.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain_models-0.39.2.dist-info/entry_points.txt,sha256=IYJAW9MpL3PXyXFWmKmALagAGXC_5rzBn2eEGJlcV04,112
-plain_models-0.39.2.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain_models-0.39.2.dist-info/RECORD,,
+plain_models-0.40.0.dist-info/METADATA,sha256=jIaS3eoDJumh9HhSOzA-bXfTYB75h5MketBZH37kV0Q,7581
+plain_models-0.40.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_models-0.40.0.dist-info/entry_points.txt,sha256=IYJAW9MpL3PXyXFWmKmALagAGXC_5rzBn2eEGJlcV04,112
+plain_models-0.40.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain_models-0.40.0.dist-info/RECORD,,

plain_models-0.39.2.dist-info/METADATA

@@ -1,147 +0,0 @@
-Metadata-Version: 2.4
-Name: plain.models
-Version: 0.39.2
-Summary: Database models for Plain.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: plain<1.0.0
-Requires-Dist: sqlparse>=0.3.1
-Description-Content-Type: text/markdown
-
-# plain.models
-
-**Model your data and store it in a database.**
-
-```python
-# app/users/models.py
-from plain import models
-from plain.passwords.models import PasswordField
-
-
-@models.register_model
-class User(models.Model):
-    email = models.EmailField()
-    password = PasswordField()
-    is_admin = models.BooleanField(default=False)
-    created_at = models.DateTimeField(auto_now_add=True)
-
-    def __str__(self):
-        return self.email
-```
-
-Every model automatically includes an `id` field which serves as the primary
-key. The name `id` is reserved and can't be used for other fields.
-
-Create, update, and delete instances of your models:
-
-```python
-from .models import User
-
-
-# Create a new user
-user = User.objects.create(
-    email="test@example.com",
-    password="password",
-)
-
-# Update a user
-user.email = "new@example.com"
-user.save()
-
-# Delete a user
-user.delete()
-
-# Query for users
-admin_users = User.objects.filter(is_admin=True)
-```
-
-## Installation
-
-Install `plain.models` from PyPI, then add it to your `INSTALLED_PACKAGES`.
-
-```python
-# app/settings.py
-INSTALLED_PACKAGES = [
-    ...
-    "plain.models",
-]
-```
-
-To connect to a database, you can provide a `DATABASE_URL` environment variable.
-
-```sh
-DATABASE_URL=postgresql://user:password@localhost:5432/dbname
-```
-
-Or you can manually define the `DATABASE` setting.
-
-```python
-# app/settings.py
-DATABASE = {
-    "ENGINE": "plain.models.backends.postgresql",
-    "NAME": "dbname",
-    "USER": "user",
-    "PASSWORD": "password",
-    "HOST": "localhost",
-    "PORT": "5432",
-}
-```
-
-Multiple backends are supported, including Postgres, MySQL, and SQLite.
-
-## Querying
-
-TODO
-
-## Migrations
-
-TODO
-
-## Fields
-
-TODO
-
-## Validation
-
-TODO
-
-## Indexes and constraints
-
-TODO
-
-## Managers
-
-TODO
-
-## Forms
-
-TODO
-
-## Sharing fields across models
-
-To share common fields across multiple models, use Python classes as mixins. The final, registered model must inherit directly from `models.Model` and the mixins should not.
-
-```python
-from plain import models
-
-
-# Regular Python class for shared fields
-class TimestampedMixin:
-    created_at = models.DateTimeField(auto_now_add=True)
-    updated_at = models.DateTimeField(auto_now=True)
-
-
-# Models inherit from the mixin AND models.Model
-@models.register_model
-class User(TimestampedMixin, models.Model):
-    email = models.EmailField()
-    password = PasswordField()
-    is_admin = models.BooleanField(default=False)
-
-
-@models.register_model
-class Note(TimestampedMixin, models.Model):
-    content = models.TextField(max_length=1024)
-    liked = models.BooleanField(default=False)
-```