luranta 0.1.0__tar.gz

luranta-0.1.0/LICENSE

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

luranta-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: luranta
+Version: 0.1.0
+Summary: Official Python SDK for the Luranta API.
+Project-URL: Documentation, https://docs.luranta.com
+Project-URL: Source, https://github.com/luranta/sdk-python
+Author-email: Luranta <support@luranta.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.10
+Requires-Dist: pydantic-core==2.46.4
+Requires-Dist: pydantic==2.13.4
+Requires-Dist: typing-extensions==4.16.0
+Description-Content-Type: text/markdown
+
+# `luranta`
+
+Official Python SDK for Luranta's preview API, published as `luranta`.
+
+```python
+from luranta import Luranta
+
+luranta = Luranta(api_key="lur_...")
+
+for job in luranta.jobs.iterate({"roles": ["software-engineering"]}):
+    print(job.title)
+```
+
+`jobs`, `companies`, `tools`, and `locations` expose `list`, `retrieve` where
+applicable, cursor iterators, and `with_raw_response` methods. Versioned role
+and industry taxonomies are available through `luranta.taxonomies.roles` and
+`luranta.taxonomies.industries`; use their `current()` and `get(version)`
+methods. Raw responses include request IDs and Luranta billing headers.
+
+Taxonomy values, tools, and locations are evolving resources. Languages are
+accepted as canonical BCP 47 strings (for example `en-GB` or `zh-Hans`) rather
+than a generated enum.
+
+Only HTTP `408`, `429`, `500`, `502`, `503`, and `504` responses carrying
+valid RFC 9457 Problem Details with `retryable: true` and no billing evidence
+are retried. `Retry-After` is honored. Network failures are ambiguous and
+immediately raise `TransportError`. Cursor iterators stop on malformed or
+repeated cursors rather than risk duplicate billable reads.
+
+## Generation
+
+`src/luranta_generated` contains disposable models generated from the canonical
+`../../apps/api/openapi/openapi.json` using OpenAPI Generator engine 7.24.0
+through the exact 2.40.1 CLI wrapper. Generated HTTP code is intentionally
+excluded so the safe runtime above is the only transport. A deterministic
+response-only transform widens schema enums to strings while retaining their
+known values as metadata, so a new server enum does not break an older SDK.
+
+```sh
+bun run generate
+bun run generate:check
+```
+
+Luranta API keys belong only in trusted server-side environments. Never expose
+one in browser or mobile application code.
+
+The preview package supports the exact tested Python 3.10 through 3.14
+maintenance lines.
+
+The public source repository is [luranta/sdk-python](https://github.com/luranta/sdk-python).
+Releases use PyPI Trusted Publishing with attestations.

luranta-0.1.0/README.md

@@ -0,0 +1,51 @@
+# `luranta`
+
+Official Python SDK for Luranta's preview API, published as `luranta`.
+
+```python
+from luranta import Luranta
+
+luranta = Luranta(api_key="lur_...")
+
+for job in luranta.jobs.iterate({"roles": ["software-engineering"]}):
+    print(job.title)
+```
+
+`jobs`, `companies`, `tools`, and `locations` expose `list`, `retrieve` where
+applicable, cursor iterators, and `with_raw_response` methods. Versioned role
+and industry taxonomies are available through `luranta.taxonomies.roles` and
+`luranta.taxonomies.industries`; use their `current()` and `get(version)`
+methods. Raw responses include request IDs and Luranta billing headers.
+
+Taxonomy values, tools, and locations are evolving resources. Languages are
+accepted as canonical BCP 47 strings (for example `en-GB` or `zh-Hans`) rather
+than a generated enum.
+
+Only HTTP `408`, `429`, `500`, `502`, `503`, and `504` responses carrying
+valid RFC 9457 Problem Details with `retryable: true` and no billing evidence
+are retried. `Retry-After` is honored. Network failures are ambiguous and
+immediately raise `TransportError`. Cursor iterators stop on malformed or
+repeated cursors rather than risk duplicate billable reads.
+
+## Generation
+
+`src/luranta_generated` contains disposable models generated from the canonical
+`../../apps/api/openapi/openapi.json` using OpenAPI Generator engine 7.24.0
+through the exact 2.40.1 CLI wrapper. Generated HTTP code is intentionally
+excluded so the safe runtime above is the only transport. A deterministic
+response-only transform widens schema enums to strings while retaining their
+known values as metadata, so a new server enum does not break an older SDK.
+
+```sh
+bun run generate
+bun run generate:check
+```
+
+Luranta API keys belong only in trusted server-side environments. Never expose
+one in browser or mobile application code.
+
+The preview package supports the exact tested Python 3.10 through 3.14
+maintenance lines.
+
+The public source repository is [luranta/sdk-python](https://github.com/luranta/sdk-python).
+Releases use PyPI Trusted Publishing with attestations.

luranta-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling==1.31.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "luranta"
+version = "0.1.0"
+description = "Official Python SDK for the Luranta API."
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "MIT"
+authors = [{ name = "Luranta", email = "support@luranta.com" }]
+dependencies = ["pydantic==2.13.4", "pydantic-core==2.46.4", "typing-extensions==4.16.0"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "License :: OSI Approved :: MIT License",
+  "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",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://docs.luranta.com"
+Source = "https://github.com/luranta/sdk-python"
+
+[tool.luranta]
+release-enabled = true
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/LICENSE", "/README.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/luranta", "src/luranta_generated"]

luranta-0.1.0/src/luranta/__init__.py

@@ -0,0 +1,66 @@
+from luranta_generated.models.company import Company
+from luranta_generated.models.company_list import CompanyList
+from luranta_generated.models.company_list_data_inner import (
+    CompanyListDataInner as CompanySummary,
+)
+from luranta_generated.models.job import Job
+from luranta_generated.models.job_list import JobList
+from luranta_generated.models.job_list_data_inner import JobListDataInner as JobSummary
+from luranta_generated.models.location import Location
+from luranta_generated.models.location_list import LocationList
+from luranta_generated.models.location_list_data_inner import (
+    LocationListDataInner as LocationSummary,
+)
+from luranta_generated.models.problem_details import ProblemDetails
+from luranta_generated.models.taxonomy_snapshot import TaxonomySnapshot
+from luranta_generated.models.taxonomy_snapshot_entries_inner import (
+    TaxonomySnapshotEntriesInner as TaxonomyEntry,
+)
+from luranta_generated.models.tool import Tool
+from luranta_generated.models.tool_list import ToolList
+from luranta_generated.models.tool_list_data_inner import ToolListDataInner as ToolSummary
+
+from ._client import (
+    CatalogueListParams,
+    LocationsRawResource,
+    LocationsResource,
+    Luranta,
+    TaxonomiesResource,
+    TaxonomyResource,
+    ToolsRawResource,
+    ToolsResource,
+)
+from ._errors import LurantaProblemError, TransportError
+from ._transport import HttpResponse, QueryParams, QueryValue, RawResponse
+
+__all__ = [
+    "Company",
+    "CompanyList",
+    "CompanySummary",
+    "CatalogueListParams",
+    "HttpResponse",
+    "Job",
+    "JobList",
+    "JobSummary",
+    "Location",
+    "LocationList",
+    "LocationSummary",
+    "LocationsRawResource",
+    "LocationsResource",
+    "Luranta",
+    "LurantaProblemError",
+    "ProblemDetails",
+    "QueryParams",
+    "QueryValue",
+    "RawResponse",
+    "TaxonomiesResource",
+    "TaxonomyEntry",
+    "TaxonomyResource",
+    "TaxonomySnapshot",
+    "Tool",
+    "ToolList",
+    "ToolSummary",
+    "ToolsRawResource",
+    "ToolsResource",
+    "TransportError",
+]

luranta-0.1.0/src/luranta/_client.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Final
+from urllib.parse import quote
+from typing_extensions import NotRequired, Required, TypedDict
+
+from luranta_generated.models.company import Company
+from luranta_generated.models.company_list import CompanyList
+from luranta_generated.models.company_list_data_inner import CompanyListDataInner
+from luranta_generated.models.job import Job
+from luranta_generated.models.job_list import JobList
+from luranta_generated.models.job_list_data_inner import JobListDataInner
+from luranta_generated.models.location import Location
+from luranta_generated.models.location_list import LocationList
+from luranta_generated.models.location_list_data_inner import LocationListDataInner
+from luranta_generated.models.taxonomy_snapshot import TaxonomySnapshot
+from luranta_generated.models.tool import Tool
+from luranta_generated.models.tool_list import ToolList
+from luranta_generated.models.tool_list_data_inner import ToolListDataInner
+
+from ._transport import (
+    ClientTransport,
+    QueryParams,
+    RawResponse,
+    Transport,
+)
+
+DEFAULT_BASE_URL: Final = "https://api.luranta.com"
+
+
+class CatalogueListParams(TypedDict):
+    query: Required[str]
+    cursor: NotRequired[str]
+    limit: NotRequired[int]
+
+
+class Luranta:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        _transport: Transport | None = None,
+    ) -> None:
+        transport = ClientTransport(
+            api_key=api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            transport=_transport,
+        )
+        self.jobs = JobsResource(transport)
+        self.companies = CompaniesResource(transport)
+        self.taxonomies = TaxonomiesResource(transport)
+        self.tools = ToolsResource(transport)
+        self.locations = LocationsResource(transport)
+
+
+class JobsResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+        self.with_raw_response = JobsRawResource(transport)
+
+    def list(self, params: QueryParams | None = None) -> JobList:
+        return self._transport.request("/v0/jobs", JobList, params)
+
+    def retrieve(self, job_id: str) -> Job:
+        return self._transport.request(
+            f"/v0/jobs/{quote(job_id, safe='')}",
+            Job,
+        )
+
+    def iterate(self, params: QueryParams | None = None) -> Iterator[JobListDataInner]:
+        original = dict(params or {})
+        current = dict(original)
+        seen_cursors = _initial_cursors(original)
+        while True:
+            page = self.list(current)
+            yield from page.data
+            cursor = _advance_cursor(page.has_more, page.next_cursor, seen_cursors)
+            if cursor is None:
+                return
+            current = {**original, "cursor": cursor}
+
+
+class JobsRawResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+
+    def list(self, params: QueryParams | None = None) -> RawResponse[JobList]:
+        return self._transport.request_raw("/v0/jobs", JobList, params)
+
+    def retrieve(self, job_id: str) -> RawResponse[Job]:
+        return self._transport.request_raw(
+            f"/v0/jobs/{quote(job_id, safe='')}",
+            Job,
+        )
+
+
+class CompaniesResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+        self.with_raw_response = CompaniesRawResource(transport)
+
+    def list(self, params: QueryParams | None = None) -> CompanyList:
+        return self._transport.request("/v0/companies", CompanyList, params)
+
+    def retrieve(self, company_id: str) -> Company:
+        return self._transport.request(
+            f"/v0/companies/{quote(company_id, safe='')}",
+            Company,
+        )
+
+    def iterate(
+        self,
+        params: QueryParams | None = None,
+    ) -> Iterator[CompanyListDataInner]:
+        original = dict(params or {})
+        current = dict(original)
+        seen_cursors = _initial_cursors(original)
+        while True:
+            page = self.list(current)
+            yield from page.data
+            cursor = _advance_cursor(page.has_more, page.next_cursor, seen_cursors)
+            if cursor is None:
+                return
+            current = {**original, "cursor": cursor}
+
+
+class CompaniesRawResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+
+    def list(self, params: QueryParams | None = None) -> RawResponse[CompanyList]:
+        return self._transport.request_raw("/v0/companies", CompanyList, params)
+
+    def retrieve(self, company_id: str) -> RawResponse[Company]:
+        return self._transport.request_raw(
+            f"/v0/companies/{quote(company_id, safe='')}",
+            Company,
+        )
+
+
+class TaxonomyResource:
+    def __init__(self, transport: ClientTransport, name: str) -> None:
+        self._transport = transport
+        self._path = f"/v0/taxonomies/{name}"
+
+    def current(self) -> TaxonomySnapshot:
+        return self._transport.request(self._path, TaxonomySnapshot)
+
+    def get(self, version: int | str) -> TaxonomySnapshot:
+        return self._transport.request(
+            f"{self._path}/{quote(str(version), safe='')}",
+            TaxonomySnapshot,
+        )
+
+
+class TaxonomiesResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self.roles = TaxonomyResource(transport, "roles")
+        self.industries = TaxonomyResource(transport, "industries")
+
+
+class ToolsResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+        self.with_raw_response = ToolsRawResource(transport)
+
+    def list(self, params: CatalogueListParams) -> ToolList:
+        return self._transport.request("/v0/tools", ToolList, params)
+
+    def retrieve(self, code: str) -> Tool:
+        return self._transport.request(
+            f"/v0/tools/{quote(code, safe='')}",
+            Tool,
+        )
+
+    def iterate(self, params: CatalogueListParams) -> Iterator[ToolListDataInner]:
+        original = dict(params)
+        current = dict(original)
+        seen_cursors = _initial_cursors(original)
+        while True:
+            page = self.list(current)
+            yield from page.data
+            cursor = _advance_cursor(page.has_more, page.next_cursor, seen_cursors)
+            if cursor is None:
+                return
+            current = {**original, "cursor": cursor}
+
+
+class ToolsRawResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+
+    def list(self, params: CatalogueListParams) -> RawResponse[ToolList]:
+        return self._transport.request_raw("/v0/tools", ToolList, params)
+
+    def retrieve(self, code: str) -> RawResponse[Tool]:
+        return self._transport.request_raw(
+            f"/v0/tools/{quote(code, safe='')}",
+            Tool,
+        )
+
+
+class LocationsResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+        self.with_raw_response = LocationsRawResource(transport)
+
+    def list(self, params: CatalogueListParams) -> LocationList:
+        return self._transport.request("/v0/locations", LocationList, params)
+
+    def retrieve(self, location_id: str) -> Location:
+        return self._transport.request(
+            f"/v0/locations/{quote(location_id, safe='')}",
+            Location,
+        )
+
+    def iterate(
+        self,
+        params: CatalogueListParams,
+    ) -> Iterator[LocationListDataInner]:
+        original = dict(params or {})
+        current = dict(original)
+        seen_cursors = _initial_cursors(original)
+        while True:
+            page = self.list(current)
+            yield from page.data
+            cursor = _advance_cursor(page.has_more, page.next_cursor, seen_cursors)
+            if cursor is None:
+                return
+            current = {**original, "cursor": cursor}
+
+
+class LocationsRawResource:
+    def __init__(self, transport: ClientTransport) -> None:
+        self._transport = transport
+
+    def list(self, params: CatalogueListParams) -> RawResponse[LocationList]:
+        return self._transport.request_raw("/v0/locations", LocationList, params)
+
+    def retrieve(self, location_id: str) -> RawResponse[Location]:
+        return self._transport.request_raw(
+            f"/v0/locations/{quote(location_id, safe='')}",
+            Location,
+        )
+
+
+def _initial_cursors(params: QueryParams) -> set[str]:
+    cursor = params.get("cursor")
+    return {cursor} if isinstance(cursor, str) else set()
+
+
+def _advance_cursor(
+    has_more: bool,
+    next_cursor: str | None,
+    seen_cursors: set[str],
+) -> str | None:
+    if not has_more:
+        return None
+
+    from ._errors import TransportError
+
+    if next_cursor is None:
+        raise TransportError(
+            "Luranta returned has_more without the next cursor required to "
+            "continue pagination."
+        )
+    if next_cursor in seen_cursors:
+        raise TransportError(
+            "Luranta returned a repeated cursor; pagination stopped to prevent "
+            "duplicate billable reads."
+        )
+    seen_cursors.add(next_cursor)
+    return next_cursor

luranta-0.1.0/src/luranta/_errors.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from luranta_generated.models.problem_details import ProblemDetails
+
+from ._transport import HttpResponse
+
+
+class LurantaProblemError(Exception):
+    """An HTTP error represented by Luranta RFC 9457 Problem Details."""
+
+    def __init__(
+        self,
+        problem: ProblemDetails | None,
+        response: HttpResponse,
+    ) -> None:
+        self.problem = problem
+        self.response = response
+        self.status = response.status_code
+        self.code = problem.code if problem is not None else "unexpected_error_response"
+        self.request_id = (
+            str(problem.request_id)
+            if problem is not None
+            else response.header("X-Request-Id")
+        )
+        self.retryable = problem.retryable if problem is not None else False
+        detail = (
+            problem.detail
+            if problem is not None
+            else f"Luranta returned HTTP {response.status_code} without valid Problem Details."
+        )
+        super().__init__(detail)
+
+
+class TransportError(Exception):
+    """A request failure without a trustworthy, parseable HTTP response."""
+