pyzotero 1.6.8__tar.gz → 1.6.10__tar.gz

pyzotero-1.6.10/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+<!-- Thanks for opening a PR. Please read the following:
+
+- **Base your changes on the `main` branch**
+    - If necessary, rebase against `main` before opening a pull request
+- This codebase uses Ruff. PRs that reformat code will not be accepted.
+- Ensure that all methods added have a proper docstring. **Please do not use Doctest**
+- If at all possible, don't add dependencies
+    - If it is unavoidable, you must ensure that the dependency is maintained, and supported
+    - Ensure that you add your dependency to [pyproject.toml](pyproject.toml)
+- Run the tests and ensure that they pass. If you are adding a feature **you must add tests that exercise it**
+- If your pull request is a feature **document the feature**
+- One feature per pull request
+- [squash](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits) your commits before opening a pull request unless it makes no sense to do so
+- If in doubt, comment your code.
+
+## License of Contributed Code
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed under the Blua Oak Model License 1.0, without any additional terms or conditions.  
+Please note that pull requests with licenses that are more restrictive than or otherwise incompatible with the license will not be accepted. -->
+
+Description of changes:
+Issue reference (if applicable):
+
+- [ ] I have read [the CONTRIBUTING doc](CONTRIBUTING.md)

{pyzotero-1.6.8 → pyzotero-1.6.10}/.github/workflows/tests.yml

@@ -3,6 +3,19 @@ name: Build wheel, release and publish on new tag
 on: [push, pull_request]
 
 jobs:
+  lint:
+    name: run Ruff
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Optional, use if you use setuptools_scm
+        submodules: false  # Optional, use if you have submodules
+      name: Check out repo
+    - uses: astral-sh/ruff-action@v3
+      with:
+        args: "check --verbose"
+
   build:
     name: Build and test
     runs-on: ubuntu-latest
@@ -11,27 +24,25 @@ jobs:
         python-version: [3.9, 3.10.9, 3.11, 3.12, 3.13]
 
     steps:
-    - uses: actions/checkout@v4
+    - name: check out repo
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0  # Optional, use if you use setuptools_scm
         submodules: false  # Optional, use if you have submodules
-      name: Check out repo
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+
+    - name: Install uv and set the python version
+      uses: astral-sh/setup-uv@v5
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install wheel
-        pip install .[test] --use-pep517
-    - name: Test with pytest
-      run: |
-        pytest
+
+    - name: Install the project and deps
+      run: uv sync --all-extras --dev
+
+    - name: Run tests
+      run: uv run pytest
+
     - name: Build wheel
-      run: |
-        python -m pip install --upgrade pip
-        pip wheel . -w dist --no-deps --use-pep517
+      run: uv build --no-sources --wheel  -o dist
 
     - uses: actions/upload-artifact@v4
       name: Upload wheel as artifact
@@ -49,17 +60,31 @@ jobs:
         fetch-depth: 0  # Optional, use if you use setuptools_scm
         submodules: true  # Optional, use if you have submodules
 
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
     - name: Build SDist
-      run: pipx run build --sdist
+      run: uv build --no-sources --sdist -o dist
 
     - uses: actions/upload-artifact@v4
       with:
         path: dist/*.tar.gz
 
+  status_check:
+    name: All Checks
+    needs: [lint, build]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Check status
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1
+
+
   release_artifacts:
     if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
     name: Release repaired and tested wheels
-    needs: build
+    needs: [status_check, make_sdist]
     runs-on: ubuntu-latest
     environment: release
     permissions:
@@ -85,6 +110,6 @@ jobs:
         token: ${{ secrets.GITHUB_TOKEN }}
 
     - name: PyPI Publish
-      uses: pypa/gh-action-pypi-publish@v1.12.3
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
         packages-dir: ${{ steps.download.outputs.download-path }}

{pyzotero-1.6.8 → pyzotero-1.6.10}/CONTRIBUTING.md

@@ -1,17 +1,18 @@
 # Contributing
 Contributions are welcome. Please bear the following in mind:
 
-- **Base your changes on the dev branch**
-    - If necessary, rebase against `dev` before opening a pull request
-- Follow [PEP 8](http://www.python.org/dev/peps/pep-0008/). I currently periodically run [`Black`](https://black.readthedocs.io/en/stable/) against the codebase and perhaps you should, too
-- Use spaces for indentation, and ensure that all methods have a proper docstring. **Please don't use Doctest**
+- **Base your changes on the `main` branch**
+    - If necessary, rebase against `main` before opening a pull request
+- This codebase uses Ruff, and PRs are gated on `ruff check` passing. Run `ruff check` locally before opening a PR
+  - PRs that reformat code will not be accepted.
+- Ensure that all methods added have a proper docstring. **Please do not use Doctest**
 - If at all possible, don't add dependencies
-    - If it's unavoidable, ensure that the dependency is maintained, and supported
-    - Ensure that you add your dependency to [setup.py](setup.py)
-- Run the tests, and ensure that they pass. If you're adding a feature, **you must add tests that exercise it**
-- If your pull request is a feature, **document it**
+    - If it is unavoidable, you must ensure that the dependency is maintained, and supported
+    - Ensure that you add your dependency to [pyproject.toml](pyproject.toml)
+- Run the tests and ensure that they pass. If you are adding a feature **you must add tests that exercise it**
+- If your pull request is a feature **document the feature**
 - One feature per pull request
-- If possible, [squash](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits) your commits before opening a pull request, unless it makes no sense to do so
+- [squash](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits) your commits before opening a pull request unless it makes no sense to do so
 - If in doubt, comment your code.
 
 # License of Contributed Code

{pyzotero-1.6.8 → pyzotero-1.6.10}/CONTRIBUTORS.md

@@ -14,7 +14,9 @@
 | 1 | [christianbrodbeck](https://github.com/urschrei/pyzotero/commits?author=christianbrodbeck) |
 | 1 | [egh](https://github.com/urschrei/pyzotero/commits?author=egh) |
 | 1 | [fmagin](https://github.com/urschrei/pyzotero/commits?author=fmagin) |
+| 1 | [pnb](https://github.com/urschrei/pyzotero/commits?author=pnb) |
 | 1 | [porduna](https://github.com/urschrei/pyzotero/commits?author=porduna) |
 | 1 | [stakats](https://github.com/urschrei/pyzotero/commits?author=stakats) |
 | 1 | [epistemery](https://github.com/urschrei/pyzotero/commits?author=epistemery) |
+| 1 | [tnajdek](https://github.com/urschrei/pyzotero/commits?author=tnajdek) |
 | 1 | [jghauser](https://github.com/urschrei/pyzotero/commits?author=jghauser) |

{pyzotero-1.6.8 → pyzotero-1.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pyzotero
-Version: 1.6.8
+Version: 1.6.10
 Summary: Python wrapper for the Zotero API
 Author-email: Stephan Hügel <urschrei@gmail.com>
 License: # Blue Oak Model License
@@ -41,6 +41,7 @@ License: # Blue Oak Model License
         
 Project-URL: Repository, https://github.com/urschrei/pyzotero
 Project-URL: Tracker, https://github.com/urschrei/pyzotero/issues
+Project-URL: documentation, https://pyzotero.readthedocs.org
 Keywords: Zotero,DH
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.9
@@ -69,6 +70,8 @@ Requires-Dist: httpretty; extra == "test"
 Requires-Dist: python-dateutil; extra == "test"
 Requires-Dist: ipython; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Dynamic: license-file
 
 [![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)  
 

{pyzotero-1.6.8 → pyzotero-1.6.10}/doc/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 #
 # Pyzotero documentation build configuration file, created by
 # sphinx-quickstart on Mon Jul  4 19:52:05 2011.
@@ -11,9 +10,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import os
 import sys
-from datetime import date
 
 sys.path.insert(1, "..")
 import pyzotero
@@ -26,7 +25,7 @@ if os.environ.get("READTHEDOCS", "") == "True":
     html_context["READTHEDOCS"] = True
 
 author = zot.__author__
-current_year = date.today().year
+current_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 
 html_context = {
     "display_github": True,  # Integrate GitHub
@@ -63,7 +62,7 @@ master_doc = "index"
 
 # General information about the project.
 project = "Pyzotero"
-copyright = "2011 – %s, %s" % (current_year, author)
+copyright = f"2011 - {current_year}, {author}"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -240,7 +239,7 @@ man_pages = [("index", "pyzotero", "Pyzotero Documentation", [author], 1)]
 epub_title = "Pyzotero"
 epub_author = author
 epub_publisher = author
-epub_copyright = "2011 – %s, %s" % (current_year, author)
+epub_copyright = f"2011 - {current_year}, {author}"
 
 # The language of the text. It defaults to the language option
 # or en if the language is not set.

{pyzotero-1.6.8 → pyzotero-1.6.10}/doc/index.rst

@@ -168,6 +168,12 @@ The following methods will retrieve either user or group items, depending on the
 
         :rtype: list of dicts
 
+    .. py:method:: Zotero.settings([since])
+
+        Returns synced Zotero user library settings such as feeds and PDF reading progress. Use the optional ``since`` parameter to specify the retrieval of changes since a known previous library version.
+
+        :rtype: list of dicts
+
     .. py:method:: Zotero.count_items()
 
         Returns a count of all items in a library / group

pyzotero-1.6.10/dump_contributors.py

@@ -0,0 +1,13 @@
+import httpx
+
+url = "https://api.github.com/repos/urschrei/pyzotero/contributors"
+result = httpx.get(url)
+result.raise_for_status()
+as_dict = [d for d in result.json() if not d["login"].lower().startswith("dependabot")]
+# remove me from the list
+as_dict.pop(0)
+header = "# This is the list of people (as distinct from [AUTHORS](AUTHORS)) who have contributed code to Pyzotero.\n\n| **Commits** | **Contributor**<br/> |\n| --- |--- |\n"
+template = "| {contributions} | [{login}](https://github.com/urschrei/pyzotero/commits?author={login}) |\n"
+with open("CONTRIBUTORS.md", "w", encoding="utf-8") as f:
+    f.write(header)
+    f.writelines(template.format(**dct) for dct in as_dict)

pyzotero-1.6.10/example/.gitignore

@@ -0,0 +1,3 @@
+*.pdf
+*.ipynb
+data/

pyzotero-1.6.10/example/local_base_use.py

@@ -0,0 +1,7 @@
+from pyzotero import zotero
+zot = zotero.Zotero(library_id='000000', library_type = 'user', local=True) # 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
+for item in items:
+    print(f"Item: {item['data']['itemType']} | Key: {item['data']['key']}")

pyzotero-1.6.10/example/local_copy_pdf.py

@@ -0,0 +1,63 @@
+from pyzotero import zotero
+from pathlib import Path
+
+def copy_specific_pdf(item_id, output_dir, new_name=None):
+    """
+    Copy a specific PDF attachment from Zotero library to specified folder using dump()
+
+    Args:
+        item_id (str): Zotero item ID
+        output_dir (str): Path to output directory
+        new_name (str, optional): New filename for the PDF. If None, uses original name
+
+    """
+    # Initialize Zotero client with local=True
+    zot = zotero.Zotero(library_id='000000', library_type='user', local=True)
+
+    # Create output directory if it doesn't exist
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Get the item metadata first
+        item = zot.item(item_id)
+
+        try:
+            # Get original filename or use default
+            default_filename = f"{item_id}.pdf"
+            original_filename = item['data'].get('filename', default_filename)
+
+            # Use new_name if provided, otherwise use original filename
+            filename = new_name if new_name else original_filename
+
+            # Add .pdf extension if not present
+            if not filename.lower().endswith('.pdf'):
+                filename += '.pdf'
+
+            # Use dump() with explicit filename
+            full_path = zot.dump(
+                item_id,
+                filename=filename,
+                path=str(output_path)
+            )
+
+            print(f"\nSuccessfully copied file to: {full_path}")
+            print(f"Title: {item['data'].get('title', 'No title')}")
+
+        except Exception as e:
+            print(f"Error copying file: {e!s}")
+            print(f"Item data: {item['data']}")  # Debug info
+
+    except Exception as e:
+        print(f"Error accessing Zotero item: {e!s}")
+
+if __name__ == "__main__":
+    # Example usage with specific item ID
+    item_id = '8M9FYC2W'
+    data_dir = "./example/data/pdfs"
+
+    # Example 1: Copy with new name
+    copy_specific_pdf(item_id, data_dir, new_name="my_paper")
+
+    # Example 2: Copy with original filename
+    copy_specific_pdf(item_id, data_dir)

pyzotero-1.6.10/example/local_get_item_detail.py

@@ -0,0 +1,68 @@
+from pyzotero import zotero
+from pprint import pprint
+
+def get_item_detail(item_id):
+    """
+    Get detailed information about a specific Zotero item
+    Args:
+        item_id (str): Zotero item ID
+    """
+    # Initialize Zotero client with local=True
+    zot = zotero.Zotero(library_id='000000', library_type='user', local=True)
+
+    try:
+        # Get the item
+        item = zot.item(item_id)
+
+        # Print basic information
+        print("\nItem Details:")
+        print("-" * 50)
+        print(f"Item ID: {item['key']}")
+        print(f"Item Type: {item['data'].get('itemType', 'Not specified')}")
+        print(f"Title: {item['data'].get('title', 'No title')}")
+
+        # If it's an attachment, show parent item
+        if item['data'].get('parentItem'):
+            try:
+                parent = zot.item(item['data']['parentItem'])
+                print("\nParent Item:")
+                print(f"Parent ID: {parent['key']}")
+                print(f"Parent Title: {parent['data'].get('title', 'No title')}")
+            except Exception as e:
+                print(f"Error getting parent item: {e!s}")
+
+        # If it has child items (attachments), show them
+        children = zot.children(item_id)
+        if children:
+            print("\nChild Items:")
+            for child in children:
+                print(f"- {child['data'].get('title', 'No title')} "
+                      f"(ID: {child['key']}, "
+                      f"Type: {child['data'].get('itemType', 'Unknown')})")
+
+        # Show collections this item belongs to
+        collections = item['data'].get('collections', [])
+        if collections:
+            print("\nCollections:")
+            try:
+                for coll_id in collections:
+                    coll = zot.collection(coll_id)
+                    print(f"- {coll['data'].get('name', 'Unnamed')} (ID: {coll_id})")
+            except Exception as e:
+                print(f"Error retrieving collections: {e!s}")
+
+        # Show all metadata
+        print("\nFull Metadata:")
+        print("-" * 50)
+        pprint(item['data'])
+
+    except Exception as e:
+        print(f"Error getting item details: {e!s}")
+        return None
+    else:
+        return item
+
+if __name__ == "__main__":
+    # Example usage with a specific item ID
+    item_id = 'K9V7JFXY'  # Replace with your item ID
+    item_detail = get_item_detail(item_id)

pyzotero-1.6.10/example/local_search_title.py

@@ -0,0 +1,43 @@
+from pyzotero import zotero
+
+def search_by_title(title_query):
+    """
+    Search Zotero items by title
+    Args:
+        title_query (str): The title or part of title to search for
+    Returns:
+        list: List of matching items
+    """
+    # Initialize Zotero client with local=True
+    zot = zotero.Zotero(library_id='000000', library_type='user', local=True)
+
+    try:
+        # Search for items where title contains the query string
+        results = zot.items(q=title_query)
+
+        # Print results
+        print(f"\nFound {len(results)} items matching '{title_query}':")
+        for item in results:
+            # Get the item data
+            title = item['data'].get('title', 'No title')
+            item_type = item['data'].get('itemType', 'Unknown type')
+            date = item['data'].get('date', 'No date')
+            item_id = item['data'].get('key', 'No ID')
+
+            print("\n##########################")
+            print(f"ID: {item_id}")
+            print(f"Title: {title}")
+            print(f"Type: {item_type}")
+            print(f"Date: {date}")
+            print("##########################\n")
+
+    except Exception as e:
+        print(f"Error searching Zotero: {e!s}")
+        return []
+    else:
+        return results
+
+if __name__ == "__main__":
+    # Example usage
+    search_query = "uORFs"  # Change this to your search term
+    search_by_title(search_query)

{pyzotero-1.6.8 → pyzotero-1.6.10}/pyproject.toml

@@ -30,6 +30,7 @@ classifiers = [
 [project.urls]
 Repository = "https://github.com/urschrei/pyzotero"
 Tracker = "https://github.com/urschrei/pyzotero/issues"
+documentation = "https://pyzotero.readthedocs.org"
 
 [project.optional-dependencies]
 test = [
@@ -38,6 +39,7 @@ test = [
     "python-dateutil",
     "ipython",
     "pytest-asyncio",
+    "pytest-cov>=6.0.0",
 ]
 
 [tool.setuptools.dynamic]
@@ -53,7 +55,7 @@ requires = [
 [tool.pytest.ini_options]
 minversion = "6.2.2"
 addopts = [
-    "--import-mode=importlib",
+    "--import-mode=importlib", "--cov=pyzotero", "--cov-report=xml",
 ]
 testpaths = [
     "tests",
@@ -63,3 +65,46 @@ asyncio_default_fixture_loop_scope = "function"
 
 [tool.setuptools_scm]
 write_to = "src/_version.py"
+
+[tool.ruff]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "N", "D4", "UP", "PL", "TRY", "PERF", "FURB", "RUF", "S", "DTZ"]
+ignore = ["ANN001", "ANN003", "ANN202", "ANN201", "DOC201", "E501", "PLR0904", "PLR0913", "PLR0917", "SLF001", "FIX002", "D400", "D415"]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"

{pyzotero-1.6.8 → pyzotero-1.6.10}/src/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.6.8'
-__version_tuple__ = version_tuple = (1, 6, 8)
+__version__ = version = '1.6.10'
+__version_tuple__ = version_tuple = (1, 6, 10)

{pyzotero-1.6.8 → pyzotero-1.6.10}/src/pyzotero/filetransport.py

@@ -32,7 +32,7 @@
 
 import asyncio
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Optional
 
 import httpx
 from httpx import (
@@ -65,7 +65,7 @@ httpx.URL.is_absolute_url = property(is_absolute_url)  # type: ignore
 
 
 class FileTransport(AsyncBaseTransport, BaseTransport):
-    def _handle(self, request: Request) -> Tuple[Optional[int], httpx.Headers]:
+    def _handle(self, request: Request) -> tuple[Optional[int], httpx.Headers]:
         if request.url.host and request.url.host != "localhost":
             raise NotImplementedError("Only local paths are allowed")
         if request.method in {"PUT", "DELETE"}:
@@ -148,4 +148,4 @@ class AsyncClient(_AsyncClient):
         self._mounts.update({URLPattern(protocol): transport})
 
 
-__all__ = ["FileTransport", "AsyncClient", "Client"]
+__all__ = ["AsyncClient", "Client", "FileTransport"]