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).
