made signals more user-friendly

README.md

@@ -1,3 +1,32 @@
 # easyconf-lemonbar
 
-A python script to easily configure lemonbar. Object-oriented.
+A python script to easily configure lemonbar.
+
+### Signals
+You may update individual modules by sending a real-time signal to the
+easyconf-lemonbar process. First, in the module configuration, specify which
+signal to listen for, e.g.
+
+```yaml
+# Display a random number, and only update when we recieve the RTMIN+1 signal.
+- name: "random"
+  command: "python -c 'from random import randrange; print(randrange(1000))'"
+  refresh: 0
+  signal: 1
+```
+
+In the example above, the refresh is `0`. This means that the module *will never
+refresh on its own*; it will wait for the RTMIN+1 signal. You may also configure
+your module to both refresh on a time interval AND listen for a signal.
+
+Unfortunately, to send the signal, you cant just `pkill easyconf-lemonbar`. You
+have to read the PID from ECL's pidfile. I would recommend creating an alias in
+your shell as shown below.
+
+```sh
+$ alias ecl_kill="cat /run/user/${UID}/easyconf-lemonbar.pid | xargs kill"
+$ ecl_kill -RTMIN+1
+```
+
+This will refresh the module that is listening for signal `1`. To kill ecl
+completely, just run `ecl_kill` (after setting the above alias).

data/example_config.yml

@@ -62,8 +62,7 @@ bar:
       # Prefix to be printed before the text of the command.
       prefix: "DATE: "
       # Linux real-time signal that, when received, will refresh the module
-      # instantly. For example, if you set this to `1`, run
+      # instantly. See docs for more info.
-      # `pkill -RTMIN+1 easyconf-lemonbar`.
       signal: 0
       # Formatting options. These will only affect the text and padding of this
       # module.

easyconf-lemonbar/main.py

@@ -1,8 +1,14 @@
+from signal import SIGTERM, signal
+from pidfile import delete_pidfile, pidfile_name, create_pidfile
 from SignalRouter import SignalRouter
 from Bar import Bar
 from Module import Module
 from parse_config_file import get_bar_config_and_module_config_list
 
+def sigterm_handler(signal, frame):
+    delete_pidfile(pidfile_name())
+    exit()
+
 def main():
     bar_config, module_config_list = get_bar_config_and_module_config_list("./data/testing_config.yml")
     padding = bar_config["padding"]
@@ -20,7 +26,9 @@ def main():
         if module.signal != 0:
             signal_router.register_signal_thread(module.signal, module.ident)
 
+    create_pidfile(pidfile_name())
 
+    signal(SIGTERM, sigterm_handler)
 
 if __name__ == "__main__":
     main()

easyconf-lemonbar/pidfile.py

@@ -0,0 +1,14 @@
+from os import chmod, getpid, getuid, remove
+
+def pidfile_name():
+    filepath = "/run/user/" + str(getuid()) + "/easyconf-lemonbar.pid"
+    return filepath
+
+
+def create_pidfile(filepath):
+    with open(filepath, "w") as file:
+        file.write(str(getpid()))
+        chmod(filepath, 0o644)
+
+def delete_pidfile(filepath):
+    remove(filepath)