pyprocore 1.0.0__py3-none-any.whl

pyprocore-1.0.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+app.py,sha256=Ov7JpwDrg0hczDCGLg-xNAKOYfi0fKJTEVxva6mwGN4,5565
+auth/__init__.py,sha256=5GxjVbiveFzp_ul6NKkopXI7MwpDD--PBNcqrTw3oss,1282
+auth/oauth.py,sha256=faFM5gdgFmqj42BCufsiQzPjV_s-l9aidq69SHc9WhI,5740
+auth/token_manager.py,sha256=lKpQyzBn111DhB1F_EybrErPNvvRfPYpQgp5ZlDDnfk,3713
+auth/token_store.py,sha256=X0I-Zg4AKq9EL55o8Gd-pWvn8RTi3LSqk4-GQAL6Uh0,5349
+core/__init__.py,sha256=RqbfJLARs_8hpR1P5qmiYcoUdkqwspWaEeN6dBcScEQ,1414
+core/client.py,sha256=CnnZUK9sQU_ZuzCHjh6dep606crHHVLE_fuF8bzJGS0,14438
+core/config.py,sha256=OTrA0kq3bpTgYqcomB9zFgJcuqhazSKXO4lTISx6MoE,2956
+core/endpoints.py,sha256=_l8S2wu5w2uvYVd4QeeQ5duyU5oJWDUe3pPQ-WWO9eg,1612
+core/exceptions.py,sha256=xndIP033kKas0VJN7oQ1L0bFZ-zsN-s_UwpThEokb3E,1585
+core/logger.py,sha256=OtPdHNZgffsSwrEVBhSwAPwbs3_MuD3RtkQdo9-2zGk,4016
+models/__init__.py,sha256=2IwIIJAo1itAnU_RCqnvWMwEj1JYC-SXopF17YCHhh4,383
+models/base.py,sha256=_qCHmEpWBuKOajD1AFKVEMNwyw3B9WQpQqIkeROl804,308
+models/resources.py,sha256=2NXNqx3UQh1gYyQyqLzt5PFVGsdTPM6TJw979A9xKgo,2009
+parser/__init__.py,sha256=ka0WVtIT1NgzQIKPP1FESTpGjW9fFxMuPRjAikzEm3s,329
+parser/email_parser.py,sha256=c6xG4oDRJMt870r5kAgoNfvepgbgOkskGgVV1ai20PI,5807
+services/__init__.py,sha256=cEzm2U-gSb-0YmUR-hwzkNwPj2OznbFXo1Eqm-vHAxQ,879
+services/companies.py,sha256=9y2zkqv-U5Jh9k4QZyLgSmKhWNwWURZz_hWCEioyRWM,1046
+services/files.py,sha256=I_mfiEn6NII8938R1XQcM4Wfh8sFHcRcf8p9bstt5t8,9884
+services/projects.py,sha256=7IK8d_TpT0qI5q1fMHl2QFeiCt8ynu7XTnxtIFI6EBQ,2769
+services/rfis.py,sha256=jc-HrJHvtRHjd-CkZySTKfWeh9HTZqLtv7C1-byLIr0,4856
+services/submittals.py,sha256=J-hMU7l3e0NqoH5I2UtDEvheENNigYxAvIlIHi3i62E,4733
+pyprocore-1.0.0.dist-info/METADATA,sha256=cszEl4t-FObr-kTPlPYoksN4PGE7RvpxZBHrK1urSw4,6348
+pyprocore-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyprocore-1.0.0.dist-info/entry_points.txt,sha256=dLRkcqKECUJsQKG0uh6lNQxe0YCYHbXVlTZV1A9UQOM,41
+pyprocore-1.0.0.dist-info/top_level.txt,sha256=B6v51zzul23u5voBAWwqzqFQG33BPcCbr7EeGiFpn7k,37
+pyprocore-1.0.0.dist-info/RECORD,,

pyprocore-1.0.0.dist-info/WHEEL

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

pyprocore-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+procore-sdk = app:main

pyprocore-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,6 @@
+app
+auth
+core
+models
+parser
+services

services/__init__.py

@@ -0,0 +1,31 @@
+"""Service layer exports for Procore resources."""
+
+from services.companies import CompaniesService, list_companies
+from services.files import FileDownloadService, attachment_filename, download_url
+from services.projects import ProjectsService, get_project, list_projects
+from services.rfis import RFIsService, download_rfi_attachments, get_rfi, list_rfis
+from services.submittals import (
+    SubmittalsService,
+    download_submittal_attachments,
+    get_submittal,
+    list_submittals,
+)
+
+__all__ = [
+    "CompaniesService",
+    "FileDownloadService",
+    "ProjectsService",
+    "RFIsService",
+    "SubmittalsService",
+    "attachment_filename",
+    "download_rfi_attachments",
+    "download_submittal_attachments",
+    "download_url",
+    "get_project",
+    "get_rfi",
+    "get_submittal",
+    "list_companies",
+    "list_projects",
+    "list_rfis",
+    "list_submittals",
+]

services/companies.py

@@ -0,0 +1,31 @@
+"""Company service for the Procore SDK."""
+
+from __future__ import annotations
+
+from core import endpoints
+from core.client import ProcoreClient
+from models import Company
+
+
+class CompaniesService:
+    """Service for Procore company resources."""
+
+    def __init__(self, client: ProcoreClient | None = None) -> None:
+        """Initialize the service.
+
+        Args:
+            client: Optional shared Procore HTTP client.
+        """
+        self._client = client or ProcoreClient()
+
+    def list_companies(self) -> list[Company]:
+        """Return companies available to the authenticated Procore user."""
+        response = self._client.get_all(endpoints.companies())
+        if isinstance(response, list):
+            return [Company.model_validate(company) for company in response]
+        return [Company.model_validate(response)]
+
+
+def list_companies(client: ProcoreClient | None = None) -> list[Company]:
+    """Return companies available to the authenticated Procore user."""
+    return CompaniesService(client=client).list_companies()

services/files.py

@@ -0,0 +1,281 @@
+"""Shared file download helpers for Procore resources."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote, urlparse
+
+import requests
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from auth.token_manager import TokenManager
+from core.client import DEFAULT_TIMEOUT_SECONDS
+from core.exceptions import ProcoreAPIError, ValidationError
+from core.logger import get_logger, log_exception, structured_message
+
+DEFAULT_DOWNLOAD_DIR = Path(__file__).resolve().parents[1] / "downloads"
+DEFAULT_CHUNK_SIZE = 1024 * 1024
+UNSAFE_FILENAME_PATTERN = re.compile(r"[^A-Za-z0-9._ -]+")
+
+
+class FileDownloadService:
+    """Service for downloading signed Procore attachment URLs."""
+
+    def __init__(
+        self,
+        token_manager: TokenManager | None = None,
+        session: requests.Session | None = None,
+        timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+    ) -> None:
+        """Initialize the file download service.
+
+        Args:
+            token_manager: Optional token manager for bearer tokens.
+            session: Optional HTTP session for file requests.
+            timeout_seconds: Timeout for file requests.
+            chunk_size: Number of bytes written per streamed chunk.
+        """
+        self._token_manager = token_manager or TokenManager()
+        self._session = session or requests.Session()
+        self._timeout_seconds = timeout_seconds
+        self._chunk_size = chunk_size
+        self._logger = get_logger("files")
+
+    def download_url(
+        self,
+        url: str,
+        destination: Path | str,
+        *,
+        overwrite: bool = False,
+    ) -> Path:
+        """Download a signed Procore URL to a destination path.
+
+        Args:
+            url: Signed Procore attachment URL.
+            destination: Full local destination path.
+            overwrite: Whether to overwrite an existing destination file.
+
+        Returns:
+            The saved file path.
+        """
+        normalized_url = url.strip()
+        if not normalized_url:
+            raise ValidationError("Attachment URL cannot be empty.")
+
+        destination_path = Path(destination)
+        if destination_path.name in {"", ".", ".."}:
+            raise ValidationError("Attachment destination must include a filename.")
+
+        destination_path = destination_path.with_name(
+            sanitize_filename(destination_path.name)
+        )
+        if destination_path.exists() and not overwrite:
+            self._logger.info(
+                structured_message(
+                    "download_skipped",
+                    path=str(destination_path),
+                    reason="exists",
+                )
+            )
+            return destination_path
+
+        destination_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            response = self._get_with_retry(normalized_url)
+            self._raise_for_download_status(response, normalized_url)
+            self._write_stream(response, destination_path)
+        except requests.RequestException as exc:
+            log_exception(
+                self._logger,
+                exc=exc,
+                request_url=normalized_url,
+                http_status=getattr(
+                    locals().get("response", None), "status_code", None
+                ),
+                response_body=getattr(locals().get("response", None), "text", None),
+            )
+            raise ProcoreAPIError(
+                f"Attachment download failed for {normalized_url}: {exc}"
+            ) from exc
+        except Exception as exc:
+            log_exception(
+                self._logger,
+                exc=exc,
+                request_url=normalized_url,
+                http_status=getattr(
+                    locals().get("response", None), "status_code", None
+                ),
+                response_body=getattr(locals().get("response", None), "text", None),
+            )
+            raise
+
+        self._logger.info(
+            structured_message(
+                "download_complete",
+                path=str(destination_path),
+                bytes=destination_path.stat().st_size,
+            )
+        )
+        return destination_path
+
+    def download_attachment(
+        self,
+        attachment: Mapping[str, Any],
+        destination_dir: Path | str,
+        fallback_name: str,
+        *,
+        overwrite: bool = False,
+    ) -> Path | None:
+        """Download an attachment mapping that contains a ``url`` value.
+
+        Args:
+            attachment: Procore attachment metadata.
+            destination_dir: Local directory where the file should be saved.
+            fallback_name: Filename used when metadata and URL do not provide
+                one.
+            overwrite: Whether to overwrite an existing destination file.
+
+        Returns:
+            The saved file path, or ``None`` when the attachment has no URL.
+        """
+        url = attachment.get("url")
+        if not isinstance(url, str) or not url.strip():
+            return None
+
+        filename = attachment_filename(attachment, fallback_name)
+        return self.download_url(
+            url,
+            Path(destination_dir) / filename,
+            overwrite=overwrite,
+        )
+
+    def download_attachments(
+        self,
+        attachments: Iterable[Mapping[str, Any]],
+        destination_dir: Path | str,
+        *,
+        fallback_prefix: str = "attachment",
+        overwrite: bool = False,
+    ) -> list[Path]:
+        """Download multiple attachment mappings to a destination directory."""
+        downloaded_files: list[Path] = []
+        for index, attachment in enumerate(attachments, start=1):
+            downloaded_file = self.download_attachment(
+                attachment,
+                destination_dir,
+                fallback_name=f"{fallback_prefix}-{index}",
+                overwrite=overwrite,
+            )
+            if downloaded_file is not None:
+                downloaded_files.append(downloaded_file)
+        return downloaded_files
+
+    @retry(
+        retry=retry_if_exception_type((requests.RequestException, ProcoreAPIError)),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
+        stop=stop_after_attempt(3),
+        reraise=True,
+    )
+    def _get_with_retry(self, url: str) -> requests.Response:
+        """GET a signed URL with retry support."""
+        headers = {"Authorization": f"Bearer {self._token_manager.get_access_token()}"}
+        response = self._session.get(
+            url,
+            headers=headers,
+            stream=True,
+            timeout=self._timeout_seconds,
+        )
+        if response.status_code >= 500 or response.status_code == 429:
+            raise ProcoreAPIError(
+                f"Attachment download failed with status {response.status_code} for {url}",
+                status_code=response.status_code,
+                response_body=response.text,
+            )
+        return response
+
+    @staticmethod
+    def _raise_for_download_status(response: requests.Response, url: str) -> None:
+        """Raise when a download response is unsuccessful."""
+        if response.ok:
+            return
+        raise ProcoreAPIError(
+            f"Attachment download failed with status {response.status_code} for {url}",
+            status_code=response.status_code,
+            response_body=response.text,
+        )
+
+    def _write_stream(
+        self, response: requests.Response, destination_path: Path
+    ) -> None:
+        """Write a streamed response to disk in chunks."""
+        temporary_path = destination_path.with_suffix(f"{destination_path.suffix}.tmp")
+        bytes_written = 0
+        try:
+            with temporary_path.open("wb") as file_handle:
+                for chunk in response.iter_content(chunk_size=self._chunk_size):
+                    if not chunk:
+                        continue
+                    file_handle.write(chunk)
+                    bytes_written += len(chunk)
+                    self._logger.info(
+                        structured_message(
+                            "download_progress",
+                            path=str(destination_path),
+                            bytes=bytes_written,
+                        )
+                    )
+            temporary_path.replace(destination_path)
+        except OSError as exc:
+            raise ProcoreAPIError(
+                f"Unable to save attachment {destination_path}: {exc}"
+            ) from exc
+
+
+def sanitize_filename(filename: str) -> str:
+    """Return a filesystem-safe filename."""
+    candidate = Path(filename.strip()).name
+    candidate = UNSAFE_FILENAME_PATTERN.sub("_", candidate)
+    candidate = candidate.strip(" .")
+    return candidate or "attachment"
+
+
+def attachment_filename(attachment: Mapping[str, Any], fallback_name: str) -> str:
+    """Return a safe filename from attachment metadata or URL path."""
+    for key in ("filename", "file_name", "name"):
+        value = attachment.get(key)
+        if isinstance(value, str) and value.strip():
+            return sanitize_filename(value)
+
+    url = attachment.get("url")
+    if isinstance(url, str) and url.strip():
+        parsed_path = unquote(urlparse(url).path)
+        path_name = Path(parsed_path).name
+        if path_name:
+            return sanitize_filename(path_name)
+
+    return sanitize_filename(fallback_name)
+
+
+def download_url(
+    url: str,
+    destination: Path | str,
+    token_manager: TokenManager | None = None,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Download a signed Procore URL with the default file service."""
+    return FileDownloadService(token_manager=token_manager).download_url(
+        url,
+        destination,
+        overwrite=overwrite,
+    )

services/projects.py

@@ -0,0 +1,87 @@
+"""Project service for the Procore SDK."""
+
+from __future__ import annotations
+
+from core import endpoints
+from core.client import ProcoreClient
+from core.config import ProcoreSettings, get_settings
+from core.exceptions import ResourceNotFoundError, ValidationError
+from models import Project
+
+
+class ProjectsService:
+    """Service for Procore project resources."""
+
+    def __init__(
+        self,
+        client: ProcoreClient | None = None,
+        settings: ProcoreSettings | None = None,
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            client: Optional shared Procore HTTP client.
+            settings: Optional SDK settings. Used for the default company ID.
+        """
+        self._client = client or ProcoreClient()
+        self._settings = settings or get_settings()
+
+    def list_projects(self, company_id: int) -> list[Project]:
+        """Return projects for a Procore company.
+
+        Args:
+            company_id: Procore company ID.
+
+        Returns:
+            A list of project records.
+        """
+        if company_id <= 0:
+            raise ValidationError("company_id must be a positive integer.")
+
+        response = self._client.get_all(endpoints.projects(company_id))
+        if isinstance(response, list):
+            return [Project.model_validate(project) for project in response]
+        return [Project.model_validate(response)]
+
+    def get_project(self, project_id: int) -> Project:
+        """Return a single project from the configured company.
+
+        This uses the verified company projects endpoint and finds the requested
+        project locally instead of relying on an unverified single-project path.
+
+        Args:
+            project_id: Procore project ID.
+
+        Returns:
+            The matching project record.
+
+        Raises:
+            ResourceNotFoundError: If the configured company does not contain
+                the requested project.
+        """
+        if project_id <= 0:
+            raise ValidationError("project_id must be a positive integer.")
+
+        for project in self.list_projects(self._settings.company_id):
+            if project.id == project_id:
+                return project
+
+        raise ResourceNotFoundError(
+            f"Project {project_id} was not found for company {self._settings.company_id}."
+        )
+
+
+def list_projects(
+    company_id: int,
+    client: ProcoreClient | None = None,
+) -> list[Project]:
+    """Return projects for a Procore company."""
+    return ProjectsService(client=client).list_projects(company_id)
+
+
+def get_project(
+    project_id: int,
+    client: ProcoreClient | None = None,
+) -> Project:
+    """Return a single project from the configured company."""
+    return ProjectsService(client=client).get_project(project_id)

services/rfis.py

@@ -0,0 +1,147 @@
+"""RFI service for the Procore SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from core import endpoints
+from core.client import ProcoreClient
+from core.exceptions import ValidationError
+from models import RFI
+from services.files import FileDownloadService
+
+DEFAULT_DOWNLOAD_DIR = Path(__file__).resolve().parents[1] / "downloads" / "rfis"
+
+
+class RFIsService:
+    """Service for Procore RFI resources."""
+
+    def __init__(
+        self,
+        client: ProcoreClient | None = None,
+        file_service: FileDownloadService | None = None,
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            client: Optional shared Procore HTTP client.
+            file_service: Optional shared file download service.
+        """
+        self._client = client or ProcoreClient()
+        self._file_service = file_service or FileDownloadService()
+
+    def list_rfis(self, project_id: int) -> list[RFI]:
+        """Return RFIs for a Procore project."""
+        self._validate_positive_id(project_id, "project_id")
+
+        response = self._client.get_all(endpoints.rfis(project_id))
+        if isinstance(response, list):
+            return [RFI.model_validate(rfi) for rfi in response]
+        return [RFI.model_validate(response)]
+
+    def get_rfi(self, project_id: int, rfi_id: int) -> RFI:
+        """Return a single RFI for a Procore project."""
+        self._validate_positive_id(project_id, "project_id")
+        self._validate_positive_id(rfi_id, "rfi_id")
+
+        response = self._client.get(endpoints.rfi(project_id, rfi_id))
+        if not isinstance(response, dict):
+            raise ValidationError("Expected Procore RFI response to be an object.")
+        return RFI.model_validate(response)
+
+    def download_rfi_attachments(
+        self,
+        project_id: int,
+        rfi_id: int,
+        destination_dir: Path | str | None = None,
+    ) -> list[Path]:
+        """Download all attachments from an RFI's questions.
+
+        RFI attachment URLs are read from ``questions[].attachments[].url``.
+
+        Args:
+            project_id: Procore project ID.
+            rfi_id: Procore RFI ID.
+            destination_dir: Optional directory to save files. Defaults to
+                ``downloads/rfis/{rfi_id}``.
+
+        Returns:
+            Paths to downloaded files.
+        """
+        rfi = self.get_rfi(project_id, rfi_id)
+        attachments = self._extract_question_attachments(rfi.model_dump())
+        output_dir = (
+            Path(destination_dir)
+            if destination_dir
+            else DEFAULT_DOWNLOAD_DIR / str(rfi_id)
+        )
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        return self._file_service.download_attachments(
+            attachments,
+            output_dir,
+            fallback_prefix=f"rfi-{rfi_id}",
+        )
+
+    @staticmethod
+    def _extract_question_attachments(rfi: Mapping[str, Any]) -> list[dict[str, Any]]:
+        """Extract ``questions[].attachments[]`` dictionaries from an RFI."""
+        questions = rfi.get("questions", [])
+        if not isinstance(questions, Sequence) or isinstance(questions, (str, bytes)):
+            return []
+
+        attachments: list[dict[str, Any]] = []
+        for question in questions:
+            if not isinstance(question, Mapping):
+                continue
+
+            question_attachments = question.get("attachments", [])
+            if not isinstance(question_attachments, Sequence) or isinstance(
+                question_attachments,
+                (str, bytes),
+            ):
+                continue
+
+            attachments.extend(
+                dict(attachment)
+                for attachment in question_attachments
+                if isinstance(attachment, Mapping)
+            )
+
+        return attachments
+
+    @staticmethod
+    def _validate_positive_id(value: int, name: str) -> None:
+        """Validate Procore integer identifiers."""
+        if value <= 0:
+            raise ValidationError(f"{name} must be a positive integer.")
+
+
+def list_rfis(project_id: int, client: ProcoreClient | None = None) -> list[RFI]:
+    """Return RFIs for a Procore project."""
+    return RFIsService(client=client).list_rfis(project_id)
+
+
+def get_rfi(
+    project_id: int,
+    rfi_id: int,
+    client: ProcoreClient | None = None,
+) -> RFI:
+    """Return a single RFI for a Procore project."""
+    return RFIsService(client=client).get_rfi(project_id, rfi_id)
+
+
+def download_rfi_attachments(
+    project_id: int,
+    rfi_id: int,
+    destination_dir: Path | str | None = None,
+    client: ProcoreClient | None = None,
+) -> list[Path]:
+    """Download all attachments from an RFI's questions."""
+    return RFIsService(client=client).download_rfi_attachments(
+        project_id,
+        rfi_id,
+        destination_dir,
+    )