Updating the location of the before_script plugin method execution. Updating corresponding tests. Starting on the documentation

Author: joseph-flinn

docs/index.rst

@@ -28,6 +28,7 @@ Table of Contents
     quickstart
     examples
     cli
+    plugin_system
     developing
     api
     history

docs/plugin_system.rst

@@ -0,0 +1,95 @@
+.. _plugin_system:
+
+=============
+Plugin System
+=============
+
+The plugin system allows users to customize and extend different aspects of 
+tmuxp without the need to change tmuxp itself. 
+
+
+Using a Plugin
+--------------
+
+To use a plugin, install it in your local python environment and add it to 
+your tmuxp configuration file. 
+
+Example Configurations
+^^^^^^^^^^^^^^^^^^^^^^
+YAML
+~~~~
+
+.. literalinclude:: ../examples/plugin-system.yaml
+    :language: yaml
+
+JSON
+~~~~
+
+.. literalinclude:: ../examples/plugin-system.json
+    :language: json
+
+.. _poetry: https://python-poetry.org/
+
+
+Developing a Plugin
+-------------------
+
+.. module:: tmuxp 
+
+Plugin API
+^^^^^^^^^^
+
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.before_workspace_builder
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.on_window_create
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.after_window_finished
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.before_script
+.. automethod:: tmuxp.plugin.TmuxpPluginInterface.reattach
+
+
+Example Plugin
+--------------
+
+Tmuxp expects all plugins to be class within a python submodule named 
+``plugin`` that is within a python module that is installed in the local 
+python environment. A plugin interface is provided by tmuxp to inherit. 
+
+`poetry`_ is the chosen python package manager for tmuxp. It is highly 
+suggested to use it when developing tmuxp plugins; however, ``pip`` will work 
+just as well.
+
+.. code-block:: bash
+
+    python_module
+    ├── my_plugin_module
+    │   ├── __init__.py
+    │   └── plugin.py
+    ├── pyproject.toml  # Poetry's module configuration file
+    └── setup.py        # pip's module configuration file
+
+The `plugin.py` file could contain something like the following:
+
+.. code-block:: python
+    
+    from tmuxp.plugin import TmuxpPluginInterface
+    import datetime
+
+    class MyTmuxpPlugin(TmuxpPluginInterface):
+        def __init__(self):
+            super.__init__(self)
+
+        def before_workspace_builder(self, session):
+            session.rename_session('my-new-session-name')
+
+        def reattach(self, session):
+            now = datetime.datetime.now().strftime('%Y-%m-%d')
+            session.rename_session('session_{}'.format(now))
+
+Once this plugin is installed in the local python environment, it can be used
+in a configuration file like the following:
+
+.. code-block: yaml
+
+    session_name: plugin example
+    plugins:
+    - my_plugin_module.plugin.MyTmuxpPlugin
+    # ... the rest of your config

examples/plugin-system.json

@@ -0,0 +1,24 @@
+{
+  "session_name": "plugin-system",
+  "plugins": [
+    "tmuxp_plugin_extended_build.plugin.PluginExtendedBuild"
+  ],
+  "windows": [
+    {
+      "window_name": "editor",
+      "layout": "tiled",
+      "shell_command_before": [
+        "cd ~/"
+      ],
+      "panes": [
+        {
+          "shell_command": [
+            "cd /var/log",
+            "ls -al | grep *.log"
+          ]
+        },
+        "echo \"hello world\""
+      ]
+    }
+  ]
+}

examples/plugin-system.yaml

@@ -0,0 +1,13 @@
+session_name: plugin-system
+plugins:
+- 'tmuxp_plugin_extended_build.plugin.PluginExtendedBuild'
+windows:
+- window_name: editor
+  layout: tiled
+  shell_command_before:
+    - cd ~/
+  panes:
+    - shell_command:
+        - cd /var/log
+        - ls -al | grep *.log
+    - echo "hello world"

tests/fixtures/workspacebuilder/plugin_multiple_plugins.yaml

@@ -1,7 +1,6 @@
 session_name: plugin-test-multiple-plugins
 plugins:
 - 'tmuxp_test_plugin_bwb.plugin.PluginBeforeWorkspaceBuilder'
-- 'tmuxp_test_plugin_bs.plugin.PluginBeforeScript'
 - 'tmuxp_test_plugin_owc.plugin.PluginOnWindowCreate'
 - 'tmuxp_test_plugin_awf.plugin.PluginAfterWindowFinished'
 windows:

tests/test_cli.py

@@ -959,6 +959,22 @@ def test_ls_cli(monkeypatch, tmpdir):
     assert cli_output == '\n'.join(stems) + '\n'
 
 
+def test_plugin_system_before_script(server, monkeypatch):
+    # this is an implementation test. Since this testsuite may be ran within
+    # a tmux session by the developer himself, delete the TMUX variable
+    # temporarily.
+    monkeypatch.delenv('TMUX', raising=False)
+    session_file = curjoin("workspacebuilder/plugin_bs.yaml")
+
+    # open it detached
+    session = load_workspace(
+        session_file, socket_name=server.socket_name, detached=True
+    )
+
+    assert isinstance(session, libtmux.Session)
+    assert session.name == 'plugin_test_bs'
+
+
 def test_reattach_plugins(server):
     config_plugins = loadfixture("workspacebuilder/plugin_r.yaml")
 
@@ -977,4 +993,4 @@ def test_reattach_plugins(server):
 
     proc = builder.session.cmd('display-message', '-p', "'#S'")
 
-    assert proc.stdout[0] == "'plugin_test_r'"
+    assert proc.stdout[0] == "'plugin_test_r'"

tests/test_workspacebuilder.py

@@ -710,22 +710,6 @@ def test_plugin_system_before_workspace_builder(session):
     assert proc.stdout[0] == "'plugin_test_bwb'"
 
 
-def test_plugin_system_before_script(session):
-    config_plugins = loadfixture("workspacebuilder/plugin_bs.yaml")
-
-    sconfig = kaptan.Kaptan(handler='yaml')
-    sconfig = sconfig.import_config(config_plugins).get()
-    sconfig = config.expand(sconfig)
-
-    builder = WorkspaceBuilder(sconf=sconfig)
-    assert len(builder.plugins) > 0
-
-    builder.build(session=session)
-
-    proc = session.cmd('display-message', '-p', "'#S'")
-    assert proc.stdout[0] == "'plugin_test_bs'"
-
-
 def test_plugin_system_on_window_create(session):
     config_plugins = loadfixture("workspacebuilder/plugin_owc.yaml")
 
@@ -806,7 +790,7 @@ def test_plugin_system_multiple_plugins(session):
 
     # Drop through to the before_script plugin hook
     proc = session.cmd('display-message', '-p', "'#S'")
-    assert proc.stdout[0] == "'plugin_test_bs'"
+    assert proc.stdout[0] == "'plugin_test_bwb'"
 
     # Drop through to the after_window_finished. This won't succeed
     # unless on_window_create succeeds because of how the test plugin

tmuxp/cli.py

@@ -601,6 +601,10 @@ def load_workspace(
         else:
             sys.exit()
 
+    # Runs after before_script
+    for plugin in builder.plugins:
+        plugin.before_script(builder.session)
+
     return builder.session
 
 

tmuxp/plugin.py

@@ -1,18 +1,83 @@
 class TmuxpPluginInterface:
     def __init__(self):
+        """
+        Initialize plugin interface.
+        """
         pass
 
     def before_workspace_builder(self, session):
-        pass
+        """
+        Provide a session hook previous to creating the workspace.
 
-    def before_script(self, session):
-        pass
+        Parameters
+        ----------
+        session : :class:`libtmux.Session`
+            session to hook into
 
-    def reattach(self, session):
+        Notes
+        -----
+        This runs after the session has been created but before any of 
+        the windows/panes/commands are entered.
+        """
         pass
 
     def on_window_create(self, window):
+        """
+        Provide a window hook previous to creating the window.
+
+        Parameters
+        ----------
+        window: :class:`libtmux.Window`
+            window to hook into
+        
+        Notes
+        -----
+        This runs runs before anything is created in the windows, like panes.
+        """
         pass
 
     def after_window_finished(self, window):
+        """
+        Provide a window hook after creating the window.
+
+        Parameters
+        ----------
+        window: :class:`libtmux.Window`
+            window to hook into
+
+        Notes
+        -----
+        This runs after everything has been created in the window, including
+        the paes and all of the commands for the panes. It also runs after the
+        ``options_after`` have been applied to the window.
+        """
         pass
+
+    def before_script(self, session):
+        """
+        Provide a session hook after the workspace has been built.
+
+        Parameters
+        ----------
+        session : :class:`libtmux.Session`
+            session to hook into
+
+        Notes
+        -----
+        This runs after the workspace has been loaded with ``tmuxp load``. It
+        augments instead of replaces the ``before_script`` section of the
+        configuration. If changes to the session need to be made prior to 
+        anything being built, please use ``before_workspace_builder`` instead.
+        """
+        pass
+
+    def reattach(self, session):
+        """
+        Provide a session hook before reattaching to the session.
+
+        Parameters
+        ----------
+        session : :class:`libtmux.Session`
+            session to hook into
+        """
+        pass

tmuxp/workspacebuilder.py

@@ -207,10 +207,6 @@ def build(self, session=None):
             for option, value in self.sconf['environment'].items():
                 self.session.set_environment(option, value)
 
-        # Runs after before_script
-        for plugin in self.plugins:
-            plugin.before_script(self.session)
-
         for w, wconf in self.iter_create_windows(session):
             assert isinstance(w, Window)