Bulk saving for metadata and exposing documentation API

[zikolach]

Allow to update multiple metadata categories at once.

Important: based on PR iiasa/ixmp_source#290

PR checklist

• Tests added.
• Documentation added.
• Release notes updated.

[codecov]

Codecov Report

Merging #314 into master will decrease coverage by 0.04%.
The diff coverage is 98.83%.

@@            Coverage Diff             @@
##           master     #314      +/-   ##
==========================================
- Coverage   97.62%   97.57%   -0.05%     
==========================================
  Files          42       42              
  Lines        4377     4454      +77     
==========================================
+ Hits         4273     4346      +73     
- Misses        104      108       +4     

Impacted Files	Coverage Δ
ixmp/backend/jdbc.py	94.66% <97.29%> (-0.51%)	⬇️
ixmp/backend/base.py	98.69% <100.00%> (+0.05%)	⬆️
ixmp/core.py	95.67% <100.00%> (+0.04%)	⬆️
ixmp/tests/backend/test_base.py	98.36% <100.00%> (+0.08%)	⬆️
ixmp/tests/backend/test_jdbc.py	100.00% <100.00%> (ø)
ixmp/tests/core/test_scenario.py	100.00% <100.00%> (ø)
ixmp/backend/io.py	98.56% <0.00%> (+0.01%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update febde8a...0a873c0. Read the comment docs.

[khaeru]

@zikolach thanks for these additions. As a first set of requested changes:

• Documentation of the Backend API goes on the abstract methods in base.Backend. The implementations of these methods on jdbc.JDBCBackend generally have no docstring, unless they have significant differences in behaviour from the general API which need explanation. See the existing code.
• Please update doc/source/api-backend.rst to refer to the new methods.

[khaeru]

Check wrapping.

[zikolach]

Not sure what you mean as wrapping

[zikolach]

@khaeru thanks for comments! Please have a look at 6c37514 - it should be fixed there

[danielhuppmann]

a few minor comments on how to name arguments and on docstrings...

[danielhuppmann]

I'm confused, is there now a top-level function to get or set docstrings?

[zikolach]

Yes, methods of backend class which are included into _backend_direct are exposed directly as methods of Platform

[danielhuppmann]

Ok, thanks for the clarification - how is this rendered in the docs? Is there an example where I can see this already?

[zikolach]

Good question! I think it is not available on Platform class documentation.

@khaeru what do you think, can we adjust __doc__ attribute to incorporate those backend methods documentation into Platform docs?

[danielhuppmann]

thanks @zikolach, looks great! I think it's fine to merge this and tackle the question how backend-functions will be displayed in the docs in a subsequent PR.

[zikolach]

* Documentation of the Backend API goes on the abstract methods in `base.Backend`. The implementations of these methods on `jdbc.JDBCBackend` generally have no docstring, unless they have significant differences in behaviour from the general API which need explanation. See the existing code.

* Please update `doc/source/api-backend.rst` to refer to the new methods.

@khaeru thanks for suggestions. I moved docstrings to backend base class and added new methods to api-backend.rst.

[danielhuppmann]

I moved docstrings to backend base class and added new methods to api-backend.rst.

Does this mean these functions will not be included in the Platform docs? If that's the case, I don't think that this is a good strategy...

[zikolach]

Does this mean these functions will not be included in the Platform docs

It depends on what you mean as Platform docs. These methods docstrings are added to Backend documentation, not to Platform class documentation.

[danielhuppmann]

This reference to the new functions is not understandable to anyone who was not part of this discussion.

The methods ~.base.Backend.open_db, ~.base.Backend.close_db, ~.base.Backend.get_doc, and ~.base.Backend.set_doc may also be called via Platform.

It's not obvious how to call these functions - Platform.base.Backend.open_db?

[khaeru]

This reference to the new functions is not understandable […]

The methods ~.base.Backend.open_db, ~.base.Backend.close_db, ~.base.Backend.get_doc, and ~.base.Backend.set_doc may also be called via Platform.

See the Sphinx docs:

If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:'~Queue.Queue.get' will refer to Queue.Queue.get but only display get as the link text.

Sphinx renders the sentence as "The methods open_db(), close_db(), …" with links.

If that doesn't suit a particular use case/target user/story, other alternatives are:

• Use the Sphinx .. py:function:: directive to put the user-facing documentation in api-python.rst.
• Don't use _backend_direct (originally introduced as a convenience when developing the Backend API), and write short (possibly one-line) methods. See for example add_unit/units, set_log_level/get_log_level. In this case, observe separation of concerns as described in the docs; e.g. just as set_log_level raises ValueError for invalid input, set_doc should raise ValueError for an invalid domain.