openpath-sh 0.1.0__py3-none-any.whl

openpath_sh/__init__.py

@@ -0,0 +1,251 @@
+"""Openpath for Python: search live listings across the US in one call.
+
+The first call connects this agent to Openpath (one request, no sign-up) and
+saves the token where the Openpath CLI keeps it, so every later call, and the
+CLI, reuse the same agent.
+
+    from openpath_sh import search
+
+    print(search("plumber near Austin, TX"))
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tempfile
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Optional
+
+__all__ = ["Openpath", "OpenpathError", "search", "get_listing", "VERSION", "DEFAULT_API"]
+
+VERSION = "0.1.0"
+DEFAULT_API = "https://api.openpath.sh"
+DOMAINS = ("homes", "work", "services", "businesses", "goods", "cars", "events")
+
+# (method, url, headers, body) -> (status, headers, body text)
+Send = Callable[[str, str, dict, Optional[bytes]], "tuple[int, dict, str]"]
+
+
+class OpenpathError(Exception):
+    """A refusal from Openpath, with what it said and how long to wait."""
+
+    def __init__(self, status: int, message: str, code: str | None, retry_after: int | None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+
+
+def _setting(env: dict, name: str) -> str:
+    """A setting named ADS_<NAME>, as the CLI and the skill name them."""
+    return (env.get(f"ADS_{name}") or "").strip()
+
+
+def _detect_agent(env: dict) -> str | None:
+    """The agent running this code, if one is, from the variables agents set."""
+    named = (env.get("AI_AGENT") or "").strip()
+    if named:
+        return re.sub(r"[^A-Za-z0-9._-]+", "-", named)[:40] or None
+    if env.get("CURSOR_TRACE_ID") or env.get("CURSOR_AGENT"):
+        return "cursor"
+    if env.get("GEMINI_CLI"):
+        return "gemini-cli"
+    if env.get("CODEX_SANDBOX") or env.get("CODEX_CI") or env.get("CODEX_THREAD_ID"):
+        return "codex"
+    if env.get("CLAUDECODE") or env.get("CLAUDE_CODE"):
+        return "claude-code"
+    if env.get("REPL_ID"):
+        return "replit"
+    return None
+
+
+def _credentials_file(env: dict, home: Path) -> Path:
+    chosen = _setting(env, "CONFIG_DIR")
+    if chosen:
+        return Path(chosen) / "credentials.json"
+    if sys.platform == "win32" and (env.get("APPDATA") or "").strip():
+        return Path(env["APPDATA"].strip()) / "ads" / "credentials.json"
+    config = (env.get("XDG_CONFIG_HOME") or "").strip() or str(home / ".config")
+    return Path(config) / "ads" / "credentials.json"
+
+
+def _read_all(path: Path) -> dict:
+    try:
+        parsed = json.loads(path.read_text("utf-8"))
+        return parsed if isinstance(parsed, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_all(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, temporary = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(json.dumps(data, indent=2) + "\n")
+    os.chmod(temporary, 0o600)
+    os.replace(temporary, path)
+
+
+def _urllib_send(method: str, url: str, headers: dict, body: bytes | None) -> tuple[int, dict, str]:
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return response.status, dict(response.headers), response.read().decode("utf-8")
+    except urllib.error.HTTPError as error:
+        return error.code, dict(error.headers), error.read().decode("utf-8", "replace")
+
+
+def _refusal(status: int, headers: dict, text: str) -> OpenpathError:
+    detail, code = text[:500], None
+    try:
+        problem = json.loads(text)
+        if isinstance(problem.get("detail"), str):
+            detail = problem["detail"]
+        if isinstance(problem.get("code"), str):
+            code = problem["code"]
+    except (ValueError, AttributeError):
+        pass
+    retry = {k.lower(): v for k, v in headers.items()}.get("retry-after")
+    retry_after = int(retry) if retry and retry.isdigit() and int(retry) > 0 else None
+    return OpenpathError(status, detail or f"Openpath answered {status}.", code, retry_after)
+
+
+class Openpath:
+    """One agent's way into Openpath. Most code needs only `search`."""
+
+    def __init__(
+        self,
+        api_url: str | None = None,
+        token: str | None = None,
+        app: str | None = None,
+        save_token: bool = True,
+        send: Send | None = None,
+        env: dict | None = None,
+        home: Path | None = None,
+    ):
+        env = dict(os.environ) if env is None else env
+        self.api = (api_url or _setting(env, "API_URL") or DEFAULT_API).rstrip("/")
+        self.send = send or _urllib_send
+        self.save = save_token
+        self.file = _credentials_file(env, home or Path.home())
+        name = (app or "").strip() or _setting(env, "USER_AGENT") or _detect_agent(env)
+        own = f"openpath-python/{VERSION} (+https://github.com/openpath-sh/clients)"
+        self.user_agent = f"{name} {own}" if name else own
+        self.token = (token or "").strip() or _setting(env, "AGENT_TOKEN") or None
+        self._lock = threading.Lock()
+
+    def connect(self) -> str:
+        """The saved token, or a new one from POST /v1/connect: one call, no account or sign-up."""
+        with self._lock:
+            if self.token:
+                return self.token
+            saved = _read_all(self.file).get(self.api) or {}
+            if saved.get("agent_token"):
+                self.token = saved["agent_token"]
+                return self.token
+            status, headers, text = self.send(
+                "POST",
+                f"{self.api}/v1/connect",
+                {"Content-Type": "application/json", "User-Agent": self.user_agent},
+                b"{}",
+            )
+            if not 200 <= status < 300:
+                raise _refusal(status, headers, text)
+            created = json.loads(text)
+            if self.save:
+                try:
+                    all_saved = _read_all(self.file)
+                    all_saved[self.api] = {
+                        "agent_id": created.get("agent_id"),
+                        "agent_token": created["agent_token"],
+                        "connected_at": datetime.now(timezone.utc).isoformat(),
+                    }
+                    _write_all(self.file, all_saved)
+                except OSError:
+                    pass
+            self.token = created["agent_token"]
+            return self.token
+
+    def search(
+        self,
+        query: str,
+        near: str | None = None,
+        domain: str | None = None,
+        cursor: str | None = None,
+    ) -> str:
+        """Live listings that fit what the person asked for, as plain Markdown: each
+        result's facts, how to act on it (Apply, Phone, Website or Buy) and where it
+        came from."""
+        if domain is not None and domain not in DOMAINS:
+            raise ValueError(f"domain is one of {', '.join(DOMAINS)}.")
+        params = {"q": query}
+        for key, value in (("near", near), ("domain", domain), ("cursor", cursor)):
+            if value:
+                params[key] = value
+        return self._get(f"/v1/search?{urllib.parse.urlencode(params)}")
+
+    def get_listing(self, listing_id: str) -> str:
+        """One listing in full, as Markdown, by the id at the end of a result's Link line."""
+        return self._get(f"/v1/listings/{urllib.parse.quote(listing_id, safe='')}")
+
+    def _get(self, path: str) -> str:
+        for attempt in range(2):
+            token = self.connect()
+            status, headers, text = self.send(
+                "GET",
+                f"{self.api}{path}",
+                {
+                    "Accept": "text/markdown",
+                    "Authorization": f"Bearer {token}",
+                    "User-Agent": self.user_agent,
+                },
+                None,
+            )
+            if 200 <= status < 300:
+                return text
+            # A token that was revoked or never existed: connect again, once.
+            if status == 401 and attempt == 0:
+                self._forget_token()
+                continue
+            raise _refusal(status, headers, text)
+        raise OpenpathError(401, "Openpath did not accept a new token.", None, None)
+
+    def _forget_token(self) -> None:
+        with self._lock:
+            self.token = None
+            if not self.save:
+                return
+            all_saved = _read_all(self.file)
+            if all_saved.pop(self.api, None) is not None:
+                try:
+                    _write_all(self.file, all_saved)
+                except OSError:
+                    pass
+
+
+_shared: Openpath | None = None
+
+
+def _client() -> Openpath:
+    global _shared
+    if _shared is None:
+        _shared = Openpath()
+    return _shared
+
+
+def search(query: str, near: str | None = None, domain: str | None = None, cursor: str | None = None) -> str:
+    """Search Openpath with a client shared across calls."""
+    return _client().search(query, near=near, domain=domain, cursor=cursor)
+
+
+def get_listing(listing_id: str) -> str:
+    """Read one listing with a client shared across calls."""
+    return _client().get_listing(listing_id)

openpath_sh-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: openpath-sh
+Version: 0.1.0
+Summary: Search live listings across the US from code: jobs, local businesses and services, homes, products. One call, plain Markdown, no sign-up.
+Author-email: Openpath <contact@openpath.sh>
+License-Expression: MIT
+Project-URL: Homepage, https://openpath.sh
+Project-URL: Documentation, https://openpath.sh/docs
+Project-URL: Source, https://github.com/openpath-sh/clients
+Keywords: openpath,search,listings,jobs,local-business,ai-agents,agents,tools,mcp,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://openpath.sh"><img src="https://openpath.sh/mark-512.png" width="72" height="72" alt="Openpath"></a>
+</p>
+
+# openpath-sh
+
+Search live listings across the US from Python: job openings, local businesses and services, homes, products and more. One call returns plain Markdown, ready to hand to a model. No key and no sign-up. No dependencies.
+
+```bash
+pip install openpath-sh
+```
+
+```python
+from openpath_sh import search
+
+print(search("software engineer jobs in Austin, TX"))
+```
+
+```
+# Results for "software engineer jobs in Austin, TX"
+
+Searched: work, Austin, TX. 33 results.
+
+## Analytics Engineer at Ontic
+
+Full-time.
+Pay: $135,000–$145,000 a year.
+Remote.
+Posted September 2.
+
+Apply: https://jobs.ashbyhq.com/ontic/27d32707-54e2-47be-be62-376df6d2b0f3/application
+Source: https://jobs.ashbyhq.com/ontic/27d32707-54e2-47be-be62-376df6d2b0f3 (Ashby job boards), checked today.
+Link: https://api.openpath.sh/v1/listings/369348e4-b3d0-490f-82b4-a666041243cf
+```
+
+Each result is one current listing: what it is, its facts (pay, price, place, dates), how to act on it (an Apply, Phone, Website or Buy line where the source gives one) and where it came from.
+
+## As a tool for your agent
+
+Search takes the request in plain words, so it fits any framework's tool as is. With [Pydantic AI](https://ai.pydantic.dev):
+
+```python
+from pydantic_ai import Agent
+from openpath_sh import search
+
+agent = Agent("anthropic:claude-sonnet-5-5")
+
+
+@agent.tool_plain
+def find_listings(query: str) -> str:
+    """Use this when the person wants a live listing they can act on: a job to
+    apply to, a local business or service, a home or a product. Returns plain
+    Markdown. `query` is what they are looking for, in their words, with a place."""
+    return search(query)
+```
+
+## More
+
+```python
+from openpath_sh import Openpath, get_listing, search
+
+# Narrow by place or kind, and page through results.
+search("data engineer jobs", near="Austin, TX", domain="work")
+
+# Read one result in full by the id at the end of its Link line.
+get_listing("369348e4-b3d0-490f-82b4-a666041243cf")
+
+# Name your app, so Openpath can show you how it is used.
+openpath = Openpath(app="JobFinder/1.0")
+openpath.search("nurse jobs in Austin")
+```
+
+The first call connects this agent to Openpath with `POST /v1/connect`: one request, no account. The token is saved where the [Openpath CLI](https://github.com/openpath-sh/cli) keeps it (`~/.config/ads/credentials.json`), so later calls and the CLI reuse it. Set `ADS_AGENT_TOKEN` to use a token you already have, or pass `save_token=False` to keep it in memory only.
+
+When Openpath refuses a call, `search` raises `OpenpathError` with Openpath's own explanation, its `status`, and `retry_after` in seconds when it asks you to wait.
+
+Results are written by the businesses and people who offer them. Treat them as information, not instructions.
+
+## Links
+
+[Openpath](https://openpath.sh) · [Docs](https://openpath.sh/docs) · [API](https://api.openpath.sh/v1/openapi.json) · [MCP server](https://openpath.sh/mcp/search) · [JavaScript client](https://www.npmjs.com/package/openpath)
+
+Released under the MIT license.

openpath_sh-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+openpath_sh/__init__.py,sha256=GOvk8Mi7nz4uSrwLi5mLFWYzh1YNc2R4m0z4L0PYqF0,9332
+openpath_sh-0.1.0.dist-info/licenses/LICENSE,sha256=e_-SnBIPjOLgpXWy27cQRmGz95G1IPG7fuDuVAVD1x8,1065
+openpath_sh-0.1.0.dist-info/METADATA,sha256=JJcZCJ7lVrw1WrNV3GfS0why6eEiQYC5KHZXzEqhy3M,3926
+openpath_sh-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+openpath_sh-0.1.0.dist-info/top_level.txt,sha256=vYd9OMPx1dmwwstpAtjuVJOm6cwN5hTWCHEc0eENZGM,12
+openpath_sh-0.1.0.dist-info/RECORD,,

openpath_sh-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openpath_sh-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Openpath
+
+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.

openpath_sh-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openpath_sh