Auto registration of new custom columns from plugin code [question/feature request]]

[Sud0]

Is it posiible to write a Calibre plugin that would automatically ask Calibre to create some new custom columns?

For example: i have some download metadata plugin "A". This plugin has a configuration option: Fetch number of ratings: true/false. If user enables this option i would like plugin "A" to automatically ask Calibre to create/register new custom column "number_of_ratings" if it does not exist already

[kovidgoyal]

You can use the calibre database APIs to create custom columns in your plugin. But note that the new column will not be useable until calibre is restarted.

[BetterRed]

Moderator Notice
Moved to Development

BR

[chaley]

See CreateNewCustomColumn in calibre.gui2.preferences.create_custom_column.py

Spoiler:

class CreateNewCustomColumn:
    """
    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 columns:
        'decimals': the number of decimal digits to allow when editing (int). Range: 1 - 9
      float and int columns:
        'number_format': the format to apply when displaying 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().

[Sud0]

@chaley thanks, it's very helpful!

@kovidgoyal my humble suggestion is to add such a simple and more obvious mechanism to the official plugin API as part of "class calibre.customize.Plugin" for example as some property: custom_columns: list[Dict]. If defined then Calibre would auto create such columns during plugin installation/upgrade and do autorestart