Metadata-Version: 2.4
Name: pyxtxt
Version: 0.2.4.1
Summary: A Python library for extracting text from different types of files (PDF, DOCX, PPTX, XLSX, ODT, ecc.).
Author-email: Giuseppe Levi <giuseppe.levi@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Giuseppe Levi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-magic; sys_platform != "win32"
Requires-Dist: python-magic-bin; sys_platform == "win32"
Provides-Extra: pdf
Requires-Dist: PyMuPDF; extra == "pdf"
Provides-Extra: docx
Requires-Dist: python-docx; extra == "docx"
Provides-Extra: presentation
Requires-Dist: python-pptx; extra == "presentation"
Provides-Extra: spreadsheet
Requires-Dist: openpyxl; extra == "spreadsheet"
Requires-Dist: xlrd; extra == "spreadsheet"
Provides-Extra: odf
Requires-Dist: odfpy; extra == "odf"
Provides-Extra: html
Requires-Dist: beautifulsoup4; extra == "html"
Requires-Dist: lxml; extra == "html"
Provides-Extra: doc
Requires-Dist: textract; extra == "doc"
Provides-Extra: markdown
Requires-Dist: markdown; extra == "markdown"
Requires-Dist: beautifulsoup4; extra == "markdown"
Provides-Extra: epub
Requires-Dist: ebooklib; extra == "epub"
Requires-Dist: beautifulsoup4; extra == "epub"
Provides-Extra: rtf
Requires-Dist: striprtf; extra == "rtf"
Provides-Extra: email
Requires-Dist: beautifulsoup4; extra == "email"
Provides-Extra: outlook
Requires-Dist: extract-msg; extra == "outlook"
Requires-Dist: beautifulsoup4; extra == "outlook"
Provides-Extra: latex
Requires-Dist: pylatexenc; extra == "latex"
Provides-Extra: audio
Requires-Dist: openai-whisper; extra == "audio"
Provides-Extra: ocr
Requires-Dist: easyocr; extra == "ocr"
Requires-Dist: pillow; extra == "ocr"
Provides-Extra: all
Requires-Dist: textract; extra == "all"
Requires-Dist: PyMuPDF; extra == "all"
Requires-Dist: python-docx; extra == "all"
Requires-Dist: python-pptx; extra == "all"
Requires-Dist: openpyxl; extra == "all"
Requires-Dist: xlrd; extra == "all"
Requires-Dist: odfpy; extra == "all"
Requires-Dist: beautifulsoup4; extra == "all"
Requires-Dist: lxml; extra == "all"
Requires-Dist: markdown; extra == "all"
Requires-Dist: ebooklib; extra == "all"
Requires-Dist: striprtf; extra == "all"
Requires-Dist: extract-msg; extra == "all"
Requires-Dist: pylatexenc; extra == "all"
Requires-Dist: openai-whisper; extra == "all"
Requires-Dist: easyocr; extra == "all"
Requires-Dist: pillow; extra == "all"
Dynamic: license-file

# PyxTxt

[![PyPI version](https://img.shields.io/pypi/v/pyxtxt.svg)](https://pypi.org/project/pyxtxt/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyxtxt.svg)](https://pypi.org/project/pyxtxt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**PyxTxt** is a simple and powerful Python library to extract text from various file formats.  
It supports PDF, DOCX, XLSX, PPTX, ODT, HTML, XML, TXT, legacy Office files, **audio/video transcription**, **OCR from images**, and more.

**NEW in v0.2.4**: Added video transcription support! Now supports both audio and video files using Whisper.

---

## ✨ Features

- **Multiple input types**: File paths, `io.BytesIO` buffers, raw `bytes` objects, and `requests.Response` objects
- **Wide format support**: PDF, DOCX, PPTX, XLSX, ODT, HTML, XML, TXT, Markdown, EPUB, RTF, EML, MSG, LaTeX, legacy Office files (.xls, .ppt, .doc)
- **Audio & Video transcription**: MP3, WAV, M4A, FLAC, MP4, MOV, AVI, WebM, MKV and more using OpenAI Whisper
- **OCR from images**: JPEG, PNG, TIFF, BMP using EasyOCR with multilingual support
- **Automatic MIME detection**: Uses `python-magic` for intelligent file type recognition
- **Web-ready**: Direct support for downloading and extracting text from URLs
- **Memory efficient**: Process files without saving to disk
- **Modern Python**: Full type hints and clean API design

---

## 📦 Installation 

The library is modular so you can install all modules:

```bash
pip install pyxtxt[all]
```
or just the modules you need:
```bash
pip install pyxtxt[pdf,docx,presentation,spreadsheet,html,markdown,epub,email]
```

### Audio & OCR (Heavy Dependencies)
```bash
# Audio transcription (~2GB download for Whisper models)
pip install pyxtxt[audio]

# OCR from images (~1GB download for EasyOCR models)
pip install pyxtxt[ocr]

# Both audio and OCR
pip install pyxtxt[audio,ocr]
```

Because needed libraries are common, installing the html module will also enable SVG and XML support.
The architecture is designed to grow with new modules for additional formats.
## ⚠️ Note: You must have libmagic installed on your system (required by python-magic).
The pyproject.toml file should select the correct version for your system. But if you have any problem you can install it manually.

**On Ubuntu/Debian:**

```bash
sudo apt install libmagic1
```

**On Mac (Homebrew):**

```bash
brew install libmagic
```
**On Windows:**

Use python-magic-bin instead of python-magic for easier installation.

## 🛠️ Dependencies

### Core Dependencies
- python-magic (automatic file type detection)

### Optional Dependencies by Format
- **PDF**: PyMuPDF
- **Office**: python-docx, python-pptx, openpyxl, xlrd
- **Web/HTML**: beautifulsoup4, lxml
- **OpenDocument**: odfpy
- **Markdown**: markdown
- **EPUB**: ebooklib
- **RTF**: striprtf
- **Email**: extract-msg (for MSG files)
- **LaTeX**: pylatexenc
- **Audio**: openai-whisper (heavy ~2GB models)
- **OCR**: easyocr, pillow (heavy ~1GB models)

Dependencies are automatically installed based on selected optional groups.

## 📚 Usage Examples

### Basic Usage
```python
from pyxtxt import xtxt

# Extract from file path
text = xtxt("document.pdf")
print(text)

# Extract from BytesIO buffer
import io
with open("document.docx", "rb") as f:
    buffer = io.BytesIO(f.read())
text = xtxt(buffer)
print(text)
```

### NEW: Web Content Support
```python
import requests
from pyxtxt import xtxt, xtxt_from_url

# Method 1: Direct from bytes
response = requests.get("https://example.com/document.pdf")
text = xtxt(response.content)

# Method 2: Direct from Response object  
text = xtxt(response)

# Method 3: URL helper function
text = xtxt_from_url("https://example.com/document.pdf")
```

### Audio & Video Transcription (NEW)
```python
from pyxtxt import xtxt

# Transcribe audio files
text = xtxt("meeting_recording.mp3")
text = xtxt("interview.wav")
text = xtxt("podcast.m4a")

# Transcribe video files (extracts audio)
text = xtxt("presentation.mp4")
text = xtxt("conference_video.mov")
text = xtxt("webinar.avi")

# From web audio/video
import requests
audio_response = requests.get("https://example.com/audio.mp3")
text = xtxt(audio_response.content)

video_response = requests.get("https://example.com/video.mp4")
text = xtxt(video_response.content)
```

### OCR from Images (NEW)
```python
from pyxtxt import xtxt

# Extract text from images
text = xtxt("scanned_document.png")
text = xtxt("screenshot.jpg")
text = xtxt("invoice.tiff")

# From web images
import requests
image_response = requests.get("https://example.com/document.png")
text = xtxt(image_response.content)
```

### Show Available Formats
```python
from pyxtxt import extxt_available_formats

# List supported MIME types
formats = extxt_available_formats()
print(formats)

# Pretty format names
formats = extxt_available_formats(pretty=True)
print(formats)
```
## 🌐 Common Web Use Cases

```python
# API responses
api_response = requests.post("https://api.example.com/generate-pdf")
text = xtxt(api_response.content)

# File uploads (Flask/Django)
uploaded_bytes = request.files['document'].read()
text = xtxt(uploaded_bytes)

# Audio/video transcription services
audio_response = requests.get("https://api.example.com/recording.mp3")
transcript = xtxt(audio_response.content)

# Video transcription from API
video_response = requests.get("https://api.example.com/meeting.mp4")
transcript = xtxt(video_response.content)

# OCR for uploaded images
image_bytes = request.files['receipt'].read()
text = xtxt(image_bytes)

# Email attachments
attachment_bytes = email_msg.get_payload(decode=True)
text = xtxt(attachment_bytes)
```

## ⚠️ Known Limitations

- **Legacy file detection**: When using raw streams without filenames, legacy files (.doc, .xls, .ppt) may not be correctly detected due to identical file signatures in libmagic
- **Filename hints recommended**: When available, providing original filenames improves detection accuracy
- **MSWrite .doc files**: Require `antiword` installation:
  ```bash
  sudo apt-get update && sudo apt-get install antiword
  ```

## 📖 Full Examples

See [examples.py](./examples.py) for comprehensive usage examples including:
- Local file processing
- Memory buffer handling  
- Web content extraction
- Error handling patterns
- All supported formats demonstration

### Accessing Examples After Installation
After installing PyxTxt from PyPI, you can access the examples file:

```python
import pkg_resources

# Get path to examples file
examples_path = pkg_resources.resource_filename('pyxtxt', 'examples.py')
print(f"Examples file location: {examples_path}")

# Or read the content directly
examples_content = pkg_resources.resource_string('pyxtxt', 'examples.py').decode('utf-8')
print(examples_content)
```

## 🔒 License

Distributed under the MIT License. See LICENSE file for details.

The software is provided "as is" without any warranty of any kind.

## 🤝 Contributing

Pull requests, issues, and feedback are warmly welcome! 🚀

- **Bug reports**: Please include file samples and error details
- **Feature requests**: Describe your use case and expected behavior
- **Code contributions**: Follow existing patterns and add tests

## 📊 Changelog

### v0.2.4
- ✅ **NEW**: Video transcription support (MP4, MOV, AVI, WebM, MKV)
- ✅ **ENHANCED**: Audio transcription now supports video files
- ✅ Whisper automatically extracts audio track from videos
- ✅ Unified interface for both audio and video processing

### v0.2.3
- ✅ **NEW**: Audio transcription support (MP3, WAV, M4A, FLAC, etc.)
- ✅ **NEW**: OCR from images (JPEG, PNG, TIFF, BMP, WebP)
- ✅ **NEW**: Markdown, EPUB, RTF, EML, MSG, LaTeX support
- ✅ Separate optional dependencies for heavy features (audio/OCR)
- ✅ Performance optimizations with model caching
- ✅ Improved multilingual OCR support (Italian/English)

### v0.1.24+
- ✅ Added support for `bytes` objects
- ✅ Added support for `requests.Response` objects  
- ✅ Added `xtxt_from_url()` helper function
- ✅ Improved type hints and error handling
- ✅ Enhanced web content processing capabilities
