natural-pdf 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

docs/pdf-navigation/index.ipynb

@@ -0,0 +1,314 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "bba1860e",
+   "metadata": {},
+   "source": [
+    "# PDF Navigation\n",
+    "\n",
+    "This guide covers the basics of working with PDFs in Natural PDF - opening documents, accessing pages, and navigating through content.\n",
+    "\n",
+    "## Opening a PDF\n",
+    "\n",
+    "The main entry point to Natural PDF is the `PDF` class:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "56d12ab5",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-03T14:50:38.434157Z",
+     "iopub.status.busy": "2025-04-03T14:50:38.433170Z",
+     "iopub.status.idle": "2025-04-03T14:50:49.768101Z",
+     "shell.execute_reply": "2025-04-03T14:50:49.767384Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from natural_pdf import PDF\n",
+    "\n",
+    "# Open a PDF file\n",
+    "pdf = PDF(\"https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/0500000US42001.pdf\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c425482a",
+   "metadata": {},
+   "source": [
+    "## Accessing Pages\n",
+    "\n",
+    "Once you have a PDF object, you can access its pages:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "a3405aa9",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-03T14:50:49.770604Z",
+     "iopub.status.busy": "2025-04-03T14:50:49.770419Z",
+     "iopub.status.idle": "2025-04-03T14:50:50.700808Z",
+     "shell.execute_reply": "2025-04-03T14:50:50.699634Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "This PDF has 153 pages\n",
+      "Page 1 has 985 characters\n",
+      "Page 2 has 778 characters\n",
+      "Page 3 has 522 characters\n",
+      "Page 4 has 984 characters\n",
+      "Page 5 has 778 characters\n",
+      "Page 6 has 523 characters\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Page 7 has 982 characters\n",
+      "Page 8 has 772 characters\n",
+      "Page 9 has 522 characters\n",
+      "Page 10 has 1008 characters\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Page 11 has 796 characters\n",
+      "Page 12 has 532 characters\n",
+      "Page 13 has 986 characters\n",
+      "Page 14 has 780 characters\n",
+      "Page 15 has 523 characters\n",
+      "Page 16 has 990 characters\n",
+      "Page 17 has 782 characters\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Page 18 has 520 characters\n",
+      "Page 19 has 1006 characters\n",
+      "Page 20 has 795 characters\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Get the total number of pages\n",
+    "num_pages = len(pdf)\n",
+    "print(f\"This PDF has {num_pages} pages\")\n",
+    "\n",
+    "# Get a specific page (0-indexed)\n",
+    "first_page = pdf.pages[0]\n",
+    "last_page = pdf.pages[-1]\n",
+    "\n",
+    "# Iterate through the first 20 pages\n",
+    "for page in pdf.pages[:20]:\n",
+    "    print(f\"Page {page.number} has {len(page.extract_text())} characters\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2eca7327",
+   "metadata": {},
+   "source": [
+    "## Page Properties\n",
+    "\n",
+    "Each `Page` object has useful properties:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "348f28d7",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-03T14:50:50.713325Z",
+     "iopub.status.busy": "2025-04-03T14:50:50.711638Z",
+     "iopub.status.idle": "2025-04-03T14:50:50.738737Z",
+     "shell.execute_reply": "2025-04-03T14:50:50.726839Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "612 792\n",
+      "20\n",
+      "19\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Page dimensions in points (1/72 inch)\n",
+    "print(page.width, page.height)\n",
+    "\n",
+    "# Page number (1-indexed as shown in PDF viewers)\n",
+    "print(page.number)\n",
+    "\n",
+    "# Page index (0-indexed position in the PDF)\n",
+    "print(page.index)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c7cf1839",
+   "metadata": {},
+   "source": [
+    "## Working Across Pages\n",
+    "\n",
+    "Natural PDF makes it easy to work with content across multiple pages:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "71a8f1ec",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-03T14:50:50.765495Z",
+     "iopub.status.busy": "2025-04-03T14:50:50.764444Z",
+     "iopub.status.idle": "2025-04-03T14:50:57.735494Z",
+     "shell.execute_reply": "2025-04-03T14:50:57.726489Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<natural_pdf.core.pdf.PDF at 0x1045224d0>"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Extract text from all pages\n",
+    "all_text = pdf.extract_text()\n",
+    "\n",
+    "# Find elements across all pages\n",
+    "all_headings = pdf.find_all('text[size>=14]:bold')\n",
+    "\n",
+    "# Add exclusion zones to all pages (like headers/footers)\n",
+    "pdf.add_exclusion(\n",
+    "    lambda page: page.find('text:contains(\"CONFIDENTIAL\")').above() if page.find('text:contains(\"CONFIDENTIAL\")') else None,\n",
+    "    label=\"header\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e18051a4",
+   "metadata": {},
+   "source": [
+    "## The Page Collection\n",
+    "\n",
+    "The `pdf.pages` object is a `PageCollection` that allows batch operations on pages:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "e5f1c662",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-03T14:50:57.752240Z",
+     "iopub.status.busy": "2025-04-03T14:50:57.751868Z",
+     "iopub.status.idle": "2025-04-03T14:50:57.770738Z",
+     "shell.execute_reply": "2025-04-03T14:50:57.759415Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# Extract text from specific pages\n",
+    "text = pdf.pages[2:5].extract_text()\n",
+    "\n",
+    "# Find elements across specific pages\n",
+    "elements = pdf.pages[2:5].find_all('text:contains(\"Annual Report\")')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9713e392",
+   "metadata": {},
+   "source": [
+    "## Document Sections Across Pages\n",
+    "\n",
+    "You can extract sections that span across multiple pages:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "d5b89a2b",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-03T14:50:57.782621Z",
+     "iopub.status.busy": "2025-04-03T14:50:57.781776Z",
+     "iopub.status.idle": "2025-04-03T14:50:57.811508Z",
+     "shell.execute_reply": "2025-04-03T14:50:57.805310Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# Get sections with headings as section starts\n",
+    "sections = pdf.pages.get_sections(\n",
+    "    start_elements='text[size>=14]:bold',\n",
+    "    new_section_on_page_break=False\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f51594ce",
+   "metadata": {},
+   "source": [
+    "## Next Steps\n",
+    "\n",
+    "Now that you know how to navigate PDFs, you can:\n",
+    "\n",
+    "- [Find elements using selectors](../element-selection/index.ipynb)\n",
+    "- [Extract text from your documents](../text-extraction/index.ipynb)\n",
+    "- [Work with specific regions](../regions/index.ipynb)"
+   ]
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "cell_metadata_filter": "-all",
+   "main_language": "python",
+   "notebook_metadata_filter": "-all",
+   "text_representation": {
+    "extension": ".md",
+    "format_name": "markdown"
+   }
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/pdf-navigation/index.md

@@ -0,0 +1,97 @@
+# PDF Navigation
+
+This guide covers the basics of working with PDFs in Natural PDF - opening documents, accessing pages, and navigating through content.
+
+## Opening a PDF
+
+The main entry point to Natural PDF is the `PDF` class:
+
+```python
+from natural_pdf import PDF
+
+# Open a PDF file
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/0500000US42001.pdf")
+```
+
+## Accessing Pages
+
+Once you have a PDF object, you can access its pages:
+
+```python
+# Get the total number of pages
+num_pages = len(pdf)
+print(f"This PDF has {num_pages} pages")
+
+# Get a specific page (0-indexed)
+first_page = pdf.pages[0]
+last_page = pdf.pages[-1]
+
+# Iterate through the first 20 pages
+for page in pdf.pages[:20]:
+    print(f"Page {page.number} has {len(page.extract_text())} characters")
+```
+
+## Page Properties
+
+Each `Page` object has useful properties:
+
+```python
+# Page dimensions in points (1/72 inch)
+print(page.width, page.height)
+
+# Page number (1-indexed as shown in PDF viewers)
+print(page.number)
+
+# Page index (0-indexed position in the PDF)
+print(page.index)
+```
+
+## Working Across Pages
+
+Natural PDF makes it easy to work with content across multiple pages:
+
+```python
+# Extract text from all pages
+all_text = pdf.extract_text()
+
+# Find elements across all pages
+all_headings = pdf.find_all('text[size>=14]:bold')
+
+# Add exclusion zones to all pages (like headers/footers)
+pdf.add_exclusion(
+    lambda page: page.find('text:contains("CONFIDENTIAL")').above() if page.find('text:contains("CONFIDENTIAL")') else None,
+    label="header"
+)
+```
+
+## The Page Collection
+
+The `pdf.pages` object is a `PageCollection` that allows batch operations on pages:
+
+```python
+# Extract text from specific pages
+text = pdf.pages[2:5].extract_text()
+
+# Find elements across specific pages
+elements = pdf.pages[2:5].find_all('text:contains("Annual Report")')
+```
+
+## Document Sections Across Pages
+
+You can extract sections that span across multiple pages:
+
+```python
+# Get sections with headings as section starts
+sections = pdf.pages.get_sections(
+    start_elements='text[size>=14]:bold',
+    new_section_on_page_break=False
+)
+```
+
+## Next Steps
+
+Now that you know how to navigate PDFs, you can:
+
+- [Find elements using selectors](../element-selection/index.ipynb)
+- [Extract text from your documents](../text-extraction/index.ipynb)
+- [Work with specific regions](../regions/index.ipynb)