TypeDAL 4.7.2__tar.gz → 4.8.1__tar.gz

{typedal-4.7.2 → typedal-4.8.1}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 <!--next-version-placeholder-->
 
+## v4.8.1 (2026-05-10)
+
+### Fix
+
+* Extend from empty type-safe `DALProtocol` during type-checking to make some LSPs happier ([`d93a361`](https://github.com/trialandsuccess/TypeDAL/commit/d93a361e9caa6c9b94d6fbfa78644c8ff5e2bc23))
+
+## v4.8.0 (2026-04-23)
+
+### Feature
+
+* TypeDAL 4.8: type... script? ([#9](https://github.com/trialandsuccess/TypeDAL/issues/9)) ([`9a688c0`](https://github.com/trialandsuccess/TypeDAL/commit/9a688c012ddcb77207b5879b7c66c6c2fee547c0))
+
+### Fix
+
+* **uuid:** Don't try to store NULL uuid as 'None' ([`29f8606`](https://github.com/trialandsuccess/TypeDAL/commit/29f8606972110b5472a42806c6c0e5b66f50095a))
+* Ensure `InvalidEnumValue` is falsey ([`21fea08`](https://github.com/trialandsuccess/TypeDAL/commit/21fea086e3219d47615f7b9539caf4d5f5c48327))
+
 ## v4.7.2 (2026-04-20)
 
 ### Fix

{typedal-4.7.2 → typedal-4.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypeDAL
-Version: 4.7.2
+Version: 4.8.1
 Summary: Typing support for PyDAL
 Project-URL: Documentation, https://typedal.readthedocs.io/
 Project-URL: Issues, https://github.com/trialandsuccess/TypeDAL/issues
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.12
 Requires-Dist: configurable-json<2
-Requires-Dist: configuraptor<3,>=2.0.1
+Requires-Dist: configuraptor<3,>=2.1.0
 Requires-Dist: dill<1
 Requires-Dist: legacy-cgi; python_version >= '3.13'
 Requires-Dist: pydal>=20251012.3
@@ -24,12 +24,19 @@ Requires-Dist: python-slugify<9
 Provides-Extra: all
 Requires-Dist: edwh-migrate[full]>=0.8.0; extra == 'all'
 Requires-Dist: py4web; extra == 'all'
-Requires-Dist: pydal2sql[all]>=1.2.0; extra == 'all'
+Requires-Dist: pydal2sql[all]>=1.3.5; extra == 'all'
 Requires-Dist: pydantic<3; extra == 'all'
 Requires-Dist: questionary; extra == 'all'
 Requires-Dist: tabulate; extra == 'all'
 Requires-Dist: tomlkit; extra == 'all'
 Requires-Dist: typer<0.19,>=0.18; extra == 'all'
+Requires-Dist: typtyp<1; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: pydal2sql>=1.3.5; extra == 'cli'
+Requires-Dist: questionary; extra == 'cli'
+Requires-Dist: tabulate; extra == 'cli'
+Requires-Dist: tomlkit; extra == 'cli'
+Requires-Dist: typer<0.19,>=0.18; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: contextlib-chdir; extra == 'dev'
 Requires-Dist: ewok; extra == 'dev'
@@ -47,13 +54,20 @@ Requires-Dist: types-requests; extra == 'dev'
 Requires-Dist: types-tabulate; extra == 'dev'
 Provides-Extra: migrations
 Requires-Dist: edwh-migrate>=0.8.0; extra == 'migrations'
-Requires-Dist: pydal2sql>=1.2.0; extra == 'migrations'
+Requires-Dist: pydal2sql>=1.3.5; extra == 'migrations'
 Requires-Dist: questionary; extra == 'migrations'
 Requires-Dist: tabulate; extra == 'migrations'
 Requires-Dist: tomlkit; extra == 'migrations'
 Requires-Dist: typer<0.19,>=0.18; extra == 'migrations'
 Provides-Extra: py4web
 Requires-Dist: py4web; extra == 'py4web'
+Provides-Extra: typescript
+Requires-Dist: pydal2sql>=1.3.5; extra == 'typescript'
+Requires-Dist: questionary; extra == 'typescript'
+Requires-Dist: tabulate; extra == 'typescript'
+Requires-Dist: tomlkit; extra == 'typescript'
+Requires-Dist: typer<0.19,>=0.18; extra == 'typescript'
+Requires-Dist: typtyp<1; extra == 'typescript'
 Description-Content-Type: text/markdown
 
 # TypeDAL
@@ -149,6 +163,7 @@ typedal --help
 - `migrations.fake`: Mark one or more migrations as completed in the database without executing the SQL code.
 - `migrations.generate`: Run `pydal2sql` based on the TypeDAL configuration.
 - `migrations.run`: Run `edwh-migrate` based on the TypeDAL configuration.
+- `typescript.generate`: Generate TypeScript interfaces from TypeDAL models.
 - `setup`: Interactively setup a `[tool.typedal]` entry in the local `pyproject.toml`.
 
 ### Configuration

{typedal-4.7.2 → typedal-4.8.1}/README.md

@@ -91,6 +91,7 @@ typedal --help
 - `migrations.fake`: Mark one or more migrations as completed in the database without executing the SQL code.
 - `migrations.generate`: Run `pydal2sql` based on the TypeDAL configuration.
 - `migrations.run`: Run `edwh-migrate` based on the TypeDAL configuration.
+- `typescript.generate`: Generate TypeScript interfaces from TypeDAL models.
 - `setup`: Interactively setup a `[tool.typedal]` entry in the local `pyproject.toml`.
 
 ### Configuration

{typedal-4.7.2 → typedal-4.8.1}/docs/10_advanced_apis.md

@@ -74,3 +74,56 @@ MyTable.reorder_fields(MyTable.id, MyTable.name, keep_others=False)
 ```
 
 This is useful when you want deterministic field order for SQL generation, inspection, or exports.
+
+## TypeScript schema generation
+
+TypeDAL can generate TypeScript types from your models.
+
+Install the optional dependency first:
+
+```bash
+uv pip install TypeDAL[typescript]  # or typedal[all]
+```
+
+### From Python APIs
+
+Generate schema for one model:
+
+```python
+ts = User.as_typescript()
+print(ts)
+```
+
+Generate schema for all currently defined models on a database instance:
+
+```python
+ts = db.as_typescript()
+print(ts)
+```
+
+Generate schema for a subset of models:
+
+```python
+ts = db.as_typescript("User", "Post")
+# or:
+ts = db.as_typescript(User, Post)
+```
+
+### From the CLI
+
+Generate TypeScript from your configured table definitions:
+
+```bash
+typedal typescript.generate
+```
+
+Useful variants:
+
+```bash
+typedal typescript.generate path/to/models.py
+typedal typescript.generate --tables User --tables Post
+typedal typescript.generate --output-file src/types/typedal.ts
+```
+
+Configuration details for `typescript.generate` (including `typescript_output`) are documented in
+[7. Configuration](./7_configuration.md).

{typedal-4.7.2 → typedal-4.8.1}/docs/6_migrations.md

@@ -88,3 +88,15 @@ You can however overwrite the behavior as defined in the config. See all options
 ```bash
 typedal migrations.run --help
 ```
+
+## Related: TypeScript generation
+
+If you also want TypeScript types from your TypeDAL models, use:
+
+```bash
+typedal typescript.generate
+```
+
+This command is separate from migrations, but uses the same style of TypeDAL config and model discovery.
+See [10. Advanced APIs](./10_advanced_apis.md#typescript-schema-generation) for usage,
+and [7. Configuration](./7_configuration.md) for config options such as `typescript_output`.

{typedal-4.7.2 → typedal-4.8.1}/docs/7_configuration.md

@@ -50,6 +50,7 @@ fake_migrate = false
 database_to_restore = "data/backup.sql"
 tables = ["users", "posts"]
 noop = false
+typescript_output = "src/types/typedal.ts"
 ```
 
 ### Generating Migrations (pydal2sql)
@@ -62,6 +63,7 @@ noop = false
 - **`function`**: Function name containing your `db.define()` calls (default: `"define_tables"`)
 - **`tables`**: Specific tables to generate migrations for (optional; usually set via CLI instead)
 - **`noop`**: Don't write to output (usually set via CLI)
+- **`typescript_output`**: Output path used by `typedal typescript.generate` (optional)
 
 ### Running Migrations (edwh-migrate)
 

{typedal-4.7.2 → typedal-4.8.1}/pyproject.toml

@@ -28,7 +28,7 @@ classifiers = [
 dependencies = [
     "pydal >= 20251012.3", # core
     "dill < 1", # caching
-    "configuraptor >= 2.0.1, < 3", # config
+    "configuraptor >= 2.1.0, < 3", # config
     "Configurable-JSON < 2", # json dumping
     "python-slugify < 9",
     "legacy-cgi; python_version >= '3.13'",
@@ -40,24 +40,48 @@ py4web = [
     "py4web",
 ]
 
-migrations = [
+cli = [
     "typer >=0.18, <0.19",
     "tabulate",
-    "pydal2sql>=1.2.0",
+    "questionary",
+    "tomlkit",
+    "pydal2sql>=1.3.5",
+]
+
+migrations = [
+    "tabulate",
+    "pydal2sql>=1.3.5",
     "edwh-migrate>=0.8.0",
+    # cli:
+    "typer >=0.18, <0.19",
+    "tabulate",
     "questionary",
     "tomlkit",
+    "pydal2sql>=1.3.5",
+]
+
+typescript = [
+    "typtyp < 1",
+    # cli:
+    "typer >=0.18, <0.19",
+    "tabulate",
+    "questionary",
+    "tomlkit",
+    "pydal2sql>=1.3.5",
 ]
 
 all = [
     "py4web",
-    "typer >=0.18, <0.19",
+    "typtyp < 1",
     "tabulate",
-    "pydal2sql[all]>=1.2.0",
     "edwh-migrate[full]>=0.8.0",
     "pydantic < 3",
+    # cli:
+    "typer >=0.18, <0.19",
+    "tabulate",
     "questionary",
     "tomlkit",
+    "pydal2sql[all]>=1.3.5",
 ]
 
 dev = [

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/__about__.py

@@ -5,4 +5,4 @@ This file contains the Version info for this package.
 # SPDX-FileCopyrightText: 2023-present Robin van der Noord <robinvandernoord@gmail.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "4.7.2"
+__version__ = "4.8.1"

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/__init__.py

@@ -6,7 +6,7 @@ from .core import TypeDAL
 from .fields import TypedField
 from .helpers import sql_expression
 from .query_builder import QueryBuilder
-from .relationships import Relationship, relationship
+from .relationships import Ref, Relationship, relationship
 from .rows import PaginatedRows, TypedRows
 from .tables import TypedTable
 
@@ -20,6 +20,7 @@ except ImportError:  # pragma: no cover
 __all__ = [
     "PaginatedRows",
     "QueryBuilder",
+    "Ref",
     "Relationship",
     "TypeDAL",
     "TypedField",

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/cli.py

@@ -17,7 +17,6 @@ from .helpers import match_strings
 from .types import AnyDict
 
 try:
-    import edwh_migrate
     import pydal2sql  # noqa: F401
     import questionary
     import rich
@@ -27,12 +26,16 @@ try:
 except ImportError as e:
     # ImportWarning is hidden by default
     warnings.warn(
-        "`migrations` extra not installed. Please run `pip install typedal[migrations]` to fix this.",
+        "`cli` extra not installed. Please run `pip install typedal[cli]` "
+        "(or `typedal[migrations]`, `typedal[typescript]`, `typedal[all]`) "
+        "to fix this.",
         source=e,
         category=RuntimeWarning,
     )
     exit(127)  # command not found
 
+from typing import Never
+
 from pydal2sql.typer_support import IS_DEBUG, with_exit_code
 from pydal2sql.types import (
     DBType_Option,
@@ -41,7 +44,11 @@ from pydal2sql.types import (
     Tables_Option,
 )
 from pydal2sql_core import core_alter, core_create, core_stub
-from typing_extensions import Never
+from pydal2sql_core.cli_support import (
+    RenderContext,
+    find_file_contents,
+    render_schema_from_code,
+)
 
 from . import caching
 from .__about__ import __version__
@@ -86,6 +93,11 @@ questionary_types: dict[typing.Hashable, Optional[AnyDict]] = {
         "message": "Python file where migrations will be written to.",
         "file_filter": lambda file: "." not in file or file.endswith(".py"),
     },
+    "typescript_output": {
+        "type": "path",
+        "message": "File where generated TypeScript will be written to.",
+        "file_filter": lambda file: "." not in file or file.endswith(".ts"),
+    },
     # disabled props:
     "pyproject": None,  # internal
     "noop": None,  # only for debugging
@@ -315,6 +327,16 @@ def run_migrations(
     """
     Run edwh-migrate based on the typedal config.
     """
+    try:
+        import edwh_migrate
+    except ImportError:
+        rich.print(
+            r"[red]missing dependency![/red] "
+            r"Please install [blue]`typedal\[migrations]`[/blue] "
+            r"to use [blue]`typedal migrations.*`[/blue]."
+        )
+        raise typer.Exit(code=127)
+
     # 1. build migrate Config from TypeDAL config
     # 2. import right file
     # 3. `activate_migrations`
@@ -360,6 +382,16 @@ def fake_migrations(
 
     glob is supported in 'names'
     """
+    try:
+        import edwh_migrate
+    except ImportError:
+        rich.print(
+            r"[red]missing dependency![/red] "
+            r"Please install [blue]`typedal\[migrations]`[/blue] "
+            r"to use [blue]`typedal migrations.*`[/blue]."
+        )
+        raise typer.Exit(code=127)
+
     if not (names or all):
         rich.print("Please provide one or more migration names, or pass --all to fake all.")
         return 1
@@ -385,13 +417,16 @@ def fake_migrations(
         db = edwh_migrate.setup_db(config=migrate_config)
     except edwh_migrate.migrate.DatabaseNotYetInitialized:
         db = edwh_migrate.setup_db(
-            config=migrate_config, migrate=True, migrate_enabled=True, remove_migrate_tablefile=True
+            config=migrate_config,
+            migrate=True,
+            migrate_enabled=True,
+            remove_migrate_tablefile=True,
         )
 
     previously_migrated = (
         db(
             db.ewh_implemented_features.name.belongs(to_fake)
-            & (db.ewh_implemented_features.installed == True)  # noqa E712
+            & (db.ewh_implemented_features.installed == True),  # noqa E712
         )
         .select(db.ewh_implemented_features.name)
         .column("name")
@@ -447,6 +482,71 @@ def migrations_stub(
     return 0
 
 
+@app.command(name="typescript.generate")
+@with_exit_code(hide_tb=IS_DEBUG)
+def generate_typescript(
+    connection: typing.Annotated[str, typer.Option("--connection", "-c")] = None,
+    filename: OptionalArgument[str] = None,
+    tables: Tables_Option = None,
+    magic: Optional[bool] = None,
+    function: Optional[str] = None,
+    output_file: Optional[str] = None,
+) -> bool:
+    """
+    Generate TypeScript interfaces from TypeDAL table definitions.
+    """
+    from .serializers.typescript import is_supported
+
+    if not is_supported():  # pragma: no cover
+        rich.print(
+            r"[red]missing dependency![/red] "
+            r"Please install [blue]`typedal\[typescript]`[/blue] "
+            r"to use [blue]`typedal typescript.generate`[/blue]."
+        )
+        raise typer.Exit(code=127)
+
+    config = load_config(connection)
+    config.update(
+        input=filename,
+        tables=tables,
+        magic=magic,
+        function=function,
+        typescript_output=output_file,
+        _skip_none=True,
+    )
+
+    def typescript_renderer(context: RenderContext) -> str:
+        db: TypeDAL = context.db_new
+        return db.as_typescript(*context.tables)
+
+    mut_functions: list[str] = []
+    source_input = config.input
+    source_code = find_file_contents(
+        source_input,
+        config.function,
+        found_functions=mut_functions,
+        default_version="current" if source_input else "stdin",
+    )
+
+    success = render_schema_from_code(
+        source_code,
+        # output_file=raw_output,
+        output_file=config.typescript_output or None,
+        renderer=typescript_renderer,
+        db_type=config.dialect,
+        tables=config.tables,
+        magic=config.magic,
+        function_name=tuple(mut_functions),
+        use_typedal=True,
+        write_mode="w",
+    )
+
+    if not success:  # pragma: no cover
+        rich.print("[red] something went wrong [/red]")
+
+    return success
+
+
 type AnyNestedDict = dict[str, AnyDict]
 
 

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/config.py

@@ -16,7 +16,7 @@ from .types import AnyDict
 
 if t.TYPE_CHECKING:
     from edwh_migrate import Config as MigrateConfig
-    from pydal2sql.typer_support import Config as P2SConfig
+    from pydal2sql_core.state import Config as P2SConfig
 
 LazyPolicy = t.Literal["forbid", "warn", "ignore", "tolerate", "allow"]
 
@@ -39,6 +39,7 @@ class TypeDALConfig(TypedConfig):
     # pydal2sql:
     input: str = ""
     output: str = ""
+    typescript_output: str = ""
     noop: bool = False
     magic: bool = True
     tables: t.Optional[list[str]] = None
@@ -70,7 +71,7 @@ class TypeDALConfig(TypedConfig):
         """
         Convert the config to the format required by pydal2sql.
         """
-        from pydal2sql.typer_support import Config, get_pydal2sql_config
+        from pydal2sql_core.state import Config, get_pydal2sql_config
 
         if self.pyproject:  # pragma: no cover
             project = Path(self.pyproject).read_text()

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/core.py

@@ -22,6 +22,7 @@ from .helpers import (
     sql_expression,
     to_snake,
 )
+from .serializers.typescript import TypedDictRegistry
 
 # noinspection PyUnusedImports
 from .types import CacheStatus, Field, Template
@@ -143,7 +144,13 @@ def resolve_annotation(ftype: str, namespace: dict[str, type] | None = None) ->
         return resolve_annotation_314(ftype, namespace=namespace)
 
 
-class TypeDAL(pydal.DAL):
+class DALProtocol(t.Protocol): ...
+
+
+BaseDAL = DALProtocol if t.TYPE_CHECKING else pydal.DAL
+
+
+class TypeDAL(BaseDAL):
     """
     Drop-in replacement for pyDAL with layer to convert class-based table definitions to classical pydal define_tables.
     """
@@ -499,6 +506,32 @@ class TypeDAL(pydal.DAL):
         """
         return memoize(self, func, *args, key=key, ttl=ttl, **kwargs)
 
+    def as_typescript(self, *tables: str | type[TypedTable]) -> str:
+        """
+        Generate a TypeScript schema string for all currently defined typedal models.
+        """
+        TypedDictRegistry.clear()  # clean registry in order to apply 'tables' filtering
+        registry = TypedDictRegistry()
+
+        do_filter: t.Callable[[str], bool]
+        if tables:
+            names = {
+                model.__name__
+                for table in tables
+                if (model := (self.find_model(table) if isinstance(table, str) else table))
+            }
+
+            do_filter = lambda name: name in names  # noqa: E731
+        else:
+            do_filter = lambda name: not name.startswith("_")  # noqa: E731
+
+        # Ensure all currently defined models are registered into the TypedDict registry/world.
+        for model in self._class_map.values():
+            if do_filter(model.__name__):
+                model.as_typeddict()
+
+        return registry.get_typescript("as_typescript")
+
 
 TypeDAL.representers.setdefault("rows_render", default_representer)
 

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/define.py

@@ -118,8 +118,9 @@ class TableDefinitionBuilder:
                 table=table,
                 relationships=t.cast(dict[str, Relationship[t.Any]], relationships),
             )
-            self.class_map[str(table)] = cls
-            self.class_map[table._rname] = cls
+            self.class_map[str(table)] = cls  # tablename - pydal name
+            self.class_map[cls.__name__] = cls  # TableName - typedal name
+            self.class_map[table._rname] = cls  # table_model - sql name
             cls.__on_define__(self.db)
         else:
             warnings.warn("db.define used without inheriting TypedTable. This could lead to strange problems!")

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/enum_helpers.py

@@ -11,6 +11,12 @@ class InvalidEnumValue:
     raw: t.Any
     value: None = None
 
+    def __bool__(self) -> bool:
+        """
+        Make this fake type falsey.
+        """
+        return False
+
 
 def enum_value_type(enum_type: type[enum.Enum]) -> type[t.Any]:
     values = [member.value for member in enum_type]

{typedal-4.7.2 → typedal-4.8.1}/src/typedal/fields.py

@@ -373,9 +373,7 @@ def UploadField(**kw: t.Unpack[FieldSettings]) -> TypedField[str]:
 Upload = UploadField
 
 
-def ReferenceField[
-    T_subclass: (TypedTable, Table)
-](
+def ReferenceField[T_subclass: (TypedTable, Table)](
     other_table: str | t.Type[TypedTable] | TypedTable | Table | T_subclass,
     **kw: t.Unpack[FieldSettings],
 ) -> TypedField[int]:
@@ -559,7 +557,7 @@ def PointField(**kw: t.Unpack[FieldSettings]) -> TypedField[tuple[float, float]]
 NativeUUIDField = SQLCustomType(
     type="string",
     native="uuid",
-    encoder=str,
+    encoder=lambda val: "" if val is None else str(val),
     decoder=lambda value: uuid.UUID(value) if value else None,
 )