shipreal 1.0.0__tar.gz

shipreal-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+*.tgz
+.DS_Store
+
+# Local artifacts from running `npx skills add` inside this repo to test it.
+# The source of truth for a skill is skills/<id>/SKILL.md, a real file; a
+# consumer install writes .agents/ and symlinks over skills/, which would
+# otherwise get committed as a broken tree.
+.agents/
+.claude/
+skills-lock.json

shipreal-1.0.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: shipreal
+Version: 1.0.0
+Summary: SDK and CLI for the public ShipReal course API: search the curriculum, read a module, read pricing. No authentication.
+Project-URL: Homepage, https://shipreal.dev/developers
+Project-URL: Documentation, https://shipreal.dev/developers
+Project-URL: Repository, https://github.com/mluggy/shipreal-dev
+Project-URL: Issues, https://github.com/mluggy/shipreal-dev/issues
+Author-email: Michael Lugassy <michael@shipreal.dev>
+License: MIT
+Keywords: agent,api-client,cli,course,curriculum,mcp,sdk,shipreal
+Classifier: Development Status :: 5 - Production/Stable
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# shipreal
+
+SDK and CLI for the public [ShipReal](https://shipreal.dev) course API: search
+the curriculum, read a module, read pricing.
+
+Zero dependencies, standard library only. No authentication: the API is public
+read-only reference data about one course, so there is no key to hold and no
+token to refresh. If something asks you for a ShipReal API key, it is not us.
+
+```
+pip install shipreal
+```
+
+## Library
+
+```python
+from shipreal import ShipReal
+
+sr = ShipReal()
+
+sr.search("caching")                  # one page of matches
+list(sr.modules())                    # every module, pagination followed
+sr.module("observability")            # by slug or partial title
+sr.pricing(region="il")               # flattened to one billing region
+sr.course()                           # totals and subtitle languages
+sr.ask("how do I size a database")    # natural language, keyword search behind it
+```
+
+Errors carry [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem
+details. Branch on `type`, not on `status`: the status says a request failed,
+the type says which failure it was.
+
+```python
+from shipreal import ShipReal, ShipRealError
+
+try:
+    ShipReal().module("does-not-exist")
+except ShipRealError as err:
+    print(err.status, err.type, err)
+```
+
+## CLI
+
+```
+shipreal search caching
+shipreal search --all --json
+shipreal module observability
+shipreal pricing --region il
+shipreal ask "what should I learn before deploying"
+```
+
+## Testing against the sandbox
+
+Frozen fixture data over the same code path, so a test written against it stays
+green when the course changes:
+
+```python
+sr = ShipReal(sandbox=True)
+```
+
+Fixture prices are 1 unit and fixture links point at `example.invalid`, so
+sandbox data that leaks into real output is obvious on sight. Assert on shape,
+pagination and error format, not on prices or titles. Details at
+[shipreal.dev/sandbox](https://shipreal.dev/sandbox).
+
+## There is nothing to write
+
+The API has no write path and no purchase endpoint in either environment.
+Enrollment runs through a hosted checkout that a person completes, so if a task
+needs a transaction the answer is a link for a human, not a call.
+
+## Other surfaces
+
+REST is one of several. There is an
+[OpenAPI 3.1 spec](https://shipreal.dev/openapi.json), an MCP server at
+[/mcp](https://shipreal.dev/mcp), and a
+[JavaScript client](https://www.npmjs.com/package/shipreal) with the same
+surface. Full notes at [shipreal.dev/developers](https://shipreal.dev/developers).
+
+MIT licensed. Source at
+[github.com/mluggy/shipreal-dev](https://github.com/mluggy/shipreal-dev).

shipreal-1.0.0/README.md

@@ -0,0 +1,81 @@
+# shipreal
+
+SDK and CLI for the public [ShipReal](https://shipreal.dev) course API: search
+the curriculum, read a module, read pricing.
+
+Zero dependencies, standard library only. No authentication: the API is public
+read-only reference data about one course, so there is no key to hold and no
+token to refresh. If something asks you for a ShipReal API key, it is not us.
+
+```
+pip install shipreal
+```
+
+## Library
+
+```python
+from shipreal import ShipReal
+
+sr = ShipReal()
+
+sr.search("caching")                  # one page of matches
+list(sr.modules())                    # every module, pagination followed
+sr.module("observability")            # by slug or partial title
+sr.pricing(region="il")               # flattened to one billing region
+sr.course()                           # totals and subtitle languages
+sr.ask("how do I size a database")    # natural language, keyword search behind it
+```
+
+Errors carry [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem
+details. Branch on `type`, not on `status`: the status says a request failed,
+the type says which failure it was.
+
+```python
+from shipreal import ShipReal, ShipRealError
+
+try:
+    ShipReal().module("does-not-exist")
+except ShipRealError as err:
+    print(err.status, err.type, err)
+```
+
+## CLI
+
+```
+shipreal search caching
+shipreal search --all --json
+shipreal module observability
+shipreal pricing --region il
+shipreal ask "what should I learn before deploying"
+```
+
+## Testing against the sandbox
+
+Frozen fixture data over the same code path, so a test written against it stays
+green when the course changes:
+
+```python
+sr = ShipReal(sandbox=True)
+```
+
+Fixture prices are 1 unit and fixture links point at `example.invalid`, so
+sandbox data that leaks into real output is obvious on sight. Assert on shape,
+pagination and error format, not on prices or titles. Details at
+[shipreal.dev/sandbox](https://shipreal.dev/sandbox).
+
+## There is nothing to write
+
+The API has no write path and no purchase endpoint in either environment.
+Enrollment runs through a hosted checkout that a person completes, so if a task
+needs a transaction the answer is a link for a human, not a call.
+
+## Other surfaces
+
+REST is one of several. There is an
+[OpenAPI 3.1 spec](https://shipreal.dev/openapi.json), an MCP server at
+[/mcp](https://shipreal.dev/mcp), and a
+[JavaScript client](https://www.npmjs.com/package/shipreal) with the same
+surface. Full notes at [shipreal.dev/developers](https://shipreal.dev/developers).
+
+MIT licensed. Source at
+[github.com/mluggy/shipreal-dev](https://github.com/mluggy/shipreal-dev).

shipreal-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shipreal"
+version = "1.0.0"
+description = "SDK and CLI for the public ShipReal course API: search the curriculum, read a module, read pricing. No authentication."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Michael Lugassy", email = "michael@shipreal.dev" }]
+keywords = ["shipreal", "sdk", "cli", "api-client", "mcp", "agent", "course", "curriculum"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "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",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+# No runtime dependencies, on purpose. The whole client is stdlib urllib, so
+# installing it cannot drag a transitive tree into an agent's environment.
+dependencies = []
+
+# These two are how a scanner confirms the package is the official SDK for the
+# domain rather than a third party with a similar name. Keep them pointing at
+# shipreal.dev and at the source repo.
+[project.urls]
+Homepage = "https://shipreal.dev/developers"
+Documentation = "https://shipreal.dev/developers"
+Repository = "https://github.com/mluggy/shipreal-dev"
+Issues = "https://github.com/mluggy/shipreal-dev/issues"
+
+[project.scripts]
+shipreal = "shipreal.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shipreal"]

shipreal-1.0.0/src/shipreal/__init__.py

@@ -0,0 +1,14 @@
+"""ShipReal SDK: a thin, dependency-free client for the public ShipReal API.
+
+There is no authentication anywhere in this package, and that is not an
+omission. The API is public read-only reference data about one course, so there
+is no key to hold, no token to refresh, and no credential this client could
+leak. If something asks you for a ShipReal API key, it is not us.
+
+Python 3.9+, standard library only.
+"""
+
+from ._client import ShipReal, ShipRealError
+
+__all__ = ["ShipReal", "ShipRealError", "__version__"]
+__version__ = "1.0.0"

shipreal-1.0.0/src/shipreal/_client.py

@@ -0,0 +1,221 @@
+"""The client itself. Standard library only: urllib, json, typing."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterator, List, Optional, Sequence
+
+DEFAULT_BASE = "https://shipreal.dev"
+VERSION = "v1"
+_USER_AGENT = "shipreal-python/1.0.0 (+https://shipreal.dev/developers)"
+
+
+class ShipRealError(Exception):
+    """Raised for any non-2xx response, carrying the RFC 9457 problem details.
+
+    Read ``type`` rather than switching on ``status``: the status says a request
+    failed, the type says which failure it was, and only the second one is
+    stable enough to branch on.
+    """
+
+    def __init__(self, status: int, problem: Optional[Dict[str, Any]], url: str) -> None:
+        message = None
+        if problem:
+            message = problem.get("detail") or problem.get("title")
+        super().__init__(message or f"Request failed with {status}")
+        self.status = status
+        #: RFC 9457 problem details, when the server sent them.
+        self.problem = problem
+        #: Stable identifier for the kind of failure.
+        self.type = problem.get("type") if problem else None
+        self.url = url
+
+
+class ShipReal:
+    """Client for the public ShipReal API.
+
+    :param base_url: Override the origin, e.g. to point at a local worker.
+    :param sandbox: Route reads at the frozen fixture data. See
+        https://shipreal.dev/sandbox for what differs and what does not.
+    :param timeout: Seconds before a request gives up.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE,
+        sandbox: bool = False,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.sandbox = sandbox
+        self.timeout = timeout
+
+    # -- plumbing ---------------------------------------------------------
+
+    def _url(self, path: str, params: Optional[Dict[str, Any]] = None) -> str:
+        prefix = f"/api/{VERSION}/sandbox" if self.sandbox else f"/api/{VERSION}"
+        url = self.base_url + prefix + path
+        query = {
+            k: str(v)
+            for k, v in (params or {}).items()
+            if v is not None and v != ""
+        }
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        return url
+
+    def _request(
+        self,
+        url: str,
+        body: Optional[Dict[str, Any]] = None,
+        accept: str = "application/json",
+    ) -> Any:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"accept": accept, "user-agent": _USER_AGENT}
+        if data is not None:
+            headers["content-type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return json.loads(res.read().decode("utf-8"))
+        except urllib.error.HTTPError as err:
+            # The error body is where the problem details live, so it gets
+            # parsed rather than discarded. A body that is not JSON is not
+            # itself an error worth raising over: the status still stands.
+            problem = None
+            try:
+                problem = json.loads(err.read().decode("utf-8"))
+            except Exception:
+                problem = None
+            raise ShipRealError(err.code, problem, url) from None
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self._request(self._url(path, params))
+
+    # -- reads ------------------------------------------------------------
+
+    def search(
+        self,
+        query: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Search the curriculum. Without a query, returns every module in
+        course order.
+
+        Matching is a case-insensitive substring over title, description and
+        part name, so an empty result means the course does not cover that
+        topic under that name, rather than that the search was too clever.
+        """
+        return self._get(
+            "/modules", {"q": query, "page": page, "limit": limit, "cursor": cursor}
+        )
+
+    def modules(self, query: Optional[str] = None) -> Iterator[Dict[str, Any]]:
+        """Every matching module, following pagination for you."""
+        cursor = None
+        while True:
+            page = self.search(query, limit=100, cursor=cursor)
+            for module in page.get("data", []):
+                yield module
+            cursor = (page.get("pagination") or {}).get("nextCursor")
+            if not cursor:
+                return
+
+    def module(self, slug_or_title: str) -> Dict[str, Any]:
+        """One module by slug, or by an exact or partial title match."""
+        if not slug_or_title:
+            raise TypeError("module(slug_or_title) needs an argument")
+        return self._get("/modules/" + urllib.parse.quote(slug_or_title, safe=""))
+
+    def pricing(self, region: Optional[str] = None) -> Dict[str, Any]:
+        """Current plans and prices.
+
+        Two regional prices are live at once, so quoting one without naming its
+        region is misleading. Pass ``region`` ("intl" or "il") when you know
+        which one applies and the response is flattened to that region.
+        """
+        every = self._get("/pricing")
+        if region not in ("intl", "il"):
+            return every
+        complete = dict(every["complete"][region])
+        complete["url"] = every["complete"].get("url")
+        teams = dict(every["teams"][region])
+        teams["minSeats"] = every["teams"].get("minSeats")
+        teams["perSeat"] = True
+        return {
+            "region": region,
+            "free": every["free"],
+            "complete": complete,
+            "teams": teams,
+        }
+
+    def course(self) -> Dict[str, Any]:
+        """Totals, language and the subtitle languages."""
+        return self._get("/course")
+
+    def batch(self, requests: Sequence[Dict[str, str]]) -> Dict[str, Any]:
+        """Several reads in one round trip, up to 20.
+
+        Each item comes back with its own status, so check per item rather than
+        assuming the whole batch succeeded.
+        """
+        items: List[Dict[str, str]] = list(requests)
+        if len(items) > 20:
+            raise ValueError("batch takes at most 20 requests")
+        return self._request(
+            f"{self.base_url}/api/{VERSION}/batch", body={"requests": items}
+        )
+
+    def ask(self, query: str) -> Dict[str, Any]:
+        """Ask in natural language (NLWeb).
+
+        There is no model behind this: it runs the same keyword search, which
+        means it says so when nothing matches instead of inventing a module.
+        """
+        if not query:
+            raise TypeError("ask(query) needs a question")
+        return self._request(f"{self.base_url}/ask", body={"query": query})
+
+    def ask_stream(self, query: str) -> Iterator[Dict[str, Any]]:
+        """The same question, streamed. Yields NLWeb events as they arrive:
+        ``start``, then one ``result`` per hit, then ``complete``.
+        """
+        if not query:
+            raise TypeError("ask_stream(query) needs a question")
+        url = f"{self.base_url}/ask"
+        req = urllib.request.Request(
+            url,
+            data=json.dumps({"query": query}).encode("utf-8"),
+            headers={
+                "accept": "text/event-stream",
+                "content-type": "application/json",
+                "user-agent": _USER_AGENT,
+            },
+        )
+        try:
+            res = urllib.request.urlopen(req, timeout=self.timeout)
+        except urllib.error.HTTPError as err:
+            raise ShipRealError(err.code, None, url) from None
+        with res:
+            event = "message"
+            data = ""
+            for raw in res:
+                line = raw.decode("utf-8").rstrip("\n").rstrip("\r")
+                if line == "":
+                    # A blank line closes an SSE frame. Anything short of one is
+                    # a partial frame and has to wait for the next line.
+                    if data:
+                        try:
+                            yield {"event": event, "data": json.loads(data)}
+                        except ValueError:
+                            pass
+                    event, data = "message", ""
+                elif line.startswith("event:"):
+                    event = line[6:].strip()
+                elif line.startswith("data:"):
+                    data += line[5:].strip()

shipreal-1.0.0/src/shipreal/cli.py

@@ -0,0 +1,125 @@
+"""shipreal: query the ShipReal course catalogue from a terminal or a script.
+
+Every command takes --json, because the reason a CLI earns its place in an
+agent's toolbox is that its output can be piped into something else without
+being scraped.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List
+
+from ._client import ShipReal, ShipRealError
+
+EPILOG = """\
+No API key. No account. The API is public read-only reference data; anything
+that asks you for a ShipReal credential is not us.
+
+Docs: https://shipreal.dev/developers
+"""
+
+
+def _print_modules(modules: List[Dict[str, Any]]) -> None:
+    if not modules:
+        print("No modules matched. The course does not cover that topic under that name.")
+        return
+    for module in modules:
+        print(f"{module.get('slug', '')}  {module.get('title', '')}")
+        part = module.get("part")
+        if part:
+            print(f"  {part}")
+        chapters, minutes = module.get("chapters"), module.get("minutes")
+        if chapters or minutes:
+            print(f"  {chapters or 0} chapters, {minutes or 0} min")
+        print()
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shipreal",
+        description="Query the ShipReal course catalogue.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--json", action="store_true", help="Raw JSON, for piping")
+    parser.add_argument("--sandbox", action="store_true", help="Frozen fixture data, for tests")
+    parser.add_argument("--base", default="https://shipreal.dev", help="Point at a different origin")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    search = sub.add_parser("search", help="Search modules by keyword")
+    search.add_argument("query", nargs="?", default=None)
+    search.add_argument("--limit", type=int, default=None, help="Results per page (max 100)")
+    search.add_argument("--all", action="store_true", help="Every result, following pagination")
+
+    module = sub.add_parser("module", help="One module")
+    module.add_argument("slug_or_title")
+
+    pricing = sub.add_parser("pricing", help="Plans and prices")
+    pricing.add_argument("--region", choices=["intl", "il"], default=None)
+
+    sub.add_parser("course", help="Totals and subtitle languages")
+
+    ask = sub.add_parser("ask", help="Natural-language query")
+    ask.add_argument("question", nargs="+")
+    ask.add_argument("--stream", action="store_true", help="Stream as it arrives")
+
+    return parser
+
+
+def main(argv: List[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    client = ShipReal(base_url=args.base, sandbox=args.sandbox)
+
+    try:
+        if args.command == "search":
+            if args.all:
+                modules = list(client.modules(args.query))
+                print(json.dumps(modules, indent=2)) if args.json else _print_modules(modules)
+            else:
+                page = client.search(args.query, limit=args.limit)
+                print(json.dumps(page, indent=2)) if args.json else _print_modules(page.get("data", []))
+
+        elif args.command == "module":
+            found = client.module(args.slug_or_title)
+            if args.json:
+                print(json.dumps(found, indent=2))
+            else:
+                print(found.get("title", ""))
+                print(found.get("part", ""))
+                print()
+                print(found.get("description", ""))
+
+        elif args.command == "pricing":
+            prices = client.pricing(region=args.region)
+            print(json.dumps(prices, indent=2))
+
+        elif args.command == "course":
+            print(json.dumps(client.course(), indent=2))
+
+        elif args.command == "ask":
+            question = " ".join(args.question)
+            if args.stream:
+                for frame in client.ask_stream(question):
+                    print(json.dumps(frame) if args.json else f"{frame['event']}: {frame['data']}")
+            else:
+                print(json.dumps(client.ask(question), indent=2))
+
+    except ShipRealError as err:
+        # The problem type is the useful half of a failure, so it goes to
+        # stderr next to the message rather than being swallowed.
+        print(f"error {err.status}: {err}", file=sys.stderr)
+        if err.type:
+            print(f"  type: {err.type}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shipreal-1.0.0/tests/test_smoke.py

@@ -0,0 +1,53 @@
+"""Smoke tests against the live sandbox.
+
+They hit the network on purpose. The sandbox exists precisely so a test can
+depend on fixed responses without depending on the course staying still, and a
+client that is never exercised against the real transport is a client that
+passes its tests and fails in use.
+"""
+
+import unittest
+
+from shipreal import ShipReal, ShipRealError
+
+
+class SandboxTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.sr = ShipReal(sandbox=True)
+
+    def test_search_returns_fixture_modules(self) -> None:
+        page = self.sr.search()
+        self.assertIn("data", page)
+        self.assertTrue(page["data"])
+        self.assertTrue(page["data"][0]["slug"].startswith("sandbox-module-"))
+
+    def test_module_by_slug(self) -> None:
+        module = self.sr.module("sandbox-module-1")
+        self.assertEqual(module["slug"], "sandbox-module-1")
+        self.assertIn("description", module)
+
+    def test_modules_iterates_every_page(self) -> None:
+        every = list(self.sr.modules())
+        self.assertTrue(every)
+        self.assertEqual(len({m["slug"] for m in every}), len(every))
+
+    def test_pricing_flattens_to_one_region(self) -> None:
+        flat = self.sr.pricing(region="intl")
+        self.assertEqual(flat["region"], "intl")
+        self.assertIn("now", flat["complete"])
+        # Unflattened keeps both regions side by side.
+        self.assertIn("intl", self.sr.pricing()["complete"])
+
+    def test_missing_module_raises_problem_details(self) -> None:
+        with self.assertRaises(ShipRealError) as caught:
+            self.sr.module("does-not-exist")
+        self.assertEqual(caught.exception.status, 404)
+        self.assertIsNotNone(caught.exception.problem)
+
+    def test_batch_rejects_more_than_twenty(self) -> None:
+        with self.assertRaises(ValueError):
+            self.sr.batch([{"path": "/modules"}] * 21)
+
+
+if __name__ == "__main__":
+    unittest.main()