[GUI Plugin] Calibre Awards - Find and add literary awards

[taurins]

Hi everyone,

I've been working on a new Calibre plugin called Calibre Awards, and I've reached the point where I'd like to put the first public beta out for testing.

The idea is pretty simple: while editing the metadata for a book, Calibre Awards adds a Check Awards button. It searches several literary-award sources for the title and author, shows you what it finds, and optionally lets you write selected awards back to a Calibre field.

Current award sources:

• Pulitzer Prizes
• Nebula Awards
• Hugo Awards
• Locus Awards via the Science Fiction Awards Database (SFADB)
• World Fantasy Awards
• Nobel Prize in Literature

The plugin is not limited to winners. Where a source provides an actual numerical placement, you can choose how far down the list you want to consider. The default is the top 5, but the cutoff can be set anywhere from 1 to 100.

For example, if a Locus result says a book placed 19th, a cutoff of 20 will allow that result to qualify. The plugin does not invent rankings from list order.

I've also tried to be deliberately conservative about author matching. For example, if Calibre has:

Allen M. Steele

but the award source has:

Allen Steele

the plugin can show that as a Possible Author Match rather than silently assuming they are the same person. These results start unchecked and require you to confirm them manually. The plugin does not change the author metadata.

Other features include:

• Enable or disable individual award sources
• Configurable award output format
• Optional write-back to a selected Calibre field
• Append or replace write-back modes
• Review results before anything is written
• One source failing does not prevent the other sources from returning results

The output format currently supports:

<placement>
<year>
<award>
<category>

The default is:

<placement> - <year> <award> - <category>

Requirements

Calibre 9.13.0 or later
Windows, macOS, or Linux
An internet connection while checking awards

This is version 0.1.0 and should definitely be considered a beta.

There are still limitations. In particular, Pulitzer.org sometimes blocks automated requests, Hugo numerical placements are available only where official ranking statistics are available, and some categories such as anthology/editor awards are not yet supported.

I'd especially appreciate reports of books where:

• an award should have been found but wasn't
• the wrong book or author was matched
• a placement/category looks incorrect
• one of the award websites has changed and the plugin stops finding results

If reporting a problem, title + author + the award/source involved would be extremely helpful.

GitHub project and documentation:
https://github.com/RealLactar/Calibre-Awards

Latest beta release:
Calibre Awards 0.1.0 Beta

Installation is the usual Calibre plugin process:

Preferences → Plugins → Load plugin from file

Select Calibre-Awards-0.1.0.zip and restart Calibre if requested.

Thanks to anyone willing to give it a try. I'm particularly interested in real-world examples that help identify awards, categories, and edge cases worth adding next.

[BetterRed]

Why min calibre version of 9.13? As at this moment that means ~86% of calibre users couldn't install the plugin, see Most popular versions in calibre - Usage Statistics.

Prize list is very USA centric, 86% of calibre users live outside US, 70+% are from countries outside the Anglosphere. Any thoughts of allowing users to add prizes, e.g. Man Booker, Le Prix Goncourt, Premio Strega, Miles Franklin, India.has 20+ official languages, there are awards for most, probably all, of them… and the dozens of non official languages.

@anyone - Is this the first optional plugin for calibre that operates from within a child window (modal dialogue too); if so, is this something new?

BR

[rantanplan]

I assume that we can just open a GH issue and add sources like https://www.deutscher-buchpreis.de, correct?

[taurins]

You're very correct about the prize list currently being US centric. I'm from the US so I initially worked with what I knew. However my plans are to definitely expand the list to international award lists. Part of this beta release is to solicit ideas of what award lists to focus on next.

As far as versioning, you make a valid point. I have only tested against 9.13. I'll put testing against earlier versions top of my list right now. Thanks.

Response to your "@anyone" question:

That's a good question. I honestly don't know enough about the history of Calibre plugins to say whether this is the first one to do it.

What Calibre Awards does is a little unusual in that the Check Awards button is added directly to Calibre's existing Edit Metadata window rather than opening a separate plugin window from the main Calibre screen.

There isn't a new Calibre plugin API that specifically allows this. The plugin hooks into the existing Edit Metadata dialog after Calibre creates it and adds the button there.

I haven't come across another optional plugin that works this way, but that certainly doesn't mean one hasn't existed. If anyone knows of another example I'd be interested to hear about it.

The only downside is that this does rely on part of Calibre's internal Edit Metadata interface, so if that changes in a future Calibre release I may have to adjust the plugin.

[taurins]

Absolutely! That's one of the main purposes of this beta release is to facilitate awards lists to go after next.

[PeterT]

If you're developing on Windows, just install a few of the Portable Calibre packages; each into their own directory.

That way you can easily test your plugin against any version of calibre, each with their own independent configuration and eBook library. Sure you can only run one instance at a time but that's a minor issue. Be sure to launch portable ones from their own launcher (I forget if the installer makes a batch file for you. Don't launch them via the standard execution of calibre.exe).

[taurins]

Quick update on the Calibre version requirement.

When I released 0.1.0 I listed Calibre 9.13 as the minimum version because that was the version I had developed and tested the plugin against. After the question was raised here, I went back and did a compatibility audit and then installed Calibre 6.0.0 Portable to test it directly.

Everything worked as expected, including installation, configuration, the Check Awards button inside Edit Metadata, live award lookups, write-back to a custom column, duplicate handling and canceling a lookup.

So version 0.1.1 is now available and officially supports Calibre 6.0.0 or later.

Thanks for pointing this out. It ended up opening the plugin up to quite a few more Calibre users.

[PeterT]

As an aside to my previous post on calibre portable and different versions on Windows one can replicate the idea on Linux.

Here are two scripts I've used in the past; one to install a given version and a second to execute it.

Install

#!/bin/sh
#
wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sh /dev/stdin version=7.26.0 install_dir=/home/peterjt/calibre_726/ isolated=y

### ./calibre_post_install.sh

Run

#!/bin/sh

ver=726
bin=~/calibre_${ver}/calibre/
config=~/calibre_${ver}/config/
eBooks=~/calibre_${ver}/eBooks/

if ! test -d ${config} ; then mkdir ${config} ; fi
if ! test -d ${eBooks} ; then mkdir ${eBooks} ; fi

if pidof calibre ; then echo Shutting down calibre; CALIBRE_CONFIG_DIRECTORY=${config} ${bin}/calibre -s ; fi

CALIBRE_CONFIG_DIRECTORY=${config} ${bin}/calibre --with-library ${eBooks}

[BetterRed]

Originally Posted by PeterT

If you're developing on Windows, just install a few of the Portable Calibre packages; each into their own directory.

That way you can easily test your plugin against any version of calibre, each with their own independent configuration and eBook library. Sure you can only run one instance at a time but that's a minor issue. Be sure to launch portable ones from their own launcher (I forget if the installer makes a batch file for you. Don't launch them via the standard execution of calibre.exe).

No need for 'launchers' on Windows, just run the calibre-portable.exe from wherever you parked it. This is what I have:



The Miller columns come from a recently discovered utility that plugs into the Windows File Explorer context menu (very handy) ==>> GitHub: ChromaFiler - Column-based file manager for Windows

BR

[PeterT]

I couldn't remember the name to launch it and I was not at home...

[BetterRed]

Originally Posted by taurins

...

The only downside is that this does rely on part of Calibre's internal Edit Metadata interface, so if that changes in a future Calibre release I may have to adjust the plugin.

The Edit Metadata feature is very stable, Kovid doesn't make changes based on what's in this month's Vogue or on the latest glitz from Cuperutino.

I suspect the ability to add plugins to the Edit metadata individually dialogue is a consequence of adding the Data Files button to that dialogue… Manage Data Files is a factory fitted plugin.

BR