pyzotero 1.6.16__py3-none-any.whl → 1.7.0__py3-none-any.whl

pyzotero/cli.py

@@ -0,0 +1,310 @@
+"""Command-line interface for pyzotero."""
+
+import json
+import sys
+
+import click
+
+from pyzotero import zotero
+
+
+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="Enable full-text search (qmode='everything')",
+)
+@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.
+
+    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 using collection_items_top() if collection specified, otherwise top()
+        if 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

@@ -43,24 +43,21 @@ from .filetransport import Client as File_Client
 # Avoid hanging the application if there's no server response
 timeout = 30
 
-NOT_MODIFIED = 304
 ONE_HOUR = 3600
 DEFAULT_NUM_ITEMS = 50
 DEFAULT_ITEM_LIMIT = 100
-TOO_MANY_REQUESTS = 429
 
 
 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):
@@ -451,8 +448,6 @@ class Zotero:
         Returns a JSON document
         """
         full_url = build_url(self.endpoint, request)
-        # The API doesn't return this any more, so we have to cheat
-        self.self_link = request
         # ensure that we wait if there's an active backoff
         self._check_backoff()
         # don't set locale if the url already contains it
@@ -485,6 +480,8 @@ class Zotero:
                 timeout=timeout,
             )
             self.request.encoding = "utf-8"
+            # The API doesn't return this any more, so we have to cheat
+            self.self_link = self.request.url
         except httpx.UnsupportedProtocol:
             # File URI handler logic
             fc = File_Client()
@@ -515,18 +512,15 @@ 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 = list(urlparse(self.self_link))
-            # strip 'format' query parameter
-            stripped = "&".join(
-                ["=".join(p) for p in parse_qsl(parsed[4])[:2] if p[0] != "format"],
-            )
-            # rebuild url fragment
-            # this is a death march
+            parsed = urlparse(str(self.self_link))
+            # strip 'format' query parameter and rebuild query string
+            query_params = [(k, v) for k, v in parse_qsl(parsed.query) if k != "format"]
+            # rebuild url fragment with just path and query (consistent with other links)
             extracted["self"] = urlunparse(
-                [parsed[0], parsed[1], parsed[2], parsed[3], stripped, parsed[5]],
+                ("", "", parsed.path, "", urlencode(query_params), "")
             )
         except KeyError:
             # No links present, because it's a single item
@@ -572,7 +566,7 @@ class Zotero:
             )
             if backoff:
                 self._set_backoff(backoff)
-            return req.status_code == NOT_MODIFIED
+            return req.status_code == httpx.codes.NOT_MODIFIED
         # Still plenty of life left in't
         return False
 
@@ -1647,7 +1641,7 @@ def error_handler(zot, req, exc=None):
 
     if error_codes.get(req.status_code):
         # check to see whether its 429
-        if req.status_code == TOO_MANY_REQUESTS:
+        if req.status_code == httpx.codes.TOO_MANY_REQUESTS:
             # try to get backoff or delay duration
             delay = req.headers.get("backoff") or req.headers.get("retry-after")
             if not delay:

{pyzotero-1.6.16.dist-info → pyzotero-1.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyzotero
-Version: 1.6.16
+Version: 1.7.0
 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,74 @@ 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
+```
+
+## 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.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyzotero/__init__.py,sha256=5QI4Jou9L-YJAf_oN9TgRXVKgt_Unc39oADo2Ch8bLI,243
+pyzotero/cli.py,sha256=H7R9Nx5OEyrET1S19kQrC2g_rDq_7_RE9iCe_dKBEwY,9126
+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.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pyzotero-1.7.0.dist-info/entry_points.txt,sha256=MzN7IMRj_oPNmDCsseYFPum3bHWE1gFxywhlbFbcn2k,48
+pyzotero-1.7.0.dist-info/METADATA,sha256=P26XM2Jb11lOpAw4McrEZFwNpwvr9jyMfvC_2v6MVr8,9233
+pyzotero-1.7.0.dist-info/RECORD,,

{pyzotero-1.6.16.dist-info → pyzotero-1.7.0.dist-info}/WHEEL

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

pyzotero-1.7.0.dist-info/entry_points.txt

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

pyzotero-1.6.16.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=wDKLPjNt-Eo1XUnLlgAscNKZkDI6J60_nVbplXsGk8A,76441
-pyzotero/zotero_errors.py,sha256=6obx9-pBO0z1bxt33vuzDluELvA5kSLCsfc-uGc3KNw,2660
-pyzotero-1.6.16.dist-info/WHEEL,sha256=pFCy50wRV2h7SjJ35YOsQUupaV45rMdgpNIvnXbG5bE,79
-pyzotero-1.6.16.dist-info/METADATA,sha256=oFB4Mcb6MtVf9eyd2cOz0LCwpzrT-CU6uOIzwDvh3jU,7292
-pyzotero-1.6.16.dist-info/RECORD,,