[GUI Plugin] Category Tags

[capink]

The main idea of this plugin is to enable the users to tag items (authors, tags, series, publisher ... etc) in the same way they can tag the books, by making use of user categories. There are two ways to do this in the plugin:

1. The plugin offers a dialog based on calibre's tag editor that enables you to tag items the same way you tag books. (see attached screenshot)
   
   The dialog is accessed by right clicking on an item in calibre's tag browser and choosing the category tags action. The plugin will apply the user categories to the selected item. If the user category is not present in calibre it will created by the plugin, this also applies to hierarchical.
2. The plugin offers import/export functionality that enables mass tagging of items as well as transferring user categories between libraries. More on this below.

Import/Export user categories

• The plugin offers import/export functionality. This allows the user to export his user categories into csv file, edit them as he wants, and re-import them back again into calibre
  
• In the csv file you can tag your items (authors, series, tags, .... etc) with whatever user categories you want.
  
• The action currently offers two different csv formats:
  
  1. The first format is "Items for category". This format allows you to apply a certain tag (i.e user category) for multiple items at once. Say for example you have a list of Nobel Laureates and want to use it to create a user category "Awards.Nobel", this is illustrated below
     
     

     ---------------------------------------------------------------------------------------------------
     category            item_type           items
     ---------------------------------------------------------------------------------------------------
     Awards.Nobel        authors             Gabriel Garcia Marquez & Naguib Mahfouz & ....
     Genre.Fantasy       series              discworld ::: Wheel of Time ::: .....

     
     

     Note: when using "Items for category" format, you should use the following to separate different items:

     • "&" for authors and author like columns.
     • ", " for tags and tag-like columns.
     • ":::" for series and text columns.

  2. The Second format is "Categories for item". This format allows you to apply a multiple tags (i.e user categories) to an item as illustrated below:
     
     

     ---------------------------------------------------------------------------------------------------
     item                        item_type           categories
     ---------------------------------------------------------------------------------------------------
     Naguib Mahfouz              authors             Awards.Nobel, Nationality.Egyptian, .....
     Gabriel Garcia Marquez      authors             Awards.Nobel, Nationality.Colombian, .....

• The plugin will create the categories for you even if they are not already in calibre.
  
• The items (authors, series, ... etc) in the csv file are matched to items in your calibre library based on criteria you define. By default, identical matching (case insensitive) is used. But you can configure different match criteria for each item_type. Matching is based on advanced mode of the Find Duplicates plugin, so you have the option to choose from: similar, fuzzy, soundex as well as custom match algorithms by using template match.
  
• After the items are matched, a dialog for manual match resolution is popped up to allow the user to modify any matches. It is based on code from the Import List plugin (Thanks to kiwidude for his awesome code).
  
• The default for items that have multiple matches (e.g Gabriel Garcia Marquez, Gabriel García Márquez) is to apply the categories to all the matches. There is an option to turn this off.
  
• As of version 0.3.0, you can export/import both links and notes, only for categories_for_item format.

Credits

• User category editor is based on calibre's Tag Editor by Kovid Goyal.
• The manual resolution wizard page is based on code from the Import List plugin by kiwidude.
• Special thanks for chaley and Kovid for adding the code that add plugins to the tag browser context menu.

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 5.24.0 or later.

Paypal Donations:

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

Version History:

Spoiler:

Version 0.3.2 - 12 March 2025
Fix: When applying user categories, make sure to do case insensitive match with existing user categories, to prevent case clashes leading to renames. (Error: found user category case overlap ..., Renaming user category ...)

Version 0.3.1 - 11 March 2025
Fix: Minor Fix.

Version 0.3.0 - 9 March 2025
Update: Add the ability to import/export both links and notes, only applicable for categories_for_items format.

Version 0.2.8 - 19 July 2023
Update: Update to latest Action Chains API.

Version 0.2.7 - 9 August 2022
Update: update to calibre6 icon fetching. Code from @JimmXinu.

Version 0.2.6 - 17 July 2022
Fix PyQt6 migration bugs.

Version 0.2.5 - 18 June 2022
Fix: remove stale db reference.

Version 0.2.4 - 27 April 2022
Fix bug affecting users on Windows.

Version 0.2.3 - 10 February 2022
Fix PyQt6 migration bug.

Version 0.2.2 - 13 January 2022
Fix PyQt6 migration bug.

Version 0.2.1 - 7 January 2022
Fix PyQt6 migration bug.

Version 0.2.0 - 6 January 2022
Changes for the upcoming PyQt6.

Version 0.1.3 - 17 December 2021
Minor fix.

Version 0.1.2 - 31 October 2021
Minor fix.

Version 0.1.1 - 2 August 2021
Minor Bug fixes.

Version 0.1.0 - 2 July 2021
Initial Release.

[jbacelar]

I hope to explain myself more or less, since my English is quite primitive:

Having defined (for example) Naguib Mahfouz (item) authors (item_type) Nationality.Egyptian (categories), how could the value Egyptian be automatically transferred to a user column, for all the books of the author Naguib Mahfouz?

[capink]

You can use the template language to populate a custom column with the user categories.

program:
    user_categories()

You can update the column with calibre's search and replace (which supports using a template as an input field), or by using the Action Chains plugin.

Also, the template language should allow you to control what user categories should be included and what should not. For example, if you want only user categories starting with "Nationality." to be included:

program:
	res = '';
	for cat in user_categories():
		if '^nationality\.' in cat then
			res = list_union(res, cat, ',')
		fi
	rof;
        res

[jbacelar]

Many thanks.
I will try it today.

[jbacelar]

It works great.

[jbacelar]

After having carried out an import of authors-nationality without any problem, in the second import with new authors this error appears:

calibre, version 5.31.1
ERROR: Excepción no considerada: <b>AttributeError</b>:'set' object has no attribute 'append'

calibre 5.31.1 [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: es
Successfully initialized third party plugins: DeDRM (7, 2, 1) && Action Chains (1, 13, 3) && Calibre Power Search Plugin (2, 1, 1) && Category Tags (0, 1, 1) && Comments Cleaner (1, 4, 1) && Count Pages (1, 11, 1) && Diaps Editing Toolbag (0, 3, 7) && EpubCheck (0, 2, 3) && EpubMerge (2, 11, 0) && EpubSplit (3, 1, 0) && Favourites Menu (1, 0, 5) && Find Duplicates (1, 8, 10) && GetFileName (0, 1, 1) && Import List (1, 5, 6) && Job Spy (1, 0, 190) && LanguageTool (0, 1, 1) && Modify ePub (1, 6, 3) && Prince PDF (1, 5, 0) && Quality Check (1, 11, 4) && Resize Cover (1, 1, 0) && Search The Internet (1, 8, 1) && TOC View Generator (2, 1, 1) && User Category (1, 5, 5) && View Manager (1, 6, 0)
Traceback (most recent call last):
File "calibre_plugins.category_tags.user_categories.pag e_resolve", line 699, in validatePage
File "calibre_plugins.category_tags.user_categories.act ions", line 115, in add_categories_for_item
AttributeError: 'set' object has no attribute 'append'

[capink]

Try this and report back, please.

[jbacelar]

I will do it.

[jbacelar]

It works perfectly.

[jbacelar]

After working without any problem, today trying to import I find the following error:

calibre, version 5.34.0
ERROR: Excepción no considerada: <b>AttributeError</b>:'list' object has no attribute 'add'

calibre 5.34 [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: es
Successfully initialized third party plugins: DeDRM (7, 2, 1) && Action Chains (1, 14, 0) && Calibre Power Search Plugin (2, 1, 1) && Category Tags (0, 1, 2) && Comments Cleaner (1, 5, 0) && Count Pages (1, 11, 1) && Diaps Editing Toolbag (0, 3, 7) && Editor Chains (0, 4, 1) && EpubCheck (0, 2, 3) && EpubMerge (2, 11, 0) && EpubSplit (3, 1, 0) && Favourites Menu (1, 0, 5) && Find Duplicates (1, 8, 10) && GetFileName (0, 1, 1) && Import List (1, 5, 6) && Job Spy (1, 0, 190) && LanguageTool (0, 1, 1) && Modify ePub (1, 6, 3) && Prince PDF (1, 5, 0) && Quality Check (1, 11, 4) && Resize Cover (1, 1, 0) && Search The Internet (1, 8, 1) && TOC View Generator (2, 1, 1) && User Category (1, 5, 5) && View Manager (1, 6, 0)
Traceback (most recent call last):
  File "calibre_plugins.category_tags.user_categories.page_resolve", line 699, in validatePage
  File "calibre_plugins.category_tags.user_categories.actions", line 115, in add_categories_for_item
AttributeError: 'list' object has no attribute 'add'

The same happens with Calibre 5.33.2

[capink]

Does this solve the problems for you?

[jbacelar]

Well yes sir! speed and efficiency.
Thanks a lot.

[capink]

Changes for the upcoming PyQt6.

[paolino]

Does it work with the new version 5.38 ?
I have tried to export but I get only a .csv file with :
"item" "item_type" "categories".

My target is to upload a new list of categories for tags to be used for classifying future ebook.

Thanks
P

[paolino]

I have also tried to import a .csv file but I get always the error message:

"name 'os' is not defined"