pdf-comments-extractor 0.1.0
Extract comments, annotations, and structured content from PDF documents
Requires Python: >=3.7
Keywords: pdf, comments, annotations, academic, papers, extraction

# PDF Comments Extractor

[![PyPI version](https://badge.fury.io/py/pdf-comments-extractor.svg)](https://badge.fury.io/py/pdf-comments-extractor)
[![Python Support](https://img.shields.io/pypi/pyversions/pdf-comments-extractor.svg)](https://pypi.org/project/pdf-comments-extractor/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful Python package for extracting comments, annotations, and structured content from PDF documents. Perfect for analyzing supervisor feedback, extracting academic paper content, and processing annotated PDFs.

## Features

- 📝 **Extract PDF Comments**: Pull all annotations (highlights, sticky notes, text comments) from PDFs
- 📄 **Academic Paper Extraction**: Extract structured content from research papers (sections, citations, references, figures, tables)
- 🔍 **Text Search**: Search for specific text across PDFs with context
- 💾 **Multiple Output Formats**: Export to JSON, CSV, or both
- 🖥️ **CLI Tools**: Easy-to-use command-line interfaces
- 🐍 **Python API**: Full programmatic access for integration into your workflows
- 🌍 **Multi-language Support**: Works with any language including Hebrew, Arabic, Chinese, etc.

## Installation

### From PyPI (recommended)

```bash
pip install pdf-comments-extractor
```

### From Source

```bash
git clone https://github.com/yourusername/pdf-comments-extractor.git
cd pdf-comments-extractor
pip install -e .
```

## Quick Start

### Command Line

#### Extract Comments from PDF

```bash
# Extract all comments
pdf-comments-extract paper.pdf

# With console output
pdf-comments-extract paper.pdf --print

# Specify output directory
pdf-comments-extract paper.pdf --output-dir ./my_comments

# Multiple files
pdf-comments-extract file1.pdf file2.pdf file3.pdf
```

#### Extract Academic Paper Content

```bash
# Extract all structured content
pdf-academic-extract paper.pdf --print

# JSON output only
pdf-academic-extract paper.pdf --format json
```

#### Search for Text in PDF

```bash
pdf-search paper.pdf "your search text"
```

### Python API

#### Extract Comments

```python
from pdf_comments_extractor import PDFCommentExtractor

# Using context manager (recommended)
with PDFCommentExtractor('paper.pdf') as extractor:
    comments = extractor.extract_all_comments()
    
    # Save to JSON
    extractor.save_to_json(comments, 'comments.json')
    
    # Save to CSV
    extractor.save_to_csv(comments, 'comments.csv')
    
    # Print summary
    extractor.print_summary(comments)

# Access individual comments
for comment in comments:
    print(f"Page {comment['page']}: {comment['comment']}")
    print(f"References: {comment['referenced_text']}")
```

#### Extract Academic Paper Content

```python
from pdf_comments_extractor import AcademicPaperExtractor

extractor = AcademicPaperExtractor('paper.pdf')
data = extractor.extract_all()

# Access different components
print(f"Abstract: {data['sections']['Abstract']}")
print(f"Total citations: {data['statistics']['total_citations']}")

# Get all citations
for citation in data['citations']:
    print(f"{citation['author']} [{citation['year']}] on page {citation['page']}")

# Save results
extractor.save_to_json(data, 'paper_analysis.json')
extractor.close()
```

#### Search for Text

```python
from pdf_comments_extractor import search_text_in_pdf

results = search_text_in_pdf('paper.pdf', 'neural networks')

for page_num, context in results:
    print(f"Found on page {page_num}:")
    print(context)
```

## Output Format

### Comment Extraction

Comments are extracted with the following information:

```json
{
  "page": 1,
  "type": "Highlight",
  "subject": "Note",
  "author": "Reviewer Name",
  "comment": "This needs clarification",
  "referenced_text": "The text that was highlighted...",
  "position": {
    "x0": 100.5,
    "y0": 200.3,
    "x1": 300.2,
    "y1": 220.8
  },
  "created": "D:20231120120000",
  "modified": "D:20231120130000",
  "color": {"stroke": [1.0, 0.0, 0.0], "fill": null}
}
```

### Academic Paper Extraction

Extracts comprehensive academic paper structure:

- **Metadata**: Title, authors, page count, word count
- **Sections**: Abstract, Introduction, Methodology, Results, Discussion, Conclusion
- **Citations**: All citations with context and page numbers
- **References**: Full bibliography
- **Figures & Tables**: Captions and locations
- **Key Contributions**: Identified contribution statements
- **Statistics**: Complete metrics

## Use Cases

### 1. Supervisor Feedback Analysis

```python
# Extract all supervisor comments
with PDFCommentExtractor('thesis_reviewed.pdf') as extractor:
    comments = extractor.extract_all_comments()
    
# Filter by author
supervisor_comments = [c for c in comments if c['author'] == 'Dr. Smith']

# Group by page
from collections import defaultdict
by_page = defaultdict(list)
for comment in comments:
    by_page[comment['page']].append(comment)
```

### 2. Literature Review

```python
# Extract citations from multiple papers
from pathlib import Path

all_citations = []
for pdf in Path('papers/').glob('*.pdf'):
    extractor = AcademicPaperExtractor(str(pdf))
    data = extractor.extract_all()
    all_citations.extend(data['citations'])
    extractor.close()

# Analyze citation patterns
from collections import Counter
authors = [c['author'] for c in all_citations]
most_cited = Counter(authors).most_common(10)
```

### 3. Multi-language Support

```python
# Works with Hebrew, Arabic, Chinese, etc.
with PDFCommentExtractor('hebrew_manuscript.pdf') as extractor:
    comments = extractor.extract_all_comments()
    
for comment in comments:
    if 'לא מובן' in comment['comment']:  # "not clear" in Hebrew
        print(f"Clarity issue on page {comment['page']}")
```

## Requirements

- Python 3.7+
- PyMuPDF (automatically installed)

## Development

### Setup Development Environment

```bash
git clone https://github.com/yourusername/pdf-comments-extractor.git
cd pdf-comments-extractor
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest tests/
```

### Format Code

```bash
black pdf_comments_extractor/
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use this package in your research, please cite:

```bibtex
@software{pdf_comments_extractor,
  author = {Goldberg, Alexander},
  title = {PDF Comments Extractor},
  year = {2024},
  url = {https://github.com/yourusername/pdf-comments-extractor}
}
```

## Acknowledgments

- Built with [PyMuPDF](https://pymupdf.readthedocs.io/)
- Inspired by the need to efficiently process supervisor feedback on academic papers

## Changelog

### Version 0.1.0 (2024-11-29)

- Initial release
- PDF comment extraction
- Academic paper content extraction
- Search functionality
- CLI tools
- JSON and CSV export

## Support

If you encounter any issues or have questions:

- Open an [issue](https://github.com/yourusername/pdf-comments-extractor/issues)
- Check the [documentation](https://github.com/yourusername/pdf-comments-extractor/wiki)

## Related Projects

- [PyMuPDF](https://github.com/pymupdf/PyMuPDF) - The underlying PDF library
- [pdfplumber](https://github.com/jsvine/pdfplumber) - Alternative PDF extraction tool
- [PyPDF2](https://github.com/py-pdf/PyPDF2) - Another PDF library

---

**Made with ❤️ by Alexander Goldberg**