sera-2 1.13.1__py3-none-any.whl → 1.14.0__py3-none-any.whl

sera/exports/schema.py

@@ -1,128 +1,154 @@
 from pathlib import Path
 from typing import Annotated
 
+import orjson
 import typer
 
-from sera.models import Cardinality, Class, DataProperty, Schema, parse_schema
-from sera.models._datatype import DataType
-
-
-def get_prisma_field_type(datatype: DataType) -> str:
-    pytype = datatype.get_python_type().type
-    if pytype == "str":
-        return "String"
-    if pytype == "int":
-        return "Int"
-    if pytype == "float":
-        return "Float"
-    if pytype == "bool":
-        return "Boolean"
-    if pytype == "bytes":
-        return "Bytes"
-    if pytype == "dict":
-        return "Json"
-    if pytype == "datetime":
-        return "DateTime"
-    if pytype == "list[str]":
-        return "String[]"
-    if pytype == "list[int]":
-        return "Int[]"
-    if pytype == "list[float]":
-        return "Float[]"
-    if pytype == "list[bool]":
-        return "Boolean[]"
-    if pytype == "list[bytes]":
-        return "Bytes[]"
-    if pytype == "list[dict]":
-        return "Json[]"
-    if pytype == "list[datetime]":
-        return "DateTime[]"
-
-    raise ValueError(f"Unsupported data type for Prisma: {pytype}")
-
-
-def to_prisma_model(schema: Schema, cls: Class, lines: list[str]):
-    """Convert a Sera Class to a Prisma model string representation."""
-    lines.append(f"model {cls.name} {{")
-
-    if cls.db is None:
-        # This class has no database mapping, we must generate a default key for it
-        lines.append(
-            f"  {'id'.ljust(30)} {'Int'.ljust(10)} @id @default(autoincrement())"
-        )
-    #     lines.append(f"  @@unique([%s])" % ", ".join(cls.properties.keys()))
-
-    for prop in cls.properties.values():
-        propattrs = ""
-        if isinstance(prop, DataProperty):
-            proptype = get_prisma_field_type(prop.datatype)
-            if prop.is_optional:
-                proptype = f"{proptype}?"
-            if prop.db is not None and prop.db.is_primary_key:
-                propattrs += "@id "
-
-            lines.append(f"  {prop.name.ljust(30)} {proptype.ljust(10)} {propattrs}")
-            continue
-
-        if prop.cardinality == Cardinality.MANY_TO_MANY:
-            # For many-to-many relationships, we need to handle the join table
-            lines.append(
-                f"  {prop.name.ljust(30)} {(prop.target.name + '[]').ljust(10)}"
-            )
-        else:
-            lines.append(
-                f"  {(prop.name + '_').ljust(30)} {prop.target.name.ljust(10)} @relation(fields: [{prop.name}], references: [id])"
-            )
-            lines.append(f"  {prop.name.ljust(30)} {'Int'.ljust(10)} @unique")
-
-    lines.append("")
-    for upstream_cls, reverse_upstream_prop in schema.get_upstream_classes(cls):
-        if (
-            reverse_upstream_prop.cardinality == Cardinality.MANY_TO_ONE
-            or reverse_upstream_prop.cardinality == Cardinality.MANY_TO_MANY
-        ):
-
-            proptype = f"{upstream_cls.name}[]"
-        else:
-            proptype = upstream_cls.name + "?"
-        lines.append(f"  {upstream_cls.name.lower().ljust(30)} {proptype.ljust(10)}")
-
-    lines.append("}\n")
-
-
-def export_prisma_schema(schema: Schema, outfile: Path):
-    """Export Prisma schema file"""
-    lines = []
-
-    # Datasource
-    lines.append("datasource db {")
-    lines.append(
-        '  provider = "postgresql"'
-    )  # Defaulting to postgresql as per user context
-    lines.append('  url      = env("DATABASE_URL")')
-    lines.append("}\n")
-
-    # Generator
-    lines.append("generator client {")
-    lines.append('  provider = "prisma-client-py"')
-    lines.append("  recursive_type_depth = 5")
-    lines.append("}\n")
-
-    # Enums
-    if schema.enums:
-        for enum_name, enum_def in schema.enums.items():
-            lines.append(f"enum {enum_name} {{")
-            # Assuming enum_def.values is a list of strings based on previous errors
-            for val_str in enum_def.values:
-                lines.append(f"  {val_str}")
-            lines.append("}\\n")
-
-    # Models
+from sera.misc import assert_not_null, to_snake_case
+from sera.models import Cardinality, DataProperty, Schema, parse_schema
+
+
+def export_tbls(schema: Schema, outfile: Path):
+    out = {
+        "name": schema.name,
+        "tables": [],
+        "relations": [],
+    }
+
+    DUMMY_IDPROP = "dkey"
+
     for cls in schema.topological_sort():
-        to_prisma_model(schema, cls, lines)
+        table = {
+            "name": cls.name,
+            "type": "BASE TABLE",
+            "columns": [],
+            "constraints": [],
+        }
+
+        if cls.db is None:
+            # This class has no database mapping, we must generate a default key for it
+            table["columns"].append(
+                {
+                    "name": DUMMY_IDPROP,
+                    "type": "UNSET",
+                    "nullable": False,
+                }
+            )
 
-    with outfile.open("w", encoding="utf-8") as f:
-        f.write("\n".join(lines))
+        for prop in cls.properties.values():
+            column = {
+                "name": prop.name,
+                "nullable": not prop.is_optional,
+            }
+
+            if isinstance(prop, DataProperty):
+                column["type"] = prop.datatype.get_python_type().type
+                if prop.db is not None and prop.db.is_primary_key:
+                    table["constraints"].append(
+                        {
+                            "name": f"{cls.name}_pkey",
+                            "type": "PRIMARY KEY",
+                            "def": f"PRIMARY KEY ({prop.name})",
+                            "table": cls.name,
+                            "referenced_table": cls.name,
+                            "columns": [prop.name],
+                        }
+                    )
+            else:
+                if prop.cardinality == Cardinality.MANY_TO_MANY:
+                    # For many-to-many relationships, we need to create a join table
+                    jointable = {
+                        "name": f"{cls.name}{prop.target.name}",
+                        "type": "JOIN TABLE",
+                        "columns": [
+                            {
+                                "name": f"{to_snake_case(cls.name)}_id",
+                                "type": assert_not_null(cls.get_id_property())
+                                .datatype.get_python_type()
+                                .type,
+                                "nullable": False,
+                            },
+                            {
+                                "name": f"{to_snake_case(prop.target.name)}_id",
+                                "type": assert_not_null(prop.target.get_id_property())
+                                .datatype.get_python_type()
+                                .type,
+                                "nullable": False,
+                            },
+                        ],
+                    }
+                    out["tables"].append(jointable)
+                    out["relations"].extend(
+                        [
+                            {
+                                "table": f"{cls.name}{prop.target.name}",
+                                "columns": [f"{to_snake_case(cls.name)}_id"],
+                                "cardinality": "zero_or_more",
+                                "parent_table": cls.name,
+                                "parent_columns": [
+                                    assert_not_null(cls.get_id_property()).name
+                                ],
+                                "parent_cardinality": "zero_or_one",
+                                "def": "",  # LiamERD does not use `def` so we can leave it empty for now
+                            },
+                            {
+                                "table": f"{cls.name}{prop.target.name}",
+                                "columns": [f"{to_snake_case(prop.target.name)}_id"],
+                                "cardinality": "zero_or_more",
+                                "parent_table": prop.target.name,
+                                "parent_columns": [
+                                    assert_not_null(prop.target.get_id_property()).name
+                                ],
+                                "parent_cardinality": "zero_or_one",
+                                "def": "",
+                            },
+                        ]
+                    )
+                    # we actually want to skip adding this N-to-N column
+                    continue
+
+                if prop.target.db is not None:
+                    idprop = assert_not_null(prop.target.get_id_property())
+                    idprop_name = idprop.name
+                    column["type"] = idprop.datatype.get_python_type().type
+                else:
+                    column["type"] = prop.target.name
+                    idprop_name = (
+                        DUMMY_IDPROP  # a dummy property name for visualization purposes
+                    )
+                    assert idprop_name not in prop.target.properties
+
+                # somehow LiamERD only support zero_or_more or zero_or_one (exactly one does not work)
+                if prop.cardinality == Cardinality.ONE_TO_ONE:
+                    cardinality = "zero_or_one"
+                    parent_cardinality = "zero_or_one"
+                elif prop.cardinality == Cardinality.ONE_TO_MANY:
+                    cardinality = "zero_or_one"
+                    parent_cardinality = "zero_or_more"
+                elif prop.cardinality == Cardinality.MANY_TO_ONE:
+                    cardinality = "zero_or_more"
+                    parent_cardinality = "zero_or_one"
+                elif prop.cardinality == Cardinality.MANY_TO_MANY:
+                    raise Exception("Unreachable")
+
+                out["relations"].append(
+                    {
+                        "table": cls.name,
+                        "columns": [prop.name],
+                        "cardinality": cardinality,
+                        "parent_table": prop.target.name,
+                        "parent_columns": [idprop_name],
+                        "parent_cardinality": parent_cardinality,
+                        "def": f"FOREIGN KEY ({prop.name}) REFERENCES {prop.target.name}({idprop_name})",
+                    }
+                )
+
+            table["columns"].append(column)
+
+        out["tables"].append(table)
+
+    outfile.parent.mkdir(parents=True, exist_ok=True)
+    outfile.write_bytes(orjson.dumps(out, option=orjson.OPT_INDENT_2))
 
 
 app = typer.Typer(pretty_exceptions_short=True, pretty_exceptions_enable=False)
@@ -139,7 +165,7 @@ def cli(
     outfile: Annotated[
         Path,
         typer.Option(
-            "-o", "--output", help="Output file for the Prisma schema", writable=True
+            "-o", "--output", help="Output file for the tbls schema", writable=True
         ),
     ],
 ):
@@ -147,7 +173,7 @@ def cli(
         "sera",
         schema_files,
     )
-    export_prisma_schema(
+    export_tbls(
         schema,
         outfile,
     )

sera/make/make_python_api.py

@@ -7,8 +7,7 @@ from loguru import logger
 
 from sera.misc import assert_not_null, to_snake_case
 from sera.models import App, DataCollection, Module, Package, SystemControlledMode
-
-GLOBAL_IDENTS = {"AsyncSession": "sqlalchemy.ext.asyncio.AsyncSession"}
+from sera.typing import GLOBAL_IDENTS
 
 
 def make_python_api(app: App, collections: Sequence[DataCollection]):
@@ -544,19 +543,20 @@ def make_python_create_api(collection: DataCollection, target_pkg: Package):
     )
     program.import_(
         app.models.data.path
-        + f".{collection.get_pymodule_name()}.Upsert{collection.name}",
+        + f".{collection.get_pymodule_name()}.Create{collection.name}",
         True,
     )
 
     # assuming the collection has only one class
     cls = collection.cls
-    has_restricted_system_controlled_prop = any(
-        prop.data.is_system_controlled == SystemControlledMode.RESTRICTED
+    is_on_create_update_props = any(
+        prop.data.system_controlled is not None
+        and prop.data.system_controlled.is_on_create_value_updated()
         for prop in cls.properties.values()
     )
     idprop = assert_not_null(cls.get_id_property())
 
-    if has_restricted_system_controlled_prop:
+    if is_on_create_update_props:
         program.import_("sera.libs.api_helper.SingleAutoUSCP", True)
 
     func_name = "create"
@@ -575,11 +575,11 @@ def make_python_create_api(collection: DataCollection, target_pkg: Package):
                             "dto",
                             PredefinedFn.item_getter(
                                 expr.ExprIdent("SingleAutoUSCP"),
-                                expr.ExprIdent(f"Upsert{cls.name}"),
+                                expr.ExprIdent(f"Create{cls.name}"),
                             ),
                         )
                     ]
-                    if has_restricted_system_controlled_prop
+                    if is_on_create_update_props
                     else []
                 ),
             )
@@ -589,7 +589,7 @@ def make_python_create_api(collection: DataCollection, target_pkg: Package):
             [
                 DeferredVar.simple(
                     "data",
-                    expr.ExprIdent(f"Upsert{cls.name}"),
+                    expr.ExprIdent(f"Create{cls.name}"),
                 ),
                 DeferredVar.simple(
                     "session",
@@ -652,7 +652,7 @@ def make_python_update_api(collection: DataCollection, target_pkg: Package):
     )
     program.import_(
         app.models.data.path
-        + f".{collection.get_pymodule_name()}.Upsert{collection.name}",
+        + f".{collection.get_pymodule_name()}.Update{collection.name}",
         True,
     )
 
@@ -661,11 +661,12 @@ def make_python_update_api(collection: DataCollection, target_pkg: Package):
     id_prop = assert_not_null(cls.get_id_property())
     id_type = id_prop.datatype.get_python_type().type
 
-    has_restricted_system_controlled_prop = any(
-        prop.data.is_system_controlled == SystemControlledMode.RESTRICTED
+    is_on_update_update_props = any(
+        prop.data.system_controlled is not None
+        and prop.data.system_controlled.is_on_update_value_updated()
         for prop in cls.properties.values()
     )
-    if has_restricted_system_controlled_prop:
+    if is_on_update_update_props:
         program.import_("sera.libs.api_helper.SingleAutoUSCP", True)
 
     func_name = "update"
@@ -684,11 +685,11 @@ def make_python_update_api(collection: DataCollection, target_pkg: Package):
                             "dto",
                             PredefinedFn.item_getter(
                                 expr.ExprIdent("SingleAutoUSCP"),
-                                expr.ExprIdent(f"Upsert{cls.name}"),
+                                expr.ExprIdent(f"Update{cls.name}"),
                             ),
                         )
                     ]
-                    if has_restricted_system_controlled_prop
+                    if is_on_update_update_props
                     else []
                 ),
             )
@@ -702,7 +703,7 @@ def make_python_update_api(collection: DataCollection, target_pkg: Package):
                 ),
                 DeferredVar.simple(
                     "data",
-                    expr.ExprIdent(f"Upsert{cls.name}"),
+                    expr.ExprIdent(f"Update{cls.name}"),
                 ),
                 DeferredVar.simple(
                     "session",

sera/make/make_python_model.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
-from typing import Callable, Optional, Sequence
+import sys
+from ast import Not
+from typing import Callable, Literal, Optional, Sequence
 
 from codegen.models import (
     AST,
@@ -28,7 +30,7 @@ from sera.models import (
     Schema,
 )
 from sera.models._property import SystemControlledMode
-from sera.typing import ObjectPath
+from sera.typing import GLOBAL_IDENTS, ObjectPath
 
 
 def make_python_enums(
@@ -144,6 +146,7 @@ def make_python_data_model(
         program: Program,
         slf: expr.ExprIdent,
         cls: Class,
+        mode: Literal["create", "update"],
         prop: DataProperty | ObjectProperty,
     ):
         value = PredefinedFn.attr_getter(slf, expr.ExprIdent(prop.name))
@@ -194,7 +197,7 @@ def make_python_data_model(
                 prop.datatype.get_python_type().type,
             )(value)
 
-            if prop.data.is_private:
+            if mode == "update" and prop.data.is_private:
                 # if the property is private and it's UNSET, we cannot transform it to the database type
                 # and has to use the UNSET value (the update query will ignore this field)
                 program.import_("sera.typing.UNSET", True)
@@ -208,7 +211,133 @@ def make_python_data_model(
                 value = converted_value
         return value
 
-    def make_upsert(program: Program, cls: Class):
+    def make_uscp_func(
+        cls: Class,
+        mode: Literal["create", "update"],
+        ast: AST,
+        ident_manager: ImportHelper,
+    ):
+        func = ast.func(
+            "update_system_controlled_props",
+            [
+                DeferredVar.simple("self"),
+                DeferredVar.simple(
+                    "conn",
+                    ident_manager.use("ASGIConnection"),
+                ),
+            ],
+        )
+
+        assign_user = False
+
+        for prop in cls.properties.values():
+            if prop.data.system_controlled is None:
+                continue
+
+            update_func = None
+            if mode == "create":
+                if prop.data.system_controlled.on_create_bypass is not None:
+                    # by-pass the update function are handled later
+                    continue
+
+                if prop.data.system_controlled.is_on_create_value_updated():
+                    update_func = (
+                        prop.data.system_controlled.get_on_create_update_func()
+                    )
+            else:
+                if prop.data.system_controlled.on_update_bypass is not None:
+                    # by-pass the update function are handled later
+                    continue
+                if prop.data.system_controlled.is_on_update_value_updated():
+                    update_func = (
+                        prop.data.system_controlled.get_on_update_update_func()
+                    )
+
+            if update_func is None:
+                continue
+
+            if update_func.func == "getattr":
+                if update_func.args[0] == "user":
+                    if len(update_func.args) != 2:
+                        raise NotImplementedError(
+                            f"Unsupported update function: {update_func.func} with args {update_func.args}"
+                        )
+                    if not assign_user:
+                        func(
+                            stmt.AssignStatement(
+                                expr.ExprIdent("user"),
+                                PredefinedFn.item_getter(
+                                    PredefinedFn.attr_getter(
+                                        expr.ExprIdent("conn"),
+                                        expr.ExprIdent("scope"),
+                                    ),
+                                    expr.ExprConstant("user"),
+                                ),
+                            )
+                        )
+                        assign_user = True
+                    epr = PredefinedFn.attr_getter(
+                        expr.ExprIdent("user"), expr.ExprIdent(update_func.args[1])
+                    )
+                elif update_func.args[0] == "self":
+                    epr = PredefinedFn.attr_getter(
+                        expr.ExprIdent("self"), expr.ExprIdent(update_func.args[1])
+                    )
+                else:
+                    raise NotImplementedError(
+                        f"Unsupported update function: {update_func.func} with args {update_func.args}"
+                    )
+            else:
+                raise NotImplementedError(update_func.func)
+
+            smt = stmt.AssignStatement(
+                PredefinedFn.attr_getter(
+                    expr.ExprIdent("self"), expr.ExprIdent(prop.name)
+                ),
+                epr,
+            )
+            func(smt)
+
+        # handle the by-pass properties here
+        for prop in cls.properties.values():
+            if prop.data.system_controlled is None:
+                continue
+
+            update_func = None
+            if mode == "create":
+                if prop.data.system_controlled.on_create_bypass is None:
+                    # non by-pass the update function are handled earlier
+                    continue
+
+                if prop.data.system_controlled.is_on_create_value_updated():
+                    update_func = (
+                        prop.data.system_controlled.get_on_create_update_func()
+                    )
+            else:
+                if prop.data.system_controlled.on_update_bypass is None:
+                    # non by-pass the update function are handled earlier
+                    continue
+
+                if prop.data.system_controlled.is_on_update_value_updated():
+                    update_func = (
+                        prop.data.system_controlled.get_on_update_update_func()
+                    )
+
+            if update_func is None:
+                continue
+
+            raise NotImplementedError("We haven't handled the by-pass properties yet.")
+
+        func(
+            stmt.AssignStatement(
+                PredefinedFn.attr_getter(
+                    expr.ExprIdent("self"), expr.ExprIdent("_is_scp_updated")
+                ),
+                expr.ExprConstant(True),
+            )
+        )
+
+    def make_create(program: Program, cls: Class):
         program.import_("__future__.annotations", True)
         program.import_("msgspec", False)
         if cls.db is not None:
@@ -221,52 +350,214 @@ def make_python_data_model(
 
         ident_manager = ImportHelper(
             program,
-            {
-                "UNSET": "sera.typing.UNSET",
-            },
+            GLOBAL_IDENTS,
         )
 
-        # property that normal users cannot set, but super users can
-        has_restricted_system_controlled = any(
-            prop.data.is_system_controlled == SystemControlledMode.RESTRICTED
+        is_on_create_value_updated = any(
+            prop.data.system_controlled is not None
+            and prop.data.system_controlled.is_on_create_value_updated()
             for prop in cls.properties.values()
         )
-        if has_restricted_system_controlled:
-            program.import_("typing.TypedDict", True)
-            program.root(
+        program.root.linebreak()
+        cls_ast = program.root.class_(
+            "Create" + cls.name,
+            [expr.ExprIdent("msgspec.Struct"), expr.ExprIdent("kw_only=True")],
+        )
+        for prop in cls.properties.values():
+            # Skip fields that are system-controlled (e.g., cached or derived fields)
+            # and cannot be updated based on information parsed from the request.
+            if (
+                prop.data.system_controlled is not None
+                and prop.data.system_controlled.is_on_create_ignored()
+            ):
+                continue
+
+            if isinstance(prop, DataProperty):
+                pytype = prop.get_data_model_datatype().get_python_type()
+                if prop.is_optional:
+                    pytype = pytype.as_optional_type()
+
+                for dep in pytype.deps:
+                    program.import_(dep, True)
+
+                pytype_type = pytype.type
+                if len(prop.data.constraints) > 0:
+                    # if the property has constraints, we need to figure out
+                    program.import_("typing.Annotated", True)
+                    if len(prop.data.constraints) == 1:
+                        pytype_type = f"Annotated[%s, %s]" % (
+                            pytype_type,
+                            prop.data.constraints[0].get_msgspec_constraint(),
+                        )
+                    else:
+                        raise NotImplementedError(prop.data.constraints)
+
+                # private property are available for creating, but not for updating.
+                # so we do not need to skip it.
+                # if prop.data.is_private:
+                #     program.import_("typing.Union", True)
+                #     program.import_("sera.typing.UnsetType", True)
+                #     program.import_("sera.typing.UNSET", True)
+                #     pytype_type = f"Union[{pytype_type}, UnsetType]"
+
+                prop_default_value = None
+                # if prop.data.is_private:
+                #     prop_default_value = expr.ExprIdent("UNSET")
+                if prop.default_value is not None:
+                    prop_default_value = expr.ExprConstant(prop.default_value)
+                elif prop.default_factory is not None:
+                    program.import_(prop.default_factory.pyfunc, True)
+                    prop_default_value = expr.ExprFuncCall(
+                        expr.ExprIdent("msgspec.field"),
+                        [
+                            PredefinedFn.keyword_assignment(
+                                "default_factory",
+                                expr.ExprIdent(prop.default_factory.pyfunc),
+                            )
+                        ],
+                    )
+
+                cls_ast(
+                    stmt.DefClassVarStatement(
+                        prop.name, pytype_type, prop_default_value
+                    )
+                )
+            elif isinstance(prop, ObjectProperty):
+                if prop.target.db is not None:
+                    # if the target class is in the database, we expect the user to pass the foreign key for it.
+                    pytype = (
+                        assert_not_null(prop.target.get_id_property())
+                        .get_data_model_datatype()
+                        .get_python_type()
+                    )
+                else:
+                    pytype = PyTypeWithDep(
+                        f"Create{prop.target.name}",
+                        [
+                            f"{target_pkg.module(prop.target.get_pymodule_name()).path}.Create{prop.target.name}"
+                        ],
+                    )
+
+                if prop.cardinality.is_star_to_many():
+                    pytype = pytype.as_list_type()
+                elif prop.is_optional:
+                    pytype = pytype.as_optional_type()
+
+                pytype_type = pytype.type
+
+                for dep in pytype.deps:
+                    program.import_(dep, True)
+
+                cls_ast(stmt.DefClassVarStatement(prop.name, pytype_type))
+
+        if is_on_create_value_updated:
+            program.import_("typing.Optional", True)
+            program.import_("sera.typing.is_set", True)
+            cls_ast(
+                stmt.Comment(
+                    "A marker to indicate that the system-controlled properties are updated"
+                ),
+                stmt.DefClassVarStatement(
+                    "_is_scp_updated", "bool", expr.ExprConstant(False)
+                ),
                 stmt.LineBreak(),
-                lambda ast: ast.class_(
-                    "SystemControlledProps",
-                    [expr.ExprIdent("TypedDict")],
+                lambda ast: ast.func(
+                    "__post_init__",
+                    [
+                        DeferredVar.simple("self"),
+                    ],
                 )(
-                    *[
-                        stmt.DefClassVarStatement(
-                            prop.name,
+                    stmt.AssignStatement(
+                        PredefinedFn.attr_getter(
+                            expr.ExprIdent("self"), expr.ExprIdent("_is_scp_updated")
+                        ),
+                        expr.ExprConstant(False),
+                    ),
+                ),
+                stmt.LineBreak(),
+                lambda ast: make_uscp_func(cls, "create", ast, ident_manager),
+            )
+
+        cls_ast(
+            stmt.LineBreak(),
+            lambda ast00: ast00.func(
+                "to_db",
+                [
+                    DeferredVar.simple("self"),
+                ],
+                return_type=expr.ExprIdent(
+                    f"{cls.name}DB" if cls.db is not None else cls.name
+                ),
+            )(
+                (
+                    stmt.AssertionStatement(
+                        PredefinedFn.attr_getter(
+                            expr.ExprIdent("self"),
+                            expr.ExprIdent("_is_scp_updated"),
+                        ),
+                        expr.ExprConstant(
+                            "The model data must be verified before converting to db model"
+                        ),
+                    )
+                    if is_on_create_value_updated
+                    else None
+                ),
+                lambda ast10: ast10.return_(
+                    expr.ExprFuncCall(
+                        expr.ExprIdent(
+                            f"{cls.name}DB" if cls.db is not None else cls.name
+                        ),
+                        [
                             (
-                                prop.get_data_model_datatype().get_python_type().type
-                                if isinstance(prop, DataProperty)
-                                else assert_not_null(prop.target.get_id_property())
-                                .get_data_model_datatype()
-                                .get_python_type()
-                                .type
-                            ),
-                        )
-                        for prop in cls.properties.values()
-                        if prop.data.is_system_controlled
-                        == SystemControlledMode.RESTRICTED
-                    ],
+                                ident_manager.use("UNSET")
+                                if prop.data.system_controlled is not None
+                                and prop.data.system_controlled.is_on_create_ignored()
+                                else to_db_type_conversion(
+                                    program, expr.ExprIdent("self"), cls, "create", prop
+                                )
+                            )
+                            for prop in cls.properties.values()
+                        ],
+                    )
                 ),
+            ),
+        )
+
+    def make_update(program: Program, cls: Class):
+        program.import_("__future__.annotations", True)
+        program.import_("msgspec", False)
+        if cls.db is not None:
+            # if the class is stored in the database, we need to import the database module
+            program.import_(
+                app.models.db.path + f".{cls.get_pymodule_name()}.{cls.name}",
+                True,
+                alias=f"{cls.name}DB",
             )
 
+        ident_manager = ImportHelper(
+            program,
+            GLOBAL_IDENTS,
+        )
+
+        # property that normal users cannot set, but super users can
+        is_on_update_value_updated = any(
+            prop.data.system_controlled is not None
+            and prop.data.system_controlled.is_on_update_value_updated()
+            for prop in cls.properties.values()
+        )
+
         program.root.linebreak()
         cls_ast = program.root.class_(
-            "Upsert" + cls.name,
+            "Update" + cls.name,
             [expr.ExprIdent("msgspec.Struct"), expr.ExprIdent("kw_only=True")],
         )
         for prop in cls.properties.values():
-            # a field that is fully controlled by the system (e.g., cached or derived fields)
-            # aren't allowed to be set by the users, so we skip them
-            if prop.data.is_system_controlled == SystemControlledMode.AUTO:
+            # Skip fields that are system-controlled (e.g., cached or derived fields)
+            # and cannot be updated based on information parsed from the request.
+            if (
+                prop.data.system_controlled is not None
+                and prop.data.system_controlled.is_on_update_ignored()
+            ):
                 continue
 
             if isinstance(prop, DataProperty):
@@ -289,20 +580,14 @@ def make_python_data_model(
                     else:
                         raise NotImplementedError(prop.data.constraints)
 
-                if (
-                    prop.data.is_private
-                    or prop.data.is_system_controlled == SystemControlledMode.RESTRICTED
-                ):
+                if prop.data.is_private:
                     program.import_("typing.Union", True)
                     program.import_("sera.typing.UnsetType", True)
                     program.import_("sera.typing.UNSET", True)
                     pytype_type = f"Union[{pytype_type}, UnsetType]"
 
                 prop_default_value = None
-                if (
-                    prop.data.is_private
-                    or prop.data.is_system_controlled == SystemControlledMode.RESTRICTED
-                ):
+                if prop.data.is_private:
                     prop_default_value = expr.ExprIdent("UNSET")
                 elif prop.default_value is not None:
                     prop_default_value = expr.ExprConstant(prop.default_value)
@@ -333,9 +618,9 @@ def make_python_data_model(
                     )
                 else:
                     pytype = PyTypeWithDep(
-                        f"Upsert{prop.target.name}",
+                        f"Update{prop.target.name}",
                         [
-                            f"{target_pkg.module(prop.target.get_pymodule_name()).path}.Upsert{prop.target.name}"
+                            f"{target_pkg.module(prop.target.get_pymodule_name()).path}.Update{prop.target.name}"
                         ],
                     )
 
@@ -345,77 +630,38 @@ def make_python_data_model(
                     pytype = pytype.as_optional_type()
 
                 pytype_type = pytype.type
-                prop_default_value = None
-                if prop.data.is_system_controlled == SystemControlledMode.RESTRICTED:
-                    program.import_("typing.Union", True)
-                    program.import_("sera.typing.UnsetType", True)
-                    program.import_("sera.typing.UNSET", True)
-                    pytype_type = f"Union[{pytype_type}, UnsetType]"
-                    prop_default_value = expr.ExprIdent("UNSET")
 
                 for dep in pytype.deps:
                     program.import_(dep, True)
 
-                cls_ast(
-                    stmt.DefClassVarStatement(
-                        prop.name, pytype_type, prop_default_value
-                    )
-                )
+                cls_ast(stmt.DefClassVarStatement(prop.name, pytype_type))
 
-        if has_restricted_system_controlled:
+        if is_on_update_value_updated:
             program.import_("typing.Optional", True)
             program.import_("sera.typing.is_set", True)
             cls_ast(
-                stmt.LineBreak(),
-                lambda ast: ast.func(
-                    "__post_init__",
-                    [
-                        DeferredVar.simple("self"),
-                    ],
-                )(
-                    *[
-                        stmt.AssignStatement(
-                            PredefinedFn.attr_getter(
-                                expr.ExprIdent("self"), expr.ExprIdent(prop.name)
-                            ),
-                            expr.ExprIdent("UNSET"),
-                        )
-                        for prop in cls.properties.values()
-                        if prop.data.is_system_controlled
-                        == SystemControlledMode.RESTRICTED
-                    ]
+                stmt.Comment(
+                    "A marker to indicate that the system-controlled properties are updated"
+                ),
+                stmt.DefClassVarStatement(
+                    "_is_scp_updated", "bool", expr.ExprConstant(False)
                 ),
                 stmt.LineBreak(),
                 lambda ast: ast.func(
-                    "update_system_controlled_props",
+                    "__post_init__",
                     [
                         DeferredVar.simple("self"),
-                        DeferredVar.simple(
-                            "data",
-                            expr.ExprIdent("Optional[SystemControlledProps]"),
-                        ),
                     ],
                 )(
-                    lambda ast00: ast00.if_(
-                        expr.ExprNegation(
-                            expr.ExprIs(expr.ExprIdent("data"), expr.ExprConstant(None))
+                    stmt.AssignStatement(
+                        PredefinedFn.attr_getter(
+                            expr.ExprIdent("self"), expr.ExprIdent("_is_scp_updated")
                         ),
-                    )(
-                        *[
-                            stmt.AssignStatement(
-                                PredefinedFn.attr_getter(
-                                    expr.ExprIdent("self"), expr.ExprIdent(prop.name)
-                                ),
-                                PredefinedFn.item_getter(
-                                    expr.ExprIdent("data"), expr.ExprConstant(prop.name)
-                                ),
-                            )
-                            for prop in cls.properties.values()
-                            if prop.data.is_system_controlled
-                            == SystemControlledMode.RESTRICTED
-                        ]
+                        expr.ExprConstant(False),
                     ),
                 ),
+                stmt.LineBreak(),
+                lambda ast: make_uscp_func(cls, "update", ast, ident_manager),
             )
 
         cls_ast(
@@ -443,15 +689,15 @@ def make_python_data_model(
                                     ],
                                 )
                                 for prop in cls.properties.values()
-                                if prop.data.is_system_controlled
-                                == SystemControlledMode.RESTRICTED
+                                if prop.data.system_controlled is not None
+                                and prop.data.system_controlled.is_on_update_value_updated()
                             ]
                         ),
                         expr.ExprConstant(
                             "The model data must be verified before converting to db model"
                         ),
                     )
-                    if has_restricted_system_controlled
+                    if is_on_update_value_updated
                     else None
                 ),
                 lambda ast10: ast10.return_(
@@ -461,12 +707,12 @@ def make_python_data_model(
                         ),
                         [
                             (
-                                to_db_type_conversion(
-                                    program, expr.ExprIdent("self"), cls, prop
+                                ident_manager.use("UNSET")
+                                if prop.data.system_controlled is not None
+                                and prop.data.system_controlled.is_on_update_ignored()
+                                else to_db_type_conversion(
+                                    program, expr.ExprIdent("self"), cls, "update", prop
                                 )
-                                if prop.data.is_system_controlled
-                                != SystemControlledMode.AUTO
-                                else ident_manager.use("UNSET")
                             )
                             for prop in cls.properties.values()
                         ],
@@ -617,7 +863,7 @@ def make_python_data_model(
                         PredefinedFn.tuple(
                             [
                                 to_db_type_conversion(
-                                    program, expr.ExprIdent("self"), cls, prop
+                                    program, expr.ExprIdent("self"), cls, "create", prop
                                 )
                                 for prop in cls.properties.values()
                             ]
@@ -631,7 +877,9 @@ def make_python_data_model(
             continue
 
         program = Program()
-        make_upsert(program, cls)
+        make_create(program, cls)
+        program.root.linebreak()
+        make_update(program, cls)
         program.root.linebreak()
         make_normal(program, cls)
         target_pkg.module(cls.get_pymodule_name()).write(program)

sera/models/_parse.py

@@ -5,6 +5,7 @@ from copy import deepcopy
 from pathlib import Path
 from typing import Sequence
 
+import orjson
 import serde.yaml
 
 from sera.models._class import Class, ClassDBMapInfo, Index
@@ -28,9 +29,11 @@ from sera.models._property import (
     DataProperty,
     ForeignKeyOnDelete,
     ForeignKeyOnUpdate,
+    GetSCPropValueFunc,
     ObjectPropDBInfo,
     ObjectProperty,
     PropDataAttrs,
+    SystemControlledAttrs,
     SystemControlledMode,
 )
 from sera.models._schema import Schema
@@ -135,6 +138,9 @@ def _parse_property(
         is_system_controlled=SystemControlledMode(
             _data.get("is_system_controlled", SystemControlledMode.NO.value)
         ),
+        system_controlled=_parse_system_controlled_attrs(
+            _data.get("system_controlled")
+        ),
     )
 
     assert isinstance(prop, dict), prop
@@ -286,3 +292,59 @@ def _parse_default_factory(default_factory: dict | None) -> DefaultFactory | Non
     return DefaultFactory(
         pyfunc=default_factory["pyfunc"], tsfunc=default_factory["tsfunc"]
     )
+
+
+def _parse_system_controlled_attrs(
+    attrs: dict | None,
+) -> SystemControlledAttrs | None:
+    if attrs is None:
+        return None
+    if not isinstance(attrs, dict):
+        raise NotImplementedError(attrs)
+
+    if "on_upsert" in attrs:
+        attrs = attrs.copy()
+        attrs.update(
+            {
+                "on_create": attrs["on_upsert"],
+                "on_create_bypass": attrs.get("on_upsert_bypass"),
+                "on_update": attrs["on_upsert"],
+                "on_update_bypass": attrs.get("on_upsert_bypass"),
+            }
+        )
+
+    if "on_create" not in attrs or "on_update" not in attrs:
+        raise ValueError(
+            "System controlled attributes must have 'on_create', 'on_update', or 'on_upsert' must be defined."
+        )
+
+    keys = {}
+    for key in ["on_create", "on_update"]:
+        if attrs[key] == "ignored":
+            keys[key] = "ignored"
+        elif attrs[key].find(":") != -1:
+            func, args = attrs[key].split(":")
+            assert func == "getattr", f"Unsupported function: {func}"
+            args = orjson.loads(args)
+            keys[key] = GetSCPropValueFunc(
+                func=func,
+                args=args,
+            )
+        else:
+            raise ValueError(
+                f"System controlled attribute '{key}' must be 'ignored' or a function call in the format '<funcname>:<args>'."
+            )
+
+        if attrs[key + "_bypass"] is not None:
+            if not isinstance(attrs[key + "_bypass"], str):
+                raise ValueError(
+                    f"System controlled attribute '{key}_bypass' must be a string."
+                )
+            keys[key + "_bypass"] = attrs[key + "_bypass"]
+
+    return SystemControlledAttrs(
+        on_create=keys["on_create"],
+        on_create_bypass=keys.get("on_create_bypass"),
+        on_update=keys["on_update"],
+        on_update_bypass=keys.get("on_update_bypass"),
+    )

sera/models/_property.py

@@ -69,6 +69,43 @@ class SystemControlledMode(str, Enum):
     NO = "no"
 
 
+@dataclass(kw_only=True)
+class GetSCPropValueFunc:
+
+    func: Literal["getattr"]
+    args: tuple[str, ...]
+
+
+@dataclass(kw_only=True)
+class SystemControlledAttrs:
+    """Attributes for a system-controlled property."""
+
+    on_create_bypass: Optional[str]
+    on_create: Literal["ignored"] | GetSCPropValueFunc
+    on_update_bypass: Optional[str]
+    on_update: Literal["ignored"] | GetSCPropValueFunc
+
+    def is_on_create_value_updated(self) -> bool:
+        return isinstance(self.on_create, GetSCPropValueFunc)
+
+    def get_on_create_update_func(self) -> GetSCPropValueFunc:
+        assert isinstance(self.on_create, GetSCPropValueFunc)
+        return self.on_create
+
+    def is_on_create_ignored(self) -> bool:
+        return self.on_create == "ignored"
+
+    def is_on_update_ignored(self) -> bool:
+        return self.on_update == "ignored"
+
+    def is_on_update_value_updated(self) -> bool:
+        return isinstance(self.on_update, GetSCPropValueFunc)
+
+    def get_on_update_update_func(self) -> GetSCPropValueFunc:
+        assert isinstance(self.on_update, GetSCPropValueFunc)
+        return self.on_update
+
+
 @dataclass(kw_only=True)
 class PropDataAttrs:
     """Storing other attributes for generating data model (upsert & public) -- this is different from a db model"""
@@ -87,6 +124,9 @@ class PropDataAttrs:
     # whether this property is controlled by the system or not
     is_system_controlled: SystemControlledMode = SystemControlledMode.NO
 
+    # if this property is controlled by the system, the attributes for the system-controlled property
+    system_controlled: Optional[SystemControlledAttrs] = None
+
 
 @dataclass(kw_only=True)
 class Property:

sera/typing.py

@@ -30,3 +30,11 @@ UNSET: Any = msgspec.UNSET
 def is_set(value: Union[T, UnsetType]) -> TypeGuard[T]:
     """Typeguard to check if a value is set (not UNSET)"""
     return value is not UNSET
+
+
+# Global identifiers for codegen
+GLOBAL_IDENTS = {
+    "AsyncSession": "sqlalchemy.ext.asyncio.AsyncSession",
+    "ASGIConnection": "litestar.connection.ASGIConnection",
+    "UNSET": "sera.typing.UNSET",
+}

{sera_2-1.13.1.dist-info → sera_2-1.14.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sera-2
-Version: 1.13.1
+Version: 1.14.0
 Summary: 
 Author: Binh Vu
 Author-email: bvu687@gmail.com
@@ -9,7 +9,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: black (>=25.1.0,<26.0.0)
-Requires-Dist: codegen-2 (>=2.11.0,<3.0.0)
+Requires-Dist: codegen-2 (>=2.11.1,<3.0.0)
 Requires-Dist: isort (>=6.0.1,<7.0.0)
 Requires-Dist: litestar (>=2.15.1,<3.0.0)
 Requires-Dist: loguru (>=0.7.0,<0.8.0)

{sera_2-1.13.1.dist-info → sera_2-1.14.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 sera/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sera/constants.py,sha256=mzAaMyIx8TJK0-RYYJ5I24C4s0Uvj26OLMJmBo0pxHI,123
 sera/exports/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sera/exports/schema.py,sha256=3F5Kx3r0zOmiVpDf9vnzGhtdcuF-vfgMhBbp4Ko4fgw,4740
+sera/exports/schema.py,sha256=EAFKwULu8Nmb3IUBMCyt7M6YM4TGPo8yRRRu_KxBTxs,7045
 sera/exports/test.py,sha256=jK1EJmLGiy7eREpnY_68IIVRH43uH8S_u5Z7STPbXOM,2002
 sera/libs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sera/libs/api_helper.py,sha256=47y1kcwk3Xd2ZEMnUj_0OwCuUmgwOs5kYrE95BDVUn4,5411
@@ -16,8 +16,8 @@ sera/libs/middlewares/uscp.py,sha256=H5umW8iEQSCdb_MJ5Im49kxg1E7TpxSg1p2_2A5zI1U
 sera/make/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sera/make/__main__.py,sha256=bt-gDF8E026OWc2zqr9_a3paMOiDkFd3ybWn8ltL2g0,1448
 sera/make/make_app.py,sha256=n9NtW73O3s_5Q31VHIRmnd-jEIcpDO7ksAsOdovde2s,5999
-sera/make/make_python_api.py,sha256=sf-J5Pt1LTyM_H-SgXSAvKjEMDrRA6WnDpgDPbJG360,26896
-sera/make/make_python_model.py,sha256=XWoNmfVNfdzF3lwEaItPZjo27ibqL9yjHA3a0vrHsnA,51708
+sera/make/make_python_api.py,sha256=9Pr5IxhC5iFkNq8DEh8Wfqa01AGm9YUxf9qdLmMdf_Y,26875
+sera/make/make_python_model.py,sha256=Q9lirILQS_J00FfRBE8JZvMZTsfkZ6iziHknwxpU-fo,61420
 sera/make/make_python_services.py,sha256=0ZpWLwQ7Nwfn8BXAikAB4JRpNknpSJyJgY5b1cjtxV4,2073
 sera/make/make_typescript_model.py,sha256=ugDdSTw_1ayHLuL--92RQ8hf_D-dpJtnvmUZNxcwcDs,63687
 sera/misc/__init__.py,sha256=Dh4uDq0D4N53h3zhvmwfa5a0TPVRSUvLzb0hkFuPirk,411
@@ -32,10 +32,10 @@ sera/models/_default.py,sha256=ABggW6qdPR4ZDqIPJdJ0GCGQ-7kfsfZmQ_DchgZEa-I,137
 sera/models/_enum.py,sha256=sy0q7E646F-APsqrVQ52r1fAQ_DCAeaNq5YM5QN3zIk,2070
 sera/models/_module.py,sha256=8QRSCubZmdDP9rL58rGAS6X5VCrkc1ZHvuMu1I1KrWk,5043
 sera/models/_multi_lingual_string.py,sha256=JETN6k00VH4wrA4w5vAHMEJV8fp3SY9bJebskFTjQLA,1186
-sera/models/_parse.py,sha256=q_YZ7PrHWIN85_WW-fPP7-2gLXlGWM2-EIdbYXuG7Xg,10052
-sera/models/_property.py,sha256=4y9F58D6DoX25-6aWPBRiE72nCPQy0KWlGNDTZXSV-8,6038
+sera/models/_parse.py,sha256=IhDBmtdwilI_SOV-Rj_DGiNUHTH_sE1s7-OhoGG0hK0,12154
+sera/models/_property.py,sha256=yITA3B5lsFTMLMwXmIjPzEun_F_Z1NoRx9lroQEWXHM,7320
 sera/models/_schema.py,sha256=VxJEiqgVvbXgcSUK4UW6JnRcggk4nsooVSE6MyXmfNY,1636
-sera/typing.py,sha256=Q4QMfbtfrCjC9tFfsZPhsAnbNX4lm4NHQ9lmjNXYdV0,772
-sera_2-1.13.1.dist-info/METADATA,sha256=xM2la_NEr7esZtrLlTbwARiHlqp43Y0VVqQR4zuFEmo,867
-sera_2-1.13.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-sera_2-1.13.1.dist-info/RECORD,,
+sera/typing.py,sha256=Fl4-UzLJu1GdLLk_g87fA7nT9wQGelNnGzag6dg_0gs,980
+sera_2-1.14.0.dist-info/METADATA,sha256=rcYbdo7hCFXIijgTD_qnQ8RAAEDTYpbZHvDHrEmicOU,867
+sera_2-1.14.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+sera_2-1.14.0.dist-info/RECORD,,