Python Utilities

A collection of useful Python scripts for various tasks.

• Python Utilities
  • Modules
    • Image Conversion
    • PDF Conversion
    • JSON to Excel
    • Pydantic AI
    • Transcription
  • Getting Started
    • Prerequisites
    • Installation and Setup
  • Usage
    • CLI Commands
    • Python API

Modules

Image Conversion

• src/python_utils/image/convert_pdf_image.py: Converts PDF files to PNG images. It uses PyMuPDF to render PDF pages into high-resolution images (300 DPI). The script preserves the directory structure of the source PDFs.

PDF Conversion

• src/python_utils/pdf/convert_docs_to_pdf.py: Converts .doc and .docx files to PDF format using LibreOffice. It recursively searches for documents in a given directory and converts them in place.

JSON to Excel

• src/python_utils/json2excel/json_to_excel.py: Converts JSON files with nested structures to Excel spreadsheets with a flattened tabular format. Supports both single file and batch directory conversion.

Pydantic AI

• src/python_utils/pydanticai/init_google_agent.py: Initializes a Pydantic AI agent with a Google language model (e.g., Gemini). It handles loading Google Cloud credentials and configuring the agent with specific model settings.

Transcription

• src/python_utils/transcription/transcribe_diarize.py: Transcribes local audio and writes Markdown, TXT, and JSON transcript files with approximate speaker labels. Transcription dependencies are optional because they are heavier and platform-sensitive.

Getting Started

Prerequisites

• Python 3.12+
• LibreOffice needs to be installed and in your system's PATH for the .doc/.docx to PDF conversion.
• Google Cloud credentials for the Pydantic AI agent.
• ffmpeg needs to be installed and in your system's PATH for audio transcription.

Installation and Setup

1. Clone the repository:

   git clone https://github.com/mfmezger/python_utils.git
   cd python_utils

2. Install dependencies: This project uses uv for package management.

   pip install uv
   uv sync

   To include optional transcription dependencies:

   uv sync --extra transcription

3. Set up pre-commit hooks: This project uses pre-commit to enforce code quality.

   pre-commit install

Usage

CLI Commands

After installation, use the python-utils CLI:

# Convert JSON to Excel
python-utils json2excel input.json -o output.xlsx
python-utils json2excel ./json_directory/ -o ./excel_output/

# Convert PDFs to images
python-utils pdf2image ./pdfs/ ./images/

# Convert .doc/.docx to PDF
python-utils doc2pdf ./documents/

# Transcribe local audio with approximate speaker labels
python-utils transcribe audio.m4a --engine mlx --model small --language de

# Show help
python-utils --help

Python API

Import modules directly in your code:

# Image conversion
from python_utils.image import convert_pdfs

convert_pdfs(src_root="./pdfs", dest_root="./images")

# JSON to Excel
from python_utils.json2excel import convert_json_to_excel

convert_json_to_excel(Path("data.json"), Path("output.xlsx"))

# Document to PDF
from python_utils.pdf import convert_docs_to_pdf

convert_docs_to_pdf("./documents")

# Pydantic AI Agent
from python_utils.pydanticai import initialize_agent

agent = initialize_agent(
    prompt="You are a helpful assistant.",
    output_model=MyOutputModel,
)

# Local transcription
from python_utils.transcription import transcribe_file

segments = transcribe_file(
    Path("audio.m4a"),
    model_size="small",
    engine="mlx",
    language="de",
)

License

MIT License - see LICENSE for details.