pyzotero 1.7.6__tar.gz → 1.9.0__tar.gz

{pyzotero-1.7.6 → pyzotero-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyzotero
-Version: 1.7.6
+Version: 1.9.0
 Summary: Python wrapper for the Zotero API
 Keywords: Zotero,DH
 Author: Stephan Hügel
@@ -82,8 +82,8 @@ Description-Content-Type: text/markdown
 Then:
 
 ``` python
-from pyzotero import zotero
-zot = zotero.Zotero(library_id, library_type, api_key) # local=True for read access to local Zotero
+from pyzotero import Zotero
+zot = Zotero(library_id, library_type, api_key)  # local=True for read access to local Zotero
 items = zot.top(limit=5)
 # we've retrieved the latest five top-level items in our library
 # we can print each item's item type and ID

{pyzotero-1.7.6 → pyzotero-1.9.0}/README.md

@@ -15,8 +15,8 @@
 Then:
 
 ``` python
-from pyzotero import zotero
-zot = zotero.Zotero(library_id, library_type, api_key) # local=True for read access to local Zotero
+from pyzotero import Zotero
+zot = Zotero(library_id, library_type, api_key)  # local=True for read access to local Zotero
 items = zot.top(limit=5)
 # we've retrieved the latest five top-level items in our library
 # we can print each item's item type and ID

{pyzotero-1.7.6 → pyzotero-1.9.0}/doc/conf.py

@@ -16,7 +16,6 @@ import sys
 
 sys.path.insert(1, "..")
 import pyzotero
-from pyzotero import zotero as zot
 
 # Tell Jinja2 templates the build is running on Read the Docs
 if os.environ.get("READTHEDOCS", "") == "True":
@@ -24,7 +23,7 @@ if os.environ.get("READTHEDOCS", "") == "True":
         html_context = {}
     html_context["READTHEDOCS"] = True
 
-author = zot.__author__
+author = "Stephan Hügel"
 current_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 
 html_context = {

{pyzotero-1.7.6 → pyzotero-1.9.0}/doc/index.rst

@@ -30,8 +30,8 @@ Getting started (short version)
     .. code-block:: python
         :emphasize-lines: 1,2,3
 
-            from pyzotero import zotero
-            zot = zotero.Zotero(library_id, library_type, api_key)
+            from pyzotero import Zotero
+            zot = Zotero(library_id, library_type, api_key)
             items = zot.top(limit=5)
             # we've retrieved the latest five top-level items in our library
             # we can print each item's item type and ID
@@ -135,6 +135,18 @@ Output as JSON for machine processing:
 
         pyzotero search -q "climate" --json
 
+Filter by tags (multiple tags use AND logic):
+
+    .. code-block:: bash
+
+        pyzotero search -q "topic" --tag "climate" --tag "adaptation"
+
+Paginate results:
+
+    .. code-block:: bash
+
+        pyzotero search -q "topic" --limit 20 --offset 20 --json
+
 List all collections:
 
     .. code-block:: bash
@@ -147,6 +159,59 @@ List available item types:
 
         pyzotero itemtypes
 
+Item and Attachment Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get a single item by key:
+
+    .. code-block:: bash
+
+        pyzotero item ABC123 --json
+
+Get child items (attachments, notes) of an item:
+
+    .. code-block:: bash
+
+        pyzotero children ABC123 --json
+
+Get multiple items by key in a single call (up to 50):
+
+    .. code-block:: bash
+
+        pyzotero subset ABC123 DEF456 GHI789 --json
+
+Get full-text content of an attachment:
+
+    .. code-block:: bash
+
+        pyzotero fulltext ABC123
+
+Tag Commands
+~~~~~~~~~~~~
+
+List all tags in the library:
+
+    .. code-block:: bash
+
+        pyzotero tags
+
+List tags from a specific collection:
+
+    .. code-block:: bash
+
+        pyzotero tags --collection ABC123
+
+DOI Index
+~~~~~~~~~
+
+Output the complete DOI-to-key mapping for caching:
+
+    .. code-block:: bash
+
+        pyzotero doiindex > doi_cache.json
+
+This returns a JSON mapping of normalised DOIs to item keys and original DOIs, allowing external tools to cache the index and avoid repeated full-library scans.
+
 Search Behaviour
 ~~~~~~~~~~~~~~~~
 
@@ -205,8 +270,8 @@ Example:
     .. code-block:: python
         :emphasize-lines: 4
 
-        from pyzotero import zotero
-        zot = zotero.Zotero('123', 'user', 'ABC1234XYZ')
+        from pyzotero import Zotero
+        zot = Zotero('123', 'user', 'ABC1234XYZ')
         # we now have a Zotero object, zot, and access to all its methods
         first_ten = zot.items(limit=10)
         # a list containing dicts of the ten most recently modified library items
@@ -731,8 +796,8 @@ Example:
 
     .. code-block:: python
 
-        from pyzotero import zotero
-        zot = zotero.Zotero(library_id, library_type, api_key)
+        from pyzotero import Zotero
+        zot = Zotero(library_id, library_type, api_key)
         # only retrieve a single item
         # this will retrieve the most recently added/modified top-level item
         first_item = zot.top(limit=1)
@@ -747,8 +812,8 @@ Example:
 
     .. code-block:: python
 
-        from pyzotero import zotero
-        zot = zotero.Zotero(library_id, library_type, api_key)
+        from pyzotero import Zotero
+        zot = Zotero(library_id, library_type, api_key)
         # retrieve all top-level items
         toplevel = zot.everything(zot.top())
 

{pyzotero-1.7.6 → pyzotero-1.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyzotero"
-version = "1.7.6"
+version = "1.9.0"
 description = "Python wrapper for the Zotero API"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -43,12 +43,11 @@ pyzotero = "pyzotero.cli:main"
 dev = [
     "pytest >= 8.4.2",
     "pytz>=2025.2",
-    "httpretty >= 1.1.4",
     "python-dateutil",
     "ipython",
     "pytest-asyncio",
     "pytest-cov>=6.0.0",
-    "tzdata>=2025.2"
+    "tzdata>=2025.2",
 ]
 doc = [
     "sphinx",
@@ -110,9 +109,15 @@ ignore = ["ANN001", "ANN003", "ANN202", "ANN201", "DOC201", "E501", "PLR0904", "
 fixable = ["ALL"]
 unfixable = []
 
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]  # Allow assert in tests
+
 [tool.ruff.format]
 # Like Black, use double quotes for strings.
 quote-style = "double"
 
 # Like Black, indent with spaces, rather than tabs.
 indent-style = "space"
+
+[tool.ty.rules]
+possibly-missing-attribute = "ignore"

pyzotero-1.9.0/src/pyzotero/__init__.py

@@ -0,0 +1,67 @@
+"""Pyzotero - Python wrapper for the Zotero API."""
+
+import importlib.metadata
+
+try:
+    # __package__ allows for the case where __name__ is "__main__"
+    __version__ = importlib.metadata.version(__package__ or __name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+# Public API exports
+from pyzotero._client import Zotero
+from pyzotero._search import SavedSearch
+from pyzotero._upload import Zupload
+from pyzotero._utils import chunks
+from pyzotero.errors import (
+    CallDoesNotExistError,
+    ConflictError,
+    CouldNotReachURLError,
+    FileDoesNotExistError,
+    HTTPError,
+    InvalidItemFieldsError,
+    MissingCredentialsError,
+    ParamNotPassedError,
+    PreConditionFailedError,
+    PreConditionRequiredError,
+    PyZoteroError,
+    RequestEntityTooLargeError,
+    ResourceNotFoundError,
+    TooManyItemsError,
+    TooManyRequestsError,
+    TooManyRetriesError,
+    UnsupportedParamsError,
+    UploadError,
+    UserNotAuthorisedError,
+)
+
+__all__ = [
+    # Exceptions
+    "CallDoesNotExistError",
+    "ConflictError",
+    "CouldNotReachURLError",
+    "FileDoesNotExistError",
+    "HTTPError",
+    "InvalidItemFieldsError",
+    "MissingCredentialsError",
+    "ParamNotPassedError",
+    "PreConditionFailedError",
+    "PreConditionRequiredError",
+    "PyZoteroError",
+    "RequestEntityTooLargeError",
+    "ResourceNotFoundError",
+    "SavedSearch",
+    "TooManyItemsError",
+    "TooManyRequestsError",
+    "TooManyRetriesError",
+    "UnsupportedParamsError",
+    "UploadError",
+    "UserNotAuthorisedError",
+    # Main classes
+    "Zotero",
+    "Zupload",
+    # Version
+    "__version__",
+    # Utilities
+    "chunks",
+]