From d447308ef0bd3e32f9ea021113f9c011b3070d1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Fri, 6 Mar 2015 01:42:49 +0100 Subject: [PATCH] Even more documentation of the internal modules --- docs/conf.py | 2 +- docs/development/index.rst | 6 +- docs/development/interface/printer.rst | 8 -- docs/index.rst | 2 +- .../interface => modules}/filemanager.rst | 11 +- .../interface => modules}/index.rst | 8 +- .../interface => modules}/plugin.rst | 7 +- docs/modules/printer.rst | 6 + docs/modules/settings.rst | 6 + .../interface => modules}/util.rst | 2 +- docs/plugins/index.rst | 2 - docs/plugins/mixins.rst | 2 +- src/octoprint/plugin/__init__.py | 107 +++++++++++++++--- src/octoprint/plugin/types.py | 28 ++++- src/octoprint/printer/__init__.py | 3 + src/octoprint/util/__init__.py | 8 +- 16 files changed, 158 insertions(+), 50 deletions(-) delete mode 100644 docs/development/interface/printer.rst rename docs/{development/interface => modules}/filemanager.rst (66%) rename docs/{development/interface => modules}/index.rst (52%) rename docs/{development/interface => modules}/plugin.rst (74%) create mode 100644 docs/modules/printer.rst create mode 100644 docs/modules/settings.rst rename docs/{development/interface => modules}/util.rst (68%) diff --git a/docs/conf.py b/docs/conf.py index 9a5f232c..7ff34180 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,7 @@ year_current = date.today().year # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.todo', 'sphinx.ext.autodoc', 'sphinxcontrib.httpdomain', 'sphinx.ext.autosummary', 'sphinxcontrib.napoleon'] +extensions = ['sphinx.ext.todo', 'sphinx.ext.autodoc', 'sphinxcontrib.httpdomain', 'sphinxcontrib.napoleon'] todo_include_todos = True # Add any paths that contain templates here, relative to this directory. diff --git a/docs/development/index.rst b/docs/development/index.rst index 9edfcb67..e3381a4e 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -4,7 +4,7 @@ Development ########### -.. toctree:: - :maxdepth: 3 +.. todo:: - interface/index.rst \ No newline at end of file + This is where notes regarding developing OctoPrint will be placed, such as workflow for setting up the + development environment, code guidelines etc. \ No newline at end of file diff --git a/docs/development/interface/printer.rst b/docs/development/interface/printer.rst deleted file mode 100644 index 79559cd6..00000000 --- a/docs/development/interface/printer.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _sec-development-interface-printer: - -octoprint.printer ------------------ - -.. automodule:: octoprint.printer - :members: Printer - :undoc-members: diff --git a/docs/index.rst b/docs/index.rst index 5243f634..7acbf1f5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,5 +19,5 @@ Contents api/index.rst events/index.rst plugins/index.rst - development/index.rst + modules/index.rst diff --git a/docs/development/interface/filemanager.rst b/docs/modules/filemanager.rst similarity index 66% rename from docs/development/interface/filemanager.rst rename to docs/modules/filemanager.rst index 28a0af7b..aaa7beeb 100644 --- a/docs/development/interface/filemanager.rst +++ b/docs/modules/filemanager.rst @@ -1,31 +1,28 @@ -.. _sec-development-interface-filemanager: +.. _sec-modules-filemanager: octoprint.filemanager --------------------- .. automodule:: octoprint.filemanager :members: - :undoc-members: -.. _sec-development-interface-filemanager-analysis: +.. _sec-modules-filemanager-analysis: octoprint.filemanager.analysis ------------------------------ .. automodule:: octoprint.filemanager.analysis :members: - :undoc-members: -.. _sec-development-interface-filemanager-destinations: +.. _sec-modules-filemanager-destinations: octoprint.filemanager.destinations ---------------------------------- .. automodule:: octoprint.filemanager.destinations :members: - :undoc-members: -.. _sec-development-interface-filemanager-storage: +.. _sec-modules-filemanager-storage: octoprint.filemanager.storage ----------------------------- diff --git a/docs/development/interface/index.rst b/docs/modules/index.rst similarity index 52% rename from docs/development/interface/index.rst rename to docs/modules/index.rst index 5b4c28fc..e9ef4825 100644 --- a/docs/development/interface/index.rst +++ b/docs/modules/index.rst @@ -1,7 +1,8 @@ -.. _sec-development-interface: +.. _sec-modules: -Internal API -============ +################ +Internal Modules +################ .. toctree:: :maxdepth: 3 @@ -9,4 +10,5 @@ Internal API filemanager.rst plugin.rst printer.rst + settings.rst util.rst diff --git a/docs/development/interface/plugin.rst b/docs/modules/plugin.rst similarity index 74% rename from docs/development/interface/plugin.rst rename to docs/modules/plugin.rst index e1dc2c03..d464b5c3 100644 --- a/docs/development/interface/plugin.rst +++ b/docs/modules/plugin.rst @@ -1,19 +1,20 @@ -.. _sec-development-interface-plugin: +.. _sec-modules-plugin: octoprint.plugin ---------------- .. automodule:: octoprint.plugin -.. _sec-development-interface-plugin-core: +.. _sec-modules-plugin-core: octoprint.plugin.core --------------------- .. automodule:: octoprint.plugin.core +.. _sec-modules-plugin-types: + octoprint.plugin.types ---------------------- .. automodule:: octoprint.plugin.types - diff --git a/docs/modules/printer.rst b/docs/modules/printer.rst new file mode 100644 index 00000000..ce752f43 --- /dev/null +++ b/docs/modules/printer.rst @@ -0,0 +1,6 @@ +.. _sec-modules-printer: + +octoprint.printer +----------------- + +.. automodule:: octoprint.printer diff --git a/docs/modules/settings.rst b/docs/modules/settings.rst new file mode 100644 index 00000000..80248cbb --- /dev/null +++ b/docs/modules/settings.rst @@ -0,0 +1,6 @@ +.. _sec-modules-settings: + +octoprint.settings +------------------ + +.. automodule:: octoprint.settings diff --git a/docs/development/interface/util.rst b/docs/modules/util.rst similarity index 68% rename from docs/development/interface/util.rst rename to docs/modules/util.rst index f855ae25..32a61b72 100644 --- a/docs/development/interface/util.rst +++ b/docs/modules/util.rst @@ -1,4 +1,4 @@ -.. _sec-development-interface-util: +.. _sec-modules-util: octoprint.util -------------- diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index b362f118..c043aaf6 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -1,5 +1,3 @@ -.. automodule:: octoprint.plugin.types - .. _sec-plugins: ####### diff --git a/docs/plugins/mixins.rst b/docs/plugins/mixins.rst index a37e9775..c414934d 100644 --- a/docs/plugins/mixins.rst +++ b/docs/plugins/mixins.rst @@ -9,7 +9,7 @@ The following plugin mixins are currently available: :local: Please note that all plugin mixins inherit from :class:`~octoprint.plugin.core.Plugin` and -:class:`~octoprint.plugin.OctoPrintPlugin`, which also provide attributes of interest to plugin developers. +:class:`~octoprint.plugin.types.OctoPrintPlugin`, which also provide attributes of interest to plugin developers. .. _sec-plugins-mixins-startupplugin: diff --git a/src/octoprint/plugin/__init__.py b/src/octoprint/plugin/__init__.py index 377e6229..9dde8c9b 100644 --- a/src/octoprint/plugin/__init__.py +++ b/src/octoprint/plugin/__init__.py @@ -11,7 +11,6 @@ registered plugin types. .. autoclass:: PluginSettings :members: - """ from __future__ import absolute_import @@ -63,11 +62,12 @@ def plugin_manager(init=False, plugin_folders=None, plugin_types=None, plugin_en """ global _instance - if _instance is None: + if _instance is not None: if init: - if _instance is not None: - raise ValueError("Plugin Manager already initialized") + raise ValueError("Plugin Manager already initialized") + else: + if init: if plugin_folders is None: plugin_folders = (settings().getBaseFolder("plugins"), os.path.abspath(os.path.join(os.path.dirname(os.path.realpath(__file__)), "..", "plugins"))) if plugin_types is None: @@ -178,40 +178,63 @@ class PluginSettings(object): It provides a couple of convenience methods for directly accessing plugin settings via the regular :class:`octoprint.settings.Settings` interfaces as well as means to access plugin specific folder locations. + All getter and setter methods will ensure that plugin settings are stored in their correct location within the + settings structure by modifying the supplied paths accordingly. + + Arguments: + settings (Settings): The :class:`~octoprint.settings.Settings` instance on which to operate. + plugin_key (str): The plugin identifer of the plugin for which to create this instance. + defaults (dict): The plugin's defaults settings, will be used to determine valid paths within the plugin's + settings structure + .. method:: get(path, merged=False, asdict=False) - Retrieves a raw key from the settings for ``path``, optionally merging the raw value with the default settings + Retrieves a raw value from the settings for ``path``, optionally merging the raw value with the default settings if ``merged`` is set to True. - :param list path: a list of path elements to navigate to the settings value - :param boolean merged: whether to merge the returned result with the default settings (True) or not (False, default) - :return: the retrieved settings value + :param path: The path for which to retrieve the value. + :type path: list, tuple + :param boolean merged: Whether to merge the returned result with the default settings (True) or not (False, + default). + :returns: The retrieved settings value. + :rtype: object .. method:: get_int(path) + Like :func:`get` but tries to convert the retrieved value to ``int``. + .. method:: get_float(path) + Like :func:`get` but tries to convert the retrieved value to ``float``. + .. method:: get_boolean(path) + Like :func:`get` but tries to convert the retrieved value to ``boolean``. + .. method:: set(path, value, force=False) + Sets the raw value on the settings for ``path``. + + :param path: The path for which to retrieve the value. + :type path: list, tuple + :param object value: The value to set. + :param boolean force: If set to True, the modified configuration will even be written back to disk if + the value didn't change. + .. method:: set_int(path, value, force=False) + Like :func:`set` but ensures the value is an ``int`` through attempted conversion before setting it. + .. method:: set_float(path, value, force=False) + Like :func:`set` but ensures the value is an ``float`` through attempted conversion before setting it. + .. method:: set_boolean(path, value, force=False) + + Like :func:`set` but ensures the value is an ``boolean`` through attempted conversion before setting it. """ def __init__(self, settings, plugin_key, defaults=None): - """ - Initializes the object with the provided :class:`octoprint.settings.Settings` manager as ``settings``, using - the ``plugin_key`` and optional ``defaults``. - - :param settings: - :param plugin_key: - :param defaults: - :return: - """ self.settings = settings self.plugin_key = plugin_key @@ -253,33 +276,83 @@ class PluginSettings(object): self.deprecated_access_methods = dict(getInt="get_int", getFloat="get_float", getBoolean="get_boolean", setInt="set_int", setFloat="set_float", setBoolean="set_boolean") def global_get(self, path, **kwargs): + """ + Getter for retrieving settings not managed by the plugin itself from the core settings structure. Use this + to access global settings outside of your plugin. + + Directly forwards to :func:`octoprint.settings.Settings.get`. + """ return self.settings.get(path, **kwargs) def global_get_int(self, path, **kwargs): + """ + Like :func:`global_get` but directly forwards to :func:`octoprint.settings.Settings.getInt`. + """ return self.settings.getInt(path, **kwargs) def global_get_float(self, path, **kwargs): + """ + Like :func:`global_get` but directly forwards to :func:`octoprint.settings.Settings.getFloat`. + """ return self.settings.getFloat(path, **kwargs) def global_get_boolean(self, path, **kwargs): + """ + Like :func:`global_get` but directly orwards to :func:`octoprint.settings.Settings.getBoolean`. + """ return self.settings.getBoolean(path, **kwargs) def global_set(self, path, value, **kwargs): + """ + Setter for modifying settings not managed by the plugin itself on the core settings structure. Use this + to modify global settings outside of your plugin. + + Directly forwards to :func:`octoprint.settings.Settings.set`. + """ self.settings.set(path, value, **kwargs) def global_set_int(self, path, value, **kwargs): + """ + Like :func:`global_set` but directly forwards to :func:`octoprint.settings.Settings.setInt`. + """ self.settings.setInt(path, value, **kwargs) def global_set_float(self, path, value, **kwargs): + """ + Like :func:`global_set` but directly forwards to :func:`octoprint.settings.Settings.setFloat`. + """ self.settings.setFloat(path, value, **kwargs) def global_set_boolean(self, path, value, **kwargs): + """ + Like :func:`global_set` but directly forwards to :func:`octoprint.settings.Settings.setBoolean`. + """ self.settings.setBoolean(path, value, **kwargs) def global_get_basefolder(self, folder_type, **kwargs): + """ + Retrieves a globally defined basefolder of the given ``folder_type``. Directly forwards to + :func:`octoprint.settings.Settings.getBaseFolder`. + """ return self.settings.getBaseFolder(folder_type, **kwargs) def get_plugin_logfile_path(self, postfix=None): + """ + Retrieves the path to a logfile specifically for the plugin. If ``postfix`` is not supplied, the logfile + will be named ``plugin_.log`` and located within the configured ``logs`` folder. If a + postfix is supplied, the name will be ``plugin__.log`` at the same location. + + Plugins may use this for specific logging tasks. For example, a :class:`~octoprint.plugin.SlicingPlugin` might + want to create a log file for logging the output of the slicing engine itself if some debug flag is set. + + Arguments: + postfix (str): Postfix of the logfile for which to create the path. If set, the file name of the log file + will be ``plugin__.log``, if not it will be + ``plugin_.log``. + + Returns: + str: Absolute path to the log file, directly usable by the plugin. + """ filename = "plugin_" + self.plugin_key if postfix is not None: filename += "_" + postfix diff --git a/src/octoprint/plugin/types.py b/src/octoprint/plugin/types.py index a703b4ac..ad81d436 100644 --- a/src/octoprint/plugin/types.py +++ b/src/octoprint/plugin/types.py @@ -6,7 +6,7 @@ class, :class:`OctoPrintPlugin`. Please note that the plugin implementation types are documented in the section :ref:`Available plugin mixins `. -.. autoclass: OctoPrintPlugin +.. autoclass:: OctoPrintPlugin """ @@ -22,21 +22,47 @@ from .core import Plugin class OctoPrintPlugin(Plugin): """ + The parent class of all OctoPrint plugin mixins. + .. attribute:: _plugin_manager + The :class:`~octoprint.plugin.core.PluginManager` instance. Injected by the plugin core system upon + initialization of the implementation. + .. attribute:: _printer_profile_manager + The :class:`~octoprint.printer.profile.PrinterProfileManager` instance. Injected by the plugin core system upon + initialization of the implementation. + .. attribute:: _event_bus + The :class:`~octoprint.events.EventManager` instance. Injected by the plugin core system upon initialization of + the implementation. + .. attribute:: _analysis_queue + The :class:`~octoprint.filemanager.analysis.AnalysisQueue` instance. Injected by the plugin core system upon + initialization of the implementation. + .. attribute:: _slicing_manager + The :class:`~octoprint.slicing.SlicingManager` instance. Injected by the plugin core system upon initialization + of the implementation. + .. attribute:: _file_manager + The :class:`~octoprint.filemanager.FileManager` instance. Injected by the plugin core system upon initialization + of the implementation. + .. attribute:: _printer + The :class:`~octoprint.printer.PrinterInterface` instance. Injected by the plugin core system upon initialization + of the implementation. + .. attribute:: _app_session_manager + + The :class:`~octoprint.users.SessionManager` instance. Injected by the plugin core system upon initialization of + the implementation. """ pass diff --git a/src/octoprint/printer/__init__.py b/src/octoprint/printer/__init__.py index ea86749c..19de90f9 100644 --- a/src/octoprint/printer/__init__.py +++ b/src/octoprint/printer/__init__.py @@ -10,6 +10,9 @@ abstracted version of the actual printer communiciation. .. autoclass:: PrinterInterface :members: + +.. autoclass:: PrinterCallback + :members: """ from __future__ import absolute_import diff --git a/src/octoprint/util/__init__.py b/src/octoprint/util/__init__.py index abbe5aac..e00245dd 100644 --- a/src/octoprint/util/__init__.py +++ b/src/octoprint/util/__init__.py @@ -22,7 +22,7 @@ import warnings logger = logging.getLogger(__name__) def warning_decorator_factory(warning_type): - def specific_warning(message, stacklevel=1, since=None, includedoc=None): + def specific_warning(message, stacklevel=1, since=None, includedoc=None, extenddoc=False): def decorator(func): @wraps(func) def func_wrapper(*args, **kwargs): @@ -33,7 +33,7 @@ def warning_decorator_factory(warning_type): if includedoc is not None and since is not None: docstring = "\n.. deprecated:: {since}\n {message}\n\n".format(since=since, message=includedoc) - if hasattr(func_wrapper, "__doc__") and func_wrapper.__doc__ is not None: + if extenddoc and hasattr(func_wrapper, "__doc__") and func_wrapper.__doc__ is not None: docstring = func_wrapper.__doc__ + "\n" + docstring func_wrapper.__doc__ = docstring @@ -57,6 +57,8 @@ Arguments: happening dynamically from a fixed position to not shadow the real caller (e.g. in case of overridden ``getattr`` methods). includedoc (string): Message about the deprecation to include in the wrapped function's docstring. + extenddoc (boolean): If True the original docstring of the wrapped function will be extended by the deprecation + message, if False (default) it will be replaced with the deprecation message. since (string): Version since when the function was deprecated, must be present for the docstring to get extended. Returns: @@ -77,6 +79,8 @@ Arguments: meaning the direct caller of the method. It might make sense to increase this in case of the function call happening dynamically from a fixed position to not shadow the real caller (e.g. in case of overridden ``getattr`` methods). + extenddoc (boolean): If True the original docstring of the wrapped function will be extended by the deprecation + message, if False (default) it will be replaced with the deprecation message. includedoc (string): Message about the deprecation to include in the wrapped function's docstring. since (string): Version since when the function was deprecated, must be present for the docstring to get extended.