python-pdf2txt

python-pdf2txt is a Dockerized Python application designed to convert PDF files into editable Word documents. The application utilizes Flask to expose a web service that handles PDF file uploads through HTTP requests and returns the converted DOCX files using OCR technology.

Features

• PDF to Word Conversion: Transforms PDF documents into DOCX format using advanced OCR capabilities.
• Dockerized Application: Facilitates easy deployment and consistent performance across various environments.
• REST API: Simple API for straightforward integration, supporting PDF uploads and DOCX retrievals.

Getting Started

Step 1: Clone the Repository

Clone the repository to your local machine to get started:

git clone https://github.com/your-username/python-pdf2txt.git
cd python-pdf2txt

Step 2: Build and Run the Docker Container

Use Docker Compose to build and run your container:

docker-compose up --build -d

This command constructs the Docker image if it hasn't been built previously and runs the container in detached mode. The service will be available at localhost on port 4000.

Step 3: Convert a PDF to Word

Convert a PDF to a Word document by executing the following curl command:

curl -X POST -F "file=@path_to_your_pdf_file.pdf" http://localhost:4000/upload-pdf --output converted.docx

Make sure to replace path_to_your_pdf_file.pdf with the actual path to the PDF you intend to convert. The output will be saved as converted.docx.

Step 4: View Application Logs

To track the application's processes in real-time, you can view the logs:

tail -f ./logs/*

This command tails the log files, offering a live view into the application’s operational logs.

New Features

Callback URL Support

The application now includes the ability to process PDF to Word conversions asynchronously. Once the conversion process is complete, the converted .docx file is sent to a specified callback URL. This feature allows the processing to occur in the background, freeing up clients to perform other tasks rather than waiting for a synchronous response.

Updated Usage Instructions

Asynchronous Conversion with Callback URL

1. Trigger the Conversion: To request a PDF conversion and have the application send the resulting .docx file to a callback URL once processing is done, use the curl command as follows:

   curl -X POST -F "file=@path_to_your_pdf_file.pdf" \
        -F "callback_url=http://<your-callback-url>/callback" \
        http://localhost:4000/upload-pdf
   

   Replace path_to_your_pdf_file.pdf with the path to your actual PDF file, and <your-callback-url> with your service's callback URL.

2. Callback Server Setup: Prepare your callback server to handle incoming POST requests at the /callback endpoint. The server should process the incoming .docx file as per your application's logic.

Example Callback Endpoint

Here's an example Flask route that could serve as your callback endpoint:

@app.route('/callback', methods=['POST'])
def callback():
    file = request.files['file']
    # Implement file handling logic here
    return jsonify({'message': 'File received successfully'}), 200

This endpoint will be invoked with the converted .docx file after the PDF conversion is complete.

Test Command for Callback Feature

To test the callback functionality, you can use the following curl command. This will send a PDF file to the /upload-pdf endpoint along with a callback_url. After the PDF is processed, the application will send the converted .docx file to the provided callback URL:

curl -X POST -F "file=@uploads/sample_input.pdf" \
     -F "callback_url=http://localhost:5000/callback" \
     http://localhost:4000/upload-pdf

Be sure to replace http://localhost:5000/callback with your actual callback endpoint that's ready to accept the file.

Configuration Details

Environment Variables

The application uses several environment variables to configure its behavior:

• FLASK_ENV: Sets the environment for the Flask application. In this case, development for enabling debug features.
• FLASK_APP: Points to the entry file of the Flask application. Here, it's set to app.py.
• TESSDATA_PREFIX: Specifies the directory where the Tesseract OCR data is stored, which is crucial for OCR functionality.

Port Configuration

The Docker container is configured to expose the Flask application on port 4000 of the host machine, mapping it to port 5000 inside the container. This mapping is defined in the docker-compose.yml file, allowing the application to be accessible via http://localhost:4000.

Volume Management

• Uploads Folder: The ./uploads folder on the host is mapped to /app/uploads inside the Docker container. This is where uploaded PDF files are stored temporarily during processing.
• Outputs Folder: Similarly, the ./outputs folder on the host is mapped to /app/outputs inside the container. This folder stores the converted Word documents, making them accessible outside the container.
• Logs Folder: The ./logs folder is used to store log files generated by the application, providing insights into its operations and any errors.

This setup ensures that data persists across container restarts and is easily accessible for both inputs and outputs.