dclassql 0.3.0__tar.gz → 0.4.0__tar.gz

{dclassql-0.3.0 → dclassql-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dclassql
-Version: 0.3.0
+Version: 0.4.0
 Summary: A type-safe ORM generator for Python, creating fully type-hinted database clients from plain dataclass definitions.
 Keywords: orm,codegen,sqlite,dataclass,typed
 Author: myuanz

{dclassql-0.3.0 → dclassql-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dclassql"
-version = "0.3.0"
+version = "0.4.0"
 description = "A type-safe ORM generator for Python, creating fully type-hinted database clients from plain dataclass definitions."
 readme = "README.md"
 authors = [

dclassql-0.4.0/src/dclassql/__init__.py

@@ -0,0 +1,21 @@
+from .asdict import asdict
+from .db_pool import BaseDBPool, save_local
+from .model_inspector import DataSourceConfig
+from .push import db_push
+from .runtime.backends.lazy import eager
+from .runtime.sql_recorder import record_sql
+from .unwarp import unwarp, unwarp_or, unwarp_or_raise
+
+
+__all__ = [
+    'db_push',
+    'eager',
+    'asdict',
+    'unwarp',
+    'unwarp_or',
+    'unwarp_or_raise',
+    'BaseDBPool',
+    'save_local',
+    'DataSourceConfig',
+    'record_sql',
+]

{dclassql-0.3.0 → dclassql-0.4.0}/src/dclassql/cli.py

@@ -18,6 +18,7 @@ from .runtime.datasource import open_sqlite_connection
 DEFAULT_MODEL_FILE = "model.py"
 GENERATED_CLIENT_FILENAME = "client.py"
 
+GenerateTarget = Literal["model-dir", "package"]
 ConfirmRebuildMode = Literal["auto", "prompt"]
 ConfirmCallback = Callable[
     [ModelInfo, SchemaPlan, tuple[ExistingColumn, ...] | None, SchemaDiff],
@@ -66,12 +67,21 @@ def _find_package_directory() -> Path:
     return Path(next(iter(spec.submodule_search_locations))).resolve()
 
 
-def resolve_generated_path() -> Path:
-    return _find_package_directory() / GENERATED_CLIENT_FILENAME
+def resolve_client_package_name(module_path: Path) -> str:
+    stem = re.sub(r"[^0-9a-zA-Z_]+", "_", module_path.stem) or "_"
+    return f"{stem}_client"
 
 
-def resolve_asdict_stub_path() -> Path:
-    return _find_package_directory() / "asdict.pyi"
+def resolve_client_class_name(module_path: Path) -> str:
+    package_name = resolve_client_package_name(module_path)
+    return "".join(part.capitalize() for part in package_name.split("_") if part)
+
+
+def resolve_generated_package_dir(module_path: Path, target: GenerateTarget = "model-dir") -> Path:
+    package_name = resolve_client_package_name(module_path)
+    if target == "model-dir":
+        return module_path.resolve().parent / package_name
+    return _find_package_directory() / package_name
 
 
 def collect_models(module: ModuleType) -> list[type[Any]]:
@@ -162,16 +172,18 @@ def push_database(
                 pass
 
 
-def command_generate(module_path: Path) -> None:
+def command_generate(module_path: Path, *, target: GenerateTarget = "model-dir") -> None:
     module = load_module(module_path)
     models = collect_models(module)
-    generated = generate_client(models)
-    output_path = resolve_generated_path()
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(generated.code, encoding="utf-8")
-    asdict_stub_path = resolve_asdict_stub_path()
-    asdict_stub_path.write_text(generated.asdict_stub, encoding="utf-8")
-    sys.stdout.write(f"Client written to {output_path}\n")
+    client_class_name = resolve_client_class_name(module_path)
+    generated = generate_client(models, client_class_name=client_class_name)
+    output_dir = resolve_generated_package_dir(module_path, target)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    (output_dir / "__init__.py").write_text(generated.init_code, encoding="utf-8")
+    (output_dir / "__init__.pyi").write_text(generated.init_stub, encoding="utf-8")
+    (output_dir / GENERATED_CLIENT_FILENAME).write_text(generated.code, encoding="utf-8")
+    (output_dir / "asdict.pyi").write_text(generated.asdict_stub, encoding="utf-8")
+    sys.stdout.write(f"Client package written to {output_dir}\n")
 
 
 def command_push_db(
@@ -197,7 +209,13 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     generate_parser = subparsers.add_parser("generate", help="Generate client code for given models")
-    generate_parser.set_defaults(handler=lambda args: command_generate(args.module))
+    generate_parser.add_argument(
+        "--target",
+        choices=("model-dir", "package"),
+        default="model-dir",
+        help="生成 client 的位置: model-dir 写到模型文件同目录; package 写到 dclassql 包内",
+    )
+    generate_parser.set_defaults(handler=lambda args: command_generate(args.module, target=args.target))
 
     push_parser = subparsers.add_parser("push-db", help="Apply schema and indexes to configured databases")
     push_parser.add_argument(

{dclassql-0.3.0 → dclassql-0.4.0}/src/dclassql/codegen.py

@@ -17,7 +17,10 @@ from .model_inspector import ColumnInfo, ModelInfo, inspect_models, DataSourceCo
 class GeneratedModule:
     code: str
     asdict_stub: str
+    init_code: str
+    init_stub: str
     model_names: tuple[str, ...]
+    client_class_name: str
 
 
 @dataclass(slots=True)
@@ -131,7 +134,7 @@ class ModelRenderContext:
 
 
 @dataclass(slots=True)
-class ClientDatasourceContext:
+class ClientDataSourceContext:
     key: str
     key_repr: str
     provider_repr: str
@@ -139,24 +142,16 @@ class ClientDatasourceContext:
     name_repr: str
 
 
-@dataclass(slots=True)
-class BackendMethodContext:
-    key: str
-    key_repr: str
-    method_name: str
-
-
 @dataclass(slots=True)
 class ClientModelBindingContext:
     attr_name: str
     model_name: str
-    backend_method: str
 
 
 @dataclass(slots=True)
 class ClientContext:
-    datasource_items: tuple[ClientDatasourceContext, ...]
-    backend_methods: tuple[BackendMethodContext, ...]
+    class_name: str
+    datasource: ClientDataSourceContext
     model_bindings: tuple[ClientModelBindingContext, ...]
 
 
@@ -176,7 +171,7 @@ def _get_environment() -> Environment:
     return _ENVIRONMENT
 
 
-def generate_client(models: Sequence[type[Any]]) -> GeneratedModule:
+def generate_client(models: Sequence[type[Any]], *, client_class_name: str = "GeneratedClient") -> GeneratedModule:
     model_infos = inspect_models(models)
     renderer = _TypeRenderer({info.model: name for name, info in model_infos.items()})
     filter_registry = _ScalarFilterRegistry(renderer)
@@ -201,8 +196,8 @@ def generate_client(models: Sequence[type[Any]]) -> GeneratedModule:
         for module, names in sorted(combined_imports.items())
     ]
 
-    client_context = _build_client_context(model_infos)
-    exports = _collect_exports(model_contexts)
+    client_context = _build_client_context(model_infos, client_class_name)
+    exports = _collect_exports(model_contexts, client_class_name)
     scalar_filters = filter_registry.render_definitions()
 
     template = _get_environment().get_template(_TEMPLATE_NAME)
@@ -216,7 +211,16 @@ def generate_client(models: Sequence[type[Any]]) -> GeneratedModule:
     if not code.endswith("\n"):
         code += "\n"
     asdict_stub = _render_asdict_stub(model_contexts)
-    return GeneratedModule(code=code, asdict_stub=asdict_stub, model_names=tuple(sorted(model_infos.keys())))
+    init_code = _render_init_code(client_class_name)
+    init_stub = _render_init_stub(client_class_name)
+    return GeneratedModule(
+        code=code,
+        asdict_stub=asdict_stub,
+        init_code=init_code,
+        init_stub=init_stub,
+        model_names=tuple(sorted(model_infos.keys())),
+        client_class_name=client_class_name,
+    )
 
 
 def _build_model_context(
@@ -418,53 +422,39 @@ def _build_model_context(
     )
 
 
-def _build_client_context(model_infos: Mapping[str, ModelInfo]) -> ClientContext:
-    datasource_configs: dict[str, DataSourceConfig] = {}
-    for info in model_infos.values():
-        datasource = info.datasource
-        key = datasource.name or datasource.provider
-        existing = datasource_configs.get(key)
-        if existing is None:
-            datasource_configs[key] = datasource
-        elif existing != datasource:
-            raise ValueError(f"Conflicting datasource key '{key}' for providers")
-
-    datasource_items = [
-        ClientDatasourceContext(
-            key=key,
-            key_repr=repr(key),
-            provider_repr=repr(ds.provider),
-            url_repr=repr(ds.url),
-            name_repr=repr(ds.name),
+def _build_client_context(model_infos: Mapping[str, ModelInfo], client_class_name: str) -> ClientContext:
+    datasource_configs = {info.datasource for info in model_infos.values()}
+    if len(datasource_configs) != 1:
+        labels = ", ".join(
+            f"{ds.key}({ds.provider}, {ds.url!r})" for ds in sorted(datasource_configs, key=lambda item: item.key)
         )
-        for key, ds in sorted(datasource_configs.items())
-    ]
-
-    backend_methods: list[BackendMethodContext] = []
-    method_map: dict[str, str] = {}
-    for key in sorted(datasource_configs.keys()):
-        method_name = f"_backend_{_sanitize_identifier(key)}"
-        backend_methods.append(BackendMethodContext(key=key, key_repr=repr(key), method_name=method_name))
-        method_map[key] = method_name
+        raise ValueError(f"Generated Client can only use one datasource, got: {labels}")
+    datasource = next(iter(datasource_configs))
+    datasource_item = ClientDataSourceContext(
+        key=datasource.key,
+        key_repr=repr(datasource.key),
+        provider_repr=repr(datasource.provider),
+        url_repr=repr(datasource.url),
+        name_repr=repr(datasource.name),
+    )
 
     model_bindings = [
         ClientModelBindingContext(
             attr_name=_camel_to_snake(name),
             model_name=name,
-            backend_method=method_map[(model_infos[name].datasource.name or model_infos[name].datasource.provider)],
         )
         for name in sorted(model_infos.keys())
     ]
 
     return ClientContext(
-        datasource_items=tuple(datasource_items),
-        backend_methods=tuple(backend_methods),
+        class_name=client_class_name,
+        datasource=datasource_item,
         model_bindings=tuple(model_bindings),
     )
 
 
-def _collect_exports(model_contexts: Sequence[ModelRenderContext]) -> list[str]:
-    exports: list[str] = ["DataSourceConfig", "ForeignKeySpec", "Client"]
+def _collect_exports(model_contexts: Sequence[ModelRenderContext], client_class_name: str) -> list[str]:
+    exports: list[str] = ["DataSourceConfig", "ForeignKeySpec", client_class_name]
     for context in model_contexts:
         name = context.name
         exports.extend(
@@ -496,6 +486,24 @@ def _render_asdict_stub(model_contexts: Sequence[ModelRenderContext]) -> str:
     return code
 
 
+def _render_init_code(client_class_name: str) -> str:
+    code = (
+        "from dclassql.asdict import asdict as asdict\n"
+        f"from .client import {client_class_name} as {client_class_name}\n\n"
+        f"__all__ = ['{client_class_name}', 'asdict']\n"
+    )
+    return code
+
+
+def _render_init_stub(client_class_name: str) -> str:
+    code = (
+        "from .asdict import asdict as asdict\n"
+        f"from .client import {client_class_name} as {client_class_name}\n\n"
+        "__all__: list[str]\n"
+    )
+    return code
+
+
 def _build_relation_entries(info: ModelInfo, model_infos: Mapping[str, ModelInfo]) -> list[dict[str, Any]]:
     entries: list[dict[str, Any]] = []
     if not info.relations:

{dclassql-0.3.0 → dclassql-0.4.0}/src/dclassql/model_inspector.py

@@ -48,7 +48,7 @@ class ModelInfo:
     datasource: 'DataSourceConfig'
 
 
-@dataclass(slots=True)
+@dataclass(slots=True, frozen=True)
 class DataSourceConfig:
     provider: str
     url: str | None

{dclassql-0.3.0 → dclassql-0.4.0}/src/dclassql/runtime/backends/protocols.py

@@ -150,6 +150,8 @@ class BackendProtocol(Protocol):
 
     def execute_raw(self, sql: str, params: Sequence[object] | None = None, auto_commit: bool = True) -> int: ...
 
+    def close(self) -> None: ...
+
     def escape_identifier(self, name: str) -> str: ...
 
     def new_parameter(self) -> Parameter: ...

{dclassql-0.3.0 → dclassql-0.4.0}/src/dclassql/runtime/backends/where_compiler.py

@@ -2,11 +2,11 @@ from __future__ import annotations
 
 import importlib
 from collections.abc import Mapping as ABCMapping
-from typing import Mapping, Sequence
+from typing import Mapping, Sequence, cast
 
 from pypika import Query, Table
 from pypika.queries import QueryBuilder
-from pypika.terms import Criterion, ExistsCriterion, Field, Parameter
+from pypika.terms import Criterion, ExistsCriterion, Field, Not, Parameter
 
 from dclassql.typing import IncludeT, InsertT, ModelT, OrderByT, WhereT
 from dclassql.utils.ensure import ensure_sequence, ensure_string
@@ -41,10 +41,14 @@ class EscapeLikeCriterion(Criterion):
         self._escape = escape
         self._negated = negated
 
-    def negate(self) -> Criterion:
-        return EscapeLikeCriterion(self._field, self._parameter, escape=self._escape, negated=not self._negated)
+    def negate(self) -> Not:
+        # PyPika 将 Term.negate() 标为 Not；这里的自定义条件只需要翻转自己的 SQL 操作符。
+        return cast(
+            Not,
+            EscapeLikeCriterion(self._field, self._parameter, escape=self._escape, negated=not self._negated),
+        )
 
-    def get_sql(self, **kwargs: object) -> str:  # type: ignore[override]
+    def get_sql(self, **kwargs: object) -> str:
         field_sql = self._field.get_sql(**kwargs)
         param_sql = self._parameter.get_sql(**kwargs)
         operator = "NOT LIKE" if self._negated else "LIKE"

dclassql-0.4.0/src/dclassql/templates/partials/client_class.jinja

@@ -0,0 +1,60 @@
+class {{ client.class_name }}(BaseDBPool):
+    datasource: DataSourceConfig = DataSourceConfig(
+        provider={{ client.datasource.provider_repr }},
+        url={{ client.datasource.url_repr }},
+        name={{ client.datasource.name_repr }},
+    )
+    datasource_key: str = {{ client.datasource.key_repr }}
+
+    def __init__(self, *, datasource: DataSourceConfig = datasource, echo_sql: bool = False) -> None:
+        self.datasource = datasource
+        self._echo_sql = echo_sql
+        self._backend_instance: BackendProtocol | None = None
+{% for binding in client.model_bindings %}        self.{{ binding.attr_name }} = {{ binding.model_name }}Table(self._backend())
+{% endfor %}
+
+    def _backend(self) -> BackendProtocol:
+        if self._backend_instance is None:
+            self._backend_instance = self._make_backend(self.datasource)
+        return self._backend_instance
+
+    def _make_backend(self, datasource: DataSourceConfig) -> BackendProtocol:
+        if datasource.provider == 'sqlite':
+            from dclassql.runtime.backends.sqlite import SQLiteBackend
+            return SQLiteBackend(lambda: self._open_connection(datasource), echo_sql=self._echo_sql)
+        raise ValueError(f"Unsupported provider '{datasource.provider}'")
+
+    def _open_connection(self, datasource: DataSourceConfig) -> Any:
+        if datasource.provider == 'sqlite':
+            conn = open_sqlite_connection(datasource.url)
+            self._setup_sqlite_db(conn)
+            return conn
+        raise ValueError(f"Unsupported provider '{datasource.provider}'")
+
+    def push_db(
+        self,
+        *,
+        sync_indexes: bool = False,
+        force_rebuild: bool = False,
+    ) -> None:
+        connection = self._open_connection(self.datasource)
+        try:
+            db_push(
+                (
+{% for binding in client.model_bindings %}                    {{ binding.model_name }},
+{% endfor %}                ),
+                {self.datasource_key: connection},
+                sync_indexes=sync_indexes,
+                confirm_rebuild=(lambda *_: True) if force_rebuild else None,
+            )
+        finally:
+            connection.close()
+
+    def close(self) -> None:
+        if self._backend_instance is not None:
+            self._backend_instance.close()
+            self._backend_instance = None
+
+    @classmethod
+    def close_all(cls, verbose: bool = False) -> None:
+        super().close_all(verbose=verbose)

{dclassql-0.3.0 → dclassql-0.4.0}/src/dclassql/templates/partials/imports.jinja

@@ -6,8 +6,8 @@ from types import MappingProxyType
 from typing import Any, Literal, Mapping, Sequence, NotRequired, overload
 from typing_extensions import TypedDict
 
-from dclassql import DataSourceConfig
-from dclassql.db_pool import BaseDBPool, save_local
+from dclassql import DataSourceConfig, db_push
+from dclassql.db_pool import BaseDBPool
 from dclassql.runtime.backends import BackendProtocol, ColumnSpec, ForeignKeySpec, RelationSpec
 from dclassql.runtime.backends.protocols import TableProtocol
 from dclassql.runtime.datasource import open_sqlite_connection

dclassql-0.3.0/src/dclassql/__init__.py

@@ -1,34 +0,0 @@
-from .asdict import asdict
-from .db_pool import BaseDBPool, save_local
-from .model_inspector import DataSourceConfig
-from .push import db_push
-from .runtime.backends.lazy import eager
-from .runtime.sql_recorder import record_sql
-from .unwarp import unwarp, unwarp_or, unwarp_or_raise
-
-
-class _MissingClient:
-    def __init__(self, *args: object, **kwargs: object) -> None:
-        raise RuntimeError(
-            "dclassql.Client 尚未生成。请先运行 `dclassql -m <model.py> generate` 生成客户端后再导入。"
-        )
-
-try:  # pragma: no cover - exercised in integration tests
-    from .client import Client  # type: ignore
-except (ModuleNotFoundError, ImportError):  # pragma: no cover - fallback when未生成
-    Client = _MissingClient  # type: ignore[assignment]
-
-
-__all__ = [
-    'Client',
-    'db_push',
-    'eager',
-    'asdict',
-    'unwarp',
-    'unwarp_or',
-    'unwarp_or_raise',
-    'BaseDBPool',
-    'save_local',
-    'DataSourceConfig',
-    'record_sql',
-]

dclassql-0.3.0/src/dclassql/asdict.pyi

@@ -1,57 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Sequence
-from typing import Any, Literal, overload
-
-from .client import (
-    Address,
-    AddressDict,
-    BirthDay,
-    BirthDayDict,
-    Book,
-    BookDict,
-    User,
-    UserDict,
-    UserBook,
-    UserBookDict,
-)
-
-RelationPolicy = Literal['skip', 'fetch', 'keep']
-
-@overload
-def asdict(value: Address, *, relation_policy: RelationPolicy = 'keep') -> AddressDict: ...
-
-@overload
-def asdict(value: BirthDay, *, relation_policy: RelationPolicy = 'keep') -> BirthDayDict: ...
-
-@overload
-def asdict(value: Book, *, relation_policy: RelationPolicy = 'keep') -> BookDict: ...
-
-@overload
-def asdict(value: User, *, relation_policy: RelationPolicy = 'keep') -> UserDict: ...
-
-@overload
-def asdict(value: UserBook, *, relation_policy: RelationPolicy = 'keep') -> UserBookDict: ...
-
-@overload
-def asdict(value: Sequence[Address], *, relation_policy: RelationPolicy = 'keep') -> list[AddressDict]: ...
-
-@overload
-def asdict(value: Sequence[BirthDay], *, relation_policy: RelationPolicy = 'keep') -> list[BirthDayDict]: ...
-
-@overload
-def asdict(value: Sequence[Book], *, relation_policy: RelationPolicy = 'keep') -> list[BookDict]: ...
-
-@overload
-def asdict(value: Sequence[User], *, relation_policy: RelationPolicy = 'keep') -> list[UserDict]: ...
-
-@overload
-def asdict(value: Sequence[UserBook], *, relation_policy: RelationPolicy = 'keep') -> list[UserBookDict]: ...
-
-@overload
-def asdict(value: Sequence[Any], *, relation_policy: RelationPolicy = 'keep') -> list[Any]: ...
-
-@overload
-def asdict(value: None, *, relation_policy: RelationPolicy = 'keep') -> None: ...
-
-def asdict(value: object, *, relation_policy: RelationPolicy = 'keep') -> Any: ...

dclassql-0.3.0/src/dclassql/templates/partials/client_class.jinja

@@ -1,32 +0,0 @@
-class Client(BaseDBPool):
-    _echo_sql: bool = False
-    datasources = {
-{% for item in client.datasource_items %}        {{ item.key_repr }}: DataSourceConfig(provider={{ item.provider_repr }}, url={{ item.url_repr }}, name={{ item.name_repr }}),
-{% endfor %}    }
-
-{% for method in client.backend_methods %}    @classmethod
-    @save_local
-    def {{ method.method_name }}(cls, *, echo_sql: bool | None = None) -> BackendProtocol:
-        config = cls.datasources[{{ method.key_repr }}]
-        backend_echo = cls._echo_sql if echo_sql is None else echo_sql
-        if config.provider == 'sqlite':
-            from dclassql.runtime.backends.sqlite import SQLiteBackend
-            conn = open_sqlite_connection(config.url)
-            cls._setup_sqlite_db(conn)
-            return SQLiteBackend(conn, echo_sql=backend_echo)
-        raise ValueError(f"Unsupported provider '{config.provider}' for datasource {{ method.key_repr }}")
-
-{% endfor %}    def __init__(self, *, echo_sql: bool = False) -> None:
-        self._echo_sql = echo_sql
-{% for binding in client.model_bindings %}        self.{{ binding.attr_name }} = {{ binding.model_name }}Table(self.{{ binding.backend_method }}(echo_sql=echo_sql))
-{% endfor %}
-
-    @classmethod
-    def close_all(cls, verbose: bool = False) -> None:
-        super().close_all(verbose=verbose)
-{% for method in client.backend_methods %}        if hasattr(cls._local, '{{ method.method_name }}'):
-            backend = getattr(cls._local, '{{ method.method_name }}')
-            if hasattr(backend, 'close') and callable(getattr(backend, 'close')):
-                backend.close()
-            delattr(cls._local, '{{ method.method_name }}')
-{% endfor %}