Metadata-Version: 2.4
Name: apple-jobs
Version: 0.1.1
Summary: A clean Python client for Apple's career job listings. No API key, no headless browser, no scraping service.
Author: Michael Danylchuk
License: MIT
Project-URL: Homepage, https://github.com/Mikedan37/apple-jobs
Project-URL: Issues, https://github.com/Mikedan37/apple-jobs/issues
Keywords: apple,jobs,careers,job-board,scraper
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# apple-jobs

A lightweight Python client for Apple job listings on jobs.apple.com. No API key, no browser automation.

## Install

```bash
# From GitHub (recommended for now)
pip install git+https://github.com/Mikedan37/apple-jobs.git

# Or clone and install locally
git clone https://github.com/Mikedan37/apple-jobs.git
cd apple-jobs
pip install -e .
```

Requires Python 3.10+ and [httpx](https://www.python-httpx.org/).

## Quick example

```python
from apple_jobs import AppleJobsClient

client = AppleJobsClient()

for job in client.search(query="iOS engineer", limit=5):
    print(f"{job.title} — {job.team.name}")
    print(f"  {job.location} · {job.posting_date}")
    print(f"  {job.url}")
    print()

client.close()
```

## CLI

~6,000+ live positions across Apple teams and locations.

```bash
apple-jobs count                          # total open positions
apple-jobs search "Swift"                 # search by keyword
apple-jobs search --team "Software"       # filter by team
apple-jobs search "iOS" --location "US"   # combine filters
apple-jobs page 5                         # fetch a specific page
apple-jobs dump > jobs.jsonl              # all jobs as JSON lines
```

Or via module: `python -m apple_jobs count`

## Why this exists

Apple does not provide a public jobs API.

This package gives you a clean, stable interface over the public job listings so you can:

- search roles programmatically
- build job matching pipelines
- automate job discovery workflows

One dependency (httpx). No Selenium. No API key.

## What this does

- Fetches Apple job listings from `jobs.apple.com`
- Parses structured job data from server-rendered HTML (no headless browser)
- Returns typed Python models (`AppleJob`, `AppleJobsPage`)
- Handles pagination, retries, and rate limiting
- Provides a small CLI for quick lookups and bulk export

## What this does NOT do

- Does not apply to jobs on your behalf
- Does not bypass authentication or access controls
- Does not scrape aggressively or circumvent rate limits
- Does not cover job boards other than Apple
- Does not enrich, score, or rank jobs

## Responsible use

This library parses data already served to standard browser requests. Built-in safeguards:

- **0.5s default delay** between page requests. Do not set it to zero.
- **3 retries max** on transient failures. No infinite loops.
- **Honest User-Agent** with a project URL. Do not spoof it.

If Apple changes their site structure or blocks automated access, this library will stop working. That is their right. File an issue and we will adapt.

## API reference

### AppleJobsClient

```python
client = AppleJobsClient(delay=0.5, retries=3, timeout=30.0)
```

| Method | Returns | Description |
|--------|---------|-------------|
| `search(query=, location=, team=, limit=)` | `list[AppleJob]` | Search with client-side filtering |
| `search_page(page=1)` | `AppleJobsPage` | Fetch a single page (20 jobs) |
| `iter_jobs(max_pages=300)` | `Iterator[AppleJob]` | Auto-paginate all jobs |
| `get_total_count()` | `int` | Total open positions |
| `close()` | — | Close HTTP client |

Supports context manager: `with AppleJobsClient() as client: ...`

### AppleJob

| Field | Type | Description |
|-------|------|-------------|
| `position_id` | `str` | Apple's unique position ID |
| `title` | `str` | Job title |
| `summary` | `str` | 2-3 paragraph description |
| `url` | `str` | Direct link to posting |
| `posted_at` | `datetime?` | UTC timestamp |
| `posting_date` | `str` | Human-readable date |
| `team` | `AppleJobTeam` | Department (name, code) |
| `locations` | `list[AppleJobLocation]` | One or more locations |
| `home_office` | `bool` | Remote-eligible |
| `weekly_hours` | `int` | 40 = full-time |

Properties: `location` (primary as string), `is_remote`, `is_part_time`

### AppleJobsPage

| Field | Type | Description |
|-------|------|-------------|
| `jobs` | `list[AppleJob]` | Up to 20 jobs |
| `total_records` | `int` | Total matching jobs |
| `page` | `int` | Current page (1-indexed) |

Properties: `total_pages`, `has_next`

## Development

```bash
git clone https://github.com/Mikedan37/apple-jobs.git
cd apple-jobs
pip install -e ".[dev]"
pytest tests/ -v              # 32 tests, ~0.5s, fully offline
```

Tests parse saved HTML fixtures. No network calls. If Apple changes their site and tests break, re-capture:

```bash
curl -s "https://jobs.apple.com/en-us/search?page=1" \
  -H "user-agent: apple-jobs-python-client/0.1" \
  -o tests/fixtures/search_page_1.html
```

## Limitations

- **Client-side filtering.** Apple's search page does not support server-side text queries via URL params. `search()` fetches pages and filters locally.
- **Summaries only.** The `summary` field is from the search listing (2-3 paragraphs). Full detail pages exist at each `url` but are not fetched.
- **HTML parsing is inherently fragile.** If Apple redesigns their career site, the parser will break. File an issue.

## Maintained by

Maintained by Danylchuk Studios, LLC ([Seeker](https://www.seekerscore.com) project).

This project is not affiliated with or endorsed by Apple Inc. Intended for personal use, research, and tooling. Not for high-volume scraping or commercial redistribution of Apple job listings.

## License

MIT
