dsa-tracker 0.2.0__tar.gz

dsa_tracker-0.2.0/.gitignore

@@ -0,0 +1,142 @@
+# Root-level safety net for the dsa-tracker monorepo. Each entry applies
+# to every subtree (backend, frontend, colab_helper). Subdirectories MAY
+# add their own .gitignore for project-local extras, but anything common
+# belongs here so we never have to chase the same rule into two files.
+
+# ---------------------------------------------------------------------------
+# Secrets / local-only state — must never reach a remote
+# ---------------------------------------------------------------------------
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# Auth scratch files used by manual API testing
+cookies.txt
+*_cookies.txt
+
+# ---------------------------------------------------------------------------
+# Databases (local dev only — production uses Postgres on a managed host)
+# ---------------------------------------------------------------------------
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+
+# ---------------------------------------------------------------------------
+# Python
+# ---------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging / build
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+sdist/
+wheels/
+*.whl
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Test / lint / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.pyre/
+.tox/
+.nox/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.cache/
+.hypothesis/
+
+# Notebooks (colab_helper has examples; checkpoints are local)
+.ipynb_checkpoints/
+
+# ---------------------------------------------------------------------------
+# Node / JS / TypeScript
+# ---------------------------------------------------------------------------
+node_modules/
+.npm/
+.yarn/
+.pnpm-store/
+.pnp.*
+
+# Build output
+dist/
+build/
+out/
+
+# Vite / TS / bundler caches
+.vite/
+.turbo/
+.parcel-cache/
+*.tsbuildinfo
+
+# JS coverage
+coverage/
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# ---------------------------------------------------------------------------
+# Logs
+# ---------------------------------------------------------------------------
+*.log
+logs/
+
+# ---------------------------------------------------------------------------
+# Editors / IDEs
+# ---------------------------------------------------------------------------
+.vscode/
+!.vscode/extensions.json
+.idea/
+*.iml
+.fleet/
+*.swp
+*.swo
+*~
+
+# ---------------------------------------------------------------------------
+# OS junk
+# ---------------------------------------------------------------------------
+.DS_Store
+.AppleDouble
+.LSOverride
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# ---------------------------------------------------------------------------
+# Misc local scratch
+# ---------------------------------------------------------------------------
+.tmp/
+tmp/
+*.local
+
+# ---------------------------------------------------------------------------
+# Whitelists — undo overly broad rules from the user's global gitignore
+# (their global has `*.ini`, which would otherwise drop alembic.ini).
+# ---------------------------------------------------------------------------
+!*.ini

dsa_tracker-0.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: dsa-tracker
+Version: 0.2.0
+Summary: Log DSA prep solves from a Colab/Jupyter notebook to your DSA Tracker instance.
+Project-URL: Homepage, https://github.com/yourusername/dsa-tracker
+Project-URL: Issues, https://github.com/yourusername/dsa-tracker/issues
+Author-email: DSA Tracker <noreply@example.com>
+License: MIT
+Keywords: colab,dsa,interview-prep,leetcode,spaced-repetition
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# dsa-tracker
+
+Tiny Python client for [DSA Tracker](https://github.com/yourusername/dsa-tracker). Log a solve from a Colab/Jupyter notebook in one call — same SM-2 scheduling and GitHub auto-push you get from the web app.
+
+## Install
+
+```bash
+pip install dsa-tracker
+```
+
+## Get an API key
+
+In your DSA Tracker dashboard → **Settings → API keys → Generate new key**. The plaintext value is shown exactly once — copy it and treat it like a password. You can name keys per device/notebook so revoking one doesn't break the others.
+
+## Use it
+
+```python
+from dsa_tracker import Tracker
+
+tracker = Tracker(
+    api_url="https://your-dsa-tracker.com",
+    api_key="dsa_xxxxxxxxxxxxxxxxxxxxxx",
+)
+
+# Solve the problem like you always do
+def two_sum(nums, target):
+    seen = {}
+    for i, n in enumerate(nums):
+        if target - n in seen:
+            return [seen[target - n], i]
+        seen[n] = i
+
+# Log it without leaving the notebook
+import inspect
+
+result = tracker.log(
+    title="Two Sum",
+    confidence=4,                            # 1 (Forgot) → 5 (Easy)
+    code=inspect.getsource(two_sum),
+    language="python",
+    difficulty="easy",
+    topics=["Array", "HashMap"],
+    pattern="Hash Lookup",
+    time_complexity="O(n)",
+    space_complexity="O(n)",
+    playlist="leetcode-75",                  # optional: push to this playlist's GitHub config
+)
+
+print(f"→ next review: {result['next_review_at']} · status: {result['status']}")
+if result.get('git_push_queued'):
+    print("→ pushed to GitHub via playlist 'leetcode-75'")
+elif result.get('git_push_skip_reason'):
+    print(f"→ no GitHub push: {result['git_push_skip_reason']}")
+```
+
+## What happens on the server
+
+1. `Two Sum` is looked up by slug. Created if new, otherwise reused.
+2. A new `Solution` row captures your code, language, complexities.
+3. A new `Review` row runs through SM-2 with your confidence rating.
+4. `problem.next_review_at` and `problem.status` are updated.
+5. If you have GitHub auto-push enabled, the solution is committed to your repo in the background.
+
+The return value tells you exactly what happened:
+
+```python
+{
+    'problem_id': 42,
+    'solution_id': 87,
+    'review_id': 105,
+    'created': True,                # False if you've logged this title before
+    'next_review_at': '2026-05-27',
+    'status': 'learning',
+    'reps': 1,
+    'interval_days': 1,
+}
+```
+
+## All parameters
+
+| Required | Optional |
+|---|---|
+| `title`, `confidence` | `code`, `language`, `difficulty`, `topics`, `pattern`, `platform`, `problem_url`, `approach`, `time_complexity`, `space_complexity`, `notes` |
+
+Defaults: `language="python"`, `difficulty="medium"`, `approach="optimal"`. Anything you omit just isn't sent.
+
+## Errors
+
+The client raises `TrackerError` on any non-2xx response with the server's reason attached:
+
+```python
+from dsa_tracker import TrackerError
+
+try:
+    tracker.log(title="X", confidence=4)
+except TrackerError as e:
+    print(f"Couldn't log: {e}")
+```
+
+Common cases: `401` (bad/revoked API key), `422` (missing required field), connection timeout.
+
+## Context manager
+
+For scripts that make many calls, use it as a context manager to clean up the underlying connection pool:
+
+```python
+with Tracker(api_url=..., api_key=...) as tracker:
+    for problem in queue:
+        tracker.log(title=problem.name, confidence=problem.rating, code=problem.code)
+```
+
+## License
+
+MIT.

dsa_tracker-0.2.0/README.md

@@ -0,0 +1,114 @@
+# dsa-tracker
+
+Tiny Python client for [DSA Tracker](https://github.com/yourusername/dsa-tracker). Log a solve from a Colab/Jupyter notebook in one call — same SM-2 scheduling and GitHub auto-push you get from the web app.
+
+## Install
+
+```bash
+pip install dsa-tracker
+```
+
+## Get an API key
+
+In your DSA Tracker dashboard → **Settings → API keys → Generate new key**. The plaintext value is shown exactly once — copy it and treat it like a password. You can name keys per device/notebook so revoking one doesn't break the others.
+
+## Use it
+
+```python
+from dsa_tracker import Tracker
+
+tracker = Tracker(
+    api_url="https://your-dsa-tracker.com",
+    api_key="dsa_xxxxxxxxxxxxxxxxxxxxxx",
+)
+
+# Solve the problem like you always do
+def two_sum(nums, target):
+    seen = {}
+    for i, n in enumerate(nums):
+        if target - n in seen:
+            return [seen[target - n], i]
+        seen[n] = i
+
+# Log it without leaving the notebook
+import inspect
+
+result = tracker.log(
+    title="Two Sum",
+    confidence=4,                            # 1 (Forgot) → 5 (Easy)
+    code=inspect.getsource(two_sum),
+    language="python",
+    difficulty="easy",
+    topics=["Array", "HashMap"],
+    pattern="Hash Lookup",
+    time_complexity="O(n)",
+    space_complexity="O(n)",
+    playlist="leetcode-75",                  # optional: push to this playlist's GitHub config
+)
+
+print(f"→ next review: {result['next_review_at']} · status: {result['status']}")
+if result.get('git_push_queued'):
+    print("→ pushed to GitHub via playlist 'leetcode-75'")
+elif result.get('git_push_skip_reason'):
+    print(f"→ no GitHub push: {result['git_push_skip_reason']}")
+```
+
+## What happens on the server
+
+1. `Two Sum` is looked up by slug. Created if new, otherwise reused.
+2. A new `Solution` row captures your code, language, complexities.
+3. A new `Review` row runs through SM-2 with your confidence rating.
+4. `problem.next_review_at` and `problem.status` are updated.
+5. If you have GitHub auto-push enabled, the solution is committed to your repo in the background.
+
+The return value tells you exactly what happened:
+
+```python
+{
+    'problem_id': 42,
+    'solution_id': 87,
+    'review_id': 105,
+    'created': True,                # False if you've logged this title before
+    'next_review_at': '2026-05-27',
+    'status': 'learning',
+    'reps': 1,
+    'interval_days': 1,
+}
+```
+
+## All parameters
+
+| Required | Optional |
+|---|---|
+| `title`, `confidence` | `code`, `language`, `difficulty`, `topics`, `pattern`, `platform`, `problem_url`, `approach`, `time_complexity`, `space_complexity`, `notes` |
+
+Defaults: `language="python"`, `difficulty="medium"`, `approach="optimal"`. Anything you omit just isn't sent.
+
+## Errors
+
+The client raises `TrackerError` on any non-2xx response with the server's reason attached:
+
+```python
+from dsa_tracker import TrackerError
+
+try:
+    tracker.log(title="X", confidence=4)
+except TrackerError as e:
+    print(f"Couldn't log: {e}")
+```
+
+Common cases: `401` (bad/revoked API key), `422` (missing required field), connection timeout.
+
+## Context manager
+
+For scripts that make many calls, use it as a context manager to clean up the underlying connection pool:
+
+```python
+with Tracker(api_url=..., api_key=...) as tracker:
+    for problem in queue:
+        tracker.log(title=problem.name, confidence=problem.rating, code=problem.code)
+```
+
+## License
+
+MIT.

dsa_tracker-0.2.0/dsa_tracker/__init__.py

@@ -0,0 +1,6 @@
+"""dsa-tracker — log DSA prep solves from a Python notebook or script."""
+
+from .client import Tracker, TrackerError
+
+__version__ = "0.1.0"
+__all__ = ["Tracker", "TrackerError", "__version__"]

dsa_tracker-0.2.0/dsa_tracker/client.py

@@ -0,0 +1,192 @@
+"""Python client for the DSA Tracker `/api/log` endpoint.
+
+Designed for use from a Colab/Jupyter notebook or any Python script. The
+common pattern:
+
+    from dsa_tracker import Tracker
+
+    tracker = Tracker(
+        api_url="https://dsa-tracker.yourdomain.com",
+        api_key="dsa_xxx",  # generated in Settings → API keys
+    )
+
+    def two_sum(nums, target):
+        seen = {}
+        for i, n in enumerate(nums):
+            if target - n in seen:
+                return [seen[target - n], i]
+            seen[n] = i
+
+    import inspect
+    tracker.log(
+        title="Two Sum",
+        code=inspect.getsource(two_sum),
+        confidence=4,
+        difficulty="easy",
+        topics=["Array", "HashMap"],
+        time_complexity="O(n)",
+        space_complexity="O(n)",
+        playlist="leetcode-75",  # optional: pushes to that playlist's Git config
+    )
+
+The optional `playlist` slug pushes the solve to GitHub using that
+playlist's per-enrollment Git config (folder template, .md sections,
+branch). Slug must match an enrolled playlist with Git enabled —
+otherwise the push is silently skipped and the response includes a
+`git_push_skip_reason` so you can debug.
+
+Returns a dict with the resulting problem/solution/review IDs plus the new
+schedule state — useful for printing back to the notebook.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+import httpx
+
+
+class TrackerError(RuntimeError):
+    """Raised when the server rejects a log call (auth, validation, etc.)."""
+
+
+VALID_DIFFICULTY = {"easy", "medium", "hard"}
+VALID_APPROACH = {"brute", "better", "optimal"}
+
+
+class Tracker:
+    """One instance per (api_url, api_key) pair. Cheap to construct.
+
+    Use as a context manager to close the underlying httpx client when done,
+    or call .close() explicitly. Leaving it open across many calls is fine —
+    the client uses connection pooling.
+    """
+
+    def __init__(self, api_url: str, api_key: str, timeout: float = 15.0):
+        if not api_url:
+            raise ValueError("api_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_url = api_url.rstrip("/")
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "dsa-tracker-python/0.2.0",
+            },
+        )
+
+    def __enter__(self) -> "Tracker":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def log(
+        self,
+        title: str,
+        confidence: int,
+        *,
+        code: str | None = None,
+        language: str | None = "python",
+        difficulty: str = "medium",
+        topics: Iterable[str] | None = None,
+        pattern: str | None = None,
+        platform: str | None = None,
+        problem_url: str | None = None,
+        approach: str | None = "optimal",
+        time_complexity: str | None = None,
+        space_complexity: str | None = None,
+        notes: str | None = None,
+        playlist: str | None = None,
+    ) -> dict:
+        """Log a solve. Creates or updates the problem by slug; always adds
+        a new Review and (if `code` is provided) a new Solution.
+
+        Required:
+          title       — human-readable problem name
+          confidence  — 1 (Forgot) to 5 (Easy)
+
+        Optional:
+          playlist    — slug of an enrolled playlist (e.g. "leetcode-75",
+                        "neetcode-150", or your custom playlist's slug).
+                        When set AND that playlist has Git enabled, this
+                        solve is auto-pushed to GitHub using that playlist's
+                        folder + .md/.code config. Otherwise the response
+                        includes a `git_push_skip_reason` explaining why.
+
+        Returns a dict like:
+          {
+            "problem_id": 42,
+            "solution_id": 87,
+            "review_id": 105,
+            "created": True,
+            "next_review_at": "2026-05-27",
+            "status": "learning",
+            "reps": 1,
+            "interval_days": 1,
+            "git_push_queued": True,
+            "git_push_skip_reason": None,
+          }
+
+        Raises TrackerError on any non-2xx response.
+        """
+        if not 1 <= confidence <= 5:
+            raise ValueError("confidence must be 1-5")
+        if difficulty not in VALID_DIFFICULTY:
+            raise ValueError(f"difficulty must be one of {sorted(VALID_DIFFICULTY)}")
+        if approach is not None and approach not in VALID_APPROACH:
+            raise ValueError(f"approach must be one of {sorted(VALID_APPROACH)} or None")
+
+        payload: dict[str, Any] = {
+            "title": title,
+            "confidence": confidence,
+            "difficulty": difficulty,
+        }
+        # Drop None so server defaults apply
+        for k, v in (
+            ("code", code),
+            ("language", language),
+            ("topics", list(topics) if topics else None),
+            ("pattern", pattern),
+            ("platform", platform),
+            ("problem_url", problem_url),
+            ("approach", approach),
+            ("time_complexity", time_complexity),
+            ("space_complexity", space_complexity),
+            ("notes", notes),
+            ("playlist", playlist),
+        ):
+            if v is not None:
+                payload[k] = v
+
+        try:
+            res = self._client.post(f"{self.api_url}/api/log", json=payload)
+        except httpx.RequestError as e:
+            raise TrackerError(f"could not reach DSA Tracker at {self.api_url}: {e}") from e
+
+        if 200 <= res.status_code < 300:
+            return res.json()
+
+        try:
+            body = res.json()
+            detail = body.get("detail") or body
+        except ValueError:
+            detail = res.text[:300]
+        raise TrackerError(f"server rejected log ({res.status_code}): {detail}")
+
+    def ping(self) -> bool:
+        """Verify api_url + api_key by hitting /health and a key-scoped check.
+
+        Returns True on success. Raises TrackerError on auth or network errors.
+        """
+        try:
+            r = self._client.get(f"{self.api_url}/health")
+        except httpx.RequestError as e:
+            raise TrackerError(f"could not reach {self.api_url}: {e}") from e
+        if r.status_code != 200:
+            raise TrackerError(f"server at {self.api_url} returned {r.status_code}")
+        return True

dsa_tracker-0.2.0/examples/colab_demo.py

@@ -0,0 +1,64 @@
+"""Example: log a problem from a Python script (mirror of the Colab cell).
+
+Run as: python colab_demo.py
+
+Set DSA_TRACKER_URL and DSA_TRACKER_KEY in the environment first.
+"""
+
+import inspect
+import os
+import sys
+
+from dsa_tracker import Tracker, TrackerError
+
+
+def two_sum(nums: list[int], target: int) -> list[int] | None:
+    """Classic hash-map one-pass solution."""
+    seen: dict[int, int] = {}
+    for i, n in enumerate(nums):
+        complement = target - n
+        if complement in seen:
+            return [seen[complement], i]
+        seen[n] = i
+    return None
+
+
+def main() -> int:
+    api_url = os.environ.get("DSA_TRACKER_URL", "http://localhost:8000")
+    api_key = os.environ.get("DSA_TRACKER_KEY")
+    if not api_key:
+        print(
+            "ERROR: set DSA_TRACKER_KEY (generate one in Settings → API keys).",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Quick sanity check
+    assert two_sum([2, 7, 11, 15], 9) == [0, 1]
+
+    with Tracker(api_url=api_url, api_key=api_key) as tracker:
+        result = tracker.log(
+            title="Two Sum",
+            confidence=4,
+            code=inspect.getsource(two_sum),
+            language="python",
+            difficulty="easy",
+            topics=["Array", "HashMap"],
+            pattern="Hash Lookup",
+            time_complexity="O(n)",
+            space_complexity="O(n)",
+        )
+
+    print(f"✅ logged — problem #{result['problem_id']}")
+    print(f"   status:      {result['status']}")
+    print(f"   reps:        {result['reps']}")
+    print(f"   next review: {result['next_review_at']}")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except TrackerError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)

dsa_tracker-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "dsa-tracker"
+version = "0.2.0"
+description = "Log DSA prep solves from a Colab/Jupyter notebook to your DSA Tracker instance."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "DSA Tracker", email = "noreply@example.com" }]
+keywords = ["dsa", "leetcode", "spaced-repetition", "colab", "interview-prep"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Education",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/dsa-tracker"
+Issues = "https://github.com/yourusername/dsa-tracker/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["dsa_tracker"]