Document public API #438
Document public API #438
Conversation
|
@SKernchen Please review changes and approve as you see fit. |
SKernchen
left a comment
SKernchen
left a comment
There was a problem hiding this comment.
I really like the improvements. My suggestion is showing a more complex example. If we keep the short version, we should mention that "bar" is the expected name.
|
|
||
| ```{code-block} python | ||
| :caption: Value check and list comprehension | ||
| if ["bar" in email for email in data["author"][1]["email"]]: |
There was a problem hiding this comment.
| if ["bar" in email for email in data["author"][1]["email"]]: | |
| if [data["author"][1]["name"][0].lower() in email for email in data["author"][1]["email"]]: |
There was a problem hiding this comment.
A more general solution could be:
author = data["author"][0]
if all(any(name in email for name in author["name"]) for email in author["email"]):
|
|
||
| #### Model instances in different types of plugin | ||
|
|
||
| You can extend `hermes` with plugins for three different commands: `harvest`, `curate`, `deposit`. |
There was a problem hiding this comment.
So "process plugins" and "post-process plugins" won't exist any more? This should (also) be mentioned in some architectural doc rather than in a side note here. As far as I can tell it is not mentioned anywhere else yet.
There was a problem hiding this comment.
Made an issue for that #447 . In the parent issue it is also described.
| ```{code-block} python | ||
| :caption: Injecting additional schemas | ||
| from hermes.model import SoftwareMetadata | ||
| # Contents served at https://bar.net/schema.jsonld: | ||
| # { | ||
| # "@context": | ||
| # { | ||
| # "baz": "https://schema.org/Thing" | ||
| # } | ||
| # } | ||
| data = SoftwareMetadata(extra_vocabs={"foo": "https://bar.net/schema.jsonld"}) | ||
| data["foo:baz"] = ... |
There was a problem hiding this comment.
This is a bit of a strange example because you're using a type as a predicate. You could use something like https://schema.org/name (/alternateName/description/image/...) instead.
| data["name"] = "My Research Software" # A simple "Text"-type value | ||
| # → Simplified model representation : { "name": [ "My Research Software" ] } | ||
| # Cf. "Accessing data" below | ||
| data["author"] = {"name": "Foo"} # An object value that uses terms available in the defined context |
There was a problem hiding this comment.
All the foos, bars, and bazes can be quite confusing as it is never obvious what they are referring to. Could we use some more meaningful examples? "author" is a real codemeta field, so why not use a "real" author? Like Josiah Carberry, or Donald E. Knuth, or Margaret Hamilton.
| for i, author in enumerate(data["author"]): | ||
| if author["name"][0] in ["Foo", "Bar"]: | ||
| print(f"Author {i + 1} has expected name.") |
There was a problem hiding this comment.
You can use enumerate(..., start=1) instead of i + 1
|
|
||
| ```{code-block} python | ||
| :caption: Value check and list comprehension | ||
| if ["bar" in email for email in data["author"][1]["email"]]: |
There was a problem hiding this comment.
| if ["bar" in email for email in data["author"][1]["email"]]: | |
| if all(["bar" in email for email in data["author"][1]["email"]]): |
I think this is what you meant
There was a problem hiding this comment.
Yes, that is true. This line is also discussed in this comment.
|
|
||
| The complex data structure of JSON-LD is internally constructed in the `hermes` data | ||
| model, and to make it possible to work with only the data that is important - the actual terms | ||
| and their values - the internal data model types provide a function `.to_python()`. |
There was a problem hiding this comment.
It's all Python though 👀 Would .to_dict() be a better name?
There was a problem hiding this comment.
I think .to_native() or .to_native_python() would be even better, since ld_dict is also a dict and this function also exists for ld_list.
But all suggestions do not mention that the structure is simplified in the process (similar, but not synonymous with compacting the expanded JSON-LD value).
|
Thanks for all of your comments. I'll address them after my holidays. |
This PR adds explanatory documentation of the public API.
It complements #432