Some API changes in the current release (0.8.8) and the next one

[chaley]

API changes in 0.8.8

• The API for gui2.tag_browser changed in 0.8.8. The file gui2.tag_browser.py no longer exists, having been split into 4 files found in gui2.tag_browser.*.py. Functions like searching and boxing tag items are in ui.py. Other functions have moved around to model.py or view.py.
• The API for starting EditAuthorsDialog changed in 0.8.8. It requires an additional argument "select_link", which if true will cause the new author_link column to be selected for the id also passed in. This new argument has been added to gui2.tag_browser.ui.do_author_sort_edit(), defaulting to false.

Not API changes but worth noting:

• the authors table now contains a column for storing a URL associated with that author. This link is set/modified using Manage Authors. The URL is used in book details. If an author has no URL, then the URL template set in preferences -> book details is used. A new template function, swap_around_comma(), has been provided to facilitate turning LN, FN names into FN LN for use in this (and other) templates. This function would be used when the library is LN, FN but the resulting URL must use FN LN order. Swap_around_comma is a convenience function, equivalent to calling re('^(.*?),(.*$)', '\2 \1').
• Composite columns now have a "show as HTML in book details" check box. The intent is to indicate that the composite column should be rendered as HTML in situations where it is appropriate, such as book details or in the content server.

API change in 0.8.9:

• database2.format_metadata() now caches during a given calibre session the data returned by os.stat(). If a format is changed outside of calibre, then the cache will be incorrect, containing stale data. For example, calibre won't know the file has changed if you use open_with and sigil to change it, so format_metadata can return stale data.
  
  The cache is not persistent. It is rebuilt every time calibre starts, which limits the lifetime of the stale data. Also, you can force format_metadata() to refresh the cache for a book by using a new additional argument "allow_cache".
  
• New template functions: The metadata for formats will be available in templates via two new template functions, formats_modtimes() and formats_sizes(). You can use these to create composite columns showing the information, or in coloring rules, or what-have-you. In addition, two template functions are provided for formatting numeric information: human_readable() and format_number(). Finally, a new function has_cover() returns whether or not a book has a cover associated with it.

[jackie_w]

Re: the API change in 0.8.9,

I hope this is not too dumb a question... I use various utilities in the 'Open With' plugin to tweak an epub's non-metadata items, e.g. toc.ncx, .xpgt, .css, <manifest> section of opf. Will I still be OK to continue as now?

[chaley]

The cached modification time and size will not be updated unless you call format_metadata with 'allow_cache=False'. Open_with can't do this because the plugin doesn't know when the user has finished. If you do, then fine. If you don't or if you do nothng, then the worst that will happen is that the cached values are wrong until the next time calibre is restarted.

Do remember, though, that when the new DB implementation hits (https://www.mobileread.com/forums/sho...d.php?t=140056), it is possible that there won't be any formats stored locally. Either your plugin(s) will stop working, or you must use the API to get a copy, let the user do whatever, then put it back.

[jackie_w]

Originally Posted by chaley

Do remember, though, that when the new DB implementation hits, it is possible that there won't be any formats stored locally. Either your plugin(s) will stop working, or you must use the API to get a copy, let the user do whatever, then put it back.

If the formats aren't local, where will they be?

Currently, I don't necessarily need Calibre to make my utilities work ('Open With' is a convenience) but I do need a physical epub to edit.

Edit: I should add, these are personal utilities not released to the Calibre community.

[chaley]

Flying with the seagulls in the clouds.

One major goal of Kovid's work (perhaps *the* major goal) is to permit calibre's database not to be on a disc on the LAN. If he is successful (and it appears he will be), then there is no guarantee that *any* files in the library are available locally. No cover, no formats, no folders for authors/tities, no metadata.db, etc.

Of course, most people will have their library on local storage. Problem is that you can't count on that.

[jackie_w]

Originally Posted by chaley

Of course, most people will have their library on local storage. Problem is that you can't count on that.

But for personal needs I can count on local storage for as long as I want it, yes?

[chaley]

Originally Posted by jackie_w

But for personal needs I can count on local storage for as long as I want it, yes?

Yes. There is no way that Kovid would make it impossible to store a library on a local disk.

[kovidgoyal]

Originally Posted by chaley

Yes. There is no way that Kovid would make it impossible to store a library on a local disk.

Absolutely, a networked backend (I am not yet reconciled to the term cloud) will be an additional feature, not a replacement.

In fact the development will proceed in two stages. The first will be to write a much better designed (and faster) replacement for the current calibre database backend, that will be a drop in replacement (i.e. calibre should continue to work exactly as it does now, only faster). This new backend will be modularised in a way that will hopefully make it easy to add support for networked storage.

[Dopedangel]

Are these changes going to allow multiple instances of calibre using the database at the same time.

[kovidgoyal]

yes .

[Starson17]

Originally Posted by kovidgoyal

yes .

Am I correct in thinking we'll also get (or be able to add) the option to change metadata from the content server interface? Perhaps also even permit running a format conversion from the CS? (I hate it when I'm remote, connected to the CS and realize I need another format, then have to log in with VNC to run Calibre, then return to the CS to get the newly converted book.)

[kovidgoyal]

Eventually, yes.

[Starson17]

Originally Posted by kovidgoyal

Eventually, yes.

I understand why the "Eventually" is there.

Still, it's nice to know it's on the roadmap.