Skip to content

Commit

Permalink
Merge pull request #27 from kyxap/main
Browse files Browse the repository at this point in the history
Sync @kyxap fork after receiving maintainer role
  • Loading branch information
kyxap authored Jul 27, 2024
2 parents 15a5b15 + 3aa82fe commit 20ac77d
Show file tree
Hide file tree
Showing 29 changed files with 332 additions and 383 deletions.
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -140,3 +140,7 @@ dmypy.json

# Cython debug symbols
cython_debug/

# Release
release
*.bak
57 changes: 49 additions & 8 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,14 +1,55 @@
version = 0.5.2-beta
zip_file = releases/KOReader Sync v$(version).zip
zip_contents = about.txt LICENSE plugin-import-name-koreader.txt *.py *.md images/*.png
# Read the version from the version.txt file
version := $(shell head -n 1 version.txt)
zip_file = KOReader_Sync_v$(version).zip
zip_contents = about.txt LICENSE plugin-import-name-koreader.txt *.py *.md images/*.png
plugin_index_file_to_upd = pluginIndexKOReaderSync.txt
init_file_to_upd = __init__.py
release_dir = release

all: zip
# Convert the version to tuple format
version_tuple := $(shell echo $(version) | awk -F. '{print "("$$1", "$$2", "$$3")"}')

zip:
@ echo "creating new $(zip_file)" && zip "$(zip_file)" $(zip_contents) && echo "created new $(zip_file)"
# Main targets
release: update_version zip load

zip: $(release_dir)
@echo "Creating new $(release_dir)/$(zip_file)" && zip "$(release_dir)/$(zip_file)" $(zip_contents) && echo "Created new $(release_dir)/$(zip_file)"

# Loads current src content, use this if doing dev changes
dev:
@ calibre-customize -b .; calibre-debug -g
@calibre-customize -b .; calibre-debug -g

# Loads zip from release dir if exists
load:
@ calibre-customize -a "$(zip_file)"; calibre-debug -g
@calibre-customize -a "$(release_dir)/$(zip_file)"; calibre-debug -g

update_version: update_version_plugin_index update_version_init
@echo "Versions updated in all files."

update_version_plugin_index:
@echo "Updating version in $(plugin_index_file_to_upd) to $(version)"
@sed -i 's/Version: [^;]*;/Version: $(version);/' $(plugin_index_file_to_upd)
@echo "Version updated in $(plugin_index_file_to_upd)"

update_version_init:
@echo "Updating version in $(init_file_to_upd) to $(version_tuple)"
@sed -i '/^[[:space:]]*version = /s/version = ([0-9, ]*)/version = $(version_tuple)/' $(init_file_to_upd)
@echo "Version updated in $(init_file_to_upd)"

$(release_dir):
@mkdir -p $(release_dir)
@echo "Created $(release_dir) directory"

debug_version:
@echo "Read version: $(version)"
@echo "Version tuple: $(version_tuple)"

tag:
@echo "Tagging version v$(version) and pushing to the repository"
@if git rev-parse "v$(version)" >/dev/null 2>&1; then \
echo "Tag v$(version) already exists. Deleting the old tag."; \
git tag -d "v$(version)"; \
git push origin ":refs/tags/v$(version)"; \
fi
@git tag -a "v$(version)" -m "Version $(version)" # Create annotated tag for the version
@git push origin "v$(version)" # Push the tag to the remote repository
240 changes: 14 additions & 226 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,5 @@
# KOReader calibre plugin

> **Hi,**
>
> **I'm looking for someone who wants to help me maintain this plugin, because I don't use it all that much anymore. Please contact me if you're up for this.**
>
> **Harm**
A calibre plugin to synchronize metadata from KOReader to calibre.

[KOReader](https://koreader.rocks/) creates sidecar files that hold read progress and annotations. This plugin reads the data from those sidecar files and updates calibre's metadata based on them. It is inspired by [the Kobo Utilities plugin](https://www.mobileread.com/forums/showthread.php?t=215339), that synchronizes reading progress between the original Kobo firmware ("Nickel") and custom columns in calibre.
Expand All @@ -26,7 +20,7 @@ Releases will also be uploaded to [this plugin thread on the MobileRead Forums](

#### Alternatively

1. Download the latest release from [here](https://github.com/harmtemolder/koreader-calibre-plugin/tree/main/releases).
1. Download the latest release from [here](https://github.com/harmtemolder/koreader-calibre-plugin/releases).
2. Go to your calibre's _Preferences_ > _Plugins_ > _Load plugin from file_ and point it to the downloaded ZIP file
3. Restart calibre

Expand All @@ -40,19 +34,24 @@ Releases will also be uploaded to [this plugin thread on the MobileRead Forums](
- A _Long text_ column to store your **review** of the book, as entered on the book's status page.
- A regular _Text_ column to store the **reading status** of the book, as entered on the book status page (_Finished_, _Reading_, _On hold_).
- A _Yes/No_ column to store the **reading status** of the book, as a boolean (_Yes_ = _Finished_, _No_ = everything else).
- A _Date_ column to store **the date on which the first highlight or bookmark was made**. (This is probably around the time you started reading.)
- A _Date_ column to store **the date on which the last highlight or bookmark was made**. (This is probably around the time you finished reading.)
- A _Long text_ column to store your **bookmarks and highlights** of the book, with _Interpret this column as_ set to _Plain text formatted using markdown_. (Highlights are an unordered list with their metadata in an HTML comment.)
- A regular _Text_ column to store the **MD5 hash** KOReader uses to sync progress to a [**KOReader Sync Server**](https://github.com/koreader/koreader-sync-server#koreader-sync-server). (_Progress sync_ in the KOReader app.) This might allow for syncing progress to calibre without having to connect your KOReader device, in the future.
- A _Date_ column to store **when the last sync was performed**.
- A _Date_ column to store **when the sidecar file was last modified**.',
- A _Long text_ column to store the **contents of the metadata sidecar** as JSON, with _Interpret this column as_ set to _Plain text_. This is required to sync metadata back to KOReader sidecars.
- A _Long text_ column to store the **contents of the metadata sidecar** as HTML, with _Interpret this column as_ set to _HTML_.
10. Add _KOReader Sync_ to _main toolbar when a device is connected_, if it isn't there already.
11. Right-click the _KOReader Sync_ icon and _Configure_.
12. Map the metadata you want to sync to the newly created calibre columns.
13. Click _OK_ to save your mapping.
14. From now on just click the _KOReader Sync_ icon to sync all mapped metadata for all books on the connected device to calibre.

**Note:** Some field are depreciated and removed from plugin since they are changed/removed `sidecar_contents` data structure:
- `first_bookmark` removed
- `last_bookmark` removed
- `bookmarks` renamed to `annotations`
- `rating` uses 5-point instead 10-point scale
- `date_sidecar_modified` removed from `calculated`
- `date_sidecar_modified` is seems always empty, part of `calculated`

### Things to consider

- The plugin overwrites existing metadata in Calibre without asking. That usually isn’t a problem, because you will probably only add to KOReader’s metadata. But be aware that you might lose data in calibre if you’re not careful.
Expand All @@ -63,6 +62,7 @@ Releases will also be uploaded to [this plugin thread on the MobileRead Forums](

This plugin has been tested successfully with:

- Kobo Clara BW connected over USB or KOreader wireless driver (means should work with prev and latest color modes as well)
- Kobo Aura connected over USB, which means it will probably work for all comparable Kobo devices (`KOBO` and `KOBOTOUCH`)
- Kobo Aura H2O over USB (`KOBOTOUCHEXTENDED`, see [#6](https://todo.sr.ht/~harmtemolder/koreader-calibre-plugin/6) for details)
- Kobo Aura connected wirelessly, which means it will probably work for all calibre connect devices (`SMART_DEVICE_APP`)
Expand Down Expand Up @@ -95,7 +95,7 @@ If you encounter any issues with the plugin, please submit them [here](https://g
- calibre allows you to auto-connect to a folder device on boot, which greatly speeds up your workflow when testing. You can find this under "Preferences" > "Tweaks", search for `auto_connect_to_folder`. Point that to the `dummy_device` folder in this repository. (I have included royalty free EPUBs for your and my convenience.)
- If you're testing and don't actually want to update any metadata, set `DRY_RUN` to `True` in `__init__.py`.
- I work in PyCharm, which offers a remote debugging server. To enable that in this plugin, set `PYDEVD` to `True` in `__init__.py`.You might need to change `sys.path.append` in `action.py`.
- The supported device drivers can be found in [the `SUPPORTED_DEVICES` list in `config.py`](https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/config.py#L30). Adding a new type here is the first step to adding support, but make sure all features are tested thoroughly before releasing a version with an added device
- The supported device drivers can be found in [the `SUPPORTED_DEVICES` list in `config.py`](https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/config.py#L32). Adding a new type here is the first step to adding support, but make sure all features are tested thoroughly before releasing a version with an added device

### Testing in calibre

Expand All @@ -121,224 +121,12 @@ make zip

### Debugging a release

1. Download the required release from [here](https://github.com/harmtemolder/koreader-calibre-plugin/tree/main/releases)
1. Add it to calibre by running this in your terminal: `calibre-customize -a "KOReader Sync vX.X.X-alpha.zip"`, where `X.X.X` refers to the version you downloaded
1. Download the required release from [here](https://github.com/harmtemolder/koreader-calibre-plugin/releases)
1. Add it to calibre by running this in your terminal: `calibre-customize -a "KOReader_Sync_vX.X.X.zip"`, where `X.X.X` refers to the version you downloaded
1. Start calibre in debug mode with `calibre-debug -g`
1. Configure the KOReader plugin as described [here](https://github.com/harmtemolder/koreader-calibre-plugin#setup)
1. Connect your device
1. Run the sync by clicking the KOReader icon in your toolbar
1. Check the details of the message when it's done if any/all books have been synced correctly
1. Check your (custom) columns for one of those books to see if their contents are what they should be
1. Check the output in your terminal for lines containing `koreader` to see what it did

## Changelog

All notable changes to this project will be documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Changed

- Removed sorting from `column_sidecar` transform because this caused an error in at least one of my books

## [0.5.2-beta] - 2023-05-22

- Many thanks to @elmodor and igorius for their help!

### Added

- Added config option to only sync if the metadata is newer than the data stored in calibre (will fallback to "Percent read column" if no "Date Modified column" exists or can not be obtained)
- Added config option to not sync if the book has already been marked as finished (via "Percent read column" or "Reading status column")
- Added a yes/no column for read status (based on [changes from igorius at MobileRead](https://www.mobileread.com/forums/showpost.php?p=4323088&postcount=90))

### Changed

- Pylint cleanup
- Update README to match new columns
- Update dummy device and library to match new columns

### Fixed

- Fixed crash for wireless connected devices while trying to get the "Date Modified column" value
- Fixed setting correct sync status for `column_status` if no status is sent from KOReader

## [0.5.1-beta] - 2022-12-27

### Added

- Add support for Date Synced column (stores date of last sync from KOReader to Calibre)
- Add support for Date Modified column (stores date modified of KOReader Sidecar)

### Changed

- Standardized results message format
- code cleanup to pass linting

### Fixed

- Error in results message
- Fix error in debug_print definition

## [0.5.0-beta] - 2022-12-27

### Added

- Add "Sync Missing Sidecars to KOReader" functionality

### Changed

- Vendor in slpp.py instead of adding it as a separate dependency to reduce fragility

## [0.4.1-beta] - 2022-11-08

### Changed

- Use calibre's built-in UTC timezone ([source](https://github.com/kovidgoyal/calibre/blob/0cecc77a22c2cc91bbb7a5b5b414804808f73976/src/calibre/utils/date.py#L14)), because `tzdata` isn't available on Windows (see [#13](https://todo.sr.ht/~harmtemolder/koreader-calibre-plugin/13))

## [0.4.0-beta] - 2022-11-02

### Added

- Calculate first and last bookmark date columns

## [0.3.2-beta] - 2022-09-16

### Added

- Enable `POCKETBOOK632`

## [0.3.1-beta] - 2022-09-15

### Added

- Enable `USER_DEFINED`

## [0.3.0-beta] - 2022-09-13

### Changed

- Don't break for unknown device class, but try to sync anyway

## [0.2.7-alpha] - 2022-02-18

### Added

- Enable `TOLINO`, for real this time

## [0.2.6-alpha] - 2022-02-04

### Added

- Enable `POCKETBOOK622`

## [0.2.5-alpha] - 2021-12-20

### Added

- Enable `POCKETBOOK626`

## [0.2.4-alpha] - 2021-12-12

### Added

- Enable `TOLINO`

## [0.2.3-alpha] - 2021-11-23

### Added

- Enable `KOBOTOUCHEXTENDED`

## [0.2.2-alpha] - 2021-06-22

### Fixed

- Skip metadata sidecars that cannot be decoded (e.g. from a very old version of KOReader)

### Changed

- Use `path` instead of `lpath` for book paths to go around `MTP_DEVICE` lowercasing the latter
- Disable `MTP_DEVICE` because it cannot be supported (see [#2](https://todo.sr.ht/~harmtemolder/koreader-calibre-plugin/2))

### Added

- Enable `KINDLE2`

## [0.2.1-alpha] - 2021-04-26

### Added

- An extra column for read progress as integer (because that’s what [the Goodreads Sync plugin](https://www.mobileread.com/forums/showthread.php?t=123281) expects)

## [0.2.0-alpha] - 2021-04-24

### Added

- Support for highlights and bookmarks
- Counts to post-sync alerts
- An `.editorconfig` and `.pylintrc` to define code layout

### Changed

- `README.md` to reflect current state of development

## [0.1.4-alpha] - 2021-04-11

### Fixed

- Multiple tweaks and bug fixes by [Glen Sawyer](https://git.sr.ht/~snelg)

## [0.1.3-alpha] - 2021-04-04

### Added

- Support for `SMART_DEVICE_APP` devices, i.e. [KOReader's wireless connnection](https://github.com/koreader/koreader/wiki/Calibre-wireless-connection)

## [0.1.2-alpha] - 2020-11-21

### Added

- Support for `KOBO` and `KOBOTOUCH` devices

## [0.1.1-alpha] - 2020-11-18

### Added

- Support for all possible filetypes
- Variables to easily enable a dry-run when debugging and remote debugging

## [0.1.0-alpha] - 2020-11-18

### Added

- Everything needed for a first working version of the plugin
- `dummy_device` and `dummy_library` for easy debugging
- `Makefile` to build a plugin release as a ZIP file
- `TODO` to keep to-dos in one place
- `environment.yml`, in case anyone wants to recreate my Conda environment
- This `README.md`

[0.1.0-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.1.0-alpha.zip
[0.1.1-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.1.1-alpha.zip
[0.1.2-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.1.2-alpha.zip
[0.1.3-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.1.3-alpha.zip
[0.1.4-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.1.4-alpha.zip
[0.2.0-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.0-alpha.zip
[0.2.1-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.1-alpha.zip
[0.2.2-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.2-alpha.zip
[0.2.3-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.3-alpha.zip
[0.2.4-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.4-alpha.zip
[0.2.5-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.5-alpha.zip
[0.2.6-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.6-alpha.zip
[0.2.7-alpha]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.2.7-alpha.zip
[0.3.0-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.3.0-beta.zip
[0.3.1-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.3.1-beta.zip
[0.3.2-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.3.2-beta.zip
[0.4.0-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/blob/main/releases/KOReader%20Sync%20v0.4.0-beta.zip
[0.4.1-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/releases/tag/v0.4.1-beta
[0.5.0-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/releases/tag/v0.5.0-beta
[0.5.1-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/releases/tag/v0.5.1-beta
[0.5.2-beta]: https://github.com/harmtemolder/koreader-calibre-plugin/releases/tag/v0.5.2-beta
[unreleased]: https://github.com/harmtemolder/koreader-calibre-plugin
Loading

0 comments on commit 20ac77d

Please sign in to comment.