INCATools / INCATools/ontology-access-kit
Document if and when to write plugins, and what the alternatives are
- Dominant language
- Python
- Stars
- 198
- Forks
- 35
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 1
Description
Currently we have docs on how to write plugins:
https://incatools.github.io/ontology-access-kit/howtos/write-a-plugin.html
From the docs:
---
A plugin is a software component that adds a specific feature to an existing computer program. When a program supports plug-ins, it enables customization ([Wikipedia](https://en.wikipedia.org/wiki/Plug-in_(computing))).
In the context of OAK, plugins allow you to add optional functionality to OAK.
An example of a plugin would be a code that uses a machine learning library such as Spacy or NLTK to provide an implementation of a text_annotator. We wouldn’t want to include this in the main library due to the additional dependencies required. But we might want to allow people to drop in this functionality, e.g.
```
runoak -i my_awesome_plugin: annotate "my text here"
```
---
We have plans to do exactly that, to use scispacy for annotation via OntoRunner. I think introducing a dependency on scispacy would be a bad idea - it is a heavyweight dependency, it could reduce portability. And just in general, the more dependencies we have the larger the surface area for things going wrong.
We also have a plugin for robot: https://github.com/INCATools/oakx-robot
Perhaps this one could be brought into the core - it doesn't actually bring robot in as a dependency per se, only py4j.
An alternative to plugins is a dynamic import statement, as in this PR:
https://github.com/INCATools/ontology-access-kit/pull/159
I am not a big fan of this:
- it hides the true dependency structure, bypassing the declarative transparent system we have in place
- it is harder to test (we can use mocking, but this is more work, and misses some classes of error)
- it is more work for the user - and makes behavior less deterministic between installations
In that PR @cthoyt states:
_I really want to stress that plug-ins should only be used by external people who want to extend the package but not in an open source way - eg the million different repo approach isn’t sustainable (I learned the hard way in bio2bel)_
I am not sure I follow this. I would certainly prefer that people contribute back open code, but everyone is free to either extend OAK, to adapt it, or make plugins in whichever way they please, open or not. And I think we can actively work to encourage the right people for key plugins.
My proposed guidelines would be:
1. if it doesn't introduce too heavyweight dependencies, include it right in this repo, no need for plugins
2. if it is a library or application that reuses oak, then just reuse it in the standard way
3. if it introduces complicated dependencies, and the functionality is optional, or provides some kind of slight gain (e.g. improved NER/CR via ML, enhanced semantic similarity via an R bridge) then that is a good candidate for a plugin
4. avoid dynamic imports, except as part of the plugin system itself
This still leaves things open. Would pandas be considered heavyweight? Probably not. What about scikit-learn? On the fence.
Contributor guide
Research direction
Start with howtos/write-a-plugin.html, then review PR #159 and the oakx-robot plugin context. Resolve the plugin-versus-core and dynamic-import guidance, including dependency-weight examples, and update the plugin documentation with agreed criteria and alternatives.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100