pyzotero 1.6.17__py3-none-any.whl → 1.7.1__py3-none-any.whl

pyzotero/cli.py

@@ -0,0 +1,352 @@
+"""Command-line interface for pyzotero."""
+
+import json
+import sys
+
+import click
+
+from pyzotero import zotero
+from pyzotero.zotero import chunks
+
+
+def _get_zotero_client(locale="en-US"):
+    """Get a Zotero client configured for local access."""
+    return zotero.Zotero(library_id="0", library_type="user", local=True, locale=locale)
+
+
+@click.group()
+@click.option(
+    "--locale",
+    default="en-US",
+    help="Locale for localized strings (default: en-US)",
+)
+@click.pass_context
+def main(ctx, locale):
+    """Search local Zotero library."""
+    ctx.ensure_object(dict)
+    ctx.obj["locale"] = locale
+
+
+@main.command()
+@click.option(
+    "-q",
+    "--query",
+    help="Search query string",
+    default="",
+)
+@click.option(
+    "--fulltext",
+    is_flag=True,
+    help="Search full-text content including PDFs. Retrieves parent items when attachments match.",
+)
+@click.option(
+    "--itemtype",
+    multiple=True,
+    help="Filter by item type (can be specified multiple times for OR search)",
+)
+@click.option(
+    "--collection",
+    help="Filter by collection key (returns only items in this collection)",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=1000000,
+    help="Maximum number of results to return (default: 1000000)",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output results as JSON",
+)
+@click.pass_context
+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"
+
+        pyzotero search -q "climate change" --fulltext
+
+        pyzotero search -q "methodology" --itemtype book --itemtype journalArticle
+
+        pyzotero search --collection ABC123 -q "test"
+
+        pyzotero search -q "climate" --json
+
+    """
+    try:
+        locale = ctx.obj.get("locale", "en-US")
+        zot = _get_zotero_client(locale)
+
+        # Build query parameters
+        params = {"limit": limit}
+
+        if query:
+            params["q"] = query
+
+        if fulltext:
+            params["qmode"] = "everything"
+
+        if itemtype:
+            # Join multiple item types with || for OR search
+            params["itemType"] = " || ".join(itemtype)
+
+        # 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)
+
+        # Handle empty results
+        if not results:
+            if output_json:
+                click.echo(json.dumps([]))
+            else:
+                click.echo("No results found.")
+            return
+
+        # Build output data structure
+        output_items = []
+        for item in results:
+            data = item.get("data", {})
+
+            title = data.get("title", "No title")
+            item_type = data.get("itemType", "Unknown")
+            date = data.get("date", "No date")
+            item_key = data.get("key", "")
+            publication = data.get("publicationTitle", "")
+            volume = data.get("volume", "")
+            issue = data.get("issue", "")
+            doi = data.get("DOI", "")
+            url = data.get("url", "")
+
+            # Format creators (authors, editors, etc.)
+            creators = data.get("creators", [])
+            creator_names = []
+            for creator in creators:
+                if "lastName" in creator:
+                    if "firstName" in creator:
+                        creator_names.append(
+                            f"{creator['firstName']} {creator['lastName']}"
+                        )
+                    else:
+                        creator_names.append(creator["lastName"])
+                elif "name" in creator:
+                    creator_names.append(creator["name"])
+
+            # Check for PDF attachments
+            pdf_attachments = []
+            num_children = item.get("meta", {}).get("numChildren", 0)
+            if num_children > 0:
+                children = zot.children(item_key)
+                for child in children:
+                    child_data = child.get("data", {})
+                    if child_data.get("contentType") == "application/pdf":
+                        # Extract file URL from links.enclosure.href
+                        file_url = (
+                            child.get("links", {}).get("enclosure", {}).get("href", "")
+                        )
+                        if file_url:
+                            pdf_attachments.append(file_url)
+
+            # Build item object for JSON output
+            item_obj = {
+                "key": item_key,
+                "itemType": item_type,
+                "title": title,
+                "creators": creator_names,
+                "date": date,
+                "publication": publication,
+                "volume": volume,
+                "issue": issue,
+                "doi": doi,
+                "url": url,
+                "pdfAttachments": pdf_attachments,
+            }
+            output_items.append(item_obj)
+
+        # Output results
+        if output_json:
+            click.echo(json.dumps(output_items, indent=2))
+        else:
+            click.echo(f"\nFound {len(results)} items:\n")
+            for idx, item_obj in enumerate(output_items, 1):
+                authors_str = (
+                    ", ".join(item_obj["creators"])
+                    if item_obj["creators"]
+                    else "No authors"
+                )
+
+                click.echo(f"{idx}. [{item_obj['itemType']}] {item_obj['title']}")
+                click.echo(f"   Authors: {authors_str}")
+                click.echo(f"   Date: {item_obj['date']}")
+                click.echo(f"   Publication: {item_obj['publication']}")
+                click.echo(f"   Volume: {item_obj['volume']}")
+                click.echo(f"   Issue: {item_obj['issue']}")
+                click.echo(f"   DOI: {item_obj['doi']}")
+                click.echo(f"   URL: {item_obj['url']}")
+                click.echo(f"   Key: {item_obj['key']}")
+
+                if item_obj["pdfAttachments"]:
+                    click.echo("   PDF Attachments:")
+                    for pdf_url in item_obj["pdfAttachments"]:
+                        click.echo(f"      {pdf_url}")
+
+                click.echo()
+
+    except Exception as e:
+        click.echo(f"Error: {e!s}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.option(
+    "--limit",
+    type=int,
+    help="Maximum number of collections to return (default: all)",
+)
+@click.pass_context
+def listcollections(ctx, limit):
+    """List all collections in the local Zotero library.
+
+    Examples:
+        pyzotero listcollections
+
+        pyzotero listcollections --limit 10
+
+    """
+    try:
+        locale = ctx.obj.get("locale", "en-US")
+        zot = _get_zotero_client(locale)
+
+        # Build query parameters
+        params = {}
+        if limit:
+            params["limit"] = limit
+
+        # Get all collections
+        collections = zot.collections(**params)
+
+        if not collections:
+            click.echo(json.dumps([]))
+            return
+
+        # Build a mapping of collection keys to names for parent lookup
+        collection_map = {}
+        for collection in collections:
+            data = collection.get("data", {})
+            key = data.get("key", "")
+            name = data.get("name", "")
+            if key:
+                collection_map[key] = name if name else None
+
+        # Build JSON output
+        output = []
+        for collection in collections:
+            data = collection.get("data", {})
+            meta = collection.get("meta", {})
+
+            name = data.get("name", "")
+            key = data.get("key", "")
+            num_items = meta.get("numItems", 0)
+            parent_collection = data.get("parentCollection", "")
+
+            collection_obj = {
+                "id": key,
+                "name": name if name else None,
+                "items": num_items,
+            }
+
+            # Add parent information if it exists
+            if parent_collection:
+                parent_name = collection_map.get(parent_collection)
+                collection_obj["parent"] = {
+                    "id": parent_collection,
+                    "name": parent_name,
+                }
+            else:
+                collection_obj["parent"] = None
+
+            output.append(collection_obj)
+
+        # Output as JSON
+        click.echo(json.dumps(output, indent=2))
+
+    except Exception as e:
+        click.echo(f"Error: {e!s}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.pass_context
+def itemtypes(ctx):
+    """List all valid item types.
+
+    Examples:
+        pyzotero itemtypes
+
+    """
+    try:
+        locale = ctx.obj.get("locale", "en-US")
+        zot = _get_zotero_client(locale)
+
+        # Get all item types
+        item_types = zot.item_types()
+
+        if not item_types:
+            click.echo(json.dumps([]))
+            return
+
+        # Output as JSON array
+        click.echo(json.dumps(item_types, indent=2))
+
+    except Exception as e:
+        click.echo(f"Error: {e!s}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pyzotero/zotero.py

@@ -51,14 +51,13 @@ DEFAULT_ITEM_LIMIT = 100
 def build_url(base_url, path, args_dict=None):
     """Build a valid URL so we don't have to worry about string concatenation errors and
     leading / trailing slashes etc.
-    Returns a list in the structure of urlparse.ParseResult
     """
     base_url = base_url.removesuffix("/")
-    url_parts = list(urlparse(base_url))
-    url_parts[2] += path
+    parsed = urlparse(base_url)
+    new_path = str(PurePosixPath(parsed.path) / path.removeprefix("/"))
     if args_dict:
-        url_parts[4] = urlencode(args_dict)
-    return urlunparse(url_parts)
+        return urlunparse(parsed._replace(path=new_path, query=urlencode(args_dict)))
+    return urlunparse(parsed._replace(path=new_path))
 
 
 def merge_params(url, params):
@@ -513,7 +512,7 @@ class Zotero:
         try:
             for key, value in self.request.links.items():
                 parsed = urlparse(value["url"])
-                fragment = f"{parsed[2]}?{parsed[4]}"
+                fragment = urlunparse(("", "", parsed.path, "", parsed.query, ""))
                 extracted[key] = fragment
             # add a 'self' link
             parsed = urlparse(str(self.self_link))

{pyzotero-1.6.17.dist-info → pyzotero-1.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyzotero
-Version: 1.6.17
+Version: 1.7.1
 Summary: Python wrapper for the Zotero API
 Keywords: Zotero,DH
 Author: Stephan Hügel
@@ -57,10 +57,12 @@ Requires-Dist: feedparser>=6.0.12
 Requires-Dist: bibtexparser>=1.4.3,<2.0.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: whenever>=0.8.8
+Requires-Dist: click>=8.0.0 ; extra == 'cli'
 Requires-Python: >=3.9
 Project-URL: Repository, https://github.com/urschrei/pyzotero
 Project-URL: Tracker, https://github.com/urschrei/pyzotero/issues
 Project-URL: documentation, https://pyzotero.readthedocs.org
+Provides-Extra: cli
 Description-Content-Type: text/markdown
 
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/Pyzotero.svg?style=flat)](https://pypi.python.org/pypi/Pyzotero/) [![Docs](https://readthedocs.org/projects/pyzotero/badge/?version=latest)](http://pyzotero.readthedocs.org/en/latest/?badge=latest) [![PyPI Version](https://img.shields.io/pypi/v/Pyzotero.svg)](https://pypi.python.org/pypi/Pyzotero) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/pyzotero/badges/version.svg)](https://anaconda.org/conda-forge/pyzotero) [![Downloads](https://pepy.tech/badge/pyzotero)](https://pepy.tech/project/pyzotero)  
@@ -93,11 +95,80 @@ for item in items:
 
 Full documentation of available Pyzotero methods, code examples, and sample output is available on [Read The Docs][3].
 
+# Command-Line Interface
+
+Pyzotero includes an optional command-line interface for searching and querying your local Zotero library. The CLI must be installed separately (see [Installation](#optional-command-line-interface)).
+
+## Basic Usage
+
+The CLI connects to your local Zotero installation and allows you to search your library, list collections, and view item types:
+
+```bash
+# Search for top-level items
+pyzotero search -q "machine learning"
+
+# Search with full-text mode
+pyzotero search -q "climate change" --fulltext
+
+# Filter by item type
+pyzotero search -q "methodology" --itemtype book --itemtype journalArticle
+
+# Search for top-level items within a collection
+pyzotero search --collection ABC123 -q "test"
+
+# Output as JSON for machine processing
+pyzotero search -q "climate" --json
+
+# List all collections
+pyzotero listcollections
+
+# 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
+
+By default, the CLI outputs human-readable text with a subset of metadata including:
+- Title, authors, date, publication
+- Volume, issue, DOI, URL
+- PDF attachments (with local file paths)
+
+Use the `--json` flag to output structured JSON.
+
 # Installation
 
 * Using [uv][11]: `uv add pyzotero`
 * Using [pip][10]: `pip install pyzotero`
 * Using Anaconda:`conda install conda-forge::pyzotero`
+
+## Optional: Command-Line Interface
+
+Pyzotero includes an optional command-line interface for searching and querying your local Zotero library.
+
+### Installing the CLI
+
+To install Pyzotero with the CLI:
+
+* Using [uv][11]: `uv add "pyzotero[cli]"`
+* Using [pip][10]: `pip install "pyzotero[cli]"`
+
+### Using the CLI without installing
+
+If you just want to use the CLI without permanently installing Pyzotero, you can run it directly:
+
+* Using [uvx][11]: `uvx --from "pyzotero[cli]" pyzotero search -q "your query"`
+* Using [pipx][10]: `pipx run --spec "pyzotero[cli]" pyzotero search -q "your query"`
+
+See the [Command-Line Interface](#command-line-interface) section below for usage details.
+
+## Installing from Source
+
 * From a local clone, if you wish to install Pyzotero from a specific branch: 
 
 Example:

pyzotero-1.7.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyzotero/__init__.py,sha256=5QI4Jou9L-YJAf_oN9TgRXVKgt_Unc39oADo2Ch8bLI,243
+pyzotero/cli.py,sha256=4vWX8SobVoHouJ1k7cumqtuWKqeFPPp5QyZzfdzBDOc,11023
+pyzotero/filetransport.py,sha256=umLik1LLmrpgaNmyjvtBoqqcaMgIq79PYsTvN5vG-gY,5530
+pyzotero/zotero.py,sha256=4qb7jLl1lNkDv3WpEPLW2L0SbleTtGYlQ6Rloz-hmN0,76497
+pyzotero/zotero_errors.py,sha256=6obx9-pBO0z1bxt33vuzDluELvA5kSLCsfc-uGc3KNw,2660
+pyzotero-1.7.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pyzotero-1.7.1.dist-info/entry_points.txt,sha256=MzN7IMRj_oPNmDCsseYFPum3bHWE1gFxywhlbFbcn2k,48
+pyzotero-1.7.1.dist-info/METADATA,sha256=-fxVGQetAnFkecnXs67FhGSJfsbL9i_a7VOMg7_Rz2c,9776
+pyzotero-1.7.1.dist-info/RECORD,,

{pyzotero-1.6.17.dist-info → pyzotero-1.7.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.23
+Generator: uv 0.8.24
 Root-Is-Purelib: true
 Tag: py3-none-any

pyzotero-1.7.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pyzotero = pyzotero.cli:main
+

pyzotero-1.6.17.dist-info/RECORD

@@ -1,7 +0,0 @@
-pyzotero/__init__.py,sha256=5QI4Jou9L-YJAf_oN9TgRXVKgt_Unc39oADo2Ch8bLI,243
-pyzotero/filetransport.py,sha256=umLik1LLmrpgaNmyjvtBoqqcaMgIq79PYsTvN5vG-gY,5530
-pyzotero/zotero.py,sha256=2Mjvr15sHRHR1MCeifniIXVtqqC4n-P_kDr8Z5Vdkhw,76427
-pyzotero/zotero_errors.py,sha256=6obx9-pBO0z1bxt33vuzDluELvA5kSLCsfc-uGc3KNw,2660
-pyzotero-1.6.17.dist-info/WHEEL,sha256=n2u5OFBbdZvCiUKAmfnY1Po2j3FB_NWfuUlt5WiAjrk,79
-pyzotero-1.6.17.dist-info/METADATA,sha256=3h20funfN9wdaduCVZ8IBFFUB1K4IlH_Tlrj-OD7BmA,7292
-pyzotero-1.6.17.dist-info/RECORD,,