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

docs/tutorials/03-extracting-blocks.md

@@ -0,0 +1,48 @@
+# Extracting Text Blocks
+
+Often, you need a specific section, like a paragraph between two headings. You can find a starting element and select everything below it until an ending element.
+
+Let's extract the "Summary" section from `01-practice.pdf`. It starts after "Summary:" and ends before the thick horizontal line.
+
+```python
+#%pip install "natural-pdf[all]"
+```
+
+
+```python
+from natural_pdf import PDF
+
+# Load the PDF and get the page
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf")
+page = pdf.pages[0]
+
+# Find the starting element ("Summary:")
+start_marker = page.find('text:contains("Summary:")')
+
+# Select elements below the start_marker, stopping *before*
+# the thick horizontal line (a line with height > 1).
+summary_elements = start_marker.below(
+    include_element=True, # Include the "Summary:" text itself
+    until="line[height > 1]"
+)
+
+# Visualize the elements found in this block
+summary_elements.highlight(color="lightgreen", label="Summary Block")
+
+# Extract and display the text from the collection of summary elements
+summary_elements.extract_text()
+
+```
+
+```python
+# Display the page image to see the visualization
+page.to_image()
+```
+
+This selects the elements using `.below(until=...)` and extracts their text. The second code block displays the page image with the visualized section.
+
+<div class="admonition note">
+<p class="admonition-title">Selector Specificity</p>
+
+    We used `line[height > 1]` to find the thick horizontal line. You might need to adjust selectors based on the specific PDF structure. Inspecting element properties can help you find reliable start and end markers.
+</div>

docs/tutorials/04-table-extraction.ipynb

@@ -0,0 +1,114 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "887b8e7a",
+   "metadata": {},
+   "source": [
+    "# Basic Table Extraction\n",
+    "\n",
+    "PDFs often contain tables, and `natural-pdf` provides methods to extract their data, building on `pdfplumber`'s capabilities.\n",
+    "\n",
+    "Let's extract the \"Violations\" table from our practice PDF."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "c920f4f6",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-16T14:57:17.973992Z",
+     "iopub.status.busy": "2025-04-16T14:57:17.973825Z",
+     "iopub.status.idle": "2025-04-16T14:57:17.979183Z",
+     "shell.execute_reply": "2025-04-16T14:57:17.978811Z"
+    },
+    "lines_to_next_cell": 2
+   },
+   "outputs": [],
+   "source": [
+    "#%pip install \"natural-pdf[all]\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "28430cf6",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-04-16T14:57:17.980899Z",
+     "iopub.status.busy": "2025-04-16T14:57:17.980746Z",
+     "iopub.status.idle": "2025-04-16T14:57:24.102292Z",
+     "shell.execute_reply": "2025-04-16T14:57:24.101834Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from natural_pdf import PDF\n",
+    "\n",
+    "# Load a PDF\n",
+    "pdf = PDF(\"https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf\")\n",
+    "page = pdf.pages[0]\n",
+    "\n",
+    "# Use extract_tables() to find all tables on the page.\n",
+    "# It returns a list of tables, where each table is a list of lists.\n",
+    "tables_data = page.extract_tables()\n",
+    "\n",
+    "# Display the first table found\n",
+    "tables_data[0] if tables_data else \"No tables found\"\n",
+    "\n",
+    "# You can also visualize the general area of the first table \n",
+    "# by finding elements in that region\n",
+    "if tables_data:\n",
+    "    # Find a header element in the table\n",
+    "    statute_header = page.find('text:contains(\"Statute\")')\n",
+    "    if statute_header:\n",
+    "        # Show the area\n",
+    "        statute_header.below(height=100).highlight(color=\"green\", label=\"Table Area\")\n",
+    "        page.to_image()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4ad2a9db",
+   "metadata": {},
+   "source": [
+    "This code uses `page.extract_tables()` which attempts to automatically detect tables based on visual cues like lines and whitespace. The result is a list of lists, representing the rows and cells of the table.\n",
+    "\n",
+    "<div class=\"admonition note\">\n",
+    "<p class=\"admonition-title\">Table Settings and Limitations</p>\n",
+    "\n",
+    "    The default `extract_tables()` works well for simple, clearly defined tables. However, it might struggle with:\n",
+    "    *   Tables without clear borders or lines.\n",
+    "    *   Complex merged cells.\n",
+    "    *   Tables spanning multiple pages.\n",
+    "\n",
+    "    `pdfplumber` (and thus `natural-pdf`) allows passing `table_settings` dictionaries to `extract_tables()` for more control over the detection strategy (e.g., `\"vertical_strategy\": \"text\"`, `\"horizontal_strategy\": \"text\"`).\n",
+    "\n",
+    "    For even more robust table detection, especially for tables without explicit lines, using Layout Analysis (like `page.analyze_layout(engine='tatr')`) first, finding the table `region`, and then calling `region.extract_table()` can yield better results. We'll explore layout analysis in a later tutorial.\n",
+    "</div> "
+   ]
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "cell_metadata_filter": "-all",
+   "main_language": "python",
+   "notebook_metadata_filter": "-all"
+  },
+  "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/tutorials/04-table-extraction.md

@@ -0,0 +1,50 @@
+# Basic Table Extraction
+
+PDFs often contain tables, and `natural-pdf` provides methods to extract their data, building on `pdfplumber`'s capabilities.
+
+Let's extract the "Violations" table from our practice PDF.
+
+```python
+#%pip install "natural-pdf[all]"
+```
+
+
+```python
+from natural_pdf import PDF
+
+# Load a PDF
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf")
+page = pdf.pages[0]
+
+# Use extract_tables() to find all tables on the page.
+# It returns a list of tables, where each table is a list of lists.
+tables_data = page.extract_tables()
+
+# Display the first table found
+tables_data[0] if tables_data else "No tables found"
+
+# You can also visualize the general area of the first table 
+# by finding elements in that region
+if tables_data:
+    # Find a header element in the table
+    statute_header = page.find('text:contains("Statute")')
+    if statute_header:
+        # Show the area
+        statute_header.below(height=100).highlight(color="green", label="Table Area")
+        page.to_image()
+```
+
+This code uses `page.extract_tables()` which attempts to automatically detect tables based on visual cues like lines and whitespace. The result is a list of lists, representing the rows and cells of the table.
+
+<div class="admonition note">
+<p class="admonition-title">Table Settings and Limitations</p>
+
+    The default `extract_tables()` works well for simple, clearly defined tables. However, it might struggle with:
+    *   Tables without clear borders or lines.
+    *   Complex merged cells.
+    *   Tables spanning multiple pages.
+
+    `pdfplumber` (and thus `natural-pdf`) allows passing `table_settings` dictionaries to `extract_tables()` for more control over the detection strategy (e.g., `"vertical_strategy": "text"`, `"horizontal_strategy": "text"`).
+
+    For even more robust table detection, especially for tables without explicit lines, using Layout Analysis (like `page.analyze_layout(engine='tatr')`) first, finding the table `region`, and then calling `region.extract_table()` can yield better results. We'll explore layout analysis in a later tutorial.
+</div>