{"id":13557342,"url":"https://github.com/karlicoss/kobuddy","last_synced_at":"2025-05-16T15:09:33.176Z","repository":{"id":47698241,"uuid":"194922392","full_name":"karlicoss/kobuddy","owner":"karlicoss","description":"Kobo database backup and parser: extracts notes, highlights, reading progress and more","archived":false,"fork":false,"pushed_at":"2025-01-25T02:26:12.000Z","size":146,"stargazers_count":160,"open_issues_count":3,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-15T14:54:28.381Z","etag":null,"topics":["annotations","data-liberation","export","kobo","kobo-ereader","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karlicoss.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-02T19:22:46.000Z","updated_at":"2025-04-25T23:22:07.000Z","dependencies_parsed_at":"2024-01-06T21:46:35.868Z","dependency_job_id":"26a65bc7-23fe-444f-b1cd-eb8c690c1e32","html_url":"https://github.com/karlicoss/kobuddy","commit_stats":{"total_commits":100,"total_committers":3,"mean_commits":"33.333333333333336","dds":"0.020000000000000018","last_synced_commit":"77346fb847e3a01601600ae29d9c6c6ed64277e6"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fkobuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fkobuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fkobuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fkobuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karlicoss","download_url":"https://codeload.github.com/karlicoss/kobuddy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","data-liberation","export","kobo","kobo-ereader","python"],"created_at":"2024-08-01T12:04:17.533Z","updated_at":"2025-05-16T15:09:28.160Z","avatar_url":"https://github.com/karlicoss.png","language":"Python","funding_links":[],"categories":["Bookmarking","Python","python"],"sub_categories":["Book and web annotations/highlights management"],"readme":"# -*- org-confirm-babel-evaluate: nil; -*-\n\n#+begin_src python :exports results :results drawer :dir src\nimport kobuddy\nreturn kobuddy.__doc__\n#+end_src\n\n#+RESULTS:\n:results:\n\nKobuddy is a tool to backup Kobo Reader sqlite database and extract useful things from it.\n\nIt gives you access to books, annotations, progress events and more!\n\nTested on Kobo Aura One, however database format should be mostly the same on other Kobo devices.\nI'll happily accept PRs if you find any issues or want to help with reverse engineering more events.\n:end:\n\n* Installing\nFrom pypi: ~pip3 install --user kobuddy~\n\nYou can also use without installing by running =./kobuddy=.\n\n* Usage\n  \n#+begin_src bash  :exports both :results scalar\nkobuddy --help\n#+end_src\n\n#+RESULTS:\n#+begin_example\nusage: kobuddy [-h] [--db DB] [--errors {throw,return}] {books,progress,annotations,backup} ...\n\nLibrary to parse and provide Python interface for your Kobo reader\n\npositional arguments:\n  {books,progress,annotations,backup}\n    books               print all books\n    progress            print all book reading progress\n    annotations         print all annotations (bookmarks/highlights/comments)\n    backup              backup the database from your Kobo device\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --db DB\n                        By default will try to read the database from your Kobo device.\n                        If you pass a directory, will try to use all Kobo databases it can find.\n\n  --errors {throw,return}\n                        throw: raise on errors immediately; return: handle defensively long as possible and reasonable\n#+end_example\n\n** as a standalone app\nExample of printing reading progress:\n\n#+begin_src bash :exports source\nkobuddy --db /L/backups/kobo progress\n#+end_src\n\n#+begin_example\nPerihelion Summer by Greg Egan\nStarted : 27 Jul 2019 14:39\nFinished: 05 Oct 2019 14:00\n-- 27 Jul 2019 14:39: reading\n-- 04 Aug 2019 16:40: highlight\n-- 27 Aug 2019 12:33: reading: 25%\n-- 02 Oct 2019 17:33: reading: 39%, read for 7 mins\n-- 02 Oct 2019 17:42: reading: 46%, read for 8 mins\n-- 02 Oct 2019 17:46: reading: 48%, read for 3 mins\n-- 02 Oct 2019 17:48: reading: 50%\n-- 02 Oct 2019 17:52: reading: 52%, read for 4 mins\n-- 02 Oct 2019 21:49: reading: 75%\n-- 02 Oct 2019 21:50: reading: 76%, read for 29 mins\n-- 05 Oct 2019 11:56: reading: 86%, read for 14 mins\n-- 05 Oct 2019 13:50: reading: 90%\n-- 05 Oct 2019 14:00: reading: 100%, read for 19 mins\n-- 05 Oct 2019 14:00: finished, total time spent 200 mins\n#+end_example\n\n** as a backup tool\n#+begin_src bash  :exports both :results scalar\nkobuddy backup --help\n#+end_src\n\n#+RESULTS:\n#+begin_example\nusage: kobuddy backup [-h] [--label LABEL] path\n\nYou can run it via cron, for example every minute. When you connect your device via USB, the database will be backed up.\n\n: * * * * * kobuddy backup /path/to/backups/kobo/\n\nAlternatively, you can add a udev rule or something similar.\n\npositional arguments:\n  path           target directory or file to dump the database\n\noptional arguments:\n  -h, --help     show this help message and exit\n  --label LABEL  device label (check lsblk if default doesn't work)\n#+end_example\n\n** as a library\n\n#+begin_src python :exports both :results value scalar :dir src\n  import kobuddy\n  kobuddy.set_databases('/L/backups/kobo/')\n  return kobuddy.get_books()[8: 10]\n\n#+end_src\n\n#+RESULTS:\n: [Blindsight by Peter Watts, Classical Mechanics by John C. Baez \u0026 Derek K. Wise]\n\n\nYou can also find [[https://github.com/karlicoss/orger/blob/master/modules/kobo2org.py][some]] [[https://github.com/karlicoss/orger/blob/master/modules/kobo.py][examples]] in Orger or [[https://github.com/karlicoss/my/blob/master/my/books/kobo.py][my]] package.\n\nIf you are looking for some specific Kobo events, check out ~EventTbl~ class, there is a good chance it's been reverse engineered.\n\n\n* Related projects/services\n- [[https://github.com/pettarin/export-kobo][export-kobo]]: only processes annotations from a single database\n- [[https://www.thekobonotes.com]]: closed source; you have to upload database manually, however it does display them as a nice html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarlicoss%2Fkobuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarlicoss%2Fkobuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarlicoss%2Fkobuddy/lists"}