opencode-db 0.7.0__tar.gz → 0.7.2__tar.gz

{opencode_db-0.7.0/opencode_db.egg-info → opencode_db-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-db
-Version: 0.7.0
+Version: 0.7.2
 Summary: OpenCode database CLI manager — browse, export, analyze, clean up sessions
 Project-URL: Homepage, https://github.com/VasilevNStas/opencode-db
 Project-URL: Source, https://github.com/VasilevNStas/opencode-db
@@ -23,6 +23,9 @@ Dynamic: license-file
 
 ```bash
 pip install opencode-db
+
+# recommended if your system python3 is older than 3.12:
+uv tool install opencode-db
 ```
 
 ## Quick start
@@ -54,6 +57,6 @@ pip install opencode-db         # zero external dependencies
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.12+ — the CLI checks the interpreter at startup and exits with a clear message instead of an `ImportError` on older versions
 - [OpenCode](https://opencode.ai) (must have been run at least once)
 - macOS / Linux

{opencode_db-0.7.0 → opencode_db-0.7.2}/README.md

@@ -22,9 +22,10 @@ opencode-db costs --total  # total token costs
 
 ### Requirements
 
-- Python 3.12+
+- Python 3.12+ — `opencode-db` refuses to start on older interpreters with a clear message (no cryptic `ImportError`)
 - OpenCode (must have been run at least once — the database is created automatically)
 - macOS / Linux
+- [`uv`](https://docs.astral.sh/uv/) — optional, but recommended for installing and running on systems whose default `python3` is older than 3.12
 
 ### Database location
 
@@ -51,13 +52,26 @@ opencode-db --db-path /path/to/opencode.db stats
 
 The `--db-path` flag takes precedence over the environment variable.
 
-### One-command install (recommended)
+### Recommended: uv
+
+If your system `python3` is older than 3.12 (for example, macOS ships 3.9), use `uv` — it installs the tool into an isolated environment with a supported interpreter:
+
+```bash
+uv tool install opencode-db
+# with enhanced Markdown rendering:
+uv tool install "opencode-db[rich]"
+
+# one-off run without installing:
+uvx opencode-db stats
+```
+
+### One-command install
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/VasilevNStas/opencode-db/master/install.sh | sh
 ```
 
-Downloads everything to `~/.local/share/opencode-db/` and creates `~/.local/bin/opencode-db`.
+Downloads everything to `~/.local/share/opencode-db/` and creates `~/.local/bin/opencode-db`. The installer looks for Python 3.12+ (including interpreters managed by `uv` or `pyenv`) and writes the discovered path into the launcher shebang.
 
 ### pip / pipx install
 
@@ -67,7 +81,7 @@ pipx install opencode-db
 pip install opencode-db
 ```
 
-[Zero external dependencies](https://treyhunner.com/2015/12/python-imports-and-path-manipulation/) — pure Python standard library only.
+[Zero external dependencies](https://treyhunner.com/2015/12/python-imports-and-path-manipulation/) — pure Python standard library only (`rich` is optional).
 
 ### Manual install
 
@@ -82,7 +96,17 @@ git clone https://github.com/VasilevNStas/opencode-db.git ~/.local/share/opencod
 ```bash
 cat > ~/.local/bin/opencode-db << 'SCRIPT'
 #!/usr/bin/env python3
-import sys, os
+import os
+import sys
+
+if sys.version_info < (3, 12):
+    print(
+        "opencode-db requires Python 3.12+; current: %s (%s)"
+        % (".".join(map(str, sys.version_info[:3])), sys.executable),
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
 PKG_DIR = os.path.expanduser("~/.local/share/opencode-db")
 if PKG_DIR not in sys.path:
     sys.path.insert(0, PKG_DIR)
@@ -488,14 +512,16 @@ Example output:
 ~/.local/share/opencode-db/               ← all source code
 │
 ├── __init__.py                           ← executable entry point
-├── __main__.py                           ← python -m opencode_db
+├── __main__.py                           ← python3 . (directory entry point)
 ├── cli.py                                ← argparse + command dispatcher
 │
 ├── config.py                             ← constants and paths
+├── runtime.py                            ← Python 3.12+ version guard
 ├── db.py                                 ← SQLite queries
 ├── utils.py                              ← date/token formatting, validation
 ├── formatters.py                         ← tables, JSON, Markdown, snapshots
-├── i18n.py                               ← localization (EN/RU, 238 keys)
+├── i18n.py                               ← localization (EN/RU, 280 keys)
+├── markdown_to_ansi.py                   ← Markdown → ANSI renderer for `view`
 │
 ├── commands/
 │   └── __init__.py                       ← command registry
@@ -512,6 +538,7 @@ Example output:
 ├── cmd_stats.py                          ← opencode-db stats
 ├── cmd_todos.py                          ← opencode-db todos
 ├── cmd_vacuum.py                         ← opencode-db vacuum
+├── cmd_view.py                           ← opencode-db view
 └── cmd_help.py                           ← opencode-db help
 
 README.md                                 ← this file (English)
@@ -522,10 +549,11 @@ opencode-db-commands.json                 ← OpenCode TUI custom commands confi
 ### How it works
 
 1. The launcher script at `~/.local/bin/opencode-db` (a shebang Python script) adds `~/.local/share/opencode-db/` to `sys.path` and calls `cli.main()`.
-2. `cli.py` builds an `argparse` parser with subparsers from every command module and dispatches the call.
-3. Each command is a separate `cmd_*.py` module exporting two functions: `register(subparsers)` and `run(args, db)`.
-4. `db.py` opens a connection to OpenCode's SQLite database (`~/.local/share/opencode/opencode.db`).
-5. Destructive operations (`delete`, `prune`) always require confirmation (or `--force`).
+2. `runtime.require_python()` checks the interpreter before importing `cli`/`db`; on Python < 3.12 it prints a clear message with remediation steps instead of failing with `ImportError`.
+3. `cli.py` builds an `argparse` parser with subparsers from every command module and dispatches the call.
+4. Each command is a separate `cmd_*.py` module exporting two functions: `register(subparsers)` and `run(args, db)`.
+5. `db.py` opens a connection to OpenCode's SQLite database (`~/.local/share/opencode/opencode.db`).
+6. Destructive operations (`delete`, `prune`) always require confirmation (or `--force`).
 
 ### Database schema (key tables)
 
@@ -617,7 +645,7 @@ opencode-db --lang en help        # English help text
 opencode-db --lang en stats       # English statistics
 ```
 
-The `--lang` flag applies to any command. All 238 UI strings are translated. Data content (session titles, project names, etc.) remains in its original language.
+The `--lang` flag applies to any command. All 280 UI strings are translated. Data content (session titles, project names, etc.) remains in its original language.
 
 The language can also be set via environment variable `OPENCODE_DB_LANG=en`.
 
@@ -659,10 +687,54 @@ Use a longer prefix or the full session ID (use `list --json` to find it).
 
 If the database is being used by another process (e.g., OpenCode is running), VACUUM may fail. Close OpenCode and try again.
 
+### `ImportError: cannot import name 'UTC' from 'datetime'`
+
+This means `opencode-db` is running on Python older than 3.12 (for example, the system Python 3.9). Check:
+
+```bash
+python3 --version
+```
+
+Fix with `uv` (recommended):
+
+```bash
+uv python install 3.13
+uv tool install opencode-db
+opencode-db stats
+```
+
+Or run the repository checkout with an explicit interpreter:
+
+```bash
+uvx --from . opencode-db stats
+# alternative for a persistent dev environment:
+uv run --python 3.13 opencode-db stats
+```
+
+After changing the interpreter, rerun `install.sh` to regenerate the `~/.local/bin/opencode-db` launcher.
+
 ---
 
 ## Development
 
+### Local development
+
+Requires Python 3.12+ and `pytest`/`ruff`:
+
+```bash
+git clone https://github.com/VasilevNStas/opencode-db.git
+cd opencode-db
+
+uv venv --python 3.13
+source .venv/bin/activate
+uv pip install -e ".[rich]"
+uv pip install pytest ruff
+
+make check          # check-python + ruff + 191 tests
+```
+
+`make check` fails fast with a clear message if the active interpreter is older than 3.12.
+
 ### Adding a new command
 
 1. Create `cmd_xxx.py`:
@@ -692,10 +764,11 @@ The command will appear in `--help` automatically.
 python3 ~/.local/share/opencode-db list
 ```
 
-Or as a module:
+Or from the repository root (Python 3.12+):
 
 ```bash
-python3 -m opencode_db list
+python3 . list
+uvx --from . opencode-db list
 ```
 
 ---

{opencode_db-0.7.0 → opencode_db-0.7.2}/README_PYPI.md

@@ -7,6 +7,9 @@
 
 ```bash
 pip install opencode-db
+
+# recommended if your system python3 is older than 3.12:
+uv tool install opencode-db
 ```
 
 ## Quick start
@@ -38,6 +41,6 @@ pip install opencode-db         # zero external dependencies
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.12+ — the CLI checks the interpreter at startup and exits with a clear message instead of an `ImportError` on older versions
 - [OpenCode](https://opencode.ai) (must have been run at least once)
 - macOS / Linux

{opencode_db-0.7.0 → opencode_db-0.7.2}/cli.py

@@ -7,14 +7,20 @@
   - Единообразный интерфейс
 """
 
+from __future__ import annotations
+
 import argparse
 import os
 import sys
 from typing import Any, Literal
 
-import commands
-from db import get_db
-from i18n import _, set_lang
+from runtime import require_python
+
+require_python()
+
+import commands  # noqa: E402
+from db import get_db  # noqa: E402
+from i18n import _, set_lang  # noqa: E402
 
 
 def build_parser() -> argparse.ArgumentParser:

{opencode_db-0.7.0 → opencode_db-0.7.2/opencode_db.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-db
-Version: 0.7.0
+Version: 0.7.2
 Summary: OpenCode database CLI manager — browse, export, analyze, clean up sessions
 Project-URL: Homepage, https://github.com/VasilevNStas/opencode-db
 Project-URL: Source, https://github.com/VasilevNStas/opencode-db
@@ -23,6 +23,9 @@ Dynamic: license-file
 
 ```bash
 pip install opencode-db
+
+# recommended if your system python3 is older than 3.12:
+uv tool install opencode-db
 ```
 
 ## Quick start
@@ -54,6 +57,6 @@ pip install opencode-db         # zero external dependencies
 
 ## Requirements
 
-- Python 3.12+
+- Python 3.12+ — the CLI checks the interpreter at startup and exits with a clear message instead of an `ImportError` on older versions
 - [OpenCode](https://opencode.ai) (must have been run at least once)
 - macOS / Linux

{opencode_db-0.7.0 → opencode_db-0.7.2}/opencode_db.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ formatters.py
 i18n.py
 markdown_to_ansi.py
 pyproject.toml
+runtime.py
 utils.py
 commands/__init__.py
 opencode_db.egg-info/PKG-INFO
@@ -34,4 +35,5 @@ tests/test_commands.py
 tests/test_db.py
 tests/test_formatters.py
 tests/test_i18n.py
+tests/test_runtime.py
 tests/test_utils.py

{opencode_db-0.7.0 → opencode_db-0.7.2}/opencode_db.egg-info/top_level.txt

@@ -19,4 +19,5 @@ db
 formatters
 i18n
 markdown_to_ansi
+runtime
 utils

{opencode_db-0.7.0 → opencode_db-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opencode-db"
-version = "0.7.0"
+version = "0.7.2"
 description = "OpenCode database CLI manager — browse, export, analyze, clean up sessions"
 readme = "README_PYPI.md"
 requires-python = ">=3.12"
@@ -23,7 +23,7 @@ opencode-db = "cli:main"
 
 [tool.setuptools]
 py-modules = [
-    "cli", "config", "db", "formatters", "i18n", "utils",
+    "cli", "config", "db", "formatters", "i18n", "runtime", "utils",
     "cmd_costs", "cmd_delete", "cmd_export", "cmd_help",
     "cmd_info", "cmd_list", "cmd_projects", "cmd_prune",
     "cmd_search", "cmd_stats", "cmd_todos", "cmd_tree", "cmd_vacuum",

opencode_db-0.7.2/runtime.py

@@ -0,0 +1,55 @@
+"""Проверка минимальной версии Python.
+
+Модуль намеренно написан без синтаксиса новее Python 3.8, чтобы его можно
+было импортировать до проверки версии и показать понятную ошибку вместо
+ImportError/SyntaxError.
+"""
+
+import sys
+
+MIN_PYTHON = (3, 12)
+REQUIRED_VERSION = "3.12"
+
+
+def format_version_error(version_info=None, executable=None) -> str:
+    """Возвращает текст ошибки для неподдерживаемой версии Python."""
+    info = version_info or sys.version_info
+    exe = executable or sys.executable
+    current = f"{info[0]}.{info[1]}.{info[2]}"
+
+    return (
+        f"opencode-db requires Python {REQUIRED_VERSION}+.\n"
+        f"opencode-db требует Python {REQUIRED_VERSION}+.\n"
+        "\n"
+        f"Current interpreter: Python {current} ({exe})\n"
+        f"Текущий интерпретатор: Python {current} ({exe})\n"
+        "\n"
+        "How to fix / Как исправить:\n"
+        "  uv python install 3.13\n"
+        "  uv venv --python 3.13\n"
+        "  source .venv/bin/activate\n"
+        "  pip install -e .\n"
+        "\n"
+        "Or run with uv / Или запуск через uv:\n"
+        "  uv run --python 3.13 opencode-db --help\n"
+        "  uv tool install --editable . && opencode-db --help\n"
+        "\n"
+        "After changing the interpreter, rerun install.sh to regenerate\n"
+        "the ~/.local/bin/opencode-db launcher."
+    )
+
+
+def check_python_version(version_info=None):
+    """Возвращает None, если версия подходит, иначе текст ошибки."""
+    info = version_info or sys.version_info
+    if tuple(info[:2]) >= MIN_PYTHON:
+        return None
+    return format_version_error(info)
+
+
+def require_python() -> None:
+    """Завершает процесс с понятной ошибкой, если Python слишком старый."""
+    message = check_python_version()
+    if message:
+        print(message, file=sys.stderr)
+        raise SystemExit(1)

opencode_db-0.7.2/tests/test_runtime.py

@@ -0,0 +1,21 @@
+from runtime import MIN_PYTHON, check_python_version, format_version_error
+
+
+class TestRuntime:
+    def test_supported_versions_pass(self) -> None:
+        assert check_python_version((3, 12, 0)) is None
+        assert check_python_version((3, 13, 5)) is None
+        assert check_python_version((4, 0, 0)) is None
+
+    def test_old_version_returns_error(self) -> None:
+        message = check_python_version((3, 9, 6))
+        assert message is not None
+        assert "3.12+" in message
+        assert "3.9.6" in message
+
+    def test_error_contains_remediation(self) -> None:
+        message = format_version_error((3, 9, 6), "/usr/bin/python3")
+        assert MIN_PYTHON == (3, 12)
+        assert "/usr/bin/python3" in message
+        assert "uv python install" in message
+        assert "uv run" in message

{opencode_db-0.7.0 → opencode_db-0.7.2}/utils.py

@@ -50,7 +50,7 @@ def parse_date(date_str: str) -> datetime | None:
         return None
 
 
-def parse_time_spec(spec) -> None | datetime:
+def parse_time_spec(spec) -> datetime | None:
     """Парсит спецификацию времени ('30d', '6m', '1y') в timedelta."""
     if not spec or not isinstance(spec, str):
         return None