From e848fc4a6f3920d5f0ccf5c83399a9f073225131 Mon Sep 17 00:00:00 2001 From: enkore Date: Wed, 31 Jul 2013 21:39:59 +0200 Subject: [PATCH] Improve documentation --- README.md | 109 ++++++++++++++++++++++------------------ i3pystatus/alsa.py | 9 +++- i3pystatus/backlight.py | 5 ++ i3pystatus/battery.py | 23 +++++---- i3pystatus/clock.py | 2 +- i3pystatus/disk.py | 6 +-- i3pystatus/mpd.py | 22 ++++---- i3pystatus/network.py | 18 +++---- i3pystatus/pyload.py | 14 +++--- i3pystatus/regex.py | 2 + i3pystatus/wireless.py | 6 +-- 11 files changed, 123 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 76e6556..796b535 100644 --- a/README.md +++ b/README.md @@ -168,10 +168,17 @@ Shows volume of ALSA mixer. You can also use this for inputs, btw. Requires pyalsaaudio +Available formatters: + +* `{volume}` — the current volume in percent +* `{muted}` — the value of one of the `muted` or `unmuted` settings +* `{card}` — the associated soundcard +* `{mixer}` — the associated ALSA mixer + __Settings:__ -* `format` — {volume} is the current volume, {muted} is one of `muted` or `unmuted`. {card} is the sound card used; {mixer} the mixer. (default: `♪: {volume}`) +* `format` — (default: `♪: {volume}`) * `mixer` — ALSA mixer (default: `Master`) * `mixer_id` — ALSA mixer id (default: `0`) * `card` — ALSA sound card (default: `0`) @@ -188,6 +195,11 @@ __Settings:__ Screen backlight info +Available formatters: +* `{brightness}` — current brightness relative to max_brightness +* `{max_brightness}` — maximum brightness value +* `{percentage}` — current brightness in percent + __Settings:__ @@ -205,26 +217,25 @@ battery status Available formatters for format and alert_format_\*: -* remaining_str -* remaining_hm -* percentage -* percentage_design -* consumption (Watts) -* status -* battery_ident +* `{remaining_str}` — remaining time for charging or discharging in the format H:MM +* `{remaining_hm}`- remaining time in the format Hh:MMm +* `{percentage}` — battery percentage relative to the last full value +* `{percentage_design}` — absolute battery charge percentage +* `{consumption (Watts)}` — current power flowing into/out of the battery +* `{status}` +* `{battery_ident}` — the same as the setting __Settings:__ -* `battery_ident` — (default: `BAT0`) +* `battery_ident` — The name of your battery, usually BAT0 or BAT1 (default: `BAT0`) * `format` — (default: `{status} {remaining_hm}`) * `alert` — Display a libnotify-notification on low battery (default: `False`) * `alert_percentage` — (default: `10`) -* `alert_format_title` — (default: `Low battery`) -* `alert_format_body` — (default: `Battery {battery_ident} has only {percentage:.2f}% ({remaining_hm}) remaining!`) -* `alert_percentage` — (default: `10`) -* `path` — (default: `None`) -* `status` — A dictionary mapping ('DIS', 'CHR', 'FULL') to alternative names (default: `{'FULL': 'FULL', 'CHR': 'CHR', 'DIS': 'DIS'}`) +* `alert_format_title` — The title of the notification, all formatters can be used (default: `Low battery`) +* `alert_format_body` — The body text of the notification, all formatters can be used (default: `Battery {battery_ident} has only {percentage:.2f}% ({remaining_hm}) remaining!`) +* `path` — Override the default-generated path (default: `None`) +* `status` — A dictionary mapping ('DIS', 'CHR', 'FULL') to alternative names (default: `{'DIS': 'DIS', 'FULL': 'FULL', 'CHR': 'CHR'}`) @@ -236,17 +247,17 @@ This class shows a clock __Settings:__ -* `format` — stftime format string (default: `None`) +* `format` — stftime format string, `None` means to use the default, locale-dependent format (default: `None`) ### disk -Gets used, free, available and total amount of bytes on the given mounted filesystem. +Gets `{used}`, `{free}`, `{available}` and `{total}` amount of bytes on the given mounted filesystem. -These values can also be expressed in percentages with the percentage_used, percentage_free -and percentage_avail formats. +These values can also be expressed in percentages with the `{percentage_used}`, `{percentage_free}` +and `{percentage_avail}` formats. __Settings:__ @@ -390,16 +401,16 @@ __Settings:__ Displays various information from MPD (the music player daemon) Available formatters: -* title (the title of the current song) -* album (the album of the current song, can be an empty string (e.g. for online streams)) -* artist (can be empty, too) -* song_elapsed (Position in the currently playing song, looks like 3:54) -* song_length (Length of the current song, same format as song_elapsed) -* pos (Position of current song in playlist, one-based) -* len (Songs in playlist) -* status (play, pause, stop mapped through the `status` dictionary) -* bitrate (Current bitrate in kilobit/s) -* volume (Volume set in MPD) +* `{title}` — (the title of the current song) +* `{album}` — (the album of the current song, can be an empty string (e.g. for online streams)) +* `{artist}` — (can be empty, too) +* `{song_elapsed}` — (Position in the currently playing song, looks like 3:54) +* `{song_length}` — (Length of the current song, same format as song_elapsed) +* `{pos}` — (Position of current song in playlist, one-based) +* `{len}` — (Songs in playlist) +* `{status}` — (play, pause, stop mapped through the `status` dictionary) +* `{bitrate}` — (Current bitrate in kilobit/s) +* `{volume}` — (Volume set in MPD) Left click on the module play/pauses, right click (un)mutes. @@ -416,7 +427,7 @@ __Settings:__ * `port` — MPD port (default: `6600`) * `format` — (default: `{title} {status}`) * `format_sparse` — (default: `None`) -* `status` — Dictionary mapping pause, play and stop to output (default: `{'stop': '◾', 'play': '▶', 'pause': '▷'}`) +* `status` — Dictionary mapping pause, play and stop to output (default: `{'stop': '◾', 'pause': '▷', 'play': '▶'}`) @@ -428,15 +439,15 @@ Display network information about a interface. Requires the PyPI package `netifaces-py3`. Available formatters: -* `{interface}` same as setting -* `{name}` same as setting -* `{v4}` IPv4 address -* `{v4mask}` subnet mask -* `{v4cidr}` IPv4 address in cidr notation (i.e. 192.168.2.204/24) -* `{v6}` IPv6 address -* `{v6mask}` subnet mask -* `{v6cidr}` IPv6 address in cidr notation -* `{mac}` MAC of interface +* `{interface}` — same as setting +* `{name}` — same as setting +* `{v4}` — IPv4 address +* `{v4mask}` — subnet mask +* `{v4cidr}` — IPv4 address in cidr notation (i.e. 192.168.2.204/24) +* `{v6}` — IPv6 address +* `{v6mask}` — subnet mask +* `{v6cidr}` — IPv6 address in cidr notation +* `{mac}` — MAC of interface Not available addresses (i.e. no IPv6 connectivity) are replaced with empty strings. @@ -484,13 +495,13 @@ __Settings:__ Shows pyLoad status Available formatters: -* captcha (see captcha_true and captcha_false, which are the values filled in for this formatter) -* progress (average over all running downloads) -* progress_all (percentage of completed files/links in queue) -* speed (kilobytes/s) -* download (downloads enabled, also see download_true and download_false) -* total (number of downloads) -* free_space (free space in download directory in gigabytes) +* `{captcha}` (see captcha_true and captcha_false, which are the values filled in for this formatter) +* `{progress}` (average over all running downloads) +* `{progress_all}` (percentage of completed files/links in queue) +* `{speed}` (kilobytes/s) +* `{download}` (downloads enabled, also see download_true and download_false) +* `{total}` (number of downloads) +* `{free_space}` (free space in download directory in gigabytes) __Settings:__ @@ -511,6 +522,8 @@ __Settings:__ Simple regex file watcher +The groups of the regex are passed to the format string as positional arguments. + __Settings:__ @@ -570,9 +583,9 @@ Requires the PyPI packages `netifaces-py3` and `basiciw`. This is based on the network module, so all options and formatters are the same, except for these additional formatters: -* {essid} ESSID of currently connected wifi -* {freq} Current frequency -* {quality} Link quality in percent +* `{essid}` — ESSID of currently connected wifi +* `{freq}` — Current frequency +* `{quality}` — Link quality in percent __Settings:__ diff --git a/i3pystatus/alsa.py b/i3pystatus/alsa.py index 71ec6fe..f93142e 100644 --- a/i3pystatus/alsa.py +++ b/i3pystatus/alsa.py @@ -7,12 +7,19 @@ class ALSA(IntervalModule): Shows volume of ALSA mixer. You can also use this for inputs, btw. Requires pyalsaaudio + + Available formatters: + + * `{volume}` — the current volume in percent + * `{muted}` — the value of one of the `muted` or `unmuted` settings + * `{card}` — the associated soundcard + * `{mixer}` — the associated ALSA mixer """ interval = 1 settings = ( - ("format", "{volume} is the current volume, {muted} is one of `muted` or `unmuted`. {card} is the sound card used; {mixer} the mixer."), + "format", ("mixer", "ALSA mixer"), ("mixer_id", "ALSA mixer id"), ("card", "ALSA sound card"), diff --git a/i3pystatus/backlight.py b/i3pystatus/backlight.py index b14441f..5b2992b 100644 --- a/i3pystatus/backlight.py +++ b/i3pystatus/backlight.py @@ -3,6 +3,11 @@ from i3pystatus.file import File class Backlight(File): """ Screen backlight info + + Available formatters: + * `{brightness}` — current brightness relative to max_brightness + * `{max_brightness}` — maximum brightness value + * `{percentage}` — current brightness in percent """ settings = ( diff --git a/i3pystatus/battery.py b/i3pystatus/battery.py index fe2d4ab..c88ccdc 100644 --- a/i3pystatus/battery.py +++ b/i3pystatus/battery.py @@ -97,20 +97,23 @@ class BatteryChecker(IntervalModule): Available formatters for format and alert_format_\*: - * remaining_str - * remaining_hm - * percentage - * percentage_design - * consumption (Watts) - * status - * battery_ident + * `{remaining_str}` — remaining time for charging or discharging in the format H:MM + * `{remaining_hm}`- remaining time in the format Hh:MMm + * `{percentage}` — battery percentage relative to the last full value + * `{percentage_design}` — absolute battery charge percentage + * `{consumption (Watts)}` — current power flowing into/out of the battery + * `{status}` + * `{battery_ident}` — the same as the setting """ settings = ( - "battery_ident", "format", + ("battery_ident", "The name of your battery, usually BAT0 or BAT1"), + "format", ("alert", "Display a libnotify-notification on low battery"), - "alert_percentage", "alert_format_title", "alert_format_body", "alert_percentage", - "path", + "alert_percentage", + ("alert_format_title", "The title of the notification, all formatters can be used"), + ("alert_format_body", "The body text of the notification, all formatters can be used"), + ("path", "Override the default-generated path"), ("status", "A dictionary mapping ('DIS', 'CHR', 'FULL') to alternative names"), ) battery_ident = "BAT0" diff --git a/i3pystatus/clock.py b/i3pystatus/clock.py index 3eb3fc9..6518192 100644 --- a/i3pystatus/clock.py +++ b/i3pystatus/clock.py @@ -11,7 +11,7 @@ class Clock(IntervalModule): """ settings = ( - ("format", "stftime format string"), + ("format", "stftime format string, `None` means to use the default, locale-dependent format"), ) format = None interval = 1 diff --git a/i3pystatus/disk.py b/i3pystatus/disk.py index bb290b6..981636c 100644 --- a/i3pystatus/disk.py +++ b/i3pystatus/disk.py @@ -5,10 +5,10 @@ from .core.util import round_dict class Disk(IntervalModule): """ - Gets used, free, available and total amount of bytes on the given mounted filesystem. + Gets `{used}`, `{free}`, `{available}` and `{total}` amount of bytes on the given mounted filesystem. - These values can also be expressed in percentages with the percentage_used, percentage_free - and percentage_avail formats. + These values can also be expressed in percentages with the `{percentage_used}`, `{percentage_free}` + and `{percentage_avail}` formats. """ settings = ( diff --git a/i3pystatus/mpd.py b/i3pystatus/mpd.py index 19c9903..afaa8f1 100644 --- a/i3pystatus/mpd.py +++ b/i3pystatus/mpd.py @@ -4,23 +4,23 @@ import socket from i3pystatus import IntervalModule def format_time(seconds): - return "{}:{:02}".format(*divmod(int(seconds), 60)) + return "{}:{:02}".format(*divmod(int(seconds), 60)) if seconds else "" class MPD(IntervalModule): """ Displays various information from MPD (the music player daemon) Available formatters: - * title (the title of the current song) - * album (the album of the current song, can be an empty string (e.g. for online streams)) - * artist (can be empty, too) - * song_elapsed (Position in the currently playing song, looks like 3:54) - * song_length (Length of the current song, same format as song_elapsed) - * pos (Position of current song in playlist, one-based) - * len (Songs in playlist) - * status (play, pause, stop mapped through the `status` dictionary) - * bitrate (Current bitrate in kilobit/s) - * volume (Volume set in MPD) + * `{title}` — (the title of the current song) + * `{album}` — (the album of the current song, can be an empty string (e.g. for online streams)) + * `{artist}` — (can be empty, too) + * `{song_elapsed}` — (Position in the currently playing song, looks like 3:54) + * `{song_length}` — (Length of the current song, same format as song_elapsed) + * `{pos}` — (Position of current song in playlist, one-based) + * `{len}` — (Songs in playlist) + * `{status}` — (play, pause, stop mapped through the `status` dictionary) + * `{bitrate}` — (Current bitrate in kilobit/s) + * `{volume}` — (Volume set in MPD) Left click on the module play/pauses, right click (un)mutes. diff --git a/i3pystatus/network.py b/i3pystatus/network.py index 1769bc4..941a144 100644 --- a/i3pystatus/network.py +++ b/i3pystatus/network.py @@ -44,15 +44,15 @@ class Network(IntervalModule): Requires the PyPI package `netifaces-py3`. Available formatters: - * `{interface}` same as setting - * `{name}` same as setting - * `{v4}` IPv4 address - * `{v4mask}` subnet mask - * `{v4cidr}` IPv4 address in cidr notation (i.e. 192.168.2.204/24) - * `{v6}` IPv6 address - * `{v6mask}` subnet mask - * `{v6cidr}` IPv6 address in cidr notation - * `{mac}` MAC of interface + * `{interface}` — same as setting + * `{name}` — same as setting + * `{v4}` — IPv4 address + * `{v4mask}` — subnet mask + * `{v4cidr}` — IPv4 address in cidr notation (i.e. 192.168.2.204/24) + * `{v6}` — IPv6 address + * `{v6mask}` — subnet mask + * `{v6cidr}` — IPv6 address in cidr notation + * `{mac}` — MAC of interface Not available addresses (i.e. no IPv6 connectivity) are replaced with empty strings. """ diff --git a/i3pystatus/pyload.py b/i3pystatus/pyload.py index 47446a1..1cb4c51 100644 --- a/i3pystatus/pyload.py +++ b/i3pystatus/pyload.py @@ -11,13 +11,13 @@ class pyLoad(IntervalModule): Shows pyLoad status Available formatters: - * captcha (see captcha_true and captcha_false, which are the values filled in for this formatter) - * progress (average over all running downloads) - * progress_all (percentage of completed files/links in queue) - * speed (kilobytes/s) - * download (downloads enabled, also see download_true and download_false) - * total (number of downloads) - * free_space (free space in download directory in gigabytes) + * `{captcha}` (see captcha_true and captcha_false, which are the values filled in for this formatter) + * `{progress}` (average over all running downloads) + * `{progress_all}` (percentage of completed files/links in queue) + * `{speed}` (kilobytes/s) + * `{download}` (downloads enabled, also see download_true and download_false) + * `{total}` (number of downloads) + * `{free_space}` (free space in download directory in gigabytes) """ interval = 5 diff --git a/i3pystatus/regex.py b/i3pystatus/regex.py index 792de19..51176f3 100644 --- a/i3pystatus/regex.py +++ b/i3pystatus/regex.py @@ -5,6 +5,8 @@ from i3pystatus import IntervalModule class Regex(IntervalModule): """ Simple regex file watcher + + The groups of the regex are passed to the format string as positional arguments. """ flags = 0 diff --git a/i3pystatus/wireless.py b/i3pystatus/wireless.py index 2c52c11..e77339f 100644 --- a/i3pystatus/wireless.py +++ b/i3pystatus/wireless.py @@ -11,9 +11,9 @@ class Wireless(Network): This is based on the network module, so all options and formatters are the same, except for these additional formatters: - * {essid} ESSID of currently connected wifi - * {freq} Current frequency - * {quality} Link quality in percent + * `{essid}` — ESSID of currently connected wifi + * `{freq}` — Current frequency + * `{quality}` — Link quality in percent """ interface = "wlan0"