API for plugins to create custom columns

[chaley]

Working with @davidfor, I added an API that plugin writers can use to create custom columns for the plugin's use. See the class CreateNewCustomColumn in calibre.gui2.preferences.create_custom_column. It is documented there.

The class is in calibre source now.

Notes:

• The custom column(s) are actually created the next time calibre starts. The column(s) don't exist until then. The plugin configurator must deal with that in some way.
• You can create columns only once per calibre instance. Further attempts to create columns or run calibre preferences will fail until calibre is restarted. If you use calibre preferences to create/edit/delete a column then this API will refuse to create new columns until calibre is restarted.
• This API doesn't support editing an existing custom column. Use calibre preferences to do that.

EDIT: I have improved the documentation for the class and methods to make it clearer that more than one column can be created, and to better explain the parameters. I will submit it to Kovid if/when I have more feedback.

The documentation as of 2/Jan/21 is:

Spoiler:

    Provide an API to create new custom columns.

    Usage:
        from calibre.gui2.preferences.create_custom_column import CreateNewCustomColumn
        creator = CreateNewCustomColumn(gui)
        if creator.must_restart():
                ...
        else:
            result = creator.create_column(....)
            if result[0] == creator.Result.COLUMN_ADDED:

    The parameter 'gui' passed when creating a class instance is the main
    calibre gui (calibre.gui2.ui.get_gui())

    Use the create_column(...) method to open a dialog to create a new custom
    column with given lookup_name, column_heading, datatype, and is_multiple.
    You can create as many columns as you wish with a single instance of the
    CreateNewCustomColumn class. Subsequent class instances will refuse to
    create columns until calibre is restarted, as will calibre Preferences.

    The lookup name must begin with a '#'. All remaining characters must be
    lower case letters, digits or underscores. The character after the '#' must
    be a letter. The lookup name must not end with the suffix '_index'.

    The datatype must be one of calibre's custom column types: 'bool',
    'comments', 'composite', 'datetime', 'enumeration', 'float', 'int',
    'rating', 'series', or 'text'. The datatype can't be changed in the dialog.

    is_multiple tells calibre that the column contains multiple values -- is
    tags-like. The value True is allowed only for 'composite' and 'text' types.

    If generate_unused_lookup_name is False then the provided lookup_name and
    column_heading must not already exist. If generate_unused_lookup_name is
    True then if necessary the method will add the suffix '_n' to the provided
    lookup_name to allocate an unused lookup_name, where 'n' is an integer.
    The same processing is applied to column_heading to make it is unique, using
    the same suffix used for the lookup name if possible. In either case the
    user can change the column heading in the dialog.

    Set freeze_lookup_name to False if you want to allow the user choose a
    different lookup name. The user will not be allowed to choose the lookup
    name of an existing column. The provided lookup_name and column_heading
    either must not exist or generate_unused_lookup_name must be True,
    regardless of the value of freeze_lookup_name.

    The 'display' parameter is used to pass item- and type-specific information
    for the column. It is a dict. The easiest way to see the current values for
    'display' for a particular column is to create a column like you want then
    look for the lookup name in the file metadata_db_prefs_backup.json. You must
    restart calibre twice after creating a new column before its information
    will appear in that file.

    The key:value pairs for each type are as follows. Note that this
    list might be incorrect. As said above, the best way to get current values
    is to create a similar column and look at the values in 'display'.
      all types:
        'default_value': a string representation of the default value for the
                         column. Permitted values are type specific
        'description': a string containing the column's description
      comments columns:
        'heading_position': a string specifying where a comment heading goes:
                            hide, above, side
        'interpret_as': a string specifying the comment's purpose:
                        html, short-text, long-text, markdown
      composite columns:
        'composite_template': a string containing the template for the composite column
        'composite_sort': a string specifying how the composite is to be sorted
        'make_category': True or False -- whether the column is shown in the tag browser
        'contains_html': True or False -- whether the column is interpreted as HTML
        'use_decorations': True or False -- should check marks be displayed
      datetime columns:
        'date_format': a string specifying the display format
      enumerated columns
        'enum_values': a string containing comma-separated valid values for an enumeration
        'enum_colors': a string containing comma-separated colors for an enumeration
        'use_decorations': True or False -- should check marks be displayed
      float and int columns:
        'number_format': the format to apply for the column
      rating columns:
        'allow_half_stars': True or False -- are half-stars allowed
      text columns:
        'is_names': True or False -- whether the items are comma or ampersand separated
        'use_decorations': True or False -- should check marks be displayed

    This method returns a tuple (Result.enum_value, message). If tuple[0] is
    Result.COLUMN_ADDED then the message is the lookup name including the '#'.
    Otherwise it is a potentially localized error message.

    You or the user must restart calibre for the column(s) to be actually added.

    Result.EXCEPTION_RAISED is returned if the create dialog raises an exception.
    This can happen if the display contains illegal values, for example a string
    where a boolean is required. The string is the exception text. Run calibre
    in debug mode to see the entire traceback.

    The method returns Result.MUST_RESTART if further calibre configuration has
    been blocked. You can check for this situation in advance by calling
    must_restart().

[thiago.eec]

Hi, Chaley.

I have two questions:

1) What is the is_multiple argument used for? I could not understand this parameter.

2) When using calibre preferences, I can create multiple columns before restarting. Can't that be replicated with the API? I plan to use this on my Skoob Sync plugin, but the user must configure seven columns, hence seven restarts.

P.S.: Just noticed you said "create columns". Maybe I misunderstood your point on my second question. Can I create multiple columns at once? Maybe this is the reason for the is_multiple argument?

[chaley]

Originally Posted by thiago.eec

Hi, Chaley.

I have two questions:

1) What is the is_multiple argument used for? I could not understand this parameter.

The is_multiple parameter tells calibre if text or composite columns hold a single value or are comma-separated (tags-like) columns. If is_multiple is True then the 'is_names' boolean in the display tells calibre if a text column is ampersand-separated instead of comma-separated (contains names ).

2) When using calibre preferences, I can create multiple columns before restarting. Can't that be replicated with the API? I plan to use this on my Skoob Sync plugin, but the user must configure seven columns, hence seven restarts.

You can create as many columns as you want with a single instance of the class, as like this:

    creator = CreateNewCustomColumn(gui)
    result1 = creator.create('#col1', ...)
    --- check result1 for correctness ---
    result2 = creator.create('#col2', ...)
    --- check result2 for correctness ---

Any instance created after one is used to create columns and before calibre is restarted will refuse to create columns.

This system is similar to what you see with calibre preferences. You can create etc as many columns as you wish using one dialog, but you can't do it again until you restart.

[chaley]

I have 'improved' the documentation for the class and methods to make it clearer that more than one column can be created, and to better explain the parameters. I will submit it to Kovid if/when I have more feedback.

EDIT: The documentation is now in the first post.

[davidfor]

As @chaley said, I was testing his code and making changes. It is working well and I nearly have all the changes ready in the Kobo Utilities plugin.

@chaley: One thing we missed was duplicate column headings. When using "generate_unused_lookup_name=True", the supplied column heading is probably not unique. Appending the same number to the column heading is probably good enough for this.

[chaley]

Originally Posted by davidfor

@chaley: One thing we missed was duplicate column headings. When using "generate_unused_lookup_name=True", the supplied column heading is probably not unique. Appending the same number to the column heading is probably good enough for this.

OK, will do.

And done.
I also added a method to return the column headings as a dict {heading:lookup_name}

[dunhill]

Geniuses !! excellent work of both as always, I take off my hat

[davidfor]

Originally Posted by chaley

OK, will do.

And it works.

And done.
I also added a method to return the column headings as a dict {heading:lookup_name}

That's a good idea.

[thiago.eec]

Hi, @chaley and @davidfor.

Thank both of you, @chaley and @davidfor, for your efforts. This is really great. Got it working here for Skoob Sync after looking at implemented version by @davidfor.