Add Functionality to API

[jcjgraf]

While working with the api for some plugins I noticed some missing functionality:

• api.mark: Additionally, it should expose:

  • api.mark.is_marked(name: str) to check if a image is marked. Currently this required accessing the private api.mark._marked list.
  • api.mark.mark2(name: str) which marks the image no matter is it is already marked or not. Currently this required checking if the image is already marked and use api.mark.mark only when it is not.
  • api.mark.unmark(name: str) which unmarks the image no matter if it is marked or not. This and the previous functionality could also be added to api.mark.mark using certain flags.
  • Since when marking multiple images, the api.mark._markdone signal has to be emitted manually it may be a good idea to provide the above mentioned functionality also for a list of paths. Currently one has to add/remove all images to/from api.mark._marked and then manually emit the signal.

• imutils.exif.ExifHandler: We should add something like api.get_exifhander(path: str) -> ExifHandler which returns the exif handler for a certain path. Currently this is done using imutils.exif.ExifHandler(path).

Besides that, one has to use utils.log.module_logger to get a logger, and to access the vimiv colors one has to use config.styles. For the status bar module I have also come across using utils.wrap_style_span.

I am not sure where we have to draw the line between what to expose to the API and what is acceptable to access directly. 😊 I think my first two points would be acceptable to add. But let me know what you think.

[karlch]

I fully agree with your first two points. The exif handler function should be very straightforward as you point out. The different utility methods in mark may need some thinking and possibly refactoring so they all have useful and intuitive names.

Everything in utils is certainly borderline. It does not really make sense to expose the little functions like wrap_style_span via a dedicated api, but of course they can be useful for plugins as well. I guess "use at own risk" should be fine for those, the chances of them being changed in a backwards-incompatible way is rather small anyway.

Getting a logger directly from utils should be safe, I don't see that infrastructure changing (anytime soon). Do you think it makes sense to have a dedicated api.utils which imports parts which are considered safe from utils or is documentation enough?

I would not expose the styles in their current state as I am not 100 % happy with the string-based usage all over the place, so there are quite some chances that this could change at some point 😆

[jcjgraf]

I do not really have a strong opinion about the utils. I rather wanted to get your view concerning access to non-api functionality from plugins. I am fine with whatever you think is right.

Do you want me to make a proposition for the first two point in a PR or do you want to look into it yourself?

[karlch]

If you don't mind, I would take a further look at this over the week-end. I feel like some mistakes were made in the mark module, e.g. mark should probably have been called mark-toggle. We could then also have mark and unmark in a straightforward manner. These could even all be commands, but this would be a breaking change both in the api and in the command name...