rahix/openflexure-microscope-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Added link to packaging

Browse source
This commit is contained in:
Joel Collins 2019-01-07 17:07:28 +00:00
parent eb181fcaa5
commit af76442149
1 changed files with 3 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/source/plugins.rst
View file

@ -15,15 +15,15 @@ Here, ``<microscope_object>`` is an instance of :py:class:`openflexure_microscop
Plugins can either be loaded as a single Python file located anywhere on disk, or as a Python package installed to the environment being used. If loaded from a single file, the namespace is set to the file name (excluding .py extension) of the plugin file. If loaded from a package, the namespace is set to the name of the top-level module in the package. For example, if your plugin class definition resides within ``my_openflexure_plugins.microscope.mypluginpackage``, the namespace will be set to ``mypluginpackage``. Where possible, try to use descriptive, unique package names for this reason. For example, rather than name your plugin package ``autofocus``, which would like cause namespace clashes, instead name it ``yourname_autofocus``, or similar.
Single-file plugins
+++++++++++++++++++
Module (single-file) plugins
++++++++++++++++++++++++++++
For adding simple functionality, such as a few basic functions and API routes, a single Python file can be loaded as a plugin.
This Python file must contain all of your plugin classes. Relative imports will not work. External modules and packages can be used with absolute imports, however for more complex plugins, it is often worth instead making use of an installable package plugin.
Package plugins
+++++++++++++++
Generally, for adding anything other than very simple functionality, plugins should be written as installable Python packages. This has the advantage of allowing relative imports, so functionality can be easily split over several files. For example, class definitions associated with API routes can be separated from class definitions associated with the microscope plugin.
Generally, for adding anything other than very simple functionality, plugins should be written as `package distributions <https://packaging.python.org/tutorials/packaging-projects/>`_. This has the advantage of allowing relative imports, so functionality can be easily split over several files. For example, class definitions associated with API routes can be separated from class definitions associated with the microscope plugin.
The main restriction is that the plugin package must be importable using an absolute import from within the Python environment being used to load your microscope.