Commits

Thorsten Weimann committed 2cfd9f0

Added documentation.

Comments (0)

Files changed (1)

 __version__ = '0.1'
 __license__ = 'MIT'
 
-SLEEP_SECS = 5
-WLAN_INTERFACE = 'wlan0'
+SLEEP_SECS = 5.0
 DEFAULT_FORMAT = (
     'CPU: {model}@{speed:<5} ESSID: {essid} [{quality}] '
     'Gmail: {gmail_count:<3} {date} {time}'
 actions = deque()
 
 
-def get_net_info(interface, encoding=None):
+def get_wireless_info(interface='wlan0', encoding=None, additional=None):
+    """Reads basic info about your wireless interface using iwconfig.
+
+    :parameters:
+        interface : str
+            WLAN interface (default: wlan0).
+        encoding : str
+            Your filesystemencoding, to decode the iwconfig output
+            (default: None). Filesystemencoding is attached automatically.
+        additional : dict
+            An optional dict mapping names to regular expressions.
+
+    The following keys are returned:
+
+    :essid: Your ESSID
+    :tx: TX-Power
+    :quality: Link quality
+    :rate: Bit Rate per second
+    :level: Signal level
+
+    And any additional information you pass in.
+    """
     d = {}
+    info = additional or {}
+    info.update(net)
     out = check_output(['iwconfig', interface])
     out = out.decode(encoding or ENC)
-    for name, regex in net.items():
+    for name, regex in info.items():
         match = regex.search(out)
         d[name] = match.group(name)
     return d
 
 
-def get_cpu_info():
+def get_cpu_info(additional=None):
+    """Reads some basic info from /proc/cpuinfo.
+
+    :parameters:
+        additional : dict
+            An optional dict mapping names to regular expressions.
+
+    The following keys are returned:
+
+    :vendor: Vendor ID
+    :model: Model name
+    :speed: Speed in MHz
+
+    And any additional information you pass in.
+    """
     d = {}
+    info = additional or {}
+    info.update(cpu)
     with open('/proc/cpuinfo') as fp:
         data = fp.read()
-    for name, regex in cpu.items():
+    for name, regex in info.items():
         match = regex.search(data)
         d[name] = match.group(name)
     return d
 
 
 def get_gmail_count(user, passwd):
+    """Counts new mails for your Gmail account. This is done by parsing
+    the provided newsfeed. Your mailbox (IMAP, POP) gets not connected
+    every time.
+
+    :parameters:
+        user : str
+            Gmail username (email address).
+        passwd : str
+            Password for your Gmail account.
+
+    Returned is only one key:
+
+    :gmail_count: Number of new (unread) messages.
+    """
     gmail = dict(realm=GMAIL_REALM, uri=GMAIL_URI, user=user, passwd=passwd)
     auth_handler = req.HTTPBasicAuthHandler()
     auth_handler.add_password(**gmail)
     return dict(gmail_count=count)
 
 
-def get_date_time(date_format='%d.%m.%Y', time_format='%H:%M'):
+def get_date_time(date_format='%Y-%m-%d', time_format='%H:%M'):
+    """Returns actual date and time. You can use this or the builtin function
+    provided by spectrwm.
+
+    :parameters:
+        date_format : str
+            Format string for the date. See Python docs for usable formats
+            (default: '%Y-%m-%d').
+        time_format : str
+            See date_format (default: '%H:%M').
+
+    Returned are two keys:
+
+    :date: Date formatted with date_format
+    :time: Time formatted with time_format
+    """
     dt = datetime.now()
     return dict(date=dt.strftime(date_format), time=dt.strftime(time_format))
 
 def register_builtins():
     actions.extend([
         get_cpu_info,
-        partial(get_net_info, WLAN_INTERFACE),
+        get_wireless_info,
         get_date_time,
     ])
 
 
 def loop(format_str=DEFAULT_FORMAT, sleep_secs=SLEEP_SECS):
+    """Main loop. Loops every `sleep_secs` over the registered functions
+    and returns the collected information formatted with `format_str`.
+
+    :parameters:
+        format_str : str
+            String which will be outputted on every loop.
+        sleep_secs : float
+            Time to sleep after every loop.
+
+    Kill the loop with CTRL+C (when testing).
+    """
     try:
         while True:
             d = defaultdict(lambda: '-')
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.