alchemist-shell 0.1.0__tar.gz

alchemist_shell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elkana Maina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alchemist_shell-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: alchemist-shell
+Version: 0.1.0
+Summary: The missing interactive shell for SQLAlchemy projects.
+License: MIT
+License-File: LICENSE
+Author: Elkana Maina
+Author-email: elisoft.engineer@gmail.com
+Requires-Python: >=3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ipython (>=8.0.0)
+Requires-Dist: nest-asyncio (>=1.5.0)
+Requires-Dist: python-dotenv (>=1.0.0)
+Requires-Dist: rich (>=13.0.0)
+Requires-Dist: sqlalchemy (>=2.0.0)
+Requires-Dist: typer (>=0.9.0)
+Description-Content-Type: text/markdown
+
+# 🔮 Alchemist Shell
+
+**The missing interactive shell for SQLAlchemy.**
+
+Working with SQLAlchemy in a standard REPL is painful. You have to manually manage imports, handle async event loops, and deal with unreadable object representations. **Alchemist Shell** turns your terminal into a powerful, zero-setup database workbench.
+
+---
+
+## 🛠 Why this exists?
+
+The current workflow for inspecting SQLAlchemy projects in the terminal is broken:
+
+1. **Manual Setup**  
+   You shouldn't have to manually import every model and session helper just to check a record.
+
+2. **Manual Session Management**  
+   In interactive environments, setting up and managing a session is repetitive boilerplate.  
+   Creating engines, instantiating sessions, and keeping them alive just to run a few queries breaks the flow.
+
+3. **Bad Visibility**  
+   Default object reprs like `<User 1>` tell you nothing. You deserve to see your data clearly.
+
+---
+
+## ✨ DX Features
+
+- **Auto-Discovery**  
+  Recursively scans your project and injects all models into the namespace instantly.
+
+- **Pre-loaded Toolkit**  
+  `select`, `func`, `text`, and other SQLAlchemy essentials are available on startup.
+
+- **Auto-Formatting**  
+  Model instances render as high-fidelity `rich` tables when evaluated.
+
+- **Modern Shell**  
+  Powered by IPython with completion, syntax highlighting, and history-based autosuggestions.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install alchemist-shell
+```
+
+---
+
+## 🧪 The Workflow
+
+### 1. Zero-Await Session Management
+
+Interact with your session without the async tax:
+
+```python
+alchemist ❯ user = User(username="alchemist")
+alchemist ❯ db.add(user)
+alchemist ❯ db.commit()
+```
+
+---
+
+### 2. Immediate Feedback
+
+Stop calling `print()` or `vars()`. Just evaluate the variable:
+
+```python
+alchemist ❯ user
+# Renders a clean table with all column values
+```
+
+---
+
+### 3. Native Async Queries
+
+Full auto-await support when you need complex queries:
+
+```python
+alchemist ❯ orders = (await db.execute(select(Order))).scalars().all()
+```
+
+---
+
+## 📜 License
+
+MIT License. Permissive and simple.
+
+---
+
+**Built to make SQLAlchemy development suck less.**

alchemist_shell-0.1.0/README.md

@@ -0,0 +1,90 @@
+# 🔮 Alchemist Shell
+
+**The missing interactive shell for SQLAlchemy.**
+
+Working with SQLAlchemy in a standard REPL is painful. You have to manually manage imports, handle async event loops, and deal with unreadable object representations. **Alchemist Shell** turns your terminal into a powerful, zero-setup database workbench.
+
+---
+
+## 🛠 Why this exists?
+
+The current workflow for inspecting SQLAlchemy projects in the terminal is broken:
+
+1. **Manual Setup**  
+   You shouldn't have to manually import every model and session helper just to check a record.
+
+2. **Manual Session Management**  
+   In interactive environments, setting up and managing a session is repetitive boilerplate.  
+   Creating engines, instantiating sessions, and keeping them alive just to run a few queries breaks the flow.
+
+3. **Bad Visibility**  
+   Default object reprs like `<User 1>` tell you nothing. You deserve to see your data clearly.
+
+---
+
+## ✨ DX Features
+
+- **Auto-Discovery**  
+  Recursively scans your project and injects all models into the namespace instantly.
+
+- **Pre-loaded Toolkit**  
+  `select`, `func`, `text`, and other SQLAlchemy essentials are available on startup.
+
+- **Auto-Formatting**  
+  Model instances render as high-fidelity `rich` tables when evaluated.
+
+- **Modern Shell**  
+  Powered by IPython with completion, syntax highlighting, and history-based autosuggestions.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install alchemist-shell
+```
+
+---
+
+## 🧪 The Workflow
+
+### 1. Zero-Await Session Management
+
+Interact with your session without the async tax:
+
+```python
+alchemist ❯ user = User(username="alchemist")
+alchemist ❯ db.add(user)
+alchemist ❯ db.commit()
+```
+
+---
+
+### 2. Immediate Feedback
+
+Stop calling `print()` or `vars()`. Just evaluate the variable:
+
+```python
+alchemist ❯ user
+# Renders a clean table with all column values
+```
+
+---
+
+### 3. Native Async Queries
+
+Full auto-await support when you need complex queries:
+
+```python
+alchemist ❯ orders = (await db.execute(select(Order))).scalars().all()
+```
+
+---
+
+## 📜 License
+
+MIT License. Permissive and simple.
+
+---
+
+**Built to make SQLAlchemy development suck less.**

alchemist_shell-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "alchemist-shell"
+version = "0.1.0"
+description = "The missing interactive shell for SQLAlchemy projects."
+authors = [
+    {name = "Elkana Maina",email = "elisoft.engineer@gmail.com"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+dependencies = [
+    "sqlalchemy>=2.0.0",
+    "typer>=0.9.0",
+    "ipython>=8.0.0",
+    "rich>=13.0.0",
+    "python-dotenv>=1.0.0",
+    "nest-asyncio>=1.5.0"
+]
+
+[tool.poetry]
+packages = [{include = "alchemist_shell", from = "src"}]
+
+[project.scripts]
+alchemist = "alchemist_shell.cli:main"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

alchemist_shell-0.1.0/src/alchemist_shell/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

alchemist_shell-0.1.0/src/alchemist_shell/cli.py

@@ -0,0 +1,206 @@
+import asyncio
+import os
+import sys
+from pathlib import Path
+from functools import wraps
+from typing import Optional, Dict, Any, Type
+
+import nest_asyncio
+import typer
+from IPython.terminal.embed import InteractiveShellEmbed
+from IPython.terminal.prompts import Prompts
+from pygments.token import Token
+from traitlets.config import Config
+from rich.console import Console
+from rich.table import Table
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.engine import Row
+
+nest_asyncio.apply()
+
+from sqlalchemy import (
+    select, insert, update, delete,
+    func, and_, or_, not_, desc, asc, text
+)
+
+from .discovery import discover_models
+from .inspect import inspect_model
+from .session import get_session
+
+console = Console()
+app = typer.Typer(name="alchemist", help="The Modern SQLAlchemy Shell")
+
+
+# --- OS-aware IPython color profile ---
+def get_ipython_colors():
+    if sys.platform.startswith("win"):
+        return "neutral"  # Windows terminals can be inconsistent
+    if "TERM" in os.environ and "256color" in os.environ["TERM"]:
+        return "linux"
+    return "neutral"
+
+
+class AlchemistPrompts(Prompts):
+    def in_prompt_tokens(self):
+        return [(Token.Prompt, "alchemist "), (Token.PromptMarker, "❯ ")]
+
+    def out_prompt_tokens(self):
+        return []
+
+    def continuation_prompt_tokens(self, width=None):
+        return [(Token.Prompt, "          ❯ ")]
+
+
+def make_sync_proxy(db: AsyncSession) -> Any:
+    class AsyncProxy:
+        def __init__(self, obj: AsyncSession):
+            self._obj = obj
+
+        def __getattr__(self, name: str) -> Any:
+            attr = getattr(self._obj, name)
+            if callable(attr):
+                @wraps(attr)
+                def wrapper(*args: Any, **kwargs: Any) -> Any:
+                    result = attr(*args, **kwargs)
+                    if asyncio.iscoroutine(result):
+                        try:
+                            asyncio.get_running_loop()
+                            return result
+                        except RuntimeError:
+                            return asyncio.get_event_loop().run_until_complete(result)
+                    return result
+                return wrapper
+            return attr
+
+    return AsyncProxy(db)
+
+
+def version_callback(value: bool):
+    if value:
+        from . import __version__
+        console.print(f"Alchemist Shell v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def common(
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-v", callback=version_callback, is_eager=True
+    )
+):
+    """The Modern SQLAlchemy Shell."""
+    pass
+
+
+# --- FINAL FORMATTER ---
+def alchemist_display_formatter(obj, p, cycle):
+    if cycle:
+        return p.text(repr(obj))
+
+    # Handle SQLAlchemy Row
+    if isinstance(obj, Row):
+        if len(obj) == 1 and hasattr(obj[0], "__table__"):
+            obj = obj[0]
+        else:
+            return p.text(repr(obj))
+
+    # Handle SQLAlchemy model instances
+    if hasattr(obj, "__table__"):
+        # ✅ Direct Rich rendering (no ANSI stripping)
+        inspect_model(obj)
+        return None
+
+    return p.text(repr(obj))
+
+
+@app.command()
+def shell(
+    db_url: Optional[str] = typer.Option(None, "--db-url", "-u"),
+    path: str = typer.Option(".", "--path", "-p"),
+    env: Optional[str] = typer.Option(None, "--env", "-e")
+) -> None:
+    with console.status("[cyan]Scanning modules...[/cyan]"):
+        models: Dict[str, Type[Any]] = discover_models(path)
+
+    try:
+        db, engine = get_session(db_url, env)
+    except Exception as e:
+        console.print(f"[bold red]Initialization Error:[/bold red] {e}")
+        raise typer.Exit(1)
+
+    is_async = isinstance(db, AsyncSession)
+    mode_label = "ASYNC" if is_async else "SYNC"
+
+    cfg = Config()
+    cfg.InteractiveShell.autoawait = True
+    cfg.InteractiveShell.display_banner = False
+    cfg.InteractiveShell.quiet = True
+    cfg.TerminalInteractiveShell.display_completions_help = False
+    cfg.TerminalInteractiveShell.prompts_class = AlchemistPrompts
+    cfg.TerminalInteractiveShell.term_title = False
+    cfg.IPCompleter.greedy = True
+    cfg.TerminalInteractiveShell.autosuggestions_provider = "NavigableAutoSuggestFromHistory"
+    cfg.IPCompleter.use_jedi = True
+
+    active_db = make_sync_proxy(db) if is_async else db
+
+    namespace: Dict[str, Any] = {
+        "db": active_db,
+        "engine": engine,
+        "inspect": inspect_model,
+        "sql_on": lambda: engine.__setattr__("echo", True),
+        "sql_off": lambda: engine.__setattr__("echo", False),
+        "select": select, "insert": insert, "update": update,
+        "delete": delete, "func": func, "and_": and_,
+        "or_": or_, "not_": not_, "desc": desc,
+        "asc": asc, "text": text,
+        **models
+    }
+
+    ipshell = InteractiveShellEmbed(
+        config=cfg,
+        user_ns=namespace,
+        colors=get_ipython_colors(),  # ✅ OS-aware colors
+        banner1=""
+    )
+
+    formatter = ipshell.display_formatter.formatters["text/plain"]
+
+    # Register formatter for models
+    for model_cls in models.values():
+        formatter.for_type(model_cls, alchemist_display_formatter)
+
+    # Register formatter for SQLAlchemy Row
+    formatter.for_type(Row, alchemist_display_formatter)
+
+    # --- UI ---
+    table = Table(show_header=True, header_style="bold blue", box=None)
+    table.add_column("Model", style="magenta")
+    table.add_column("Table", style="dim")
+
+    for name, cls in models.items():
+        table.add_row(name, str(getattr(cls, "__tablename__", "N/A")))
+
+    console.print("\n[bold magenta]🔮 Alchemist Shell[/bold magenta]")
+    console.print(table)
+
+    db_name = engine.url.database or "memory"
+    console.print(f"[bold cyan]Connected:[/bold cyan] [white]{db_name}[/white] [dim]({mode_label})[/dim]")
+    console.print("[dim]Common imports pre-loaded. Type a model instance to view it.[/dim]\n")
+
+    history_file = Path.home() / ".alchemist_history"
+    if not history_file.exists():
+        history_file.touch()
+
+    ipshell.history_manager.hist_file = str(history_file)
+    ipshell.history_manager.enabled = True
+
+    ipshell()
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

alchemist_shell-0.1.0/src/alchemist_shell/discovery.py

@@ -0,0 +1,34 @@
+import importlib
+import pkgutil
+import sys
+import inspect
+from pathlib import Path
+from typing import Any, Dict, Type
+
+def discover_models(start_dir: str = ".") -> Dict[str, Type[Any]]:
+    """
+    Dynamically discovers SQLAlchemy models in the project root.
+    """
+    path: Path = Path(start_dir).resolve()
+    if str(path) not in sys.path:
+        sys.path.insert(0, str(path))
+    
+    found_models: Dict[str, Type[Any]] = {}
+    ignored_patterns: list[str] = ["venv", "tests", "__pycache__", "alembic"]
+
+    for _, module_name, _ in pkgutil.walk_packages([str(path)]):
+        if any(p in module_name for p in ignored_patterns):
+            continue
+            
+        try:
+            module = importlib.import_module(module_name)
+            for _, obj in inspect.getmembers(module):
+                # Identify models by the __tablename__ convention
+                if inspect.isclass(obj) and hasattr(obj, "__tablename__"):
+                    if obj.__module__.startswith("sqlalchemy"):
+                        continue
+                    found_models[obj.__name__] = obj
+        except (ImportError, AttributeError):
+            continue
+            
+    return found_models

alchemist_shell-0.1.0/src/alchemist_shell/inspect.py

@@ -0,0 +1,32 @@
+from typing import Any
+from rich.console import Console
+from rich.table import Table
+from sqlalchemy import inspect
+
+
+def inspect_model(obj: Any, console: Console | None = None) -> None:
+    console = console or Console()
+
+    if not hasattr(obj, "__table__"):
+        console.print("[bold red]Error:[/bold red] Object is not a SQLAlchemy model instance.")
+        return
+
+    table = Table(
+        title=f"Inspecting {obj.__class__.__name__}",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Column", style="magenta")
+    table.add_column("Value", style="white")
+
+    state = inspect(obj)
+
+    for column in obj.__table__.columns:
+        name = column.name
+        if name in state.unloaded:
+            value = "[italic yellow]<Not Loaded>[/italic yellow]"
+        else:
+            value = str(getattr(obj, name))
+        table.add_row(name, value)
+
+    console.print(table)

alchemist_shell-0.1.0/src/alchemist_shell/session.py

@@ -0,0 +1,55 @@
+import os
+from typing import Optional, Union, Tuple
+from sqlalchemy import create_engine, Engine
+from sqlalchemy.ext.asyncio import (
+    create_async_engine, 
+    AsyncSession, 
+    AsyncEngine, 
+    async_sessionmaker
+)
+from sqlalchemy.orm import sessionmaker, Session
+from .utils import find_and_load_env
+
+# Strict Type Aliases
+DatabaseSession = Union[Session, AsyncSession]
+DatabaseEngine = Union[Engine, AsyncEngine]
+
+def _create_sync_session(url: str) -> Tuple[Session, Engine]:
+    engine: Engine = create_engine(url, echo=False)
+    # Correct sessionmaker typing for SQLAlchemy 2.0
+    factory: sessionmaker[Session] = sessionmaker(
+        bind=engine, 
+        expire_on_commit=False
+    )
+    return factory(), engine
+
+def _create_async_session(url: str) -> Tuple[AsyncSession, AsyncEngine]:
+    engine: AsyncEngine = create_async_engine(url, echo=False)
+    # async_sessionmaker is the future-proof standard
+    factory: async_sessionmaker[AsyncSession] = async_sessionmaker(
+        engine, 
+        expire_on_commit=False, 
+        class_=AsyncSession
+    )
+    return factory(), engine
+
+def get_session(
+    db_url: Optional[str] = None, 
+    env_file: Optional[str] = None
+) -> Tuple[DatabaseSession, DatabaseEngine]:
+    """
+    Gateway to initialize the database connection.
+    """
+    find_and_load_env(env_file)
+    url: Optional[str] = db_url or os.getenv("DATABASE_URL")
+    
+    if not url:
+        raise ValueError("DATABASE_URL not found. Check your .env or --db-url.")
+
+    # Detection logic
+    is_async: bool = any(d in url for d in ["+asyncpg", "+aiosqlite"])
+
+    if is_async:
+        return _create_async_session(url)
+    
+    return _create_sync_session(url)

alchemist_shell-0.1.0/src/alchemist_shell/utils.py

@@ -0,0 +1,17 @@
+import os
+from pathlib import Path
+from typing import Optional
+from dotenv import load_dotenv
+
+def find_and_load_env(env_file: Optional[str] = None) -> None:
+    """Searches for and loads the appropriate .env file."""
+    if env_file and Path(env_file).exists():
+        load_dotenv(env_file)
+        return
+
+    # Priority: .env.dev -> .env.local -> .env
+    targets: list[str] = [".env.dev", ".env.local", ".env"]
+    for target in targets:
+        if Path(target).exists():
+            load_dotenv(target)
+            break