From 9c4b1aeb8d7802af80fac180dbe8a876cf897c5c Mon Sep 17 00:00:00 2001
From: "James R. Barlow" <jim@purplerock.ca>
Date: Thu, 20 Jun 2019 02:44:29 -0700
Subject: [PATCH] docs: plugin; renaming

---
 docs/index.rst           |  1 +
 docs/plugins.rst         | 22 ++++++++++++++++++++++
 src/ocrmypdf/_plugins.py | 28 ++++++++++++++--------------
 3 files changed, 37 insertions(+), 14 deletions(-)
 create mode 100644 docs/plugins.rst

diff --git a/docs/index.rst b/docs/index.rst
index 5936e7da..f3a28781 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -28,6 +28,7 @@ PDF is the best format for storing and exchanging scanned documents.  Unfortunat
    docker
    advanced
    api
+   plugins
    batch
    security
    errors
diff --git a/docs/plugins.rst b/docs/plugins.rst
new file mode 100644
index 00000000..b962081b
--- /dev/null
+++ b/docs/plugins.rst
@@ -0,0 +1,22 @@
+Plugins
+=======
+
+You can use plugins to customize the behavior of OCRmyPDF at certain points of interest.
+
+Currently, it is possible to:
+- override the decision for whether or not to perform OCR on a particular file
+- modify the image is about to be sent for OCR
+
+How plugins are imported
+------------------------
+
+Plugins are imported on demand, by the OCRmyPDF worker process that needs to use them.
+As such, plugins cannot share state with each other, and will be imported many times,
+once for each worker process.
+
+Plugins currently cannot override the same hook.
+
+How plugins are invoked
+-----------------------
+
+Plugins may be called from the command line:
diff --git a/src/ocrmypdf/_plugins.py b/src/ocrmypdf/_plugins.py
index c4bf5d0a..2a52b105 100644
--- a/src/ocrmypdf/_plugins.py
+++ b/src/ocrmypdf/_plugins.py
@@ -24,39 +24,39 @@ from pathlib import Path
 log = logging.getLogger(__name__)
 
 
-def _load_function_from_module(location):
-    """Load a function given a module location
+def _load_object_from_module(location):
+    """Load a object given a module location
 
     For location=a.b.c, will effectively run "from a.b import c"
 
     Example:
-        _load_function_from_module("a.b.c")
+        _load_object_from_module("a.b.c")
 
     """
     module_parts = location.split('.')
     module_name = '.'.join(module_parts[:-1])
     object_name = module_parts[-1]
     module = importlib.import_module(module_name)
-    fn = getattr(module, object_name)
-    log.debug(f"Loaded function: from {module_name} import {object_name}")
-    return fn
+    obj = getattr(module, object_name)
+    log.debug(f"Loaded object: from {module_name} import {object_name}")
+    return obj
 
 
-def _load_function_from_pyfile(location):
-    """Load a function from a file
+def _load_object_from_pyfile(location):
+    """Load a object from a file
 
     Example:
-        _load_function_from_pyfile("test.py::blur_filter")
+        _load_object_from_pyfile("test.py::blur_filter")
     """
     filename, object_name = location.split('::', maxsplit=1)
-    log.debug(f"Loading function {object_name} from {filename}")
+    log.debug(f"Loading object {object_name} from {filename}")
 
     module_name = Path(filename).stem
     spec = importlib.util.spec_from_file_location(module_name, filename)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
-    fn = getattr(module, object_name)
-    return fn
+    obj = getattr(module, object_name)
+    return obj
 
 
 def load_plugin(plugin):
@@ -67,9 +67,9 @@ def load_plugin(plugin):
         raise TypeError()
 
     if '::' not in plugin:
-        plugin = _load_function_from_module(plugin)
+        plugin = _load_object_from_module(plugin)
     else:
-        plugin = _load_function_from_pyfile(plugin)
+        plugin = _load_object_from_pyfile(plugin)
 
     return plugin