# Zotero ➡️ Readwise
`zotero2readwise` is a Python library that retrieves all [Zotero](https://www.zotero.org/) annotations† and notes.
Then, It automatically uploads them to your [Readwise](https://readwise.io/)§.
This is particularly useful for the new [Zotero PDF Reader](https://www.zotero.org/support/pdf_reader_preview)
that stores all highlights in the Zotero database.
The new Zotero, also available for [iOS app](https://www.zotero.org/iosbeta) (currently in beta).
In the new Zotero, the annotations are NOT saved in the PDF file unless you export the highlights in order to save them.
If you annotate your files outside the new Zotero PDF reader, this library may not work with your PDF annotations as those are not retrievable from Zotero API.
**_This library is for you if you annotate (highlight + note) using the Zotero's PDF reader (including the Zotero iOS)_**
👉***Updating an existing Zotero annotation or note and re-running this library will update the corresponding Readwise highlight without creating a duplicate!***
† Annotations made in the new Zotero PDF reader and note editor.
§ Readwise is a _paid_ service/software that integrates your highlights from almost everywhere (Pocket, Instapaper, Twitter, Medium, Apple Books, and many more).
It even has an amazing OCR for directly importing your highlights on a physical book/article into Readwise and allowing
you to export all your highlights to Obsidian, Notion, Roam, Markdown, etc.
Moreover, It has an automated [Spaced Repition](https://en.wikipedia.org/wiki/Spaced_repetition) and [Active Recall](https://en.wikipedia.org/wiki/Testing_effect).
---
# Installation
You can install the library by running
```shell
pip install zotero2readwise
```
Note: If you do not have pip installed on your system, you can follow the instructions [here](https://pip.pypa.io/en/stable/installation/).
# Usage
Since we have to retrieve the notes from Zotero API and then upload them to the Readwise, the minimum requirements are:
* **Readwise access token** [Required]: You can get your access token from https://readwise.io/access_token
* **Zotero API key** [Required]: Create a new Zotero Key from [your Zotero settings](https://www.zotero.org/settings/keys/new)
* **Zotero personal or group ID** [Required]:
* Your **personal library ID** (aka **userID**) can be found [here](https://www.zotero.org/settings/keys) next to `Your userID for use in API calls is XXXXXX`.
* If you're using a **group library**, you can find the library ID by
1. Go to `https://www.zotero.org/groups/`
2. Click on the interested group.
3. You can find the library ID from the URL link that has format like *https://www.zotero.org/groups/<group_id>/group_name*. The number between `/groups/` and `/group_name` is the libarry ID.
* **Zotero library type** [Optional]: *"user"* (default) if using personal library and *"group"* if using group library.
Note that if you want to retrieve annotations and notes from a group, you should provide the group ID (`zotero_library_id=<group_id>`) and set the library type to group (`zotero_library_type="group"`).
## Approach 1 (running a python script)
For this approach you can download `run.py` script (from [here](https://github.com/e-alizadeh/Zotero2Readwise/blob/master/zotero2readwise/run.py)). Run `python run.py -h` to get more information about all options.
You can simply run the script as the following:
```shell
python run.py <readwise_token> <zotero_key> <zotero_id>
```
## Approach 2 (through python terminal)
```python
from zotero2readwise.zt2rw import Zotero2Readwise
zt_rw = Zotero2Readwise(
readwise_token="your_readwise_access_token", # Visit https://readwise.io/access_token)
zotero_key="your_zotero_key", # Visit https://www.zotero.org/settings/keys
zotero_library_id="your_zotero_id", # Visit https://www.zotero.org/settings/keys
zotero_library_type="user", # "user" (default) or "group"
include_annotations=True, # Include Zotero annotations -> Default: True
include_notes=False, # Include Zotero notes -> Default: False
)
zt_rw.run()
```
Just to make sure that all files are created, you can run `save_failed_items_to_json()` from `readwise` attribute of
the class object to save any highlight that failed to upload to Readwise.
If a file or more failed to create, the filename (item title) and the corresponding Zotero
item key will be saved to a txt file.
```python
zt_rw.readwise.save_failed_items_to_json("failed_readwise_highlights.json")
```
---
# [Zotero2Readwise-Sync](https://github.com/e-alizadeh/Zotero2Readwise-Sync)
### 👉 Set up a scheduled automation once and forget about it!
You can fork my repo [Zotero2Readwise-Sync](https://github.com/e-alizadeh/Zotero2Readwise-Sync) repository that contain
the cronjob (time-based Job scheduler) using GitHub actions to automatically retrieve all your Zotero annotations/notes,
and then push them to Readwise.
You can use the forked repo without even changing a single line (of course if you're happy with the default settings!)
# Request a new feature or report a bug
Feel free to request a new feature or report a bug in GitHub issue [here](https://github.com/e-alizadeh/Zotero2Readwise/issues).
# 📫 How to reach me:
<a href="https://ealizadeh.com" target="_blank"><img alt="Personal Website" src="https://img.shields.io/badge/Personal%20Website-%2312100E.svg?&style=for-the-badge&logoColor=white" /></a>
<a href="https://www.linkedin.com/in/alizadehesmaeil/" target="_blank"><img alt="LinkedIn" src="https://img.shields.io/badge/linkedin-%230077B5.svg?&style=for-the-badge&logo=linkedin&logoColor=white" /></a>
<a href="https://medium.ealizadeh.com/" target="_blank"><img alt="Medium" src="https://img.shields.io/badge/medium-%2312100E.svg?&style=for-the-badge&logo=medium&logoColor=white" /></a>
<a href="https://twitter.com/intent/follow?screen_name=es_alizadeh&tw_p=followbutton" target="_blank"><img alt="Twitter" src="https://img.shields.io/badge/twitter-%231DA1F2.svg?&style=for-the-badge&logo=twitter&logoColor=white" /></a>
<a href="https://www.buymeacoffee.com/ealizadeh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
Raw data
{
"_id": null,
"home_page": "https://github.com/e-alizadeh/Zotero2Readwise",
"name": "zotero2readwise",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "Zotero,Readwise",
"author": "ealizadeh",
"author_email": "hello@ealizadeh.com",
"download_url": "https://files.pythonhosted.org/packages/43/be/e94937ffe3a76c3eab676c512c3b7e1fafe8fb186b285ca2c76beed9812d/zotero2readwise-0.4.5.tar.gz",
"platform": null,
"description": "# Zotero \u27a1\ufe0f Readwise\n\n`zotero2readwise` is a Python library that retrieves all [Zotero](https://www.zotero.org/) annotations\u2020 and notes. \nThen, It automatically uploads them to your [Readwise](https://readwise.io/)\u00a7. \n\nThis is particularly useful for the new [Zotero PDF Reader](https://www.zotero.org/support/pdf_reader_preview) \nthat stores all highlights in the Zotero database. \nThe new Zotero, also available for [iOS app](https://www.zotero.org/iosbeta) (currently in beta). \nIn the new Zotero, the annotations are NOT saved in the PDF file unless you export the highlights in order to save them.\n\nIf you annotate your files outside the new Zotero PDF reader, this library may not work with your PDF annotations as those are not retrievable from Zotero API.\n\n**_This library is for you if you annotate (highlight + note) using the Zotero's PDF reader (including the Zotero iOS)_**\n\n\ud83d\udc49***Updating an existing Zotero annotation or note and re-running this library will update the corresponding Readwise highlight without creating a duplicate!***\n\n\u2020 Annotations made in the new Zotero PDF reader and note editor.\n\n\u00a7 Readwise is a _paid_ service/software that integrates your highlights from almost everywhere (Pocket, Instapaper, Twitter, Medium, Apple Books, and many more). \nIt even has an amazing OCR for directly importing your highlights on a physical book/article into Readwise and allowing \nyou to export all your highlights to Obsidian, Notion, Roam, Markdown, etc. \nMoreover, It has an automated [Spaced Repition](https://en.wikipedia.org/wiki/Spaced_repetition) and [Active Recall](https://en.wikipedia.org/wiki/Testing_effect). \n\n---\n\n\n# Installation \nYou can install the library by running \n```shell\npip install zotero2readwise\n```\n\nNote: If you do not have pip installed on your system, you can follow the instructions [here](https://pip.pypa.io/en/stable/installation/).\n\n\n# Usage\nSince we have to retrieve the notes from Zotero API and then upload them to the Readwise, the minimum requirements are:\n* **Readwise access token** [Required]: You can get your access token from https://readwise.io/access_token\n* **Zotero API key** [Required]: Create a new Zotero Key from [your Zotero settings](https://www.zotero.org/settings/keys/new)\n* **Zotero personal or group ID** [Required]: \n * Your **personal library ID** (aka **userID**) can be found [here](https://www.zotero.org/settings/keys) next to `Your userID for use in API calls is XXXXXX`.\n * If you're using a **group library**, you can find the library ID by \n 1. Go to `https://www.zotero.org/groups/`\n 2. Click on the interested group.\n 3. You can find the library ID from the URL link that has format like *https://www.zotero.org/groups/<group_id>/group_name*. The number between `/groups/` and `/group_name` is the libarry ID. \n* **Zotero library type** [Optional]: *\"user\"* (default) if using personal library and *\"group\"* if using group library.\n\nNote that if you want to retrieve annotations and notes from a group, you should provide the group ID (`zotero_library_id=<group_id>`) and set the library type to group (`zotero_library_type=\"group\"`).\n\n## Approach 1 (running a python script)\nFor this approach you can download `run.py` script (from [here](https://github.com/e-alizadeh/Zotero2Readwise/blob/master/zotero2readwise/run.py)). Run `python run.py -h` to get more information about all options. \nYou can simply run the script as the following:\n```shell\npython run.py <readwise_token> <zotero_key> <zotero_id> \n```\n\n## Approach 2 (through python terminal)\n```python \nfrom zotero2readwise.zt2rw import Zotero2Readwise\n\nzt_rw = Zotero2Readwise(\n readwise_token=\"your_readwise_access_token\", # Visit https://readwise.io/access_token)\n zotero_key=\"your_zotero_key\", # Visit https://www.zotero.org/settings/keys\n zotero_library_id=\"your_zotero_id\", # Visit https://www.zotero.org/settings/keys\n zotero_library_type=\"user\", # \"user\" (default) or \"group\"\n include_annotations=True, # Include Zotero annotations -> Default: True\n include_notes=False, # Include Zotero notes -> Default: False\n)\nzt_rw.run()\n```\nJust to make sure that all files are created, you can run `save_failed_items_to_json()` from `readwise` attribute of \nthe class object to save any highlight that failed to upload to Readwise. \nIf a file or more failed to create, the filename (item title) and the corresponding Zotero \nitem key will be saved to a txt file. \n```python\nzt_rw.readwise.save_failed_items_to_json(\"failed_readwise_highlights.json\")\n```\n---\n# [Zotero2Readwise-Sync](https://github.com/e-alizadeh/Zotero2Readwise-Sync)\n\n### \ud83d\udc49 Set up a scheduled automation once and forget about it!\n\nYou can fork my repo [Zotero2Readwise-Sync](https://github.com/e-alizadeh/Zotero2Readwise-Sync) repository that contain \nthe cronjob (time-based Job scheduler) using GitHub actions to automatically retrieve all your Zotero annotations/notes, \nand then push them to Readwise. \nYou can use the forked repo without even changing a single line (of course if you're happy with the default settings!)\n\n# Request a new feature or report a bug\nFeel free to request a new feature or report a bug in GitHub issue [here](https://github.com/e-alizadeh/Zotero2Readwise/issues).\n\n\n# \ud83d\udceb How to reach me:\n<a href=\"https://ealizadeh.com\" target=\"_blank\"><img alt=\"Personal Website\" src=\"https://img.shields.io/badge/Personal%20Website-%2312100E.svg?&style=for-the-badge&logoColor=white\" /></a>\n<a href=\"https://www.linkedin.com/in/alizadehesmaeil/\" target=\"_blank\"><img alt=\"LinkedIn\" src=\"https://img.shields.io/badge/linkedin-%230077B5.svg?&style=for-the-badge&logo=linkedin&logoColor=white\" /></a>\n<a href=\"https://medium.ealizadeh.com/\" target=\"_blank\"><img alt=\"Medium\" src=\"https://img.shields.io/badge/medium-%2312100E.svg?&style=for-the-badge&logo=medium&logoColor=white\" /></a>\n<a href=\"https://twitter.com/intent/follow?screen_name=es_alizadeh&tw_p=followbutton\" target=\"_blank\"><img alt=\"Twitter\" src=\"https://img.shields.io/badge/twitter-%231DA1F2.svg?&style=for-the-badge&logo=twitter&logoColor=white\" /></a>\n\n<a href=\"https://www.buymeacoffee.com/ealizadeh\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-blue.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" ></a>\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Export your Zotero annotations and notes to Readwise",
"version": "0.4.5",
"project_urls": {
"Documentation": "https://github.com/e-alizadeh/Zotero2Readwise",
"Homepage": "https://github.com/e-alizadeh/Zotero2Readwise",
"Repository": "https://github.com/e-alizadeh/Zotero2Readwise"
},
"split_keywords": [
"zotero",
"readwise"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3daae67f319490128a3b8c59ecb6cfa25b3e412bb1ecca5a5e2bec0c943d2c0b",
"md5": "89cd54adb0a4d1b35b69e60fe8e45079",
"sha256": "c74333cdf0eb8f3d20c77bb9598512203e1428afaa92649a997cbde61341acf0"
},
"downloads": -1,
"filename": "zotero2readwise-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89cd54adb0a4d1b35b69e60fe8e45079",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 12871,
"upload_time": "2024-02-22T02:49:35",
"upload_time_iso_8601": "2024-02-22T02:49:35.043979Z",
"url": "https://files.pythonhosted.org/packages/3d/aa/e67f319490128a3b8c59ecb6cfa25b3e412bb1ecca5a5e2bec0c943d2c0b/zotero2readwise-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "43bee94937ffe3a76c3eab676c512c3b7e1fafe8fb186b285ca2c76beed9812d",
"md5": "5cc4e5098ebb7b37e87c08f71b14d0cc",
"sha256": "07e9fe61493eb80f666a063569c3aec24e20ef379cd662010d253ec88a043da0"
},
"downloads": -1,
"filename": "zotero2readwise-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "5cc4e5098ebb7b37e87c08f71b14d0cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 13030,
"upload_time": "2024-02-22T02:49:36",
"upload_time_iso_8601": "2024-02-22T02:49:36.709677Z",
"url": "https://files.pythonhosted.org/packages/43/be/e94937ffe3a76c3eab676c512c3b7e1fafe8fb186b285ca2c76beed9812d/zotero2readwise-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-22 02:49:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "e-alizadeh",
"github_project": "Zotero2Readwise",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zotero2readwise"
}
JSON
