Pyzotero: a Python client for the Zotero API pyzotero.readthedocs.io
zotero

Make search params more visible

+124 -143
+3 -1
doc/conf.py
··· 117 117 # Theme options are theme-specific and customize the look and feel of a theme 118 118 # further. For a list of options available for each theme, see the 119 119 # documentation. 120 - # html_theme_options = {} 120 + html_theme_options = { 121 + "collapse_navigation": False, 122 + } 121 123 122 124 # Add any paths that contain custom themes here, relative to this directory. 123 125 # html_theme_path = []
+121 -142
doc/index.rst
··· 1 - Description 2 - =========== 3 1 Pyzotero is a Python wrapper for the `Zotero API (v3) <https://www.zotero.org/support/dev/web_api/v3/start>`_. 4 2 5 3 ··· 12 10 13 11 14 12 13 + =============================== 15 14 Getting started (short version) 16 15 =============================== 17 16 1. ``uv add pyzotero`` or ``pip install pyzotero`` or ``conda install conda-forge::pyzotero`` ··· 42 41 Refer to the :ref:`read` and :ref:`write`. 43 42 44 43 44 + ============================================= 45 45 Installation, testing, usage (longer version) 46 46 ============================================= 47 47 48 - ============ 49 48 Installation 50 - ============ 49 + ------------ 51 50 Using `uv <https://docs.astral.sh/uv/concepts/projects/dependencies/#adding-dependencies>`_: ``uv add pyzotero`` 52 51 53 52 Using `pip <http://www.pip-installer.org/en/latest/index.html>`_: ``pip install pyzotero`` 54 53 55 54 Using `Anaconda <https://www.anaconda.com/distribution/>`_: ``conda install conda-forge::pyzotero`` 56 55 57 - ------------------------------- 58 56 Optional: Command-Line Interface 59 - ------------------------------- 57 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 58 61 59 Pyzotero includes an optional command-line interface for searching and querying your local Zotero library. 62 60 ··· 86 84 87 85 88 86 89 - =============================== 90 87 Installing development versions 91 - =============================== 88 + ------------------------------- 92 89 Pyzotero remains in development as of 2025. Unstable development versions can be found on the `Github main branch <https://github.com/urschrei/pyzotero/tree/main>`_, and installed directly from a checked-out ``main`` branch on a local clone, as in the example above: specify ``--dev`` (uv) / ``--group dev`` (pip). 93 90 94 91 95 - ======= 96 92 Testing 97 - ======= 93 + ------- 98 94 Testing requires installation of the ``dev`` dependency group (see above). 99 95 100 96 Run ``pytest .`` from the top-level directory. 101 97 102 98 .. _cli-usage: 103 99 104 - ========================== 105 100 Command-Line Interface Usage 106 - ========================== 101 + ---------------------------- 107 102 108 103 The Pyzotero CLI connects to your local Zotero installation and allows you to search your library, list collections, and view item types. 109 104 110 105 Basic Commands 111 - -------------- 106 + ~~~~~~~~~~~~~~ 112 107 113 108 Search for top-level items: 114 109 ··· 153 148 pyzotero itemtypes 154 149 155 150 Search Behaviour 156 - ---------------- 151 + ~~~~~~~~~~~~~~~~ 157 152 158 153 By default, ``pyzotero search`` searches only top-level item titles and metadata fields. 159 154 160 155 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. 161 156 162 157 Output Format 163 - ------------- 158 + ~~~~~~~~~~~~~ 164 159 165 160 By default, the CLI outputs human-readable text with all relevant metadata including: 166 161 ··· 171 166 Use the ``--json`` flag to output structured JSON suitable for consumption by other tools and agents. 172 167 173 168 174 - ====================== 175 169 Building Documentation 176 - ====================== 170 + ---------------------- 177 171 If you wish to build Pyzotero's documentation for offline use, it can be built from the ``doc`` directory of a local git repo by running ``make`` followed by the desired output format(s) (``html``, ``epub``, ``latexpdf`` etc.) 178 172 179 173 This functionality requires Sphinx. 180 174 See the `Sphinx documentation <http://sphinx.pocoo.org/tutorial.html#running-the-build>`_ for full details. 181 175 182 176 183 - ================ 184 177 Reporting issues 185 - ================ 178 + ---------------- 186 179 If you encounter an error while using Pyzotero, please open an issue on its `Github issues page <https://github.com/urschrei/pyzotero/issues>`_. 187 180 188 181 ··· 222 215 .. _read: 223 216 224 217 Errors 225 - ======= 218 + ------ 226 219 Where possible, any ``ZoteroError`` which is raised will preserve the underlying error in its ``__cause__`` and ``__context__`` properties, should you wish to work with these directly. 227 220 228 221 222 + ==================== 229 223 Read API Methods 230 224 ==================== 231 225 ··· 235 229 .. tip:: 236 230 The Read API returns 25 results by default (the API documentation claims 50). In the interests of usability, Pyzotero returns 100 items by default, by setting the API ``limit`` parameter to 100, unless it's set by the user. If you wish to retrieve e.g. all top-level items without specifying a ``limit`` parameter, you'll have to wrap your call with :py:meth:`Zotero.everything()`: ``results = zot.everything(zot.top())``. 237 231 232 + Search / Request Parameters for Read API calls 233 + ---------------------------------------------- 234 + 235 + Additional parameters may be set on Read API methods **following any required parameters**, or set using the :py:meth:`Zotero.add_parameters()` method detailed below. 236 + 237 + The following two examples produce the same result: 238 + 239 + .. code-block:: python 240 + 241 + # set parameters on the call itself 242 + z = zot.top(limit=7, start=3) 243 + 244 + # set parameters using explicit method 245 + zot.add_parameters(limit=7, start=3) 246 + z = zot.top() 247 + 248 + The following parameters are **optional**. 249 + 250 + **You may also set a search term here, using the 'itemType', 'q', 'qmode', or 'tag' parameters**. 251 + 252 + This area of the Zotero Read API is under development, and may change frequently. See `the API documentation <https://www.zotero.org/support/dev/web_api/v3/basics#read_requests>`_ for the most up-to-date details of search syntax usage and export format details. 253 + 254 + 255 + 256 + .. py:method:: Zotero.add_parameters([format=None, itemKey=None, itemType=None, q=None, qmode=None, since=None, tag=None, sort=None, direction=None, limit=None, start=None, [content=None[ ,style=None]]]) 257 + 258 + :param str format: "atom", "bib", "bibtex", json", "keys", "versions". Pyzotero retrieves and decodes JSON responses by default 259 + 260 + .. attention:: 261 + 262 + Setting ``format='bib'`` will remove the ``limit`` parameter if it's been set, as **the API does not allow a limit on bibliography output**; it instead enforces a limit of 150 items, and if the set of items you are trying to generate a bibliography for exceeds 150, an error will be raised. 263 + 264 + :param str itemKey: A comma-separated list of item keys. Valid only for item requests. Up to 50 items can be specified in a single request 265 + 266 + Search parameters: 267 + 268 + :param str itemType: item type search. See the `Search Syntax <https://www.zotero.org/support/dev/web_api/v3/basics#search_syntax>`_ for details 269 + :param str q: Quick search. Searches titles and individual creator fields by default. Use the ``qmode`` parameter to change the mode. Currently supports phrase searching only 270 + :param str qmode: Quick search mode. To include full-text content in the search, use ``everything``. Defaults to ``titleCreatorYear``. Searching of other fields will be possible in the future 271 + :param int since: default ``0``. Return only objects modified after the specified library version 272 + :param str tag: tag search. See the `Search Syntax <https://www.zotero.org/support/dev/web_api/v3/basics#search_syntax>`_ for details. More than one tag may be passed by passing a list of strings – These are treated as ``AND`` search terms, meaning only items which include all of the specified tags are returned. You can search for items matching any tag in a list by using ``OR``: ``"tag1 OR tag2"``, and all items which exclude a tag: ``"-tag"``. 273 + 274 + The following parameters can be used for search requests: 275 + 276 + :param str sort: The name of the field by which entries are sorted: (``dateAdded``, ``dateModified``, ``title``, ``creator``, ``type``, ``date``, ``publisher``, ``publicationTitle``, ``journalAbbreviation``, ``language``, ``accessDate``, ``libraryCatalog``, ``callNumber``, ``rights``, ``addedBy``, ``numItems``, ``tags``) 277 + :param str direction: ``asc`` or ``desc`` 278 + :param int limit: 1 – 100 or None 279 + :param int start: 1 – total number of items in your library or None 280 + 281 + 282 + If you wish to retrieve citation or bibliography entries, use the following parameters: 283 + 284 + :param str content: 'bib', 'html', or one of the export formats (see below). If 'bib' is passed, you may **also** pass: 285 + :param str style: Any valid CSL style in the Zotero style repository 286 + :param str linkwrap: Set this to "1" to have URLs in bibliography entries (see below) wrapped in ``<a>`` tags. 287 + :rtype: list of HTML strings or None. 288 + 289 + 290 + .. note:: 291 + 292 + Any parameters you set will be valid **for the next call only**. Any parameters set using ``add_parameters()`` will be overridden by parameters you pass in the call itself. 293 + 294 + 295 + A note on the ``content`` and ``style`` parameters: 296 + 297 + Example: 298 + 299 + .. code-block:: python 300 + 301 + zot.add_parameters(content='bib', style='mla') 302 + 303 + 304 + If these are set, the return value is a list of UTF-8 formatted HTML ``div`` elements, each containing an item: 305 + 306 + ``['<div class="csl-entry">(content)</div>']``. 307 + 308 + You may also set ``content='citation'`` if you wish to retrieve citations. Similar to ``bib``, the result will be a list of one or more HTML ``span`` elements. 309 + 310 + 311 + If you select one of the available `export formats <https://www.zotero.org/support/dev/web_api/v3/basics#export_formats>`_ as the ``content`` parameter, pyzotero will in most cases return a list of unicode strings in the format you specified. The exception is the ``csljson`` format, which is parsed into a list of dicts. Please note that you must provide a ``limit`` parameter if you specify one of these export formats. Multiple simultaneous retrieval of particular formats, e.g. ``content="json,coins"`` is not currently supported. 312 + 313 + If you set ``format='keys'``, a newline-delimited string containing item keys will be returned 314 + 315 + If you set ``format='bibtex'``, a `bibtexparser <https://bibtexparser.readthedocs.io/en/v0.6.2/bibtexparser.html#bibdatabase.BibDatabase.entries>`_ object containing citations will be returned. You can access the citations as a list of dicts using the ``.entries`` property. The bibtexparser object also implements a `dump method <https://bibtexparser.readthedocs.io/en/v0.6.2/bibtexparser.html#bibtexparser.dump>`_, if you'd like to write your citations to a ``.bib`` file. 238 316 239 317 .. py:method:: Zotero.key_info() 240 318 ··· 242 320 243 321 :rtype: dict 244 322 245 - ==================== 246 323 Retrieving Items 247 - ==================== 324 + ---------------- 248 325 249 326 .. tip:: 250 327 In contrast to the v1 API, a great deal of additional metadata is now returned. In most cases, simply accessing items by referring to their ``item['data']`` key will suffice. ··· 400 477 401 478 See :ref:`'Hello World' <hello-world>` example, above 402 479 403 - ==================== 404 480 Retrieving Files 405 - ==================== 481 + ---------------- 406 482 407 483 .. py:method:: Zotero.file(itemID[, search/request parameters]) 408 484 ··· 440 516 441 517 File retrieval and dumping should work for most common document, audio and video file formats. If you encounter an error, `please open an issue <https://github.com/urschrei/pyzotero/issues>`_. 442 518 443 - ======================= 444 519 Retrieving Collections 445 - ======================= 520 + ---------------------- 446 521 .. py:method:: Zotero.collections([search/request parameters]) 447 522 448 523 Returns a library's collections. **This includes subcollections**. ··· 499 574 u'version': 778}] 500 575 501 576 502 - ========================== 503 577 Retrieving groups 504 - ========================== 578 + ----------------- 505 579 .. py:method:: Zotero.groups([search/request parameters]) 506 580 507 581 Retrieve the Zotero group data to which the current library_id and api_key has access ··· 535 609 u'version': 0}] 536 610 537 611 538 - =================== 539 612 Retrieving Tags 540 - =================== 613 + --------------- 541 614 542 615 .. py:method:: Zotero.tags([search/request parameters]) 543 616 ··· 558 631 559 632 ['Authority in literature', 'Errata'] 560 633 561 - ============================== 562 634 Retrieving Version Information 563 - ============================== 635 + ------------------------------ 564 636 565 637 The `Zotero API <https://www.zotero.org/support/dev/web_api/v3/syncing>`_ recommends requesting version information for all (or all changed) items and collections when implementing syncing. The following convenience methods (which by default return an unlimited number of responses) simplify this process. 566 638 ··· 585 657 {'C9KW275P': 3915, 'IB489TKM': 4025 } 586 658 587 659 588 - ================= 589 660 Full–Text Content 590 - ================= 661 + ----------------- 591 662 592 663 These methods allow the retrieval of full–text content for given library items 593 664 ··· 649 720 "totalPages": 50 650 721 } 651 722 652 - ============================================== 653 723 The ``follow()``, and ``everything()`` methods 654 - ============================================== 724 + ---------------------------------------------- 655 725 656 726 These methods (currently experimental) aim to make Pyzotero a little more RESTful. Following any Read API call which can retrieve **multiple items**, calling ``follow()`` will repeat that call, but for the next *x* number of items, where *x* is either a number set by the user for the original call, or 50 by default. Each subsequent call to ``follow()`` will extend the offset. 657 727 ··· 685 755 The ``everything()`` method should work with all Pyzotero Read API calls which can return multiple items, but has not yet been extensively tested. `Feedback is welcomed <https://github.com/urschrei/pyzotero/issues>`_. 686 756 687 757 Related generator methods 688 - ------------------------- 758 + ~~~~~~~~~~~~~~~~~~~~~~~~~ 689 759 690 760 The :py:meth:`Zotero.iterfollow()` and :py:meth:`Zotero.makeiter()` methods are available for users who prefer to work directly with generators: 691 761 ··· 721 791 722 792 .. warning:: The ``follow()``, ``everything()`` and ``makeiter()`` methods are only valid for methods which can return multiple library items. For instance, you cannot use ``follow()`` after an ``item()`` call. The generator methods will raise a ``StopIteration`` error when all available items retrievable by your chosen API call have been exhausted. 723 793 724 - ====================== 725 794 Retrieving item counts 726 - ====================== 795 + ---------------------- 727 796 728 797 If you wish to retrieve item counts for subsets of a library, you can use the following methods: 729 798 ··· 739 808 740 809 :rtype: int 741 810 742 - ================================ 743 811 Retrieving last modified version 744 - ================================ 812 + -------------------------------- 745 813 746 814 If you wish to retrieve the last modified version of a user or group library, you can use the following method: 747 815 ··· 751 819 752 820 :rtype: int 753 821 754 - 755 - ============================================== 756 - Search / Request Parameters for Read API calls 757 - ============================================== 758 - 759 - Additional parameters may be set on Read API methods **following any required parameters**, or set using the :py:meth:`Zotero.add_parameters()` method detailed below. 760 - 761 - 762 - The following two examples produce the same result: 763 - 764 - .. code-block:: python 765 - 766 - # set parameters on the call itself 767 - z = zot.top(limit=7, start=3) 768 - 769 - # set parameters using explicit method 770 - zot.add_parameters(limit=7, start=3) 771 - z = zot.top() 772 - 773 - The following parameters are **optional**. 774 - 775 - **You may also set a search term here, using the 'itemType', 'q', 'qmode', or 'tag' parameters**. 776 - 777 - This area of the Zotero Read API is under development, and may change frequently. See `the API documentation <https://www.zotero.org/support/dev/web_api/v3/basics#read_requests>`_ for the most up-to-date details of search syntax usage and export format details. 778 - 779 - 780 - 781 - .. py:method:: Zotero.add_parameters([format=None, itemKey=None, itemType=None, q=None, qmode=None, since=None, tag=None, sort=None, direction=None, limit=None, start=None, [content=None[ ,style=None]]]) 782 - 783 - :param str format: "atom", "bib", "bibtex", json", "keys", "versions". Pyzotero retrieves and decodes JSON responses by default 784 - 785 - .. attention:: 786 - 787 - Setting ``format='bib'`` will remove the ``limit`` parameter if it's been set, as **the API does not allow a limit on bibliography output**; it instead enforces a limit of 150 items, and if the set of items you are trying to generate a bibliography for exceeds 150, an error will be raised. 788 - 789 - :param str itemKey: A comma-separated list of item keys. Valid only for item requests. Up to 50 items can be specified in a single request 790 - 791 - Search parameters: 792 - 793 - :param str itemType: item type search. See the `Search Syntax <https://www.zotero.org/support/dev/web_api/v3/basics#search_syntax>`_ for details 794 - :param str q: Quick search. Searches titles and individual creator fields by default. Use the ``qmode`` parameter to change the mode. Currently supports phrase searching only 795 - :param str qmode: Quick search mode. To include full-text content in the search, use ``everything``. Defaults to ``titleCreatorYear``. Searching of other fields will be possible in the future 796 - :param int since: default ``0``. Return only objects modified after the specified library version 797 - :param str tag: tag search. See the `Search Syntax <https://www.zotero.org/support/dev/web_api/v3/basics#search_syntax>`_ for details. More than one tag may be passed by passing a list of strings – These are treated as ``AND`` search terms, meaning only items which include all of the specified tags are returned. You can search for items matching any tag in a list by using ``OR``: ``"tag1 OR tag2"``, and all items which exclude a tag: ``"-tag"``. 798 - 799 - The following parameters can be used for search requests: 800 - 801 - :param str sort: The name of the field by which entries are sorted: (``dateAdded``, ``dateModified``, ``title``, ``creator``, ``type``, ``date``, ``publisher``, ``publicationTitle``, ``journalAbbreviation``, ``language``, ``accessDate``, ``libraryCatalog``, ``callNumber``, ``rights``, ``addedBy``, ``numItems``, ``tags``) 802 - :param str direction: ``asc`` or ``desc`` 803 - :param int limit: 1 – 100 or None 804 - :param int start: 1 – total number of items in your library or None 805 - 806 - 807 - If you wish to retrieve citation or bibliography entries, use the following parameters: 808 - 809 - :param str content: 'bib', 'html', or one of the export formats (see below). If 'bib' is passed, you may **also** pass: 810 - :param str style: Any valid CSL style in the Zotero style repository 811 - :param str linkwrap: Set this to "1" to have URLs in bibliography entries (see below) wrapped in ``<a>`` tags. 812 - :rtype: list of HTML strings or None. 813 - 814 - 815 - .. note:: 816 - 817 - Any parameters you set will be valid **for the next call only**. Any parameters set using ``add_parameters()`` will be overridden by parameters you pass in the call itself. 818 - 819 - 820 - A note on the ``content`` and ``style`` parameters: 821 - 822 - Example: 823 - 824 - .. code-block:: python 825 - 826 - zot.add_parameters(content='bib', style='mla') 827 - 828 - 829 - If these are set, the return value is a list of UTF-8 formatted HTML ``div`` elements, each containing an item: 830 - 831 - ``['<div class="csl-entry">(content)</div>']``. 832 - 833 - You may also set ``content='citation'`` if you wish to retrieve citations. Similar to ``bib``, the result will be a list of one or more HTML ``span`` elements. 834 - 835 - 836 - If you select one of the available `export formats <https://www.zotero.org/support/dev/web_api/v3/basics#export_formats>`_ as the ``content`` parameter, pyzotero will in most cases return a list of unicode strings in the format you specified. The exception is the ``csljson`` format, which is parsed into a list of dicts. Please note that you must provide a ``limit`` parameter if you specify one of these export formats. Multiple simultaneous retrieval of particular formats, e.g. ``content="json,coins"`` is not currently supported. 837 - 838 - If you set ``format='keys'``, a newline-delimited string containing item keys will be returned 839 - 840 - If you set ``format='bibtex'``, a `bibtexparser <https://bibtexparser.readthedocs.io/en/v0.6.2/bibtexparser.html#bibdatabase.BibDatabase.entries>`_ object containing citations will be returned. You can access the citations as a list of dicts using the ``.entries`` property. The bibtexparser object also implements a `dump method <https://bibtexparser.readthedocs.io/en/v0.6.2/bibtexparser.html#bibtexparser.dump>`_, if you'd like to write your citations to a ``.bib`` file. 841 - 842 - 843 822 .. _write: 844 823 824 + ================= 845 825 Write API Methods 846 826 ================= 847 827 848 - ============== 849 828 Saved Searches 850 - ============== 829 + -------------- 851 830 Pyzotero allows you to retrieve, delete, or modify saved searches: 852 831 853 832 .. py:method:: Zotero.searches() ··· 891 870 :param str condition: a valid saved search condition 892 871 :rtype: list 893 872 894 - ================= 895 873 Item Methods 896 - ================= 874 + ------------ 897 875 898 876 .. py:method:: Zotero.item_types() 899 877 ··· 936 914 :rtype: dict 937 915 938 916 Creating and Updating Items 939 - --------------------------- 917 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 940 918 941 919 .. py:method:: Zotero.create_items(items[, parentid, last_modified]) 942 920 ··· 1010 988 1011 989 1012 990 Uploading files 1013 - --------------- 991 + ~~~~~~~~~~~~~~~ 1014 992 1015 993 .. warning:: Attachment methods are in beta. 1016 994 ··· 1054 1032 unlike the space-saving responses from the server, the return value here eschews the complex index / key lookup and simply passes back the ``imported_file`` item template populated with keys (if created successfully or passed in) corresponding to each result. This is the return type for all of these methods. 1055 1033 1056 1034 Deleting items 1057 - -------------- 1035 + ~~~~~~~~~~~~~~ 1058 1036 1059 1037 .. py:method:: Zotero.delete_item(item[, last_modified]) 1060 1038 ··· 1064 1042 :param str/int last_modified: If not ``None``, will set the value of the If-Unmodified-Since-Version header. 1065 1043 1066 1044 Deleting tags 1067 - -------------- 1045 + ~~~~~~~~~~~~~ 1068 1046 1069 1047 .. py:method:: Zotero.delete_tags(tag_a[, tag …]) 1070 1048 ··· 1074 1052 1075 1053 You may also pass a list using ``zot.delete_tags(*[tag_list])`` 1076 1054 1077 - =========== 1078 1055 Adding tags 1079 - =========== 1056 + ----------- 1080 1057 1081 1058 .. py:method:: Zotero.add_tags(item, tag[, tag …]) 1082 1059 ··· 1098 1075 # updated now contains a representation of the updated server item 1099 1076 1100 1077 1101 - ==================== 1102 1078 Collection Methods 1103 - ==================== 1079 + ------------------ 1104 1080 1105 1081 .. py:method:: Zotero.create_collections(dicts[, last_modified]) 1106 1082 ··· 1180 1156 1181 1157 1182 1158 1159 + ===== 1183 1160 Notes 1184 1161 ===== 1185 1162 Most Read API methods return **lists** of **dicts** or, in the case of tag methods, **lists** of **strings**. Most Write API methods return either ``True`` if successful, or raise an error. See ``zotero_errors.py`` for a full listing of these. 1186 1163 1187 1164 .. warning:: URL parameters will supersede API calls which should return e.g. a single item: ``https://api.zotero.org/users/436/items/ABC?start=50&limit=10`` will return 10 items beginning at position 50, even though ``ABC`` does not exist. Be aware of this, and don't pass URL parameters which do not apply to a given API method. 1188 1165 1166 + ======= 1189 1167 License 1190 1168 ======= 1191 1169 Pyzotero is licensed under the `Blue Oak Model Licence <https://opensource.org/license/blue-oak-model-license>`_ license. 1192 1170 1193 1171 1172 + =========== 1194 1173 Cat Picture 1195 1174 =========== 1196 1175 This is The Grinch.