[GUI Plugin] Action Chains

capink · 11-20-2020, 02:01 PM

Using this plugin you can define action chains that can be run from menu entries or an assigned keyboard shortcut. A chain can contain one or more action(s) that are run sequentially.

Available Actions:
The plugin defines some builtin actions you can use, it also provides a module editor where you can write your own actions using python.

Open With: Similar to the open with plugin, but with some modifications. Used in this plugin it allows you to chain it to other actions. e.g. update timestamps
Single Field Edit: Allows you to edit the value of a single field for selected books. You can choose the value at run-time, or use a predefined value, or define a template.
Search and replace: This action is based on calibre's search and replace and have the same interface, only difference is that it allows you define the values ahead of time in your chain. At run-time, it gets the predefined search/replace values and executes them, giving you the ability to chain it to multiple other actions (other search/replace or other actions).
Calibre Actions: This action allows you to choose an action from calibre interface actions, for the purpose of chaining it to other actions.
Selection Modifier: This action is useful when chaining actions together as it allows you to change the selections in calibre before an action. There are multiple criteria for modifying the selections. More on this below.
Copy to Clipboard: copy book metadata for selected books to clipboard. You choose the data copied by defining a template.
Formulas: Excel like formulas. e.g sum, mean, median .... etc. This action leverages calibre template language. Formulas can be entered at runtime or can be predefined. For more on this see this post.
Converts books: This uses calibre convert functionality. It allows you to create different conversion profile and chain them to other actions.
Run Python Code: For people who can program in python.

Limitations:

The chain runs in the main gui thread because some actions cannot run in a thread other than that of the main gui. As a result, the abort button for the progress bar (which is displayed in the status bar) is non responsive, so I removed it. There is currently no way to stop the chain midway.

How to use the plugin:

To make a new chain follow these steps:

From the drop-down menu choose the "Add/Modify chains" entry to open the config dialog.
In the config dialog press the add button to add a new empty chain.
Double click on the name field to give the new chain a name, and optionally choose a sub-menu and an icon.
To start adding actions to the chain, press the settings button in the chain row, which will open the add actions dialog.
In the add actions dialog, press on the add action button. After this choose and action you want from the actions combo-box. Press the action settings button configure the action.
Repeat for all actions you want to add, and then press OK.

Suggested Use Cases:

Here are some tips to help get you started:

Chaining multiple search/replace actions to together.
Adding a chain to edit the rating value and applying a custom last_rated_date timestamps afterwards. For this chain, you need two actions:
- for the first action select Single Field Action and configure it by choosing the rating field and ticking the option to ask for value at run-time.
- Add a second Single Field Action to apply the timestamps to your custom last rated date field. This time set it to a predefined value, then check the option "set to current time".
Whenever you run this action through the menu or a keyboard shortcut, a rating dialog editor will pop up, choose the rating you want and it will apply to all selected books together with the timestamps.
You can take the above idea one step further, by defining 5 chains and assigning each one to a different keyboard shortcut. In each of those chain, instead of letting the chain ask you for a value at run-time, specify a predefined value for each chain, starting with value of ★ for the first chain and repeating for the others until you reach ★★★★★ for the last chain. Each chain can contain an extra action for timestamps as in the previous example. Now you can rate your books with configured shortcuts. To make this easier, there is a copy button that allows you to copy chains.

Note: you need to insert the selection modifier even if you are using a single metadata edit dialog, as this dialog can change selections through the next and previous buttons, and by applying the selection modifier, it will select all books whose metadata have been updated.
You can use the template feature in the Single Field Action to setup persistent composite columns. Note however that while it might improve performance for huge libraries, you lose the convenience of composite columns being updated automatically, so you will have to run the chain periodically to update them.
A chain does not have to contain multiple actions, you can have a chain with only one action. For example you can have multiple chains for different copy to clipboard templates. As an example, if you want to copy a format (e.g. epub) path to clipboard, create a chain containing a single copy to clipboard action with the following template:
Code:
```
program: select(formats_paths(),'EPUB')
```
Another action that can be used alone in a chain is the Formulas action. For more on formulas, see this post.
You can use the Book List Double Clicked event to change the default action to any calibre action you want, by using the Event Manager to connect the event to a whatever chain you want. For more on this, see this post.

Note on the Selection Modifier Action:

Since all the actions are selection dependent, the Modifier Selection Action gives you the option to change the current selection ahead of any action. You can choose only books modified by previous action, or you can specify search criteria to further narrow down you selections
If you choose a search to narrow down you selection, this will only change the current view of calibre to results of this search, so you need tick option "select all books in current view" together with the search.
Some actions may affect only some of the selected books. For example if you use the bulk metadata editor to remove certain tags, this action will only affect books that have that tags. If you want your next action to apply only to modified books (e.g. you want to add timestamp to only modified books), add a Selection Modifier to change the selections to "books modified by last action".
The point above applies to adding new books. If you want to select all books added by last action, add a selection modified right after the add action, with option "Select books modified by last action" checked.
For users who have the highlight search setting turned on, the selection modifier will temporarily turn it off, and then restores it back after it finishes. This is done to allow the "select all books in current view" option to work as expected when combined with a search.
Starting with version 1.6.0, the plugin introduced a new feature called scopes that can replace the functionality of the selection modifier. Note that not all actions support the new scopes feature, so some actions, most notably Calibre Actions, will still depend on the Selection Modifier specify which book they will act on.

Note on Module Editor:

For information on how to write your own actions, see the comments in calibre_plugins.action_chains.actions.base
Instead of making a plugin for every small task you want, you can use the module to add a custom action and add it to its own chain, which will get its own menu entry.
For examples on how to write a simple custom action, see here. Another example that illustrate how to add a settings dialog to a custom action can be found here.

Conditional execution for chains and actions (branching):

For more information on how to implement conditions on chains and actions, that allows for branching, see this post.

Action chains template functions:

Action chains define some extra template functions to supplement calibre's template language. You can read more on this here.

Scopes:

Starting with version 1.6.0, the plugin introduced a new feature called scopes that can replace the functionality of the selection modifier for actions that support this new feature.

Event Manager

Starting with version 0.5.0 actions chains added an event manager where you can configure chains to run in response to events. You can read more on this here.

Action chains API

Starting with version 1.4.0 actions chains added an API that enables other plugins to communicate with action chains. You can read more on this here.

Custom actions and events:

A list of custom actions and events posted on this thread is maintained here.

Misc tips:

A list of some of the tips posted on this thread is maintained here.

Misc links

Editor Chains:

A plugin called Editor Chains that can automate editor actions can be found here. Note that is an experimental plugin.

Credits:

The icon dialog and the dynamic menus are based on code from the Open With plugin by kiwidude.
The Open With action is based on code from Open With plugin by kiwidude.
The Calibre Actions is based on code from the Favourites Menu plugin by kiwidude.
The module editor is based on calibre editor function editor by Kovid Goyal.
The Search and Replace Action is based on calibre's search and replace. (chaley and Kovid Goyal)
Special thanks for chaley for introducing multiple modifications to template language and dialog that are used by the plugin.

Installation Notes:

Download the attached zip file/install the plugin/add to toolbar or menu as described in the Introduction to plugins thread.

Special Notes:

Requires Calibre 6.12.0 or later.

Paypal Donations:

If you find this useful please feel free to show your appreciation.

Version History:

Spoiler:

capink · 11-20-2020, 05:18 PM

reserved post.

ownedbycats · 11-20-2020, 11:39 PM

This sounds almost like an exact solution to my post here. Definitely giving it a try.

Early feedback: One small feature that seems to be missing is the ability to add a descriptor/label to actions.

Works pretty well otherwise though. I'm experimenting with the selection modifier so I don't have separate actions for AO3 and FFNet fics.

Also, I found it's helpful to add a Calibre Action to toggle mark on all the books before starting a chain, and then at the very end setting a search to marked:true.

A small suggestion: It might be a good idea to have a custom action to prompt for confirmation for more...destructive action chains, and pressing "no" would halt the entire thing. I guess this could be made with a module though I'm not sure how.

capink · 11-21-2020, 08:52 AM

Quote:

Originally Posted by ownedbycats

Early feedback: One small feature that seems to be missing is the ability to add a descriptor/label to actions.

Yes. I realized this after I've done it. First I needed to change the order of some actions, so I added drag and drop, but it is not perfect because it does not have visual indication of what is being dragged. So I thought adding identifiers might help.

I am thinking about rewriting it as a table to add identifiers and make changing order easier.

Quote:

Originally Posted by ownedbycats

Also, I found it's helpful to add a Calibre Action to toggle mark on all the books before starting a chain, and then at the very end setting a search to marked:true.

Nice. At least some extra use for Calibre Actions

Quote:

Originally Posted by ownedbycats

A small suggestion: It might be a good idea to have a custom action to prompt for confirmation for more...destructive action chains, and pressing "no" would halt the entire thing. I guess this could be made with a module though I'm not sure how.

As I pointed out in first post, I have not yet settled on how to deal with the control flow. But your request is simple enough to be used as demonstration of how to write custom actions, so here it is:

Code:

from PyQt5.Qt import QWidget, QVBoxLayout, QGroupBox, QTextEdit

from calibre.gui2 import question_dialog
from calibre_plugins.action_chains.actions.base import ChainAction

class ConfirmConfigWidget(QWidget):
    def __init__(self, plugin_action):
        QWidget.__init__(self)
        self._init_controls()

    def _init_controls(self):

        l = QVBoxLayout()
        self.setLayout(l)

        gb = QGroupBox('Confirm message')
        gb_l = QVBoxLayout()
        gb.setLayout(gb_l)

        self.tb = QTextEdit()
        self.tb.insertPlainText('Are you sure you want to proceed?')

        gb_l.addWidget(self.tb)
        l.addWidget(gb)

    def load_settings(self, settings):
        if settings:
            self.tb.setText(settings['message'])

    def save_settings(self):
        settings = {}
        settings['message'] = self.tb.toPlainText()
        return settings

class ConfirmAction(ChainAction):

    name = 'Confirm'

    def config_widget(self):
        return ConfirmConfigWidget

    def run(self, gui, settings, chain):
        message = settings.get('message', 'Are you sure you want to proceed?')
        if not question_dialog(gui, _('Are you sure?'), message, show_copy_button=False):
            raise chain.UserInterrupt

ownedbycats · 11-21-2020, 03:41 PM

Here's a small glitch I found:

Single Field Edit > Predefined Value > Today on a timestamp column seems to have trouble with timezones.

I'm -4:00 GMT, and running an action at 3:30 pm produces a timestamp of 7:30 pm. Not sure what would happen if I ran it when the timezones are on different dates.

EDIT: Actually, it seems to produce timestamps of the time that the action was created....not the time it was run. Odd.

capink · 11-21-2020, 04:09 PM

Quote:

Originally Posted by ownedbycats

Here's a small glitch I found:

Single Field Edit > Predefined Value > Today on a timestamp column seems to have trouble with timezones.

I'm -4:00 GMT, and running an action at 3:30 pm produces a timestamp of 7:30 pm. Not sure what would happen if I ran it when the timezones are on different dates.

EDIT: Actually, it seems to produce timestamps of the time that the action was created....not the time it was run. Odd.

Sorry. I made a last minute change before posting that altered it. Can you try this one attached here and report back on it.

Edit: You will have to remove the action and add it again.

ownedbycats · 11-21-2020, 04:18 PM

Trying to run/edit an existing action changing a datetime column failed with an error, but creating a new one worked with the proper timestamp.

Here's the error in case you need it anyways:

Code:

calibre, version 5.5.0
ERROR: Unhandled exception: <b>TypeError</b>:cannot unpack non-iterable datetime.datetime object

calibre 5.5 [64bit]  embedded-python: True is64bit: True
Windows-10-10.0.19041 Windows ('64bit', 'WindowsPE')
('Windows', '10', '10.0.19041')
Python 3.8.5
Windows: ('10', '10.0.19041', '', 'Multiprocessor Free')
Interface language: None
Successfully initialized third party plugins: Action Chains (0, 1, 0) && Barnes & Noble (1, 2, 16) && Calibre Power Search Plugin (1, 7, 0) && CalibreSpy (1, 0, 83) && Comments Cleaner (1, 3, 0) && Count Pages (1, 11, 0) && Drop Search Results (1, 0, 10) && Embed Comic Metadata (1, 5, 2) && EpubCheck (0, 2, 3) && EpubMerge (2, 11, 0) && Extract ISBN (1, 5, 0) && FanFicFare (3, 25, 8) && Fantastic Fiction (1, 4, 0) && Favourites Menu (1, 0, 5) && Find Duplicates (1, 8, 3) && Generate Cover (2, 0, 0) && GetFileName (0, 1, 1) && Goodreads (1, 5, 1) && Import List (1, 5, 1) && Job Spy (1, 0, 188) && Kindle hi-res covers (0, 5, 0) && Kobo Books (1, 8, 0) && Kobo Utilities (2, 11, 8) && KoboTouchExtended (3, 4, 1) && Library Codes (1, 0, 47) && Manage Series (1, 2, 11) && Modify ePub (1, 6, 1) && MultiColumnSearch (1, 0, 85) && Open With (1, 5, 13) && Quality Check (1, 10, 1) && Reading List (1, 7, 1) && Save To Format (0, 0, 6) && SmartEject (2, 3, 0) && Sum Column (0, 3, 1) && View Manager (1, 6, 0)
Traceback (most recent call last):
  File "calibre_plugins.action_chains.action", line 209, in run_chain
  File "calibre_plugins.action_chains.chain_tools", line 96, in run_loop
  File "calibre_plugins.action_chains.chain_tools", line 79, in run_loop
  File "calibre_plugins.action_chains.actions.single_field", line 378, in run
  File "calibre_plugins.action_chains.dialogs.single_field_widgets", line 1009, in setter
TypeError: cannot unpack non-iterable datetime.datetime object

capink · 11-21-2020, 04:26 PM

Quote:

Originally Posted by ownedbycats

Trying to run/edit an existing action changing a datetime column failed with an error, but creating a new one worked with the proper timestamp.

Here's the error in case you need it anyways:

Code:

calibre, version 5.5.0
ERROR: Unhandled exception: <b>TypeError</b>:cannot unpack non-iterable datetime.datetime object

calibre 5.5 [64bit]  embedded-python: True is64bit: True
Windows-10-10.0.19041 Windows ('64bit', 'WindowsPE')
('Windows', '10', '10.0.19041')
Python 3.8.5
Windows: ('10', '10.0.19041', '', 'Multiprocessor Free')
Interface language: None
Successfully initialized third party plugins: Action Chains (0, 1, 0) && Barnes & Noble (1, 2, 16) && Calibre Power Search Plugin (1, 7, 0) && CalibreSpy (1, 0, 83) && Comments Cleaner (1, 3, 0) && Count Pages (1, 11, 0) && Drop Search Results (1, 0, 10) && Embed Comic Metadata (1, 5, 2) && EpubCheck (0, 2, 3) && EpubMerge (2, 11, 0) && Extract ISBN (1, 5, 0) && FanFicFare (3, 25, 8) && Fantastic Fiction (1, 4, 0) && Favourites Menu (1, 0, 5) && Find Duplicates (1, 8, 3) && Generate Cover (2, 0, 0) && GetFileName (0, 1, 1) && Goodreads (1, 5, 1) && Import List (1, 5, 1) && Job Spy (1, 0, 188) && Kindle hi-res covers (0, 5, 0) && Kobo Books (1, 8, 0) && Kobo Utilities (2, 11, 8) && KoboTouchExtended (3, 4, 1) && Library Codes (1, 0, 47) && Manage Series (1, 2, 11) && Modify ePub (1, 6, 1) && MultiColumnSearch (1, 0, 85) && Open With (1, 5, 13) && Quality Check (1, 10, 1) && Reading List (1, 7, 1) && Save To Format (0, 0, 6) && SmartEject (2, 3, 0) && Sum Column (0, 3, 1) && View Manager (1, 6, 0)
Traceback (most recent call last):
  File "calibre_plugins.action_chains.action", line 209, in run_chain
  File "calibre_plugins.action_chains.chain_tools", line 96, in run_loop
  File "calibre_plugins.action_chains.chain_tools", line 79, in run_loop
  File "calibre_plugins.action_chains.actions.single_field", line 378, in run
  File "calibre_plugins.action_chains.dialogs.single_field_widgets", line 1009, in setter
TypeError: cannot unpack non-iterable datetime.datetime object

I put the bulk edit widget erroneously in place of the config widget. So any single field action containing timestamps will need to be deleted and re-added again.

Edit: I updated the first post to include the fixed version. Please note that any single field action with date columns will have to be removed and re-added again.

ownedbycats · 11-21-2020, 04:30 PM

Thankfully I only have the one. "Mark as Read" sets #read to yes, #percentread to 100, #lastread to the current time, and pops up a rating dialog.

jbacelar · 11-22-2020, 06:17 AM

I've tried it with a fairly long searchs and replaces chain, and it works like a charm (ugh! what a break).

Quote:

Originally Posted by capink

I am thinking about rewriting it as a table to add identifiers and make changing order easier.

That will be very useful.

Congratulations! and thank you very much for this magnificent work.

capink · 11-22-2020, 09:25 AM

Quote:

Originally Posted by jbacelar

I've tried it with a fairly long searchs and replaces chain, and it works like a charm (ugh! what a break).

Glad it is of help to you.

Quote:

Originally Posted by jbacelar

That will be very useful.

I will see about this. The current view has the advantage of integrating better with error messages. I am still trying to figure the best way to do this.

Another thing I am not sure about, is whether it makes sense to make the chains library specific, or keep them as they are now. If people have any input about this, I would be interested in hearing it. It might break existing settings though.

capink · 11-22-2020, 09:32 AM

Quote:

Originally Posted by ownedbycats

Thankfully I only have the one. "Mark as Read" sets #read to yes, #percentread to 100, #lastread to the current time, and pops up a rating dialog.

After you are done exploring you should come back and write your own use cases

.

One suggestion though, put the rating dialog action first and put a selection modifier with the option "select books modified by last action" right below it, and after that put all the other actions. This way if you press the cancel button on the rating dialog for whatever reason, the rest of actions are not carried out since there are no selection.

compurandom · 11-22-2020, 11:29 AM

Haven't tried this plugin yet, but it looks really useful!

Quote:

Originally Posted by capink

"select books modified by last action"

How about in addition to select books, you mark books with tag and take a user supplied tag.

This would let you search for marked:usertag after the chain ran to select subsets from different actions within the chain or maybe even reuse previous results within the chain.

capink · 11-22-2020, 12:14 PM

Quote:

Originally Posted by compurandom

Haven't tried this plugin yet, but it looks really useful!

How about in addition to select books, you mark books with tag and take a user supplied tag.

This would let you search for marked:usertag after the chain ran to select subsets from different actions within the chain or maybe even reuse previous results within the chain.

Nice idea. I was actually thinking about how to revert to selections from previous actions. My initial thought was to store the selections somewhere. But your idea also works. If calibre mark tool allowed for marking with text, it would have been easy to use it from the "Calibre Action" action.

compurandom · 11-22-2020, 12:50 PM

Quote:

Originally Posted by capink

If calibre mark tool allowed for marking with text, it would have been easy to use it from the "Calibre Action" action.

I also wish I could see the list of text marks and select them from a menu.
I've thought about writing a plugin to do that, but haven't gotten around to it.

11-20-2020, 05:18 PM	#2
capink Wizard Posts: 1,139 Karma: 1954142 Join Date: Aug 2015 Device: Kindle	reserved post. Last edited by capink; 08-01-2023 at 05:15 PM.

11-20-2020, 11:39 PM	#3
ownedbycats Custom User Title Posts: 9,588 Karma: 65099765 Join Date: Oct 2018 Location: Canada Device: Kobo Libra H2O, formerly Aura HD	This sounds almost like an exact solution to my post here. Definitely giving it a try. Early feedback: One small feature that seems to be missing is the ability to add a descriptor/label to actions. Works pretty well otherwise though. I'm experimenting with the selection modifier so I don't have separate actions for AO3 and FFNet fics. Also, I found it's helpful to add a Calibre Action to toggle mark on all the books before starting a chain, and then at the very end setting a search to marked:true. A small suggestion: It might be a good idea to have a custom action to prompt for confirmation for more...destructive action chains, and pressing "no" would halt the entire thing. I guess this could be made with a module though I'm not sure how. Last edited by ownedbycats; 11-21-2020 at 02:46 AM.

11-21-2020, 03:41 PM	#5
ownedbycats Custom User Title Posts: 9,588 Karma: 65099765 Join Date: Oct 2018 Location: Canada Device: Kobo Libra H2O, formerly Aura HD	Here's a small glitch I found: Single Field Edit > Predefined Value > Today on a timestamp column seems to have trouble with timezones. I'm -4:00 GMT, and running an action at 3:30 pm produces a timestamp of 7:30 pm. Not sure what would happen if I ran it when the timezones are on different dates. EDIT: Actually, it seems to produce timestamps of the time that the action was created....not the time it was run. Odd. Attached Thumbnails Last edited by ownedbycats; 11-21-2020 at 03:51 PM.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Action Chains Resources	capink	Plugins	66	11-10-2024 08:13 PM
[Editor Plugin] Editor Chains	capink	Plugins	94	07-03-2024 08:26 PM
[GUI Plugin] Noosfere_util, a companion plugin to noosfere DB	lrpirlet	Plugins	2	08-18-2022 04:15 PM
[GUI Plugin] Save Virtual Libraries To Column (GUI)	chaley	Plugins	14	04-04-2021 06:25 AM

11-21-2020, 04:30 PM	#9
ownedbycats Custom User Title Posts: 9,588 Karma: 65099765 Join Date: Oct 2018 Location: Canada Device: Kobo Libra H2O, formerly Aura HD	Thankfully I only have the one. "Mark as Read" sets #read to yes, #percentread to 100, #lastread to the current time, and pops up a rating dialog.

Advert

Advert