pywuzzuf 0.1.0__tar.gz

pywuzzuf-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.3
+Name: pywuzzuf
+Version: 0.1.0
+Summary: Async Python client for the Wuzzuf job-search API
+Keywords: wuzzuf,jobs,api,scraper,egypt,async,client
+Author: Hossam Elshabory
+Author-email: Hossam Elshabory <hossam.elshabory97@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Dist: backoff>=2.2.1
+Requires-Dist: curl-cffi>=0.14.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/hossam-elshabory/pywuzzuf
+Project-URL: Documentation, https://hossam-elshabory.github.io/pywuzzuf/
+Project-URL: Repository, https://github.com/hossam-elshabory/pywuzzuf.git
+Project-URL: Issues, https://github.com/hossam-elshabory/pywuzzuf/issues
+Project-URL: Changelog, https://github.com/hossam-elshabory/pywuzzuf/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>🔍 PyWuzzuf</h1>
+  <p><em>An unofficial, async-first Python client for the Wuzzuf Jobs API</em></p>
+
+  <p>
+    <img src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=yellow" alt="python - 3.12+">
+    <img src="https://img.shields.io/badge/UV-blue?logo=uv" alt="UV">
+    <a href="https://prek.j178.dev/">
+      <img src="https://img.shields.io/badge/Prek-blue?logo=prek" alt="Prek - Ready">
+    </a>
+    <img src="https://img.shields.io/badge/Async-Ready-blue?logo=async" alt="Async - Ready">
+    <img src="https://img.shields.io/badge/License-MIT-blue?logo=LICENSE" alt="License - MIT">
+  </p>
+
+  <p>
+    <a href="https://hossam-elshabory.github.io/pywuzzuf/">📖 Read The Documentation</a>
+  </p>
+</div>
+
+---
+
+## 📑 Table of Contents <!-- omit in toc -->
+
+- [🔧 Core Features](#-core-features)
+- [🚀 Installation](#-installation)
+- [🎯 Quick Start](#-quick-start)
+- [🤝 Contributions](#-contributions)
+
+---
+
+## ⚠️ Important Considerations <!-- omit in toc -->
+
+> [!WARNING]
+> PyWuzzuf is an **unofficial**, **educational** project and is not affiliated with, endorsed by, or connected to [Wuzzuf](https://wuzzuf.net). Users are responsible for ensuring their use of this library complies with Wuzzuf's [Terms and Conditions](https://wuzzuf.net/policies) and `robots.txt` policies.
+
+> [!IMPORTANT]
+> **Search Accuracy Notice**: The Wuzzuf API uses "soft matching," meaning irrelevant results often appear after the first few pages. PyWuzzuf solves this with **Client-Side Filtering**, enforcing your criteria locally to guarantee data integrity. [Read more in the Filtering Guide](docs/usage/filters.md).
+
+### Rate Limiting & Ethics <!-- omit in toc -->
+- Client-side filtering means you may fetch more pages than requested to reach your target count
+- Be respectful with request volumes — this tool is for educational and personal projects, not for scraping at scale
+- Consider implementing delays between requests for larger operations
+
+---
+
+## 🔧 Core Features
+
+| Feature                     | What It Does                                                                             |
+| --------------------------- | ---------------------------------------------------------------------------------------- |
+| **🎭 Browser Impersonation** | Uses `curl_cffi` to mimic real Chrome/Firefox TLS fingerprints. No more 403s.            |
+| **🔄 Smart Pagination**      | Automatic retries with exponential backoff. Control flow with `STOP`/`CONTINUE`/`RETRY`. |
+| **✅ Client-Side Filtering** | Enforces your criteria locally — no more irrelevant results slipping through.            |
+| **📊 Data Quality Audits**   | Built-in detection for missing companies, salaries, and malformed entries.               |
+| **🔒 Type Safety**           | Full Pydantic v2 models with IDE autocomplete and validation.                            |
+
+---
+
+## 🚀 Installation
+
+**One-liner with uv (recommended):**
+```bash
+uv add pywuzzuf
+```
+
+**Classic pip:**
+```bash
+pip install pywuzzuf
+```
+
+**Poetry:**
+```bash
+poetry add pywuzzuf
+```
+
+> Requires **Python 3.12+**
+
+---
+
+## 🎯 Quick Start
+
+Get the first 10 "Python Developer" jobs posted in the last 24 hours:
+
+```python
+import asyncio
+from pywuzzuf import WuzzufClient, SearchFilters, DateRange
+
+async def main():
+    async with WuzzufClient() as client:
+        results = await client.jobs.search("Python Developer") \
+            .filter(SearchFilters(posted_within=DateRange.LAST_24_HOURS)) \
+            .limit(10) \
+            .all()
+
+        for job in results.items:
+            company = job.company.attributes.name if job.company else "Unknown"
+            print(f"📌 {job.attributes.title} @ {company}")
+            
+            if job.quality.has_anomalies:
+                print(f"   ⚠️  Missing: {', '.join(job.quality.missing_fields)}")
+
+asyncio.run(main())
+```
+
+**Output:**
+```bash
+📌 Senior Python Engineer @ Instabug
+📌 Backend Python Developer @ Paymob
+   ⚠️  Missing: salary_range
+📌 Python Team Lead @ Vezeeta
+...
+```
+---
+
+## 🤝 Contributions
+
+> [!IMPORTANT]
+> **Not accepting contributions at this time.** Contributions will reopen once the project the more stable.

pywuzzuf-0.1.0/README.md

@@ -0,0 +1,117 @@
+<div align="center">
+  <h1>🔍 PyWuzzuf</h1>
+  <p><em>An unofficial, async-first Python client for the Wuzzuf Jobs API</em></p>
+
+  <p>
+    <img src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=yellow" alt="python - 3.12+">
+    <img src="https://img.shields.io/badge/UV-blue?logo=uv" alt="UV">
+    <a href="https://prek.j178.dev/">
+      <img src="https://img.shields.io/badge/Prek-blue?logo=prek" alt="Prek - Ready">
+    </a>
+    <img src="https://img.shields.io/badge/Async-Ready-blue?logo=async" alt="Async - Ready">
+    <img src="https://img.shields.io/badge/License-MIT-blue?logo=LICENSE" alt="License - MIT">
+  </p>
+
+  <p>
+    <a href="https://hossam-elshabory.github.io/pywuzzuf/">📖 Read The Documentation</a>
+  </p>
+</div>
+
+---
+
+## 📑 Table of Contents <!-- omit in toc -->
+
+- [🔧 Core Features](#-core-features)
+- [🚀 Installation](#-installation)
+- [🎯 Quick Start](#-quick-start)
+- [🤝 Contributions](#-contributions)
+
+---
+
+## ⚠️ Important Considerations <!-- omit in toc -->
+
+> [!WARNING]
+> PyWuzzuf is an **unofficial**, **educational** project and is not affiliated with, endorsed by, or connected to [Wuzzuf](https://wuzzuf.net). Users are responsible for ensuring their use of this library complies with Wuzzuf's [Terms and Conditions](https://wuzzuf.net/policies) and `robots.txt` policies.
+
+> [!IMPORTANT]
+> **Search Accuracy Notice**: The Wuzzuf API uses "soft matching," meaning irrelevant results often appear after the first few pages. PyWuzzuf solves this with **Client-Side Filtering**, enforcing your criteria locally to guarantee data integrity. [Read more in the Filtering Guide](docs/usage/filters.md).
+
+### Rate Limiting & Ethics <!-- omit in toc -->
+- Client-side filtering means you may fetch more pages than requested to reach your target count
+- Be respectful with request volumes — this tool is for educational and personal projects, not for scraping at scale
+- Consider implementing delays between requests for larger operations
+
+---
+
+## 🔧 Core Features
+
+| Feature                     | What It Does                                                                             |
+| --------------------------- | ---------------------------------------------------------------------------------------- |
+| **🎭 Browser Impersonation** | Uses `curl_cffi` to mimic real Chrome/Firefox TLS fingerprints. No more 403s.            |
+| **🔄 Smart Pagination**      | Automatic retries with exponential backoff. Control flow with `STOP`/`CONTINUE`/`RETRY`. |
+| **✅ Client-Side Filtering** | Enforces your criteria locally — no more irrelevant results slipping through.            |
+| **📊 Data Quality Audits**   | Built-in detection for missing companies, salaries, and malformed entries.               |
+| **🔒 Type Safety**           | Full Pydantic v2 models with IDE autocomplete and validation.                            |
+
+---
+
+## 🚀 Installation
+
+**One-liner with uv (recommended):**
+```bash
+uv add pywuzzuf
+```
+
+**Classic pip:**
+```bash
+pip install pywuzzuf
+```
+
+**Poetry:**
+```bash
+poetry add pywuzzuf
+```
+
+> Requires **Python 3.12+**
+
+---
+
+## 🎯 Quick Start
+
+Get the first 10 "Python Developer" jobs posted in the last 24 hours:
+
+```python
+import asyncio
+from pywuzzuf import WuzzufClient, SearchFilters, DateRange
+
+async def main():
+    async with WuzzufClient() as client:
+        results = await client.jobs.search("Python Developer") \
+            .filter(SearchFilters(posted_within=DateRange.LAST_24_HOURS)) \
+            .limit(10) \
+            .all()
+
+        for job in results.items:
+            company = job.company.attributes.name if job.company else "Unknown"
+            print(f"📌 {job.attributes.title} @ {company}")
+            
+            if job.quality.has_anomalies:
+                print(f"   ⚠️  Missing: {', '.join(job.quality.missing_fields)}")
+
+asyncio.run(main())
+```
+
+**Output:**
+```bash
+📌 Senior Python Engineer @ Instabug
+📌 Backend Python Developer @ Paymob
+   ⚠️  Missing: salary_range
+📌 Python Team Lead @ Vezeeta
+...
+```
+---
+
+## 🤝 Contributions
+
+> [!IMPORTANT]
+> **Not accepting contributions at this time.** Contributions will reopen once the project the more stable.

pywuzzuf-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "pywuzzuf"
+version = "0.1.0"
+description = "Async Python client for the Wuzzuf job-search API"
+readme = "README.md"
+authors = [
+    { name = "Hossam Elshabory", email = "hossam.elshabory97@gmail.com" },
+]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = ["backoff>=2.2.1", "curl-cffi>=0.14.0", "pydantic>=2.12.5"]
+
+keywords = ["wuzzuf", "jobs", "api", "scraper", "egypt", "async", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: AsyncIO",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/hossam-elshabory/pywuzzuf"
+Documentation = "https://hossam-elshabory.github.io/pywuzzuf/"
+Repository = "https://github.com/hossam-elshabory/pywuzzuf.git"
+Issues = "https://github.com/hossam-elshabory/pywuzzuf/issues"
+Changelog = "https://github.com/hossam-elshabory/pywuzzuf/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.7",
+    "zensical>=0.0.28",
+    "commitizen>=4.13.9",
+    "ty>=0.0.25",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.ruff]
+line-length = 104
+
+[tool.ruff.lint]
+ignore = [
+    # --- Formatting / Line Length ---
+    "E501",
+
+    "D105", # Missing docstring in magic method (e.g., __repr__)
+    "D200", # One-line docstring should fit on one line
+    "D107", # Missing docstring in __init__
+    "D102", # Missing docstring in public method (@property getters)
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+select = ["E", "F", "I", "D"]
+# Ignore ALL documentation rules inside the tests directory
+"tests/**" = ["D"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_scheme = "semver"
+version_provider = "uv"
+update_changelog_on_bump = true
+major_version_zero = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["live: mark test as live API test"]

pywuzzuf-0.1.0/src/pywuzzuf/__init__.py

@@ -0,0 +1,158 @@
+"""
+PyWuzzuf — Production-grade Python client for the Wuzzuf Jobs API.
+
+This package provides a robust, async-first interface to the Wuzzuf API,
+featuring built-in browser impersonation, resilient pagination, and
+comprehensive data quality reporting.
+
+Quick start
+-----------
+
+Async (recommended)::
+
+    import asyncio
+    from pywuzzuf import WuzzufClient, SearchFilters, DateRange
+
+    async def main():
+        async with WuzzufClient() as client:
+            # Build and execute a filtered search
+            result = await (
+                client.jobs
+                    .search("Python Developer")
+                    .filter(SearchFilters(posted_within=DateRange.LAST_WEEK))
+                    .limit(50)
+                    .all()
+            )
+
+            for job in result.items:
+                print(f"{job.attributes.title} at {job.company.attributes.name}")
+
+    asyncio.run(main())
+
+Synchronous (notebooks/scripts)::
+
+    from pywuzzuf import SyncWuzzufClient
+
+    with SyncWuzzufClient() as client:
+        result = client.jobs.search("Data Scientist").limit(10).all()
+        for job in result.items:
+            print(job.attributes.title)
+
+Key Improvements in v3
+----------------------
+* **Resilient Pagination**: Error callbacks can now return ``CONTINUE`` to skip
+  failing pages instead of stopping iteration.
+* **Accurate Status Tracking**: ``terminated_early`` now correctly captures all
+  stop reasons, including manual signals from callbacks.
+* **Type Safety**: Fixed a critical ``TypeError`` when comparing mixed
+  tz-aware/tz-naive datetimes in filters.
+* **Enhanced Diagnostics**: Improved ``DataQualityReport`` to reduce false
+  positives on optional fields like ``requirements``.
+* **API Compatibility**: Standardized outbound date formats to match Wuzzuf's
+  native ``MM/DD/YYYY HH:MM:SS`` requirement.
+
+Public Surface
+--------------
+
+Clients
+~~~~~~~
+* ``WuzzufClient``: Asynchronous context manager (primary entry point).
+* ``SyncWuzzufClient``: Synchronous wrapper with persistent event loop.
+
+Filtering
+~~~~~~~~~
+* ``SearchFilters``: Immutable container for keywords and metadata.
+* ``DateRange``: Enum for relative time windows (e.g., ``LAST_WEEK``).
+* ``AbsoluteDateFilter``: Precise datetime boundaries.
+
+Pagination
+~~~~~~~~~~
+* ``PaginationConfig``: Controls caps, page size, and callbacks.
+* ``PaginationResult``: Aggregated items with exhaustive metadata.
+* ``PaginationSignal``: Flow control (STOP/CONTINUE/RETRY) for callbacks.
+
+Models
+~~~~~~
+* ``EnrichedJob``: The core job object with company data and quality reports.
+* ``DataQualityReport``: Detailed anomaly analysis for API responses.
+
+Exceptions
+~~~~~~~~~~
+* ``WuzzufAPIError``: Base exception for all client errors.
+* ``BotDetectionError``: Raised when fingerprint-based rejection is suspected.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Package version
+# ---------------------------------------------------------------------------
+# Dynamically retrieve the version from installed package metadata.
+# This ensures pyproject.toml is the single source of truth.
+# Falls back to "0.0.0" if the package is not installed (e.g., running from source).
+# ---------------------------------------------------------------------------
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("pywuzzuf")
+except PackageNotFoundError:
+    # Fallback for local development or if running from source without installation
+    __version__ = "0.0.0+local"
+
+from .client import SyncWuzzufClient, WuzzufClient
+from .exceptions import (
+    BotDetectionError,
+    InvalidResponseError,
+    RateLimitError,
+    WuzzufAPIError,
+)
+from .filters import AbsoluteDateFilter, DateRange, SearchFilters
+from .models import (
+    Company,
+    CompanyAttributes,
+    DataQualityReport,
+    EnrichedJob,
+    JobAttributes,
+    JobDetails,
+    Location,
+    NamedAttribute,
+    Salary,
+)
+from .pagination import (
+    AsyncPaginator,
+    PaginationConfig,
+    PaginationResult,
+    PaginationSignal,
+)
+
+__all__ = [
+    # Package metadata
+    "__version__",
+    # Clients
+    "WuzzufClient",
+    "SyncWuzzufClient",
+    # Filtering
+    "SearchFilters",
+    "DateRange",
+    "AbsoluteDateFilter",
+    # Pagination
+    "PaginationConfig",
+    "PaginationResult",
+    "PaginationSignal",
+    "AsyncPaginator",
+    # Models
+    "EnrichedJob",
+    "JobDetails",
+    "JobAttributes",
+    "Company",
+    "CompanyAttributes",
+    "Salary",
+    "Location",
+    "NamedAttribute",
+    "DataQualityReport",
+    # Exceptions
+    "WuzzufAPIError",
+    "RateLimitError",
+    "InvalidResponseError",
+    "BotDetectionError",
+]