diff --git a/README.md b/README.md index 28e0f7a..65b7041 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,119 @@ for it in these places: /etc/xdg/i3pystatus.py $XDG_CONFIG_DIRS/i3pystatus.py -A sample configuration file is `i3pystatus/__main__.py.dist` +The config file is just a normal Python module that is executed if you execute +i3pystatus (it is placed inside the i3pystatus package). + +You can also execute your config file instead of i3pystatus, but you need to +use an absolute import (`from i3pystatus import Status`) and cannot name it +i3pystatus.py. This is very handy for using different status lines for different +outputs. + +A simple configuration file could look like this (note the additional dependencies +from network, wireless and pulseaudio in this example): + + # -*- coding: utf-8 -*- + + import subprocess + + from . import Status + + status = Status(standalone=True) + + # Displays clock like this: + # Tue 30 Jul 11:59:46 PM KW31 + # ^-- calendar week + status.register("clock", + format="%a %-d %b %X KW%V",) + + # Shows the average load of the last minute and the last 5 minutes + # (the default value for format is used) + status.register("load") + + # Shows your CPU temperature, if you have a Intel CPU + status.register("temp", + format="{temp:.0f}°C",) + + # The battery monitor has many formatting options, see README for details + + # This would look like this, when discharging (or charging) + # ↓14.22W 56.15% [77.81%] 2h:41m + # And like this if full: + # =14.22W 100.0% [91.21%] + # + # This would also display a desktop notification (via dbus) if the percentage + # goes below 5 percent while discharging. The block will also color RED. + status.register("battery", + format="{status}/{consumption:.2f}W {percentage:.2f}% [{percentage_design:.2f}%] {remaining_hm}", + alert=True, + alert_percentage=5, + status={ + "DIS": "↓", + "CHR": "↑", + "FULL": "=", + },) + + # This would look like this: + # Discharging 6h:51m + status.register("battery", + format="{status} {remaining_hm}", + alert=True, + alert_percentage=5, + status={ + "DIS": "Discharging", + "CHR": "Charging", + "FULL": "Bat full", + },) + + # Displays whether a DHCP client is running + status.register("runwatch", + name="DHCP", + path="/var/run/dhclient*.pid",) + + # Shows the address and up/down state of eth0. If it is up the address is shown in + # green (the default value of color_up) and the CIDR-address is shown + # (i.e. 10.10.10.42/24). + # If it's down just the interface name (eth0) will be displayed in red + # (defaults of format_down and color_down) + # + # Note: the network module requires PyPI package netifaces-py3 + status.register("network", + interface="eth0", + format_up="{v4cidr}",) + + # Has all the options of the normal network and adds some wireless specific things + # like quality and network names. + # + # Note: requires both netifaces-py3 and basiciw + status.register("wireless", + interface="wlan0", + format_up="{essid} {quality:03.0f}%",) + + # Shows disk usage of / + # Format: + # 42/128G [86G] + status.register("disk", + path="/", + format="{used}/{total}G [{avail}G]",) + + # Shows pulseaudio default sink volume + # + # Note: requires libpulseaudio from PyPI + status.register("pulseaudio", + format="♪{volume}",) + + # Shows mpd status + # Format: + # Cloud connected▶Reroute to Remain + status.register("mpd", + format="{title}{status}{album}", + status={ + "pause": "▷", + "play": "▶", + "stop": "◾", + },) + + status.run() Also change your i3wm config to the following: @@ -112,7 +224,7 @@ __Settings:__ * `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: `{'DIS': 'DIS', 'CHR': 'CHR', 'FULL': 'FULL'}`) +* `status` — A dictionary mapping ('DIS', 'CHR', 'FULL') to alternative names (default: `{'CHR': 'CHR', 'FULL': 'FULL', 'DIS': 'DIS'}`) @@ -296,7 +408,7 @@ __Settings:__ * `host` — (default: `localhost`) * `port` — MPD port (default: `6600`) * `format` — (default: `{title} {status}`) -* `status` — Dictionary mapping pause, play and stop to output (default: `{'stop': '◾', 'pause': '▷', 'play': '▶'}`) +* `status` — Dictionary mapping pause, play and stop to output (default: `{'play': '▶', 'pause': '▷', 'stop': '◾'}`) @@ -475,9 +587,10 @@ use IntervalModule, which just calls a function repeatedly in a specified interv The output attribute should be set to a dictionary which represents your modules output, the protocol is documented [here](http://i3wm.org/docs/i3bar-protocol.html). -Please add an example for how to configure it to `__main__.py.dist`. It should be -a python class that can be registered with the `I3statusHandler` class. Also don't -forget to add yourself to the LICENSE file. - **Patches and pull requests are very welcome :-)** +### The README + +The README.md file is generated from the README.tpl.md file; only edit the latter +and run `python -m i3pystatus.mkdocs`. + diff --git a/README.tpl.md b/README.tpl.md index 1173f2f..7e1d935 100644 --- a/README.tpl.md +++ b/README.tpl.md @@ -32,7 +32,119 @@ for it in these places: /etc/xdg/i3pystatus.py $XDG_CONFIG_DIRS/i3pystatus.py -A sample configuration file is `i3pystatus/__main__.py.dist` +The config file is just a normal Python module that is executed if you execute +i3pystatus (it is placed inside the i3pystatus package). + +You can also execute your config file instead of i3pystatus, but you need to +use an absolute import (`from i3pystatus import Status`) and cannot name it +i3pystatus.py. This is very handy for using different status lines for different +outputs. + +A simple configuration file could look like this (note the additional dependencies +from network, wireless and pulseaudio in this example): + + # -*- coding: utf-8 -*- + + import subprocess + + from . import Status + + status = Status(standalone=True) + + # Displays clock like this: + # Tue 30 Jul 11:59:46 PM KW31 + # ^-- calendar week + status.register("clock", + format="%a %-d %b %X KW%V",) + + # Shows the average load of the last minute and the last 5 minutes + # (the default value for format is used) + status.register("load") + + # Shows your CPU temperature, if you have a Intel CPU + status.register("temp", + format="{temp:.0f}°C",) + + # The battery monitor has many formatting options, see README for details + + # This would look like this, when discharging (or charging) + # ↓14.22W 56.15% [77.81%] 2h:41m + # And like this if full: + # =14.22W 100.0% [91.21%] + # + # This would also display a desktop notification (via dbus) if the percentage + # goes below 5 percent while discharging. The block will also color RED. + status.register("battery", + format="{status}/{consumption:.2f}W {percentage:.2f}% [{percentage_design:.2f}%] {remaining_hm}", + alert=True, + alert_percentage=5, + status={ + "DIS": "↓", + "CHR": "↑", + "FULL": "=", + },) + + # This would look like this: + # Discharging 6h:51m + status.register("battery", + format="{status} {remaining_hm}", + alert=True, + alert_percentage=5, + status={ + "DIS": "Discharging", + "CHR": "Charging", + "FULL": "Bat full", + },) + + # Displays whether a DHCP client is running + status.register("runwatch", + name="DHCP", + path="/var/run/dhclient*.pid",) + + # Shows the address and up/down state of eth0. If it is up the address is shown in + # green (the default value of color_up) and the CIDR-address is shown + # (i.e. 10.10.10.42/24). + # If it's down just the interface name (eth0) will be displayed in red + # (defaults of format_down and color_down) + # + # Note: the network module requires PyPI package netifaces-py3 + status.register("network", + interface="eth0", + format_up="{v4cidr}",) + + # Has all the options of the normal network and adds some wireless specific things + # like quality and network names. + # + # Note: requires both netifaces-py3 and basiciw + status.register("wireless", + interface="wlan0", + format_up="{essid} {quality:03.0f}%",) + + # Shows disk usage of / + # Format: + # 42/128G [86G] + status.register("disk", + path="/", + format="{used}/{total}G [{avail}G]",) + + # Shows pulseaudio default sink volume + # + # Note: requires libpulseaudio from PyPI + status.register("pulseaudio", + format="♪{volume}",) + + # Shows mpd status + # Format: + # Cloud connected▶Reroute to Remain + status.register("mpd", + format="{title}{status}{album}", + status={ + "pause": "▷", + "play": "▶", + "stop": "◾", + },) + + status.run() Also change your i3wm config to the following: @@ -58,8 +170,9 @@ use IntervalModule, which just calls a function repeatedly in a specified interv The output attribute should be set to a dictionary which represents your modules output, the protocol is documented [here](http://i3wm.org/docs/i3bar-protocol.html). -Please add an example for how to configure it to `__main__.py.dist`. It should be -a python class that can be registered with the `I3statusHandler` class. Also don't -forget to add yourself to the LICENSE file. - **Patches and pull requests are very welcome :-)** + +### The README + +The README.md file is generated from the README.tpl.md file; only edit the latter +and run `python -m i3pystatus.mkdocs`.