discolike 0.1.0__tar.gz

discolike-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

discolike-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: discolike
+Version: 0.1.0
+Summary: Official Python SDK for the DiscoLike API
+Project-URL: Homepage, https://www.discolike.com
+Project-URL: Documentation, https://docs.discolike.com
+Project-URL: Repository, https://github.com/Discolike/discolike-python
+Author-email: DiscoLike <support@discolike.com>
+License-Expression: MIT
+Keywords: business-data,discolike,enrichment,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: cli
+Requires-Dist: discolike-cli>=0.1.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# discolike
+
+Official Python SDK for the [DiscoLike API](https://www.discolike.com) — discover lookalike companies, enrich domain lists, match company names to domains, and find contacts, from typed Python.
+
+For the terminal, see [`discolike-cli`](https://pypi.org/project/discolike-cli/) (`pip install discolike-cli` or `uvx --from discolike-cli discolike`).
+
+## Installation
+
+```bash
+pip install discolike
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+```bash
+export DISCOLIKE_API_KEY="dl_..."
+```
+
+Create a key at [app.discolike.com/account/management/keys](https://app.discolike.com/account/management/keys). You can also pass `api_key=...` explicitly to `Discolike()`.
+
+## Quickstart
+
+```python
+from discolike import Discolike
+
+client = Discolike()
+
+companies = client.discover(
+    icp_text="Cybersecurity for SMBs, managed IT services, endpoint protection",
+    country=["US"],
+    max_records=25,
+)
+for company in companies:
+    print(company.domain, company.name, company.similarity)
+```
+
+The client is a context manager if you want deterministic cleanup:
+
+```python
+with Discolike() as client:
+    ...
+```
+
+### Async
+
+Every resource has an async twin on `AsyncDiscolike`:
+
+```python
+import asyncio
+from discolike import AsyncDiscolike
+
+async def main() -> None:
+    async with AsyncDiscolike() as client:
+        companies = await client.discover(icp_text="B2B SaaS for logistics", max_records=10)
+        print([c.domain for c in companies])
+
+asyncio.run(main())
+```
+
+### Long-running jobs
+
+Bulk operations (`match.bulk`, `segment`, `validate_icp`, `contacts.bulk_match`) return a `Job` handle instead of blocking:
+
+```python
+job = client.segment(domains=["stripe.com", "adyen.com", "checkout.com"])
+result = job.wait()
+```
+
+`Job.status()` polls without blocking, `Job.cancel()` aborts, and `wait()` raises `JobFailedError` / `JobTimeoutError` on failure.
+
+## Links
+
+- **API documentation**: [docs.discolike.com](https://docs.discolike.com)
+- **Source**: [github.com/Discolike/discolike-python](https://github.com/Discolike/discolike-python)
+
+## License
+
+[MIT](https://github.com/Discolike/discolike-python/blob/main/LICENSE)

discolike-0.1.0/README.md

@@ -0,0 +1,80 @@
+# discolike
+
+Official Python SDK for the [DiscoLike API](https://www.discolike.com) — discover lookalike companies, enrich domain lists, match company names to domains, and find contacts, from typed Python.
+
+For the terminal, see [`discolike-cli`](https://pypi.org/project/discolike-cli/) (`pip install discolike-cli` or `uvx --from discolike-cli discolike`).
+
+## Installation
+
+```bash
+pip install discolike
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+```bash
+export DISCOLIKE_API_KEY="dl_..."
+```
+
+Create a key at [app.discolike.com/account/management/keys](https://app.discolike.com/account/management/keys). You can also pass `api_key=...` explicitly to `Discolike()`.
+
+## Quickstart
+
+```python
+from discolike import Discolike
+
+client = Discolike()
+
+companies = client.discover(
+    icp_text="Cybersecurity for SMBs, managed IT services, endpoint protection",
+    country=["US"],
+    max_records=25,
+)
+for company in companies:
+    print(company.domain, company.name, company.similarity)
+```
+
+The client is a context manager if you want deterministic cleanup:
+
+```python
+with Discolike() as client:
+    ...
+```
+
+### Async
+
+Every resource has an async twin on `AsyncDiscolike`:
+
+```python
+import asyncio
+from discolike import AsyncDiscolike
+
+async def main() -> None:
+    async with AsyncDiscolike() as client:
+        companies = await client.discover(icp_text="B2B SaaS for logistics", max_records=10)
+        print([c.domain for c in companies])
+
+asyncio.run(main())
+```
+
+### Long-running jobs
+
+Bulk operations (`match.bulk`, `segment`, `validate_icp`, `contacts.bulk_match`) return a `Job` handle instead of blocking:
+
+```python
+job = client.segment(domains=["stripe.com", "adyen.com", "checkout.com"])
+result = job.wait()
+```
+
+`Job.status()` polls without blocking, `Job.cancel()` aborts, and `wait()` raises `JobFailedError` / `JobTimeoutError` on failure.
+
+## Links
+
+- **API documentation**: [docs.discolike.com](https://docs.discolike.com)
+- **Source**: [github.com/Discolike/discolike-python](https://github.com/Discolike/discolike-python)
+
+## License
+
+[MIT](https://github.com/Discolike/discolike-python/blob/main/LICENSE)

discolike-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "discolike"
+dynamic = ["version"]
+description = "Official Python SDK for the DiscoLike API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "DiscoLike", email = "support@discolike.com" }]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.7",
+]
+keywords = ["discolike", "sdk", "business-data", "enrichment"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.optional-dependencies]
+cli = ["discolike-cli>=0.1.0"]
+
+[project.urls]
+Homepage = "https://www.discolike.com"
+Documentation = "https://docs.discolike.com"
+Repository = "https://github.com/Discolike/discolike-python"
+
+[tool.uv.sources]
+discolike-cli = { workspace = true }
+
+[tool.hatch.version]
+path = "src/discolike/_version.py"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.8",
+  "ty",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

discolike-0.1.0/src/discolike/__init__.py

@@ -0,0 +1,41 @@
+from discolike._client import AsyncDiscolike
+from discolike._client import Discolike
+from discolike._exceptions import APIConnectionError
+from discolike._exceptions import AuthenticationError
+from discolike._exceptions import DiscolikeError
+from discolike._exceptions import JobFailedError
+from discolike._exceptions import JobTimeoutError
+from discolike._exceptions import NotFoundError
+from discolike._exceptions import PlanAccessError
+from discolike._exceptions import RateLimitError
+from discolike._exceptions import ServerError
+from discolike._exceptions import ValidationError
+from discolike._jobs import AsyncJob
+from discolike._jobs import Job
+from discolike._jobs import JobStatus
+from discolike._models import DiscolikeModel
+from discolike._version import __version__
+from discolike.resources.discovery import Company
+from discolike.resources.discovery import Count
+
+__all__ = [
+    "APIConnectionError",
+    "AsyncDiscolike",
+    "AsyncJob",
+    "AuthenticationError",
+    "Company",
+    "Count",
+    "Discolike",
+    "DiscolikeError",
+    "DiscolikeModel",
+    "Job",
+    "JobFailedError",
+    "JobStatus",
+    "JobTimeoutError",
+    "NotFoundError",
+    "PlanAccessError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "__version__",
+]

discolike-0.1.0/src/discolike/_client.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from discolike._config import DEFAULT_BASE_URL
+from discolike._config import resolve_api_key
+from discolike._jobs import AsyncJob
+from discolike._jobs import Job
+from discolike._transport import AsyncTransport
+from discolike._transport import Transport
+from discolike.resources.account import AccountResource
+from discolike.resources.account import AsyncAccountResource
+from discolike.resources.companies import AsyncCompaniesResource
+from discolike.resources.companies import CompaniesResource
+from discolike.resources.contacts import AsyncContactsResource
+from discolike.resources.contacts import ContactsResource
+from discolike.resources.discogen import AsyncDiscogenResource
+from discolike.resources.discogen import AsyncValidateResource
+from discolike.resources.discogen import DiscogenResource
+from discolike.resources.discogen import ValidateResource
+from discolike.resources.discovery import AsyncDiscoveryResource
+from discolike.resources.discovery import Company
+from discolike.resources.discovery import Count
+from discolike.resources.discovery import DiscoveryResource
+from discolike.resources.enrich import AppendResult
+from discolike.resources.enrich import AsyncEnrichResource
+from discolike.resources.enrich import EnrichResource
+from discolike.resources.match import AsyncMatchResource
+from discolike.resources.match import MatchResource
+from discolike.resources.queries import AsyncQueriesResource
+from discolike.resources.queries import QueriesResource
+
+DEFAULT_TIMEOUT_SECONDS = 60.0
+DEFAULT_MAX_RETRIES = 3
+
+
+class Discolike:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = Transport(
+            resolve_api_key(api_key),
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.account = AccountResource(self._transport)
+        self.companies = CompaniesResource(self._transport)
+        self.contacts = ContactsResource(self._transport)
+        self.match = MatchResource(self._transport)
+        self.discogen = DiscogenResource(self._transport)
+        self.queries = QueriesResource(self._transport)
+        self._discovery = DiscoveryResource(self._transport)
+        self._validate = ValidateResource(self._transport)
+        self._enrich = EnrichResource(self._transport)
+
+    def discover(self, **kwargs: Any) -> list[Company]:  # noqa: ANN401 -- forwards to DiscoveryResource.discover's typed signature
+        return self._discovery.discover(**kwargs)
+
+    def count(self, **kwargs: Any) -> Count:  # noqa: ANN401 -- forwards to DiscoveryResource.count's typed signature
+        return self._discovery.count(**kwargs)
+
+    def validate_icp(self, **kwargs: Any) -> Job:  # noqa: ANN401 -- forwards to ValidateResource.icp's typed signature
+        return self._validate.icp(**kwargs)
+
+    def append(self, **kwargs: Any) -> list[AppendResult] | bytes:  # noqa: ANN401 -- forwards to EnrichResource.append's typed signature
+        return self._enrich.append(**kwargs)
+
+    def segment(self, **kwargs: Any) -> Job:  # noqa: ANN401 -- forwards to EnrichResource.segment's typed signature
+        return self._enrich.segment(**kwargs)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Discolike:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncDiscolike:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(
+            resolve_api_key(api_key),
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.account = AsyncAccountResource(self._transport)
+        self.companies = AsyncCompaniesResource(self._transport)
+        self.contacts = AsyncContactsResource(self._transport)
+        self.match = AsyncMatchResource(self._transport)
+        self.discogen = AsyncDiscogenResource(self._transport)
+        self.queries = AsyncQueriesResource(self._transport)
+        self._discovery = AsyncDiscoveryResource(self._transport)
+        self._validate = AsyncValidateResource(self._transport)
+        self._enrich = AsyncEnrichResource(self._transport)
+
+    async def discover(self, **kwargs: Any) -> list[Company]:  # noqa: ANN401 -- forwards to AsyncDiscoveryResource.discover's typed signature
+        return await self._discovery.discover(**kwargs)
+
+    async def count(self, **kwargs: Any) -> Count:  # noqa: ANN401 -- forwards to AsyncDiscoveryResource.count's typed signature
+        return await self._discovery.count(**kwargs)
+
+    async def validate_icp(self, **kwargs: Any) -> AsyncJob:  # noqa: ANN401 -- forwards to AsyncValidateResource.icp's typed signature
+        return await self._validate.icp(**kwargs)
+
+    async def append(self, **kwargs: Any) -> list[AppendResult] | bytes:  # noqa: ANN401 -- forwards to AsyncEnrichResource.append's typed signature
+        return await self._enrich.append(**kwargs)
+
+    async def segment(self, **kwargs: Any) -> AsyncJob:  # noqa: ANN401 -- forwards to AsyncEnrichResource.segment's typed signature
+        return await self._enrich.segment(**kwargs)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncDiscolike:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()

discolike-0.1.0/src/discolike/_config.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from discolike._exceptions import AuthenticationError
+
+DEFAULT_BASE_URL = "https://api.discolike.com/v1"
+ENV_API_KEY = "DISCOLIKE_API_KEY"  # foxguard: ignore[py/no-hardcoded-secret]
+KEYS_URL = "https://app.discolike.com/account/management/keys"
+
+_NO_KEY_MESSAGE = (
+    "No API key found. Set the DISCOLIKE_API_KEY environment variable, pass api_key=..., "
+    f"or run `discolike auth login`. Create a key at {KEYS_URL}"
+)
+
+
+def config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "discolike" / "config.json"
+
+
+def load_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.is_file():
+        return {}
+    try:
+        loaded = json.loads(path.read_text())
+    except (ValueError, OSError):
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def save_config(config: dict[str, Any]) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as handle:
+        handle.write(json.dumps(config, indent=2) + "\n")
+    path.chmod(0o600)
+
+
+def delete_config() -> None:
+    config_path().unlink(missing_ok=True)
+
+
+def resolve_api_key(explicit: str | None = None) -> str:
+    if explicit:
+        return explicit
+    from_env = os.environ.get(ENV_API_KEY)
+    if from_env:
+        return from_env
+    from_file = load_config().get("api_key")
+    if from_file:
+        return str(from_file)
+    raise AuthenticationError(_NO_KEY_MESSAGE)

discolike-0.1.0/src/discolike/_exceptions.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+
+class DiscolikeError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: Any = None,  # noqa: ANN401 -- decoded JSON body, shape is server-defined
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+class AuthenticationError(DiscolikeError): ...
+
+
+class PlanAccessError(DiscolikeError): ...
+
+
+class ValidationError(DiscolikeError): ...
+
+
+class NotFoundError(DiscolikeError): ...
+
+
+class ServerError(DiscolikeError): ...
+
+
+class APIConnectionError(DiscolikeError): ...
+
+
+class JobFailedError(DiscolikeError): ...
+
+
+class JobTimeoutError(DiscolikeError): ...
+
+
+class RateLimitError(DiscolikeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: Any = None,  # noqa: ANN401 -- decoded JSON body, shape is server-defined
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, payload=payload)
+        self.retry_after = retry_after
+
+
+_STATUS_MAP: dict[int, type[DiscolikeError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: PlanAccessError,
+    403: PlanAccessError,
+    404: NotFoundError,
+    422: ValidationError,
+}
+
+
+def _extract_message(response: httpx.Response) -> tuple[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError:
+        return response.text[:500] or f"HTTP {response.status_code}", None
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    if isinstance(detail, str):
+        return detail, payload
+    if isinstance(detail, list):
+        parts = [
+            f"{'.'.join(str(x) for x in item.get('loc', []))}: {item.get('msg', '')}"
+            if isinstance(item, dict)
+            else str(item)
+            for item in detail
+        ]
+        return "; ".join(parts) or f"HTTP {response.status_code}", payload
+    return json.dumps(payload)[:500], payload
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    message, payload = _extract_message(response)
+    if response.status_code == 429:
+        header = response.headers.get("Retry-After")
+        retry_after = float(header) if header and header.replace(".", "", 1).isdigit() else None
+        raise RateLimitError(message, status_code=429, payload=payload, retry_after=retry_after)
+    exc_type = _STATUS_MAP.get(response.status_code, ServerError if response.status_code >= 500 else DiscolikeError)
+    raise exc_type(message, status_code=response.status_code, payload=payload)

discolike-0.1.0/src/discolike/_jobs.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from typing import Any
+
+import pydantic
+
+from discolike._exceptions import JobFailedError
+from discolike._exceptions import JobTimeoutError
+from discolike._models import DiscolikeModel
+from discolike._transport import AsyncTransport
+from discolike._transport import Transport
+
+TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
+FAMILY_DISCOGEN = "discogen"
+FAMILY_BULKMATCH = "bulkmatch"
+FAMILY_CONTACTMATCH = "contactmatch"
+FAMILY_SEGMENT = "segment"
+DEFAULT_WAIT_TIMEOUT_SECONDS = 900.0
+DEFAULT_POLL_INTERVAL_SECONDS = 5.0
+
+
+class JobStatus(DiscolikeModel):
+    status: str
+    progress: int | None = None
+    results: Any = None
+    result: Any = None
+    warnings: list[str] = pydantic.Field(default_factory=list)
+
+
+class Job:
+    def __init__(self, transport: Transport, *, task_family: str, task_id: str) -> None:
+        self._transport = transport
+        self.task_family = task_family
+        self.task_id = task_id
+
+    def status(self) -> JobStatus:
+        response = self._transport.request("GET", f"/{self.task_family}/status/{self.task_id}")
+        return JobStatus.model_validate(response.json())
+
+    def cancel(self) -> None:
+        self._transport.request("DELETE", f"/{self.task_family}/cancel/{self.task_id}")
+
+    def wait(
+        self,
+        *,
+        timeout: float = DEFAULT_WAIT_TIMEOUT_SECONDS,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+        on_poll: Callable[[JobStatus], None] | None = None,
+    ) -> JobStatus:
+        deadline = time.monotonic() + timeout
+        while True:
+            current = self.status()
+            if on_poll is not None:
+                on_poll(current)
+            if current.status == "failed":
+                raise JobFailedError(str(current.result or "task failed"), payload=current.to_dict())
+            if current.status in TERMINAL_STATUSES:
+                return current
+            if time.monotonic() >= deadline:
+                raise JobTimeoutError(f"Task {self.task_id} did not finish within {timeout:.0f}s")
+            time.sleep(poll_interval)
+
+
+class AsyncJob:
+    def __init__(self, transport: AsyncTransport, *, task_family: str, task_id: str) -> None:
+        self._transport = transport
+        self.task_family = task_family
+        self.task_id = task_id
+
+    async def status(self) -> JobStatus:
+        response = await self._transport.request("GET", f"/{self.task_family}/status/{self.task_id}")
+        return JobStatus.model_validate(response.json())
+
+    async def cancel(self) -> None:
+        await self._transport.request("DELETE", f"/{self.task_family}/cancel/{self.task_id}")
+
+    async def wait(
+        self,
+        *,
+        timeout: float = DEFAULT_WAIT_TIMEOUT_SECONDS,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+        on_poll: Callable[[JobStatus], None] | None = None,
+    ) -> JobStatus:
+        deadline = time.monotonic() + timeout
+        while True:
+            current = await self.status()
+            if on_poll is not None:
+                on_poll(current)
+            if current.status == "failed":
+                raise JobFailedError(str(current.result or "task failed"), payload=current.to_dict())
+            if current.status in TERMINAL_STATUSES:
+                return current
+            if time.monotonic() >= deadline:
+                raise JobTimeoutError(f"Task {self.task_id} did not finish within {timeout:.0f}s")
+            await asyncio.sleep(poll_interval)

discolike-0.1.0/src/discolike/_models.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pydantic
+
+
+class DiscolikeModel(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra="allow")
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json")