resumereaderapi 1.0.0__py3-none-any.whl

resumereaderapi/__init__.py

@@ -0,0 +1,4 @@
+from .client import ResumeReader, ResumeReaderError
+
+__all__ = ["ResumeReader", "ResumeReaderError"]
+__version__ = "1.0.0"

resumereaderapi/client.py

@@ -0,0 +1,108 @@
+"""Client for the Resume Reader API (https://www.resumereaderapi.com)."""
+import base64
+import os
+from typing import Any, Dict, Iterable, List, Optional
+
+import requests
+
+__version__ = "1.0.0"
+BASE = "https://www.resumereaderapi.com/api/"
+
+STATUS_TEXT = {
+    400: "Missing or invalid input",
+    401: "Invalid API key",
+    402: "Insufficient credits, nothing was billed",
+    413: "Document beyond 20 pages, about 30,000 tokens or 10 MB, nothing was billed",
+    422: "File could not be read as a resume",
+    429: "Rate limit exceeded, 30 requests per 60 seconds per IP",
+}
+
+
+class ResumeReaderError(Exception):
+    """The HTTP status is always 200, so errors come from the status field of the JSON body."""
+
+    def __init__(self, status: int, message: str, body: Optional[dict] = None):
+        super().__init__("[%s] %s" % (status, message))
+        self.status = status
+        self.body = body or {}
+
+
+class ResumeReader:
+    def __init__(self, api_key: str, schema_version: int = 2, timeout: float = 120.0,
+                 session: Optional[requests.Session] = None):
+        if not api_key:
+            raise ValueError("An API key is required")
+        self.api_key = api_key
+        self.schema_version = schema_version
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.session.headers["User-Agent"] = "resumereaderapi-python/%s (+https://www.resumereaderapi.com)" % __version__
+
+    def _post(self, endpoint: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        resp = self.session.post(BASE + endpoint, json=payload, timeout=self.timeout)
+        try:
+            body = resp.json()
+        except ValueError:
+            raise ResumeReaderError(resp.status_code, "Response was not JSON")
+        status = body.get("status", 200) if isinstance(body, dict) else 200
+        if status != 200:
+            raise ResumeReaderError(status, STATUS_TEXT.get(status) or body.get("message", "API error"), body)
+        return body
+
+    def _parse(self, source: Dict[str, Any], field_names: Optional[str], exclude_sensitive: bool,
+               anonymize: bool, max_pages: Optional[int], sections: Optional[List[str]],
+               language: Optional[str]) -> Dict[str, Any]:
+        payload = {"api_key": self.api_key, "schema_version": self.schema_version}
+        payload.update(source)
+        if field_names:
+            payload["field_names"] = field_names
+        if exclude_sensitive:
+            payload["exclude_sensitive"] = True
+        if anonymize:
+            payload["anonymize"] = True
+        if max_pages:
+            payload["max_pages"] = max_pages
+        if sections:
+            payload["sections"] = sections
+        if language:
+            payload["language"] = language
+        return self._post("parse.php", payload)
+
+    def parse_text(self, text: str, field_names: Optional[str] = None, exclude_sensitive: bool = False,
+                   anonymize: bool = False, max_pages: Optional[int] = None,
+                   sections: Optional[List[str]] = None, language: Optional[str] = None) -> Dict[str, Any]:
+        return self._parse({"text": text}, field_names, exclude_sensitive, anonymize, max_pages, sections, language)
+
+    def parse_file(self, path: str, field_names: Optional[str] = None, exclude_sensitive: bool = False,
+                   anonymize: bool = False, max_pages: Optional[int] = None,
+                   sections: Optional[List[str]] = None, language: Optional[str] = None) -> Dict[str, Any]:
+        with open(path, "rb") as fh:
+            encoded = base64.b64encode(fh.read()).decode("ascii")
+        source = {"file_base64": encoded, "filename": os.path.basename(path)}
+        return self._parse(source, field_names, exclude_sensitive, anonymize, max_pages, sections, language)
+
+    def parse_url(self, file_url: str, field_names: Optional[str] = None, exclude_sensitive: bool = False,
+                  anonymize: bool = False, max_pages: Optional[int] = None,
+                  sections: Optional[List[str]] = None, language: Optional[str] = None) -> Dict[str, Any]:
+        return self._parse({"file_url": file_url}, field_names, exclude_sensitive, anonymize, max_pages, sections, language)
+
+    def _normalize(self, endpoint: str, key: str, items: Iterable[str]) -> Dict[str, Any]:
+        values = [items] if isinstance(items, str) else list(items)
+        results: List[Dict[str, Any]] = []
+        used = 0.0
+        remaining = None
+        for i in range(0, len(values), 100):
+            body = self._post(endpoint, {"api_key": self.api_key, key: values[i:i + 100]})
+            results.extend(body.get("results", []))
+            used += body.get("credits_used", 0)
+            remaining = body.get("remaining_credits", remaining)
+        return {"results": results, "credits_used": round(used, 4), "remaining_credits": remaining}
+
+    def normalize_titles(self, titles: Iterable[str]) -> Dict[str, Any]:
+        return self._normalize("normalize_title.php", "titles", titles)
+
+    def normalize_skills(self, skills: Iterable[str]) -> Dict[str, Any]:
+        return self._normalize("normalize_skills.php", "skills", skills)
+
+    def normalize_locations(self, locations: Iterable[str]) -> Dict[str, Any]:
+        return self._normalize("normalize_locations.php", "locations", locations)

resumereaderapi-1.0.0.dist-info/LICENSE

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

resumereaderapi-1.0.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.1
+Name: resumereaderapi
+Version: 1.0.0
+Summary: Python client for the Resume Reader API: parse PDF, DOCX and scanned resumes into 114 structured JSON fields, and normalize job titles, skills and locations.
+Home-page: https://www.resumereaderapi.com
+Author: Alpha Quantum
+Author-email: info@alpha-quantum.com
+License: MIT
+Project-URL: Homepage, https://www.resumereaderapi.com
+Project-URL: Documentation, https://www.resumereaderapi.com/api-v2.php
+Project-URL: Source, https://github.com/explainableaixai/resumereaderapi
+Project-URL: Mirror, https://gitlab.com/url-classifications/resumereaderapi
+Project-URL: Pricing, https://www.resumereaderapi.com/pricing.php
+Keywords: resume parser,cv parser,resume parsing api,resume to json,ats,recruiting,hr tech,job title normalization,skill normalization,location normalization,ocr,cv anonymization
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20.0
+
+# resumereaderapi (Python)
+
+Resume parser client for Python. Hand it a PDF, a DOCX, a scan or raw text and get structured candidate data back as a dictionary.
+
+Needs `requests`. Python 3.7 and later.
+
+```bash
+pip install resumereaderapi
+```
+
+## Why use a hosted resume parser
+
+Writing regular expressions for CVs is a trap. Layouts vary, languages vary, and half the documents are scans. A hosted resume parser gives you one stable shape no matter what the candidate uploaded.
+
+The service behind this package is the [resume parser](https://www.resumereaderapi.com/) from Alpha Quantum. It returns 114 fields and marks missing facts as `None` instead of guessing.
+
+## Parse in three lines
+
+```python
+from resumereaderapi import ResumeReader
+
+rr = ResumeReader("YOUR_API_KEY")
+data = rr.parse_file("cv.pdf")
+
+print(data["resume"]["contact"]["emails"])
+print(data["remaining_credits"])
+```
+
+## Calls
+
+```python
+rr.parse_text(text, field_names=None, exclude_sensitive=False, anonymize=False,
+              max_pages=None, sections=None, language=None)
+rr.parse_file(path, ...same options...)
+rr.parse_url(https_url, ...same options...)
+
+rr.normalize_titles(["Sr. SWE II"])
+rr.normalize_skills(["K8s", "JS"])
+rr.normalize_locations(["NYC"])
+```
+
+Normalizer methods batch in groups of 100 and return `{"results": [...], "credits_used": float, "remaining_credits": float}`.
+
+## Skill normalization in practice
+
+Candidates write the same skill ten ways. `JS`, `Javascript` and `java script` should be one filter value.
+
+```python
+raw = ["JS", "Javascript", "Python 3.11", "py", "MS Excel", "n/a"]
+out = rr.normalize_skills(raw)
+for item in out["results"]:
+    print(item["input"], "->", item["normalized_skill"], item["skill_type"])
+```
+
+Junk entries such as "n/a" come back with `normalized_skill` set to `None`. See the [skill normalization](https://www.resumereaderapi.com/normalization/skills.php) page for fifty real examples.
+
+## Anonymize before a human sees the CV
+
+```python
+data = rr.parse_file(
+    "cv.docx",
+    anonymize=True,
+    exclude_sensitive=True,
+)
+```
+
+Names, contact values and sensitive fields become placeholders such as `[NAME]` and `[EMAIL]`. This is the base of a blind review process, covered under [CV anonymization](https://www.resumereaderapi.com/use-cases/cv-anonymization.php).
+
+## Handle errors
+
+```python
+from resumereaderapi import ResumeReaderError
+
+try:
+    rr.parse_file(path)
+except ResumeReaderError as exc:
+    if exc.status == 402:
+        print("buy more credits")
+    elif exc.status in (413, 422):
+        print("bad document:", exc)
+    else:
+        raise
+```
+
+## Example: into a DataFrame
+
+```python
+import pandas as pd
+from pathlib import Path
+
+rows = []
+for p in Path("cvs").glob("*.pdf"):
+    r = rr.parse_file(str(p))["resume"]
+    rows.append({
+        "name": r["contact"]["full_name"],
+        "city": r["contact"]["address"]["city"],
+        "title": (r["career"]["current_position"] or {}).get("title"),
+        "years": r["career"]["total_experience_years"],
+        "skills": ", ".join(r["skills"]["technical"]),
+    })
+
+pd.DataFrame(rows).to_csv("candidates.csv", index=False)
+```
+
+## Example: Flask upload endpoint
+
+```python
+from flask import Flask, request, jsonify
+import tempfile, os
+
+app = Flask(__name__)
+
+@app.post("/parse")
+def parse():
+    f = request.files["cv"]
+    with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(f.filename)[1]) as tmp:
+        f.save(tmp.name)
+    try:
+        return jsonify(rr.parse_file(tmp.name)["resume"])
+    finally:
+        os.unlink(tmp.name)
+```
+
+## Questions
+
+**What file types?** PDF, DOCX, TXT, RTF, HTML, ODT, spreadsheets and images including scanned PDFs.
+
+**Is there a limit per call?** 10 MB, 20 pages and about 30,000 tokens.
+
+**Does it work in French?** Pass `field_names="fr"` for French keys. Values keep the language of the resume.
+
+MIT license. Contact: info@alpha-quantum.com
+
+

resumereaderapi-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+resumereaderapi/__init__.py,sha256=nMU49uyWRJdT1aHcV38rOs_6pVkS8TmXsAKOyvz7KI4,123
+resumereaderapi/client.py,sha256=2kUXRmBH3eDn0DWv6207fvaYOpZcfXOwJSwAIXU1POM,5311
+resumereaderapi-1.0.0.dist-info/LICENSE,sha256=-kjrwollysEMZkPQkJIq5zyefl9XyPw5egz8knSXiB4,1070
+resumereaderapi-1.0.0.dist-info/METADATA,sha256=QEJMAA_AQ_itf1mWw-tlcFY8cS6LmUYbIYVGW0FQq_U,5262
+resumereaderapi-1.0.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+resumereaderapi-1.0.0.dist-info/top_level.txt,sha256=LVu9C0Qs8FspbvMkktipSuIdrzLDnDjblGrJ42v5xMY,16
+resumereaderapi-1.0.0.dist-info/RECORD,,

resumereaderapi-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

resumereaderapi-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+resumereaderapi