pyzotero 1.6.16__tar.gz → 1.7.0__tar.gz

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

@@ -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.6.16 → pyzotero-1.7.0}/README.md

@@ -28,11 +28,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.6.16 → pyzotero-1.7.0}/doc/index.rst

@@ -54,6 +54,24 @@ Using `pip <http://www.pip-installer.org/en/latest/index.html>`_: ``pip install
 
 Using `Anaconda <https://www.anaconda.com/distribution/>`_: ``conda install conda-forge::pyzotero``
 
+-------------------------------
+Optional: Command-Line Interface
+-------------------------------
+
+Pyzotero includes an optional command-line interface for searching and querying your local Zotero library.
+
+To install Pyzotero with the CLI:
+
+* Using `uv <https://docs.astral.sh/uv/>`_: ``uv add "pyzotero[cli]"``
+* Using `pip <http://www.pip-installer.org/en/latest/index.html>`_: ``pip install "pyzotero[cli]"``
+
+If you just want to use the CLI without permanently installing Pyzotero:
+
+* Using `uvx <https://docs.astral.sh/uv/>`_: ``uvx --from "pyzotero[cli]" pyzotero search -q "your query"``
+* Using `pipx <https://pipx.pypa.io/>`_: ``pipx run --spec "pyzotero[cli]" pyzotero search -q "your query"``
+
+See :ref:`cli-usage` for usage details.
+
 From a local clone, if you wish to install Pyzotero from a specific branch:
 
     .. code-block:: bash
@@ -81,6 +99,70 @@ Testing requires installation of the ``dev`` dependency group (see above).
 
 Run ``pytest .`` from the top-level directory.
 
+.. _cli-usage:
+
+==========================
+Command-Line Interface Usage
+==========================
+
+The Pyzotero CLI connects to your local Zotero installation and allows you to search your library, list collections, and view item types.
+
+Basic Commands
+--------------
+
+Search for top-level items:
+
+    .. code-block:: bash
+
+        pyzotero search -q "machine learning"
+
+Search with full-text mode:
+
+    .. code-block:: bash
+
+        pyzotero search -q "climate change" --fulltext
+
+Filter by item type:
+
+    .. code-block:: bash
+
+        pyzotero search -q "methodology" --itemtype book --itemtype journalArticle
+
+Search for top-level items within a collection:
+
+    .. code-block:: bash
+
+        pyzotero search --collection ABC123 -q "test"
+
+Output as JSON for machine processing:
+
+    .. code-block:: bash
+
+        pyzotero search -q "climate" --json
+
+List all collections:
+
+    .. code-block:: bash
+
+        pyzotero listcollections
+
+List available item types:
+
+    .. code-block:: bash
+
+        pyzotero itemtypes
+
+Output Format
+-------------
+
+By default, the CLI outputs human-readable text with all relevant metadata including:
+
+* Title, authors, date, publication
+* Volume, issue, DOI, URL
+* PDF attachments (with local file paths)
+
+Use the ``--json`` flag to output structured JSON suitable for consumption by other tools and agents.
+
 
 ======================
 Building Documentation

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

@@ -1,6 +1,6 @@
 [project]
 name = "pyzotero"
-version = "1.6.16"
+version = "1.7.0"
 description = "Python wrapper for the Zotero API"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -33,6 +33,12 @@ Repository = "https://github.com/urschrei/pyzotero"
 Tracker = "https://github.com/urschrei/pyzotero/issues"
 documentation = "https://pyzotero.readthedocs.org"
 
+[project.optional-dependencies]
+cli = ["click>=8.0.0"]
+
+[project.scripts]
+pyzotero = "pyzotero.cli:main"
+
 [dependency-groups]
 dev = [
     "pytest >= 8.4.2",

pyzotero-1.7.0/src/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-1.6.16 → pyzotero-1.7.0}/src/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 → pyzotero-1.7.0}/tests/test_zotero.py

@@ -413,7 +413,28 @@ class ZoteroTests(unittest.TestCase):
         zot.tags()
         self.assertEqual(zot.links["next"], "/users/436/items/top?limit=1&start=1")
         self.assertEqual(zot.links["last"], "/users/436/items/top?limit=1&start=2319")
-        self.assertEqual(zot.links["alternate"], "/users/436/items/top?")
+        self.assertEqual(zot.links["alternate"], "/users/436/items/top")
+
+    @httpretty.activate
+    def testParseLinkHeadersPreservesAllParameters(self):
+        """Test that the self link preserves all parameters, not just the first 2"""
+        zot = z.Zotero("myuserID", "user", "myuserkey")
+        HTTPretty.register_uri(
+            HTTPretty.GET,
+            "https://api.zotero.org/users/myuserID/items/top",
+            content_type="application/json",
+            body=self.items_doc,
+            adding_headers={
+                "Link": '<https://api.zotero.org/users/myuserID/items/top?start=1>; rel="next"'
+            },
+        )
+        # Call with multiple parameters including limit
+        zot.top(limit=1)
+        # The self link should preserve all parameters except format
+        self.assertIn("limit=1", zot.links["self"])
+        self.assertIn("locale=", zot.links["self"])
+        # format should be stripped
+        self.assertNotIn("format=", zot.links["self"])
 
     @httpretty.activate
     def testParseGroupsJSONDoc(self):
@@ -1614,6 +1635,27 @@ class ZoteroTests(unittest.TestCase):
             # Verify the mock was called
             mock_iterfollow.assert_called_once()
 
+    def test_makeiter_preserves_limit_parameter(self):
+        """Test that makeiter preserves the limit parameter in the self link"""
+        zot = z.Zotero("myuserID", "user", "myuserkey")
+
+        # Simulate a self link with multiple parameters including limit
+        # This mimics what _extract_links() creates
+        test_self_link = "/users/myuserID/items/top?limit=1&locale=en-US"
+        zot.links = {
+            "self": test_self_link,
+            "next": "/users/myuserID/items/top?start=1",
+        }
+
+        # Call makeiter (with a dummy function since we're testing link manipulation)
+        with patch.object(zot, "iterfollow"):
+            zot.makeiter(lambda: None)
+
+        # Verify that the 'next' link was set to 'self' and still contains limit parameter
+        self.assertEqual(zot.links["next"], test_self_link)
+        self.assertIn("limit=1", zot.links["next"])
+        self.assertIn("locale=en-US", zot.links["next"])
+
     @httpretty.activate
     def test_publications_user(self):
         """Test the publications method for user libraries"""