dsa-tracker 0.2.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+dsa_tracker/__init__.py,sha256=xvCklHMHOAxgvMXPDNHcvYP8_kNoc4APFTJh8R0SUQY,195
+dsa_tracker/client.py,sha256=Qf9QrbYr-Df1dAlVRp2_-3oeI59_YtktNm-GdH8_8-M,6506
+dsa_tracker-0.2.0.dist-info/METADATA,sha256=IczhQ8oBrKoKKz7on1ogNJ8rzN1D278V9Ga_9IWMTJM,4368
+dsa_tracker-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dsa_tracker-0.2.0.dist-info/RECORD,,

dsa_tracker-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any