gandharva 0.0.1__tar.gz

gandharva-0.0.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: gandharva
+Version: 0.0.1
+Summary: All-purpose data science application builder
+Author: hingebase
+Author-email: hingebase <zcliu@pku.edu.cn>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Dist: fastapi>=0.119.1,<2.0.0
+Requires-Dist: hypothesis-jsonschema>=0.23.1,<2.0.0
+Requires-Dist: lumen>=0.6.1,<2.0.0
+Requires-Dist: packaging>=26.0.0
+Requires-Dist: panel>=1.8.3,<2.0.0
+Requires-Dist: platformdirs>=4.6.0,<5.0.0
+Requires-Dist: pydantic>=2.12.1,<4.0.0
+Requires-Dist: pydantic-settings>=2.13.0,<4.0.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: rich-argparse>=1.7.2,<2.0.0
+Requires-Dist: typing-extensions>=4.15.0,<5.0.0
+Requires-Dist: pandas-stubs>=1.4.2,<4.0.0 ; extra == 'typing'
+Requires-Python: >=3.10, <3.15
+Project-URL: Homepage, https://github.com/hingebase/gandharva
+Project-URL: Source Code, https://github.com/hingebase/gandharva
+Project-URL: Issue Tracker, https://github.com/hingebase/gandharva/issues
+Provides-Extra: typing
+Description-Content-Type: text/markdown
+
+# Gandharva
+In active development. Check the [issue tracker][1] for upcoming features.
+
+[1]: https://github.com/hingebase/gandharva/issues

gandharva-0.0.1/README.md

@@ -0,0 +1,4 @@
+# Gandharva
+In active development. Check the [issue tracker][1] for upcoming features.
+
+[1]: https://github.com/hingebase/gandharva/issues

gandharva-0.0.1/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["uv-build >=0.10.2,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "gandharva"
+version = "0.0.1"
+description = "All-purpose data science application builder"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Education",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: User Interfaces",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi >=0.119.1,<2.0.0",
+    "hypothesis-jsonschema >=0.23.1,<2.0.0",
+    "lumen >=0.6.1,<2.0.0",
+    "packaging >=26.0.0",
+    "panel >=1.8.3,<2.0.0",
+    "platformdirs >=4.6.0,<5.0.0",
+    "pydantic >=2.12.1,<4.0.0",
+    "pydantic-settings >=2.13.0,<4.0.0",
+    "rich >=14.2.0",
+    "rich-argparse >=1.7.2,<2.0.0",
+    "typing-extensions >=4.15.0,<5.0.0",
+]
+
+[project.optional-dependencies]
+typing = [
+    "pandas-stubs >=1.4.2,<4.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "attrs >=25.4.0",
+    "basedpyright >=1.39.3",
+    "httpx >=0.28.1",
+    "nodejs-wheel-binaries <=20.18.0; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "pytest >=9.0.3",
+    "ruff >=0.15.11",
+]
+
+[[project.authors]]
+name = "hingebase"
+email = "zcliu@pku.edu.cn"
+
+[project.urls]
+Homepage = "https://github.com/hingebase/gandharva"
+"Source Code" = "https://github.com/hingebase/gandharva"
+"Issue Tracker" = "https://github.com/hingebase/gandharva/issues"
+
+[tool.basedpyright]
+reportUnnecessaryTypeIgnoreComment = "warning"
+strict = ["."]
+typeCheckingMode = "off"
+
+[tool.ruff]
+extend-exclude = [".pixi"]
+line-length = 79
+preview = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["INP001", "S101"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 72
+
+[tool.tombi.files]
+exclude = [".venv/**/*.toml"]
+
+[tool.tombi.lint.rules]
+tables-out-of-order = "off"

gandharva-0.0.1/src/gandharva/__init__.py

@@ -0,0 +1,35 @@
+# Copyright 2026 hingebase
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# permissions and limitations under the License.
+
+"""Gandharva: All-purpose data science application builder."""
+
+__all__ = [
+    "ApplicationBuilderError",
+    "ApplicationRegisterError",
+    "Error",
+    "Field",
+    "Gandharva",
+    "run",
+]
+
+from pydantic import Field
+
+from . import typing as typing
+from ._app import Gandharva
+from ._runner import run
+from .exceptions import (
+    ApplicationBuilderError,
+    ApplicationRegisterError,
+    Error,
+)

gandharva-0.0.1/src/gandharva/_app/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2026 hingebase
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# permissions and limitations under the License.
+
+__all__ = ["Gandharva"]
+
+from ._gandharva import Gandharva

gandharva-0.0.1/src/gandharva/_app/_base.py

@@ -0,0 +1,72 @@
+# Copyright 2026 hingebase
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# permissions and limitations under the License.
+
+__all__ = ["App", "normalize"]
+
+import abc
+import inspect
+import os
+from typing import TYPE_CHECKING, ClassVar, Literal
+
+import packaging.utils
+import platformdirs
+import pydantic.alias_generators
+from typing_extensions import final
+
+if TYPE_CHECKING:
+    import gandharva as gd
+
+
+class App(abc.ABC):
+    children: ClassVar["list[type[gd.Gandharva]]"]
+    run_mode: Literal["api", "cli", "gui"]
+
+    @abc.abstractmethod
+    def main(self) -> object:
+        raise NotImplementedError
+
+    @classmethod
+    def app_description(cls) -> str:
+        if doc := cls.__doc__:
+            return inspect.cleandoc(doc)
+        # Unlike `inspect.getdoc`, we are not interested in the base
+        # classes
+        return ""
+
+    @classmethod
+    def app_normalized_name(cls) -> str:
+        return normalize(cls.__name__)
+
+    @classmethod
+    def app_summary(cls) -> str:
+        if lines := cls.app_description().splitlines():
+            return lines[0].rstrip(".")
+        return ""
+
+    @final
+    def __init__(self, run_mode: Literal["api", "cli", "gui"]) -> None:
+        self.run_mode = run_mode
+
+
+def normalize(name: str) -> str:
+    return packaging.utils.canonicalize_name(
+        pydantic.alias_generators.to_snake(name).removeprefix("_"),
+        validate=True,
+    )
+
+
+os.environ.setdefault(
+    "HYPOTHESIS_STORAGE_DIRECTORY",
+    platformdirs.user_cache_dir("gandharva", appauthor=False),
+)

gandharva-0.0.1/src/gandharva/_app/_fastapi.py

@@ -0,0 +1,147 @@
+# Copyright 2026 hingebase
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# permissions and limitations under the License.
+
+__all__ = ["App"]
+
+import importlib.metadata
+import inspect
+from email.message import Message
+from typing import Annotated, Literal, no_type_check
+
+import fastapi
+from typing_extensions import Any, Self, final, overload
+
+import gandharva as gd
+from gandharva import _convert
+
+from . import _pydantic
+
+
+class App(_pydantic.App):
+    fastapi_request: fastapi.Request
+
+    @classmethod
+    def fastapi_apiroute_params(cls) -> gd.typing.APIRouteParameters:
+        return {
+            "summary": cls.app_summary(),
+            "description": cls.app_description(),
+            "deprecated": hasattr(cls, "__deprecated__"),
+        }
+
+    @classmethod
+    def fastapi_apirouter_params(cls) -> gd.typing.APIRouterParameters:
+        return {}
+
+    @classmethod
+    def fastapi_app_params(cls, meta: Message) -> gd.typing.FastAPIParameters:
+        kwargs: gd.typing.FastAPIParameters = {
+            "summary": meta.get("Summary"),
+        }
+        for key in "description", "version":
+            if value := meta.get(key):
+                kwargs[key] = value
+        if name := meta.get("Name"):
+            kwargs["title"] = name.replace("-", " ").title()
+        if identifier := meta.get("License-Expression"):
+            kwargs["license_info"] = {
+                "name": "License",
+                "identifier": identifier,
+            }
+        return kwargs
+
+    @classmethod
+    def fastapi_post_init(
+        cls,
+        router: fastapi.APIRouter | fastapi.FastAPI,
+    ) -> None:
+        pass
+
+    @classmethod
+    @final
+    def to_router(cls) -> fastapi.APIRouter:
+        kwargs: dict[str, Any] = dict(
+            cls.fastapi_apirouter_params(),
+            prefix="/" + cls.app_normalized_name(),
+        )
+        router = fastapi.APIRouter(**kwargs)
+        cls._fastapi_routes(router)
+        return router
+
+    @overload
+    def __new__(cls, run_mode: None = ...) -> fastapi.FastAPI: ...
+    @overload
+    def __new__(cls, run_mode: Literal["api", "cli", "gui"]) -> Self: ...
+    @final
+    def __new__(  # pyright: ignore[reportInconsistentConstructor]
+        cls,
+        run_mode: Literal["api", "cli", "gui"] | None = None,
+    ) -> fastapi.FastAPI | Self:
+        if run_mode:
+            return super().__new__(cls)
+        distribution_name = cls.__module__.split(".", 1)[0]
+        try:
+            meta = importlib.metadata.metadata(distribution_name)
+        except ModuleNotFoundError:
+            message = Message()
+        else:
+            message = meta if isinstance(meta, Message) else Message()
+        app = fastapi.FastAPI(**cls.fastapi_app_params(message))
+        cls._fastapi_routes(app)
+        return app
+
+    def _fastapi_main(self, request: fastapi.Request) -> object:
+        self.fastapi_request = request
+        try:
+            result = self.main()
+            result = _convert.to_response(result)
+        except Exception as e:  # noqa: BLE001
+            return {"code": 1, "message": str(e), "data": None}
+        return result
+
+    @classmethod
+    def _fastapi_routes(
+        cls,
+        router: fastapi.APIRouter | fastapi.FastAPI,
+    ) -> None:
+        responses: dict[int | str, dict[str, Any]] = {}
+        kwargs: dict[str, Any] = dict(
+            cls.fastapi_apiroute_params(),
+            path="/",
+            responses=responses,
+            name=cls.__name__,
+        )
+        _convert.to_response_model(
+            f"__Response_{cls.__name__}",
+            inspect.signature(cls.main, eval_str=True).return_annotation,
+            kwargs,
+        )
+        model = cls.to_pydantic()
+        if model.__pydantic_fields__:
+            @no_type_check
+            @router.post(**kwargs)
+            def _(
+                request: fastapi.Request,
+                body: Annotated[model, fastapi.Body()],
+            ) -> object:
+                self = cls.from_pydantic(body, run_mode="api")
+                return self._fastapi_main(request)
+        else:
+            @router.get(**kwargs)
+            def _(request: fastapi.Request) -> object:
+                self = cls(run_mode="api")
+                return self._fastapi_main(request)
+
+        for child in cls.children:
+            router.include_router(child.to_router())
+        cls.fastapi_post_init(router)

gandharva-0.0.1/src/gandharva/_app/_gandharva.py

@@ -0,0 +1,82 @@
+# Copyright 2026 hingebase
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# permissions and limitations under the License.
+
+__all__ = ["Gandharva"]
+
+import asyncio
+import functools
+import inspect
+from collections.abc import Callable, Coroutine
+
+import anyio.from_thread
+from typing_extensions import Any, ParamSpec, TypeVar, disjoint_base
+
+import gandharva as gd
+
+from . import _fastapi, _panel
+
+_GandharvaT = TypeVar("_GandharvaT", bound=type["Gandharva"])
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+
+@disjoint_base
+class Gandharva(_fastapi.App, _panel.App):
+    @classmethod
+    def register(cls, child: _GandharvaT) -> _GandharvaT:
+        if inspect.isabstract(cls) or inspect.isabstract(child):
+            message = (
+                "Can't register sub-application if either the parent or the "
+                "child is an abstract class. Please implement the main() "
+                "method."
+            )
+            raise gd.ApplicationRegisterError(message) from None
+        if cls is child or cls._registered(child):
+            message = (
+                "Can't register sub-application if a cycle would be formed "
+                "in the application structure graph"
+            )
+            raise gd.ApplicationRegisterError(message)
+        cls.children.append(child)
+        return child
+
+    def syncify(
+        self,
+        func: Callable[_P, Coroutine[Any, Any, _T]],
+    ) -> Callable[_P, _T]:
+        match self.run_mode:
+            case "api":
+                @functools.wraps(func)
+                def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _T:
+                    wrapped = functools.partial(func, *args, **kwargs)
+                    return anyio.from_thread.run(wrapped)
+            case "cli":
+                @functools.wraps(func)
+                def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _T:
+                    coro = func(*args, **kwargs)
+                    return asyncio.run(coro)
+            case "gui":
+                @functools.wraps(func)
+                def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _T:
+                    coro = func(*args, **kwargs)
+                    fut = asyncio.run_coroutine_threadsafe(coro, loop)
+                    return fut.result()
+
+                loop = self.panel_event_loop
+        return wrapper
+
+    @classmethod
+    def _registered(cls, parent: type["Gandharva"]) -> bool:
+        children = parent.children
+        return cls in children or any(map(cls._registered, children))