pyzotero 1.7.0__tar.gz → 1.7.1__tar.gz

{pyzotero-1.7.0 → pyzotero-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyzotero
-Version: 1.7.0
+Version: 1.7.1
 Summary: Python wrapper for the Zotero API
 Keywords: Zotero,DH
 Author: Stephan Hügel
@@ -126,6 +126,12 @@ pyzotero listcollections
 pyzotero itemtypes
 ```
 
+## Search Behaviour
+
+By default, `pyzotero search` searches only top-level item titles and metadata fields.
+
+When the `--fulltext` flag is used, the search expands to include all full-text indexed content, including PDFs and other attachments. Since most full-text content comes from PDF attachments rather than top-level items, the CLI automatically retrieves the parent bibliographic items for any matching attachments. This ensures you receive useful bibliographic records (journal articles, books, etc.) rather than raw attachment items.
+
 ## Output Format
 
 By default, the CLI outputs human-readable text with a subset of metadata including:

{pyzotero-1.7.0 → pyzotero-1.7.1}/README.md

@@ -59,6 +59,12 @@ pyzotero listcollections
 pyzotero itemtypes
 ```
 
+## Search Behaviour
+
+By default, `pyzotero search` searches only top-level item titles and metadata fields.
+
+When the `--fulltext` flag is used, the search expands to include all full-text indexed content, including PDFs and other attachments. Since most full-text content comes from PDF attachments rather than top-level items, the CLI automatically retrieves the parent bibliographic items for any matching attachments. This ensures you receive useful bibliographic records (journal articles, books, etc.) rather than raw attachment items.
+
 ## Output Format
 
 By default, the CLI outputs human-readable text with a subset of metadata including:

{pyzotero-1.7.0 → pyzotero-1.7.1}/doc/index.rst

@@ -152,6 +152,13 @@ List available item types:
 
         pyzotero itemtypes
 
+Search Behaviour
+----------------
+
+By default, ``pyzotero search`` searches only top-level item titles and metadata fields.
+
+When the ``--fulltext`` flag is used, the search expands to include all full-text indexed content, including PDFs and other attachments. Since most full-text content comes from PDF attachments rather than top-level items, the CLI automatically retrieves the parent bibliographic items for any matching attachments. This ensures you receive useful bibliographic records (journal articles, books, etc.) rather than raw attachment items.
+
 Output Format
 -------------
 

{pyzotero-1.7.0 → pyzotero-1.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyzotero"
-version = "1.7.0"
+version = "1.7.1"
 description = "Python wrapper for the Zotero API"
 readme = "README.md"
 requires-python = ">=3.9"

{pyzotero-1.7.0 → pyzotero-1.7.1}/src/pyzotero/cli.py

@@ -6,6 +6,7 @@ import sys
 import click
 
 from pyzotero import zotero
+from pyzotero.zotero import chunks
 
 
 def _get_zotero_client(locale="en-US"):
@@ -36,7 +37,7 @@ def main(ctx, locale):
 @click.option(
     "--fulltext",
     is_flag=True,
-    help="Enable full-text search (qmode='everything')",
+    help="Search full-text content including PDFs. Retrieves parent items when attachments match.",
 )
 @click.option(
     "--itemtype",
@@ -63,6 +64,12 @@ def main(ctx, locale):
 def search(ctx, query, fulltext, itemtype, collection, limit, output_json):  # noqa: PLR0912, PLR0915
     """Search local Zotero library.
 
+    By default, searches top-level items in titles and metadata.
+
+    When --fulltext is enabled, searches all items including attachment content
+    (PDFs, documents, etc.). If a match is found in an attachment, the parent
+    bibliographic item is retrieved and included in results.
+
     Examples:
         pyzotero search -q "machine learning"
 
@@ -92,8 +99,43 @@ def search(ctx, query, fulltext, itemtype, collection, limit, output_json):  # n
             # Join multiple item types with || for OR search
             params["itemType"] = " || ".join(itemtype)
 
-        # Execute search using collection_items_top() if collection specified, otherwise top()
-        if collection:
+        # Execute search
+        # When fulltext is enabled, use items() or collection_items() to get both
+        # top-level items and attachments. Otherwise use top() or collection_items_top()
+        # to only get top-level items.
+        if fulltext:
+            if collection:
+                results = zot.collection_items(collection, **params)
+            else:
+                results = zot.items(**params)
+
+            # When using fulltext, we need to retrieve parent items for any attachments
+            # that matched, since most full-text content comes from PDFs and other attachments
+            top_level_items = []
+            attachment_items = []
+
+            for item in results:
+                data = item.get("data", {})
+                if "parentItem" in data:
+                    attachment_items.append(item)
+                else:
+                    top_level_items.append(item)
+
+            # Retrieve parent items for attachments in batches of 50
+            parent_items = []
+            if attachment_items:
+                parent_ids = list(
+                    {item["data"]["parentItem"] for item in attachment_items}
+                )
+                for chunk in chunks(parent_ids, 50):
+                    parent_items.extend(zot.get_subset(chunk))
+
+            # Combine top-level items and parent items, removing duplicates by key
+            all_items = top_level_items + parent_items
+            items_dict = {item["data"]["key"]: item for item in all_items}
+            results = list(items_dict.values())
+        # Non-fulltext search: use top() or collection_items_top() as before
+        elif collection:
             results = zot.collection_items_top(collection, **params)
         else:
             results = zot.top(**params)