pyprocore 1.0.0__py3-none-any.whl

core/logger.py

@@ -0,0 +1,141 @@
+"""Centralized structured logging utilities for the Procore SDK."""
+
+from __future__ import annotations
+
+import json
+import logging
+import traceback
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+LOGGER_NAME = "procore_sdk"
+LOG_DIR = Path(__file__).resolve().parents[1] / "logs"
+SDK_LOG_FILE = LOG_DIR / "sdk.log"
+ERROR_LOG_FILE = LOG_DIR / "errors.log"
+DEFAULT_LOG_FORMAT = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+
+SENSITIVE_KEYS = {
+    "authorization",
+    "access_token",
+    "refresh_token",
+    "client_secret",
+}
+
+
+def ensure_log_directory() -> Path:
+    """Create and return the SDK log directory."""
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    return LOG_DIR
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a configured SDK logger.
+
+    Args:
+        name: Optional child logger name.
+
+    Returns:
+        A configured SDK ``logging.Logger`` instance.
+    """
+    ensure_log_directory()
+    logger_name = LOGGER_NAME if name is None else f"{LOGGER_NAME}.{name}"
+    logger = logging.getLogger(logger_name)
+
+    if not any(
+        getattr(handler, "_procore_sdk_handler", False) for handler in logger.handlers
+    ):
+        formatter = logging.Formatter(DEFAULT_LOG_FORMAT)
+
+        stream_handler = logging.StreamHandler()
+        stream_handler.setFormatter(formatter)
+        stream_handler._procore_sdk_handler = True  # type: ignore[attr-defined]
+
+        sdk_file_handler = logging.FileHandler(SDK_LOG_FILE, encoding="utf-8")
+        sdk_file_handler.setFormatter(formatter)
+        sdk_file_handler._procore_sdk_handler = True  # type: ignore[attr-defined]
+
+        error_file_handler = logging.FileHandler(ERROR_LOG_FILE, encoding="utf-8")
+        error_file_handler.setLevel(logging.ERROR)
+        error_file_handler.setFormatter(formatter)
+        error_file_handler._procore_sdk_handler = True  # type: ignore[attr-defined]
+
+        logger.addHandler(stream_handler)
+        logger.addHandler(sdk_file_handler)
+        logger.addHandler(error_file_handler)
+
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+    return logger
+
+
+def sanitize_log_value(value: Any) -> Any:
+    """Return a log-safe version of a value."""
+    if isinstance(value, dict):
+        return {
+            key: (
+                "[REDACTED]"
+                if key.lower() in SENSITIVE_KEYS
+                else sanitize_log_value(item)
+            )
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [sanitize_log_value(item) for item in value]
+    return value
+
+
+def structured_message(event: str, **fields: Any) -> str:
+    """Return a compact JSON log message."""
+    payload = {
+        "event": event,
+        "timestamp": datetime.now(tz=UTC).isoformat(),
+        **sanitize_log_value(fields),
+    }
+    return json.dumps(payload, default=str, sort_keys=True)
+
+
+def log_api_request(
+    logger: logging.Logger,
+    *,
+    method: str,
+    endpoint: str,
+    status_code: int | None,
+    elapsed_ms: float,
+    retry_count: int = 0,
+) -> None:
+    """Log structured metadata for an API request."""
+    logger.info(
+        structured_message(
+            "api_request",
+            method=method,
+            endpoint=endpoint,
+            status_code=status_code,
+            elapsed_ms=round(elapsed_ms, 2),
+            retry_count=retry_count,
+        )
+    )
+
+
+def log_exception(
+    logger: logging.Logger,
+    *,
+    exc: BaseException,
+    request_url: str | None = None,
+    http_status: int | None = None,
+    response_body: Any | None = None,
+) -> None:
+    """Log a structured exception record with stack trace."""
+    logger.error(
+        structured_message(
+            "exception",
+            exception_type=type(exc).__name__,
+            request_url=request_url,
+            http_status=http_status,
+            response_body=response_body,
+            stack_trace="".join(traceback.format_exception(exc)),
+        )
+    )
+
+
+logger = get_logger()

models/__init__.py

@@ -0,0 +1,25 @@
+"""Typed response models for Procore resources."""
+
+from models.base import ProcoreModel
+from models.resources import (
+    Attachment,
+    Company,
+    Project,
+    RFI,
+    RFIQuestion,
+    Status,
+    Submittal,
+    User,
+)
+
+__all__ = [
+    "Attachment",
+    "Company",
+    "ProcoreModel",
+    "Project",
+    "RFI",
+    "RFIQuestion",
+    "Status",
+    "Submittal",
+    "User",
+]

models/base.py

@@ -0,0 +1,11 @@
+"""Base model primitives for Procore response models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ProcoreModel(BaseModel):
+    """Base model that preserves unknown Procore response fields."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)

models/resources.py

@@ -0,0 +1,86 @@
+"""Typed Pydantic models for common Procore resources."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, HttpUrl
+
+from models.base import ProcoreModel
+
+
+class Status(ProcoreModel):
+    """Status metadata returned by Procore resources."""
+
+    id: int | None = None
+    name: str | None = None
+    status: str | None = None
+
+
+class User(ProcoreModel):
+    """Procore user summary."""
+
+    id: int | None = None
+    name: str | None = None
+    login: str | None = None
+    email_address: str | None = None
+
+
+class Attachment(ProcoreModel):
+    """Attachment metadata with a signed download URL."""
+
+    id: int | None = None
+    name: str | None = None
+    filename: str | None = None
+    file_name: str | None = None
+    url: str | HttpUrl | None = None
+    content_type: str | None = None
+
+
+class Company(ProcoreModel):
+    """Procore company resource."""
+
+    id: int
+    name: str | None = None
+
+
+class Project(ProcoreModel):
+    """Procore project resource."""
+
+    id: int
+    name: str | None = None
+    project_number: str | None = None
+    active: bool | None = None
+    company: Company | None = None
+
+
+class RFIQuestion(ProcoreModel):
+    """Question nested under a Procore RFI."""
+
+    id: int | None = None
+    body: str | None = None
+    plain_text_body: str | None = None
+    attachments: list[Attachment] = Field(default_factory=list)
+
+
+class RFI(ProcoreModel):
+    """Procore RFI resource."""
+
+    id: int
+    number: str | int | None = None
+    subject: str | None = None
+    status: Status | str | None = None
+    assignee: User | None = None
+    created_by: User | None = None
+    questions: list[RFIQuestion] = Field(default_factory=list)
+
+
+class Submittal(ProcoreModel):
+    """Procore submittal resource."""
+
+    id: int
+    number: str | int | None = None
+    title: str | None = None
+    status: Status | str | None = None
+    responsible_contractor: dict[str, Any] | None = None
+    attachments: list[Attachment] = Field(default_factory=list)

parser/__init__.py

@@ -0,0 +1,17 @@
+"""Parser utilities for Procore automation workflows."""
+
+from parser.email_parser import (
+    EmailParser,
+    ParsedEmail,
+    ParsedEmailAttachment,
+    parse_email_file,
+    parse_email_text,
+)
+
+__all__ = [
+    "EmailParser",
+    "ParsedEmail",
+    "ParsedEmailAttachment",
+    "parse_email_file",
+    "parse_email_text",
+]

parser/email_parser.py

@@ -0,0 +1,165 @@
+"""Email parsing utilities for future Procore automation workflows."""
+
+from __future__ import annotations
+
+from email import policy
+from email.message import EmailMessage, Message
+from email.parser import BytesParser, Parser
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class ParsedEmailAttachment(BaseModel):
+    """Metadata for an attachment found in an email message."""
+
+    filename: str
+    content_type: str
+    size_bytes: int = Field(ge=0)
+
+
+class ParsedEmail(BaseModel):
+    """Structured representation of an email message."""
+
+    subject: str | None = None
+    sender: str | None = None
+    recipients: list[str] = Field(default_factory=list)
+    cc: list[str] = Field(default_factory=list)
+    date: str | None = None
+    text_body: str | None = None
+    html_body: str | None = None
+    attachments: list[ParsedEmailAttachment] = Field(default_factory=list)
+
+
+class EmailParser:
+    """Parse raw email messages into structured data."""
+
+    def parse_file(self, path: Path | str) -> ParsedEmail:
+        """Parse an email message from a file path.
+
+        Args:
+            path: Path to a raw ``.eml`` style email file.
+
+        Returns:
+            Parsed email data.
+        """
+        message_path = Path(path)
+        with message_path.open("rb") as file_handle:
+            message = BytesParser(policy=policy.default).parse(file_handle)
+        return self.parse_message(message)
+
+    def parse_text(self, raw_email: str) -> ParsedEmail:
+        """Parse an email message from raw text."""
+        message = Parser(policy=policy.default).parsestr(raw_email)
+        return self.parse_message(message)
+
+    def parse_bytes(self, raw_email: bytes) -> ParsedEmail:
+        """Parse an email message from raw bytes."""
+        message = BytesParser(policy=policy.default).parsebytes(raw_email)
+        return self.parse_message(message)
+
+    def parse_message(self, message: Message) -> ParsedEmail:
+        """Parse an ``email.message.Message`` object."""
+        text_body, html_body = self._extract_bodies(message)
+        return ParsedEmail(
+            subject=self._header_value(message, "subject"),
+            sender=self._header_value(message, "from"),
+            recipients=self._split_addresses(message.get_all("to", [])),
+            cc=self._split_addresses(message.get_all("cc", [])),
+            date=self._header_value(message, "date"),
+            text_body=text_body,
+            html_body=html_body,
+            attachments=self._extract_attachments(message),
+        )
+
+    @staticmethod
+    def _extract_bodies(message: Message) -> tuple[str | None, str | None]:
+        """Extract plain text and HTML body content from a message."""
+        text_body: str | None = None
+        html_body: str | None = None
+
+        if message.is_multipart():
+            for part in message.walk():
+                if (
+                    part.is_multipart()
+                    or part.get_content_disposition() == "attachment"
+                ):
+                    continue
+
+                content_type = part.get_content_type()
+                payload = EmailParser._part_text(part)
+                if content_type == "text/plain" and text_body is None:
+                    text_body = payload
+                elif content_type == "text/html" and html_body is None:
+                    html_body = payload
+        else:
+            payload = EmailParser._part_text(message)
+            if message.get_content_type() == "text/html":
+                html_body = payload
+            else:
+                text_body = payload
+
+        return text_body, html_body
+
+    @staticmethod
+    def _extract_attachments(message: Message) -> list[ParsedEmailAttachment]:
+        """Return attachment metadata without writing files to disk."""
+        attachments: list[ParsedEmailAttachment] = []
+        for part in message.walk():
+            if part.get_content_disposition() != "attachment":
+                continue
+
+            filename = part.get_filename()
+            if not filename:
+                filename = "attachment"
+
+            payload = part.get_payload(decode=True) or b""
+            attachments.append(
+                ParsedEmailAttachment(
+                    filename=Path(filename).name,
+                    content_type=part.get_content_type(),
+                    size_bytes=len(payload),
+                )
+            )
+
+        return attachments
+
+    @staticmethod
+    def _part_text(part: Message) -> str | None:
+        """Decode a message part into text when possible."""
+        if hasattr(part, "get_content"):
+            content = part.get_content()
+            return content if isinstance(content, str) else None
+
+        payload = part.get_payload(decode=True)
+        if payload is None:
+            return None
+
+        charset = part.get_content_charset() or "utf-8"
+        return payload.decode(charset, errors="replace")
+
+    @staticmethod
+    def _header_value(message: Message, name: str) -> str | None:
+        """Return a header as a string when present."""
+        value = message.get(name)
+        return str(value) if value is not None else None
+
+    @staticmethod
+    def _split_addresses(values: list[str]) -> list[str]:
+        """Split comma-separated address headers into normalized strings."""
+        addresses: list[str] = []
+        for value in values:
+            addresses.extend(
+                part.strip() for part in str(value).split(",") if part.strip()
+            )
+        return addresses
+
+
+def parse_email_file(path: Path | str) -> ParsedEmail:
+    """Parse an email message from a file path."""
+    return EmailParser().parse_file(path)
+
+
+def parse_email_text(raw_email: str) -> ParsedEmail:
+    """Parse an email message from raw text."""
+    return EmailParser().parse_text(raw_email)

pyprocore-1.0.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: pyprocore
+Version: 1.0.0
+Summary: Production-ready Python SDK foundation for the Procore REST API.
+Author-email: Author Placeholder <author@example.com>
+License: Proprietary - placeholder
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.3
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: tenacity>=8.5.0
+Provides-Extra: dev
+Requires-Dist: black>=24.10.0; extra == "dev"
+Requires-Dist: coverage>=7.6.0; extra == "dev"
+Requires-Dist: flake8>=7.1.0; extra == "dev"
+Requires-Dist: isort>=5.13.2; extra == "dev"
+Requires-Dist: mypy>=1.13.0; extra == "dev"
+Requires-Dist: types-requests>=2.32.0; extra == "dev"
+
+# Procore SDK
+
+Production-quality Python SDK and automation foundation for the Procore REST API.
+
+The SDK handles configuration, OAuth token refresh, authenticated HTTP requests,
+pagination, typed response models, structured logging, and attachment downloads
+for companies, projects, RFIs, and submittals.
+
+## Installation
+
+Requires Python 3.12+.
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -r requirements.txt
+```
+
+## Configuration
+
+Copy the example file and fill in real values:
+
+```bash
+cp .env.example .env
+```
+
+Required variables:
+
+```bash
+PROCORE_CLIENT_ID=your_client_id
+PROCORE_CLIENT_SECRET=your_client_secret
+PROCORE_REDIRECT_URI=http://localhost:8080/callback
+PROCORE_LOGIN_URL=https://login.procore.com
+PROCORE_API_BASE=https://api.procore.com
+PROCORE_COMPANY_ID=123456
+```
+
+Secrets, tokens, URLs, and company IDs are never hardcoded in source.
+
+## Authentication
+
+Exchange the first authorization code and save the token locally:
+
+```python
+from auth.oauth import exchange_authorization_code
+from auth.token_manager import TokenManager
+
+token_response = exchange_authorization_code("authorization-code-from-procore")
+TokenManager().save_oauth_response(token_response)
+```
+
+After that, SDK clients call:
+
+```python
+from auth.token_manager import get_access_token
+
+access_token = get_access_token()
+```
+
+Expired access tokens refresh automatically when a refresh token is available.
+
+## CLI Examples
+
+```bash
+.venv/bin/python app.py companies
+.venv/bin/python app.py projects
+.venv/bin/python app.py rfis --project 352338
+.venv/bin/python app.py rfi --project 352338 --id 102784
+.venv/bin/python app.py submittals --project 352338
+.venv/bin/python app.py submittal --project 352338 --id 309641
+.venv/bin/python app.py download-rfi --project 352338 --id 102784
+.venv/bin/python app.py download-submittal --project 352338 --id 309641
+```
+
+The CLI prints nicely formatted JSON. Typed SDK models are serialized with
+`model_dump(mode="json")`.
+
+## SDK Examples
+
+```python
+from services import (
+    download_rfi_attachments,
+    download_submittal_attachments,
+    get_rfi,
+    get_submittal,
+    list_companies,
+    list_projects,
+    list_rfis,
+    list_submittals,
+)
+
+companies = list_companies()
+projects = list_projects(company_id=123456)
+
+rfis = list_rfis(project_id=352338)
+rfi = get_rfi(project_id=352338, rfi_id=102784)
+first_attachment_url = rfi.questions[0].attachments[0].url
+
+submittals = list_submittals(project_id=352338)
+submittal = get_submittal(project_id=352338, submittal_id=309641)
+```
+
+All typed models can be serialized back to JSON:
+
+```python
+json_payload = rfi.model_dump(mode="json")
+json_string = rfi.model_dump_json()
+```
+
+## Downloading Attachments
+
+RFI attachments are read from:
+
+```text
+questions[].attachments[].url
+```
+
+Submittal attachments are read from:
+
+```text
+attachments[].url
+```
+
+Download from services:
+
+```python
+rfi_files = download_rfi_attachments(project_id=352338, rfi_id=102784)
+submittal_files = download_submittal_attachments(
+    project_id=352338,
+    submittal_id=309641,
+)
+```
+
+The shared file service supports safe filenames, streaming writes, retries,
+progress logging, batch downloads, and skip-existing behavior by default.
+
+```python
+from services.files import FileDownloadService
+
+files = FileDownloadService().download_attachments(
+    attachments,
+    "downloads/custom",
+    fallback_prefix="attachment",
+    overwrite=False,
+)
+```
+
+## Pagination
+
+Collection service methods use `ProcoreClient.get_all()`, which follows Procore
+pagination headers automatically. Business logic should call the service method
+or `get_all()` and should not manually request page 2.
+
+## Logging
+
+The SDK writes structured logs to:
+
+```text
+logs/sdk.log
+logs/errors.log
+```
+
+API request logs include method, endpoint, response status, elapsed time, and
+retry count. Exception logs include stack traces, exception type, request URL,
+HTTP status, and response body when available.
+
+The logger redacts sensitive keys such as authorization headers, access tokens,
+refresh tokens, and client secrets.
+
+## Architecture
+
+- `auth/`: OAuth exchange, token persistence, token refresh
+- `core/`: configuration, endpoint paths, HTTP client, logging, exceptions
+- `models/`: Pydantic response models
+- `services/`: company, project, RFI, submittal, and file services
+- `parser/`: email parsing utilities for future automation
+- `tests/`: mocked unit tests with no live Procore dependency
+
+## Verified Endpoint Assumptions
+
+- `GET /rest/v1.0/companies`
+- `GET /rest/v1.0/companies/{company_id}/projects`
+- `GET /rest/v1.1/projects/{project_id}/rfis`
+- `GET /rest/v1.1/projects/{project_id}/rfis/{rfi_id}`
+- `GET /rest/v1.1/projects/{project_id}/submittals`
+- `GET /rest/v1.1/projects/{project_id}/submittals/{submittal_id}`
+
+## Troubleshooting
+
+`ConfigurationError`
+: Check that `.env` exists and all required keys are present.
+
+`AuthenticationError`
+: Complete the first OAuth code exchange and confirm `auth/token_store.json`
+contains a refresh token.
+
+`AuthorizationError`
+: Confirm the Procore user has access to the target company/project/resource.
+
+`ResourceNotFoundError`
+: Confirm project, RFI, or submittal IDs are correct for the configured company.
+
+Attachment files are not downloading
+: Check `logs/errors.log` for HTTP status and response body details. Existing
+files are skipped unless `overwrite=True`.
+
+## Tests
+
+Run unit tests:
+
+```bash
+.venv/bin/python -m unittest discover -s tests
+```
+
+Run coverage:
+
+```bash
+.venv/bin/python -m coverage run -m unittest discover -s tests
+.venv/bin/python -m coverage report
+```
+