jobfeeds 0.1.0__tar.gz

jobfeeds-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e .[dev]
+      - name: Test
+        run: pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI Trusted Publishing (OIDC), no long-lived token
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

jobfeeds-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e .[dev]
+      - name: Test
+        run: pytest -q

jobfeeds-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.vscode/
+.idea/
+desktop.ini
+.DS_Store

jobfeeds-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to jobfeeds are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-07-04
+
+### Added
+
+- Six async adapters behind one interface: `Remotive`, `Arbeitnow`,
+  `Greenhouse`, `RemoteOK`, `WeWorkRemotely`, `HNWhoIsHiring`.
+- `Posting` pydantic model normalized across sources, with `posting_hash()`
+  for cross-source dedupe.
+- `fetch_all()` with per-source failure isolation (`SourceResult`).
+- Per-adapter configuration via constructor args: Greenhouse board tokens,
+  per-board cap and optional title pattern; Arbeitnow page count;
+  We Work Remotely category feeds; timeout and user agent everywhere.
+- `py.typed` marker; the package is fully typed.
+- Test suite with all HTTP traffic mocked (respx); no live calls in CI.

jobfeeds-0.1.0/LICENSE

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

jobfeeds-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: jobfeeds
+Version: 0.1.0
+Summary: One typed, async Python interface to six public job boards: Remotive, Arbeitnow, Greenhouse, RemoteOK, We Work Remotely, and Hacker News Who is hiring
+Project-URL: Homepage, https://github.com/n3ndor/jobfeeds
+Project-URL: Repository, https://github.com/n3ndor/jobfeeds
+Project-URL: Changelog, https://github.com/n3ndor/jobfeeds/blob/main/CHANGELOG.md
+Project-URL: Used in production by, https://jobradar.nagysolution.com
+Author-email: Nandor Nagy <n3ndor@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,async,greenhouse,hackernews,job-board,jobs,remoteok,remotive
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 📡 jobfeeds
+
+**One typed, async Python interface to six public job boards.**
+
+```
+pip install jobfeeds
+```
+
+![PyPI](https://img.shields.io/pypi/v/jobfeeds)
+![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-3776AB?logo=python&logoColor=white)
+![Tests](https://img.shields.io/github/actions/workflow/status/n3ndor/jobfeeds/test.yml?label=tests)
+![Typed](https://img.shields.io/badge/typing-py.typed-3ddc97)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+</div>
+
+---
+
+Fetching job postings should not require writing six API clients. jobfeeds
+gives you Remotive, Arbeitnow, Greenhouse boards, RemoteOK, We Work Remotely,
+and the Hacker News "Who is hiring" thread through one interface, normalized
+into one pydantic model, with failures isolated per source.
+
+Extracted from, and used in production by,
+[**JobRadar**](https://jobradar.nagysolution.com), a live job-market
+intelligence dashboard.
+
+## Quickstart
+
+```python
+import asyncio
+from jobfeeds import Remotive, Greenhouse, fetch_all
+
+async def main():
+    # One source
+    jobs = await Remotive().fetch()               # list[Posting]
+    print(jobs[0].company, jobs[0].title, jobs[0].url)
+
+    # Configured source
+    jobs = await Greenhouse(boards=["stripe", "anthropic"]).fetch()
+
+    # Everything, concurrently, failure-isolated
+    results = await fetch_all()                   # list[SourceResult]
+    for r in results:
+        print(r.source, len(r.postings) if r.ok else f"FAILED: {r.error}")
+
+asyncio.run(main())
+```
+
+## The model
+
+Every source normalizes into the same `Posting`:
+
+| Field | Notes |
+| --- | --- |
+| `source` | adapter name (`"remotive"`, `"greenhouse"`, ...) |
+| `external_id` | the source's own id |
+| `company`, `title`, `url` | always present |
+| `location_raw` | as the source states it, unparsed |
+| `posted_at` | `datetime` or `None`, when the source provides one |
+| `raw` | source-specific payload; descriptions truncated to 8,000 chars |
+| `.hash` | cross-source dedupe key (normalized company + title + location) |
+
+Boards syndicate each other's postings; `posting_hash()` collapses the
+duplicates without trusting any board-specific id.
+
+## Sources and their quirks
+
+| Adapter | Config | Worth knowing |
+| --- | --- | --- |
+| `Remotive()` | | Curated remote listings, JSON API |
+| `Arbeitnow(pages=3)` | page count | DACH-market coverage; paginates explicitly because the API's own `links.next` can point at filtered views |
+| `Greenhouse(boards=[...], per_board_limit=40, title_pattern=None)` | board tokens, cap, optional title regex | Direct-employer postings (Stripe, Anthropic, GitLab, ...). No global search endpoint exists, you choose boards. A default starter set is included |
+| `RemoteOK()` | | Their terms require a visible link back to remoteok.com in what you build. The API's first element is a legal notice, already skipped |
+| `WeWorkRemotely(categories=[...])` | category slugs | RSS per category; defaults to programming, devops, design, product |
+| `HNWhoIsHiring()` | | Finds the latest monthly thread via Algolia, parses only structured "Company \| Role \| Location" comments; freeform replies are ignored |
+
+All adapters accept `timeout=` and `user_agent=`. Public APIs change; every
+adapter parses defensively and skips malformed entries instead of raising.
+
+## Failure isolation
+
+`fetch_all()` never lets one dead API take down the run:
+
+```python
+results = await fetch_all([Remotive(), Greenhouse(boards=["stripe"])])
+postings = [p for r in results if r.ok for p in r.postings]
+errors = {r.source: r.error for r in results if not r.ok}
+```
+
+Your own adapter joins the party by satisfying the `SourceAdapter` protocol:
+anything with a `name` and an `async fetch() -> list[Posting]`.
+
+## Design notes
+
+- **httpx + pydantic only.** No framework, no ORM, no surprises in your
+  dependency tree.
+- **Fully typed**, ships `py.typed`.
+- **No product logic.** Filtering, enrichment, and storage belong to your
+  application; this package only does feed access done well. (JobRadar's
+  tech-role filter, LLM enrichment, and database live in
+  [its repo](https://github.com/n3ndor/jobradar), on top of this package.)
+- **Tests never touch the network.** Every adapter is tested against mocked
+  responses (respx) in CI on Python 3.11, 3.12, and 3.13.
+
+## License
+
+MIT. Built by [Nandor Nagy](https://github.com/n3ndor) as part of a public
+portfolio; the ingestion layer of [jobradar.nagysolution.com](https://jobradar.nagysolution.com).

jobfeeds-0.1.0/README.md

@@ -0,0 +1,111 @@
+<div align="center">
+
+# 📡 jobfeeds
+
+**One typed, async Python interface to six public job boards.**
+
+```
+pip install jobfeeds
+```
+
+![PyPI](https://img.shields.io/pypi/v/jobfeeds)
+![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-3776AB?logo=python&logoColor=white)
+![Tests](https://img.shields.io/github/actions/workflow/status/n3ndor/jobfeeds/test.yml?label=tests)
+![Typed](https://img.shields.io/badge/typing-py.typed-3ddc97)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+</div>
+
+---
+
+Fetching job postings should not require writing six API clients. jobfeeds
+gives you Remotive, Arbeitnow, Greenhouse boards, RemoteOK, We Work Remotely,
+and the Hacker News "Who is hiring" thread through one interface, normalized
+into one pydantic model, with failures isolated per source.
+
+Extracted from, and used in production by,
+[**JobRadar**](https://jobradar.nagysolution.com), a live job-market
+intelligence dashboard.
+
+## Quickstart
+
+```python
+import asyncio
+from jobfeeds import Remotive, Greenhouse, fetch_all
+
+async def main():
+    # One source
+    jobs = await Remotive().fetch()               # list[Posting]
+    print(jobs[0].company, jobs[0].title, jobs[0].url)
+
+    # Configured source
+    jobs = await Greenhouse(boards=["stripe", "anthropic"]).fetch()
+
+    # Everything, concurrently, failure-isolated
+    results = await fetch_all()                   # list[SourceResult]
+    for r in results:
+        print(r.source, len(r.postings) if r.ok else f"FAILED: {r.error}")
+
+asyncio.run(main())
+```
+
+## The model
+
+Every source normalizes into the same `Posting`:
+
+| Field | Notes |
+| --- | --- |
+| `source` | adapter name (`"remotive"`, `"greenhouse"`, ...) |
+| `external_id` | the source's own id |
+| `company`, `title`, `url` | always present |
+| `location_raw` | as the source states it, unparsed |
+| `posted_at` | `datetime` or `None`, when the source provides one |
+| `raw` | source-specific payload; descriptions truncated to 8,000 chars |
+| `.hash` | cross-source dedupe key (normalized company + title + location) |
+
+Boards syndicate each other's postings; `posting_hash()` collapses the
+duplicates without trusting any board-specific id.
+
+## Sources and their quirks
+
+| Adapter | Config | Worth knowing |
+| --- | --- | --- |
+| `Remotive()` | | Curated remote listings, JSON API |
+| `Arbeitnow(pages=3)` | page count | DACH-market coverage; paginates explicitly because the API's own `links.next` can point at filtered views |
+| `Greenhouse(boards=[...], per_board_limit=40, title_pattern=None)` | board tokens, cap, optional title regex | Direct-employer postings (Stripe, Anthropic, GitLab, ...). No global search endpoint exists, you choose boards. A default starter set is included |
+| `RemoteOK()` | | Their terms require a visible link back to remoteok.com in what you build. The API's first element is a legal notice, already skipped |
+| `WeWorkRemotely(categories=[...])` | category slugs | RSS per category; defaults to programming, devops, design, product |
+| `HNWhoIsHiring()` | | Finds the latest monthly thread via Algolia, parses only structured "Company \| Role \| Location" comments; freeform replies are ignored |
+
+All adapters accept `timeout=` and `user_agent=`. Public APIs change; every
+adapter parses defensively and skips malformed entries instead of raising.
+
+## Failure isolation
+
+`fetch_all()` never lets one dead API take down the run:
+
+```python
+results = await fetch_all([Remotive(), Greenhouse(boards=["stripe"])])
+postings = [p for r in results if r.ok for p in r.postings]
+errors = {r.source: r.error for r in results if not r.ok}
+```
+
+Your own adapter joins the party by satisfying the `SourceAdapter` protocol:
+anything with a `name` and an `async fetch() -> list[Posting]`.
+
+## Design notes
+
+- **httpx + pydantic only.** No framework, no ORM, no surprises in your
+  dependency tree.
+- **Fully typed**, ships `py.typed`.
+- **No product logic.** Filtering, enrichment, and storage belong to your
+  application; this package only does feed access done well. (JobRadar's
+  tech-role filter, LLM enrichment, and database live in
+  [its repo](https://github.com/n3ndor/jobradar), on top of this package.)
+- **Tests never touch the network.** Every adapter is tested against mocked
+  responses (respx) in CI on Python 3.11, 3.12, and 3.13.
+
+## License
+
+MIT. Built by [Nandor Nagy](https://github.com/n3ndor) as part of a public
+portfolio; the ingestion layer of [jobradar.nagysolution.com](https://jobradar.nagysolution.com).

jobfeeds-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jobfeeds"
+dynamic = ["version"]
+description = "One typed, async Python interface to six public job boards: Remotive, Arbeitnow, Greenhouse, RemoteOK, We Work Remotely, and Hacker News Who is hiring"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Nandor Nagy", email = "n3ndor@gmail.com" }]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.5",
+]
+keywords = ["jobs", "job-board", "api", "async", "remotive", "greenhouse", "remoteok", "hackernews"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/n3ndor/jobfeeds"
+Repository = "https://github.com/n3ndor/jobfeeds"
+Changelog = "https://github.com/n3ndor/jobfeeds/blob/main/CHANGELOG.md"
+"Used in production by" = "https://jobradar.nagysolution.com"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[tool.hatch.version]
+path = "src/jobfeeds/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

jobfeeds-0.1.0/src/jobfeeds/__init__.py

@@ -0,0 +1,37 @@
+"""jobfeeds: one typed, async interface to six public job boards.
+
+    from jobfeeds import Remotive, Greenhouse, fetch_all
+
+    jobs = await Remotive().fetch()                     # list[Posting]
+    jobs = await Greenhouse(boards=["stripe"]).fetch()  # configurable
+    results = await fetch_all()                         # failure-isolated
+"""
+
+from .fetch import fetch_all
+from .models import Posting, SourceResult, posting_hash
+from .sources import (
+    Arbeitnow,
+    Greenhouse,
+    HNWhoIsHiring,
+    RemoteOK,
+    Remotive,
+    SourceAdapter,
+    WeWorkRemotely,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Arbeitnow",
+    "Greenhouse",
+    "HNWhoIsHiring",
+    "Posting",
+    "RemoteOK",
+    "Remotive",
+    "SourceAdapter",
+    "SourceResult",
+    "WeWorkRemotely",
+    "fetch_all",
+    "posting_hash",
+    "__version__",
+]

jobfeeds-0.1.0/src/jobfeeds/_text.py

@@ -0,0 +1,34 @@
+"""Shared text helpers, internal."""
+
+from __future__ import annotations
+
+import re
+
+MAX_DESCRIPTION_CHARS = 8000
+
+_TAG_RE = re.compile(r"<[^>]+>")
+
+_ENTITIES = (
+    ("&amp;", "&"),
+    ("&lt;", "<"),
+    ("&gt;", ">"),
+    ("&#39;", "'"),
+    ("&#x27;", "'"),
+    ("&#x2F;", "/"),
+    ("&quot;", '"'),
+    ("&nbsp;", " "),
+)
+
+
+def decode_entities(text: str) -> str:
+    for entity, char in _ENTITIES:
+        text = text.replace(entity, char)
+    return text
+
+
+def strip_html(html: str) -> str:
+    return re.sub(r"\s+", " ", decode_entities(_TAG_RE.sub(" ", html))).strip()
+
+
+def truncate(text: str | None) -> str:
+    return (text or "")[:MAX_DESCRIPTION_CHARS]

jobfeeds-0.1.0/src/jobfeeds/fetch.py

@@ -0,0 +1,45 @@
+"""Fetch several sources concurrently with per-source failure isolation."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Sequence
+
+from .models import SourceResult
+from .sources import (
+    Arbeitnow,
+    Greenhouse,
+    HNWhoIsHiring,
+    RemoteOK,
+    Remotive,
+    SourceAdapter,
+    WeWorkRemotely,
+)
+
+
+def default_sources() -> list[SourceAdapter]:
+    """All six adapters with their default configuration."""
+    return [
+        Remotive(),
+        Arbeitnow(),
+        Greenhouse(),
+        RemoteOK(),
+        WeWorkRemotely(),
+        HNWhoIsHiring(),
+    ]
+
+
+async def fetch_all(sources: Sequence[SourceAdapter] | None = None) -> list[SourceResult]:
+    """Fetch every source concurrently. One failing source never takes down
+    the run: each adapter's outcome (postings or error) is reported in its
+    own SourceResult, in the same order as `sources`."""
+    adapters = list(sources) if sources is not None else default_sources()
+
+    async def run(adapter: SourceAdapter) -> SourceResult:
+        try:
+            postings = await adapter.fetch()
+            return SourceResult(source=adapter.name, postings=postings)
+        except Exception as exc:  # noqa: BLE001 - isolation is the point
+            return SourceResult(source=adapter.name, error=f"{type(exc).__name__}: {exc}")
+
+    return list(await asyncio.gather(*(run(a) for a in adapters)))

jobfeeds-0.1.0/src/jobfeeds/models.py

@@ -0,0 +1,58 @@
+"""Public data models."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime
+
+from pydantic import BaseModel, Field, HttpUrl
+
+
+def _normalize(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip().lower()
+
+
+def posting_hash(company: str, title: str, location_raw: str) -> str:
+    """Cross-source dedupe key: same company + title + normalized location.
+
+    Boards syndicate each other's postings; hashing the normalized triple
+    lets you collapse duplicates across sources without trusting any
+    board-specific id.
+    """
+    key = "|".join((_normalize(company), _normalize(title), _normalize(location_raw)))
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()
+
+
+class Posting(BaseModel):
+    """One job posting, normalized across all sources.
+
+    `raw` carries the source-specific payload (descriptions are truncated to
+    a bounded size); everything else is the common denominator every adapter
+    can fill.
+    """
+
+    source: str
+    external_id: str
+    company: str
+    title: str
+    url: HttpUrl
+    location_raw: str = ""
+    posted_at: datetime | None = None
+    raw: dict = Field(default_factory=dict)
+
+    @property
+    def hash(self) -> str:
+        return posting_hash(self.company, self.title, self.location_raw)
+
+
+class SourceResult(BaseModel):
+    """Outcome of one adapter's fetch, success or failure."""
+
+    source: str
+    postings: list[Posting] = Field(default_factory=list)
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None

jobfeeds-0.1.0/src/jobfeeds/sources/__init__.py

@@ -0,0 +1,17 @@
+from .arbeitnow import Arbeitnow
+from .base import SourceAdapter
+from .greenhouse import Greenhouse
+from .hn_hiring import HNWhoIsHiring
+from .remoteok import RemoteOK
+from .remotive import Remotive
+from .wwr import WeWorkRemotely
+
+__all__ = [
+    "Arbeitnow",
+    "Greenhouse",
+    "HNWhoIsHiring",
+    "RemoteOK",
+    "Remotive",
+    "SourceAdapter",
+    "WeWorkRemotely",
+]