natural-pdf 0.1.16__tar.gz → 0.1.17__tar.gz

{natural_pdf-0.1.16/natural_pdf.egg-info → natural_pdf-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: natural-pdf
-Version: 0.1.16
+Version: 0.1.17
 Summary: A more intuitive interface for working with PDFs
 Author-email: Jonathan Soma <jonathan.soma@gmail.com>
 License-Expression: MIT

natural_pdf-0.1.17/docs/describe/index.ipynb

@@ -0,0 +1,438 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "725fe29c",
+   "metadata": {},
+   "source": [
+    "# Describe Functionality\n",
+    "\n",
+    "The `describe()` and `inspect()` methods provide an easy way to understand the contents of your PDF elements without having to visualize them as images.\n",
+    "\n",
+    "## Basic Usage\n",
+    "\n",
+    "Get a summary of an entire page:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "5bc39925",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-06-15T16:10:40.070939Z",
+     "iopub.status.busy": "2025-06-15T16:10:40.070809Z",
+     "iopub.status.idle": "2025-06-15T16:10:45.409526Z",
+     "shell.execute_reply": "2025-06-15T16:10:45.409235Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "CropBox missing from /Page, defaulting to MediaBox\n"
+     ]
+    },
+    {
+     "data": {
+      "text/markdown": [
+       "## Page 1 Summary\n",
+       "\n",
+       "**Elements**:\n",
+       "  - **text**: 44 elements\n",
+       "  - **line**: 21 elements\n",
+       "  - **rect**: 8 elements\n",
+       "\n",
+       "**Text Analysis**:\n",
+       "  - **typography**:\n",
+       "    - **fonts**:\n",
+       "      - Helvetica: 44\n",
+       "    - **sizes**:\n",
+       "      - 10.0pt: 40\n",
+       "      - 8.0pt: 3\n",
+       "      - 12.0pt: 1\n",
+       "    - styles: 9 bold\n",
+       "    - **colors**:\n",
+       "      - black: 43\n",
+       "      - other: 1"
+      ],
+      "text/plain": [
+       "## Page 1 Summary\n",
+       "\n",
+       "**Elements**:\n",
+       "  - **text**: 44 elements\n",
+       "  - **line**: 21 elements\n",
+       "  - **rect**: 8 elements\n",
+       "\n",
+       "**Text Analysis**:\n",
+       "  - **typography**:\n",
+       "    - **fonts**:\n",
+       "      - Helvetica: 44\n",
+       "    - **sizes**:\n",
+       "      - 10.0pt: 40\n",
+       "      - 8.0pt: 3\n",
+       "      - 12.0pt: 1\n",
+       "    - styles: 9 bold\n",
+       "    - **colors**:\n",
+       "      - black: 43\n",
+       "      - other: 1"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from natural_pdf import PDF\n",
+    "\n",
+    "pdf = PDF(\"https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf\")\n",
+    "page = pdf.pages[0]\n",
+    "\n",
+    "page.describe()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b0e3354c",
+   "metadata": {},
+   "source": [
+    "## Element collection summaries\n",
+    "\n",
+    "You can describe element collections on a page with `.describe()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "eac4e22b",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-06-15T16:10:45.411081Z",
+     "iopub.status.busy": "2025-06-15T16:10:45.410822Z",
+     "iopub.status.idle": "2025-06-15T16:10:45.413903Z",
+     "shell.execute_reply": "2025-06-15T16:10:45.413620Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "## Collection Summary (44 elements)\n",
+       "\n",
+       "**Typography**:\n",
+       "  - **fonts**:\n",
+       "    - Helvetica: 44\n",
+       "  - **sizes**:\n",
+       "    - 10.0pt: 40\n",
+       "    - 8.0pt: 3\n",
+       "    - 12.0pt: 1\n",
+       "  - **styles**: 9 bold\n",
+       "  - **colors**:\n",
+       "    - black: 43\n",
+       "    - other: 1"
+      ],
+      "text/plain": [
+       "## Collection Summary (44 elements)\n",
+       "\n",
+       "**Typography**:\n",
+       "  - **fonts**:\n",
+       "    - Helvetica: 44\n",
+       "  - **sizes**:\n",
+       "    - 10.0pt: 40\n",
+       "    - 8.0pt: 3\n",
+       "    - 12.0pt: 1\n",
+       "  - **styles**: 9 bold\n",
+       "  - **colors**:\n",
+       "    - black: 43\n",
+       "    - other: 1"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Describe all elements on the page\n",
+    "page.find_all('text').describe()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "503c2a31",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-06-15T16:10:45.415172Z",
+     "iopub.status.busy": "2025-06-15T16:10:45.415052Z",
+     "iopub.status.idle": "2025-06-15T16:10:45.417592Z",
+     "shell.execute_reply": "2025-06-15T16:10:45.417343Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "## Collection Summary (8 elements)\n",
+       "\n",
+       "**Size Stats**:\n",
+       "  - **width range**: 8-180\n",
+       "  - **height range**: 8-35\n",
+       "  - **avg area**: 844 sq pts\n",
+       "\n",
+       "**Styles**:\n",
+       "  - **stroke widths**:\n",
+       "    - 0.5: 7\n",
+       "  - **colors**:\n",
+       "    - black: 8"
+      ],
+      "text/plain": [
+       "## Collection Summary (8 elements)\n",
+       "\n",
+       "**Size Stats**:\n",
+       "  - **width range**: 8-180\n",
+       "  - **height range**: 8-35\n",
+       "  - **avg area**: 844 sq pts\n",
+       "\n",
+       "**Styles**:\n",
+       "  - **stroke widths**:\n",
+       "    - 0.5: 7\n",
+       "  - **colors**:\n",
+       "    - black: 8"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Describe all elements on the page\n",
+    "page.find_all('rect').describe()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5b468a5e",
+   "metadata": {},
+   "source": [
+    "## Inspecting lists of elements\n",
+    "\n",
+    "For more detail, you can view specific details of element collections with `inspect()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "ea04905b",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-06-15T16:10:45.418792Z",
+     "iopub.status.busy": "2025-06-15T16:10:45.418688Z",
+     "iopub.status.idle": "2025-06-15T16:10:45.421581Z",
+     "shell.execute_reply": "2025-06-15T16:10:45.421321Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "## Collection Inspection (44 elements)\n",
+       "\n",
+       "### Word Elements\n",
+       "\n",
+       "| text | x0 | top | x1 | bottom | font_family | size | bold | italic | source | confidence | color |\n",
+       "|------|------|------|------|------|------|------|------|------|------|------|------|\n",
+       "| Jungle Health and Safety Inspection Service | 385 | 36 | 542 | 44 | Helvetica | 8 | False | False | native | 1.00 | #000000 |\n",
+       "| INS-UP70N51NCL41R | 385 | 46 | 466 | 54 | Helvetica | 8 | False | False | native | 1.00 | #ff0000 |\n",
+       "| Site:  | 50 | 84 | 74 | 94 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Durham’s Meatpacking   | 74 | 84 | 182 | 94 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Chicago, Ill. | 182 | 84 | 235 | 94 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Date:   | 50 | 104 | 81 | 114 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| February 3, 1905 | 81 | 104 | 157 | 114 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Violation Count:  | 50 | 124 | 130 | 134 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| 7 | 130 | 124 | 136 | 134 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Summary:  | 50 | 144 | 102 | 154 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Worst of any, however, were the fertilizer men, an... | 102 | 144 | 506 | 154 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| These people could not be shown to the visitor - f... | 50 | 160 | 512 | 170 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| visitor at a hundred yards, and as for the other m... | 50 | 176 | 491 | 186 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| some of which there were open vats near the level ... | 50 | 192 | 496 | 202 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| into the vats; and when they were fished out, ther... | 50 | 208 | 465 | 218 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| exhibiting - sometimes they would be overlooked fo... | 50 | 224 | 492 | 234 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| to the world as Durham’s Pure Leaf Lard! | 50 | 240 | 232 | 250 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Violations | 50 | 372 | 107 | 384 | Helvetica | 12 | True | False | native | 1.00 | #000000 |\n",
+       "| Statute | 55 | 398 | 89 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Description | 105 | 398 | 160 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Level | 455 | 398 | 481 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Repeat? | 505 | 398 | 544 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| 4.12.7 | 55 | 418 | 83 | 428 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Unsanitary Working Conditions. | 105 | 418 | 245 | 428 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Critical | 455 | 418 | 486 | 428 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| 5.8.3 | 55 | 438 | 77 | 448 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Inadequate Protective Equipment. | 105 | 438 | 256 | 448 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Serious | 455 | 438 | 489 | 448 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| 6.3.9 | 55 | 458 | 77 | 468 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Ineffective Injury Prevention. | 105 | 458 | 231 | 468 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "_Showing 30 of 44 elements (pass limit= to see more)_"
+      ],
+      "text/plain": [
+       "## Collection Inspection (44 elements)\n",
+       "\n",
+       "### Word Elements\n",
+       "\n",
+       "| text | x0 | top | x1 | bottom | font_family | size | bold | italic | source | confidence | color |\n",
+       "|------|------|------|------|------|------|------|------|------|------|------|------|\n",
+       "| Jungle Health and Safety Inspection Service | 385 | 36 | 542 | 44 | Helvetica | 8 | False | False | native | 1.00 | #000000 |\n",
+       "| INS-UP70N51NCL41R | 385 | 46 | 466 | 54 | Helvetica | 8 | False | False | native | 1.00 | #ff0000 |\n",
+       "| Site:  | 50 | 84 | 74 | 94 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Durham’s Meatpacking   | 74 | 84 | 182 | 94 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Chicago, Ill. | 182 | 84 | 235 | 94 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Date:   | 50 | 104 | 81 | 114 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| February 3, 1905 | 81 | 104 | 157 | 114 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Violation Count:  | 50 | 124 | 130 | 134 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| 7 | 130 | 124 | 136 | 134 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Summary:  | 50 | 144 | 102 | 154 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Worst of any, however, were the fertilizer men, an... | 102 | 144 | 506 | 154 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| These people could not be shown to the visitor - f... | 50 | 160 | 512 | 170 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| visitor at a hundred yards, and as for the other m... | 50 | 176 | 491 | 186 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| some of which there were open vats near the level ... | 50 | 192 | 496 | 202 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| into the vats; and when they were fished out, ther... | 50 | 208 | 465 | 218 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| exhibiting - sometimes they would be overlooked fo... | 50 | 224 | 492 | 234 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| to the world as Durham’s Pure Leaf Lard! | 50 | 240 | 232 | 250 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Violations | 50 | 372 | 107 | 384 | Helvetica | 12 | True | False | native | 1.00 | #000000 |\n",
+       "| Statute | 55 | 398 | 89 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Description | 105 | 398 | 160 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Level | 455 | 398 | 481 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| Repeat? | 505 | 398 | 544 | 408 | Helvetica | 10 | True | False | native | 1.00 | #000000 |\n",
+       "| 4.12.7 | 55 | 418 | 83 | 428 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Unsanitary Working Conditions. | 105 | 418 | 245 | 428 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Critical | 455 | 418 | 486 | 428 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| 5.8.3 | 55 | 438 | 77 | 448 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Inadequate Protective Equipment. | 105 | 438 | 256 | 448 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Serious | 455 | 438 | 489 | 448 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| 6.3.9 | 55 | 458 | 77 | 468 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "| Ineffective Injury Prevention. | 105 | 458 | 231 | 468 | Helvetica | 10 | False | False | native | 1.00 | #000000 |\n",
+       "_Showing 30 of 44 elements (pass limit= to see more)_"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "page.find_all('text').inspect()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "06c8d813",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2025-06-15T16:10:45.422781Z",
+     "iopub.status.busy": "2025-06-15T16:10:45.422665Z",
+     "iopub.status.idle": "2025-06-15T16:10:45.425191Z",
+     "shell.execute_reply": "2025-06-15T16:10:45.424938Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "## Collection Inspection (21 elements)\n",
+       "\n",
+       "### Line Elements\n",
+       "\n",
+       "| x0 | top | x1 | bottom | width | is_horizontal | is_vertical |\n",
+       "|------|------|------|------|------|------|------|\n",
+       "| 50 | 352 | 550 | 352 | 2 | True | False |\n",
+       "| 50 | 392 | 550 | 392 | 0 | True | False |\n",
+       "| 50 | 392 | 50 | 552 | 0 | False | True |\n",
+       "| 100 | 392 | 100 | 552 | 0 | False | True |\n",
+       "| 450 | 392 | 450 | 552 | 0 | False | True |\n",
+       "| 500 | 392 | 500 | 552 | 0 | False | True |\n",
+       "| 550 | 392 | 550 | 552 | 0 | False | True |\n",
+       "| 50 | 412 | 550 | 412 | 0 | True | False |\n",
+       "| 520 | 418 | 528 | 426 | 0 | False | False |\n",
+       "| 520 | 418 | 528 | 426 | 0 | False | False |\n",
+       "| 50 | 432 | 550 | 432 | 0 | True | False |\n",
+       "| 520 | 438 | 528 | 446 | 0 | False | False |\n",
+       "| 520 | 438 | 528 | 446 | 0 | False | False |\n",
+       "| 50 | 452 | 550 | 452 | 0 | True | False |\n",
+       "| 50 | 472 | 550 | 472 | 0 | True | False |\n",
+       "| 50 | 492 | 550 | 492 | 0 | True | False |\n",
+       "| 50 | 512 | 550 | 512 | 0 | True | False |\n",
+       "| 520 | 518 | 528 | 526 | 0 | False | False |\n",
+       "| 520 | 518 | 528 | 526 | 0 | False | False |\n",
+       "| 50 | 532 | 550 | 532 | 0 | True | False |\n",
+       "| 50 | 552 | 550 | 552 | 0 | True | False |"
+      ],
+      "text/plain": [
+       "## Collection Inspection (21 elements)\n",
+       "\n",
+       "### Line Elements\n",
+       "\n",
+       "| x0 | top | x1 | bottom | width | is_horizontal | is_vertical |\n",
+       "|------|------|------|------|------|------|------|\n",
+       "| 50 | 352 | 550 | 352 | 2 | True | False |\n",
+       "| 50 | 392 | 550 | 392 | 0 | True | False |\n",
+       "| 50 | 392 | 50 | 552 | 0 | False | True |\n",
+       "| 100 | 392 | 100 | 552 | 0 | False | True |\n",
+       "| 450 | 392 | 450 | 552 | 0 | False | True |\n",
+       "| 500 | 392 | 500 | 552 | 0 | False | True |\n",
+       "| 550 | 392 | 550 | 552 | 0 | False | True |\n",
+       "| 50 | 412 | 550 | 412 | 0 | True | False |\n",
+       "| 520 | 418 | 528 | 426 | 0 | False | False |\n",
+       "| 520 | 418 | 528 | 426 | 0 | False | False |\n",
+       "| 50 | 432 | 550 | 432 | 0 | True | False |\n",
+       "| 520 | 438 | 528 | 446 | 0 | False | False |\n",
+       "| 520 | 438 | 528 | 446 | 0 | False | False |\n",
+       "| 50 | 452 | 550 | 452 | 0 | True | False |\n",
+       "| 50 | 472 | 550 | 472 | 0 | True | False |\n",
+       "| 50 | 492 | 550 | 492 | 0 | True | False |\n",
+       "| 50 | 512 | 550 | 512 | 0 | True | False |\n",
+       "| 520 | 518 | 528 | 526 | 0 | False | False |\n",
+       "| 520 | 518 | 528 | 526 | 0 | False | False |\n",
+       "| 50 | 532 | 550 | 532 | 0 | True | False |\n",
+       "| 50 | 552 | 550 | 552 | 0 | True | False |"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "page.find_all('line').inspect()"
+   ]
+  }
+ ],
+ "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.11.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

natural_pdf-0.1.17/docs/describe/index.md

@@ -0,0 +1,42 @@
+# Describe Functionality
+
+The `describe()` and `inspect()` methods provide an easy way to understand the contents of your PDF elements without having to visualize them as images.
+
+## Basic Usage
+
+Get a summary of an entire page:
+
+```python
+from natural_pdf import PDF
+
+pdf = PDF("https://github.com/jsoma/natural-pdf/raw/refs/heads/main/pdfs/01-practice.pdf")
+page = pdf.pages[0]
+
+page.describe()
+```
+
+## Element collection summaries
+
+You can describe element collections on a page with `.describe()`.
+
+```python
+# Describe all elements on the page
+page.find_all('text').describe()
+```
+
+```python
+# Describe all elements on the page
+page.find_all('rect').describe()
+```
+
+## Inspecting lists of elements
+
+For more detail, you can view specific details of element collections with `inspect()`.
+
+```python
+page.find_all('text').inspect()
+```
+
+```python
+page.find_all('line').inspect()
+```