py-pdf

API w FastAPI do:

• scalania PDF-ów,
• dzielenia PDF-ów na strony,
• uploadu rozbitych stron na Google Drive,
• inspekcji folderów Google Drive z PDF-ami,
• uruchamiania długich inspekcji w tle jako joby.

Serwer działa z pliku main.py.

Wymagania

• Python 3.11+
• client_secrets.json dla Google OAuth
• zmienne środowiskowe API_AUTH_TOKEN i AUTH_USERS_JSON

Aplikacja ładuje .env przy starcie. Przy pierwszym użyciu operacji Google Drive utworzy lokalny token.json.

Szybki start

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

Domyślny adres:

http://localhost:5555

Swagger:

http://localhost:5555/docs

Konfiguracja

Minimalny .env:

API_AUTH_TOKEN=super-sekretowy-token
AUTH_USERS_JSON="{\"admin\":{\"password\":\"twoje-haslo\",\"display_name\":\"Administrator\"}}"
FRONTEND_URL=http://localhost:5173

Obsługiwane zmienne:

• API_AUTH_TOKEN - globalny token Bearer dla integracji serwisowych
• AUTH_USERS_JSON - konta do POST /auth/login w formacie JSON
• FRONTEND_URL - dodatkowy origin dopisywany do CORS

Przykład AUTH_USERS_JSON z dwoma kontami:

{
  "admin": {
    "password": "haslo-admina",
    "display_name": "Administrator"
  }

Uwierzytelnianie

Publiczne są tylko:

• GET /health
• POST /auth/login

Pozostałe endpointy wymagają:

Authorization: Bearer <API_AUTH_TOKEN>

Alternatywnie frontend może zalogować użytkownika przez POST /auth/login i używać zwróconego access_token jako Bearer tokenu sesyjnego.

Google Drive

Operacje Drive używają OAuth użytkownika i plików:

• client_secrets.json
• token.json

Konto zapisane w token.json wykonuje wszystkie operacje na Google Drive.

Docker

Budowanie:

docker build -t py-pdf .

Uruchomienie:

docker run --rm -p 5555:5555 -e API_AUTH_TOKEN=super-sekretowy-token -e AUTH_USERS_JSON="{\"admin\":{\"password\":\"twoje-haslo\",\"display_name\":\"Administrator\"}}" py-pdf

Compose:

docker compose up --build

Endpointy

GET /health

Prosty healthcheck:

{
  "status": "ok"
}

POST /auth/login

Logowanie użytkownika z AUTH_USERS_JSON.

Body:

{
  "username": "admin",
  "password": "twoje-haslo"
}

Odpowiedź:

{
  "access_token": "SESSION_TOKEN",
  "token_type": "bearer",
  "user": {
    "username": "admin",
    "display_name": "Administrator"
  }
}

POST /pdf-tools

Zbiorczy endpoint dla uploadowanych PDF-ów.

multipart/form-data:

• operation: merge albo split
• files: jeden lub wiele plików PDF

Zachowanie:

• merge zwraca merged.pdf
• split zwraca split_pdf.zip

POST /split-pdf-file

Rozbija jeden uploadowany PDF do ZIP-a.

multipart/form-data:

• file: jeden PDF

Odpowiedź: <nazwa>_split.zip

POST /split-pdf-upload

Rozbija uploadowany PDF i wgrywa strony na Google Drive.

multipart/form-data:

• folder_id
• file

Zwraca metadane utworzonych plików i dimensions_table_html.

POST /split-pdf

Rozbija PDF już istniejący na Google Drive.

Body:

{
  "file_id": "GOOGLE_DRIVE_FILE_ID",
  "folder_id": "GOOGLE_DRIVE_PARENT_FOLDER_ID"
}

Tworzy nowy podfolder na Drive, zapisuje tam strony jako osobne PDF-y i zwraca:

• dane folderu docelowego,
• listę stron,
• dimensions_table_html

POST /split-pdf-legacy

Starszy wariant split-pdf.

Różnica:

• nie tworzy nowego podfolderu,
• zapisuje pliki bezpośrednio do podanego folder_id,
• zwraca samą listę stron.

POST /inspect-drive-folder

Synchroniczna inspekcja folderu Google Drive.

Body:

{
  "folder_link": "https://drive.google.com/drive/folders/..."
}

folder_link może być:

• pełnym linkiem,
• linkiem z id=...,
• samym folder_id

Wynik zawiera listę znalezionych PDF-ów, ścieżki folderów, liczbę stron i wymiary stron w mm.

POST /inspect-drive-folder/jobs

Tworzy asynchroniczny job inspekcji i zwraca:

• job_id
• status
• status_url
• result_url

GET /inspect-drive-folder/jobs

Zwraca listę zapisanych jobów z job_data.

GET /inspect-drive-folder/jobs/{job_id}

Zwraca status i postęp joba.

Statusy:

• queued
• running
• completed
• failed
• cancelled

POST /inspect-drive-folder/jobs/{job_id}/cancel

Zleca miękkie anulowanie joba.

GET /inspect-drive-folder/jobs/{job_id}/result

Zwraca wynik joba:

• 200 gdy job jest zakończony,
• 409 gdy nadal trwa,
• 500 gdy zakończył się błędem,
• dla cancelled zwraca wynik częściowy, jeśli powstał.

Przykłady

Logowanie:

curl.exe -X POST "http://localhost:5555/auth/login" `
  -H "Content-Type: application/json" `
  -d "{\"username\":\"admin\",\"password\":\"twoje-haslo\"}"

Start joba inspekcji:

curl.exe -X POST "http://localhost:5555/inspect-drive-folder/jobs" `
  -H "Authorization: Bearer super-sekretowy-token" `
  -H "Content-Type: application/json" `
  -d "{\"folder_link\":\"https://drive.google.com/drive/folders/FOLDER_ID\"}"

Pobranie statusu joba:

curl.exe "http://localhost:5555/inspect-drive-folder/jobs/TWOJ_JOB_ID" `
  -H "Authorization: Bearer super-sekretowy-token"