{
    "info": {
        "author": "Harvey Hunt",
        "author_email": "harveyhuntnexus@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "i3situation\n=============\n\nA replacement for i3status written in Python 3 with support for huge\ncustomisability through plugins.\n\nPlease feel free to send a pull request or request features by opening an issue.\n\nContents\n============\n\n* [Installation](#installation)\n* [Configuring Plugins](#configuring-plugins)\n* [Plugins](#plugins)\n* [Creating A Plugin](#creating-a-plugin)\n    * [Events](#events)\n* [Advanced Plugin Options](#advanced-plugin-options)\n\nInstallation\n=============\n\nIf you're lucky enough to be using Arch Linux, i3situation is available from the [AUR](https://aur.archlinux.org/packages/i3situation-git/).\n\ni3situation is also available over at [PyPi](https://pypi.python.org/pypi/i3situation/1.0.1).\n\nIf you want to install straight from this git repository, first clone it and then change\ninto the cloned directory.\n\n    git clone https://github.com/HarveyHunt/i3situation\n    cd i3situation\n\nYou then need to install i3situation using the setup.py file that is provided.\n\n    sudo python setup.py install\n    \nNext, use your editor of choice to create a configuration file.\n\n    vim ~/.config/i3situation/config\n    \nThe minimum that you need to enter in order to run the application is as\nfollows:\n\n    [general]\n    interval = 1\n    logging_level = ERROR\n    log_file = ~/.config/i3situation/log.txt\n  \nYou then need to change the status_command value in the bar section of your i3\nconfiguration to:\n\n    status_command i3situation\n    \nIt is a good idea to run i3situation at this point, as it will handle copying over the\nplugins into your configuration directory.\n    \nConfiguring Plugins\n=============\nPlugins are the way to get this application to output to i3bar and allow for large\namounts of expandability. The configuration file is automatically reloaded when\nany changes occur to it. Changing the content of a plugin file will also cause\na reload of all plugins and settings.\n\n__Note:__ When using the % symbol in the config file, it needs to be escaped with another %.\n\nPlugins are configured in the config file. You must first denote a new plugin\nconfig section by using a unique name for that instance of a plugin. For example:\n\n    [my_time_plugin]\n\nInside this section you need to say which plugin you wish to use (Note: the plugin\nfield refers to the filename of the plugin less the .py extension).\n\n    [my_time_plugin]\n    plugin = date_time\n    \nEach plugin needs to have an interval set. This interval refers to how often the\nplugin's displayed text is updated.\n\n    [my_time_plugin]\n    plugin = date_time\n    interval = 1\n\nEach plugin has an on_click function already defined. This function allows the user to\nspecify a shell command that should be executed each time a plugin's text area is clicked\nwith a mouse button (of which there are three, defined [here](#events)). For example:\n\n    [my_time_plugin]\n    plugin = date_time\n    interval = 1\n    button1 = urxvt\n    button2 = xterm\n    \nYou can then change the options for a plugin by defining them next. The available\noptions can be seen in the plugin file in a dictionary- with the defaults next to it.\n\nA list of values should be comma separated and a boolean value can be written as:\n\n- on\n- True\n- true\n- off\n- False\n- false\n\nThe example below illustrates using a comma separated list:\n\n    [my_reddit_plugin]\n    plugin = reddit\n    interval = 30\n    mode = subreddit\n    subreddits = programming,linux\n    \nYou can also edit options that affect how the output is displayed (Note: the\nsame options are available for all plugins). The following example illustrates\nchanging the colour of the output:\n\n    [my_reddit_plugin]\n    plugin = reddit\n    interval = 30\n    mode = subreddit\n    subreddits = programming,linux\n    color = #808080\n\nThe rest of the output options that can be edited are discussed in the Advanced Plugin \nOptions section of this document.\n\nMy personal i3situation configuration file can be found with my [dotfiles](https://github.com/HarveyHunt/dotfiles).\n    \nPlugins\n============\n\n* [Cmus](#cmus)\n* [Date and Time](#date and time)\n* [Reddit](#reddit)\n* [Run](#run)\n* [Text](#text)\n* [Conky](#conky)\n* [Battery](#battery)\n\n## Cmus\nA plugin to display information provided by Cmus (current song etc).\n\nOptions:\n* **Format**: A string showing the format in which the output should be displayed.\n Keywords in the string will be replaced with data. Possible keywords can be found [here](i3situation/plugins/cmus.py).\n\n```\nformat=artist -> title\n```\n\n## Date and Time\nA plugin to display the current date and time. Has support for multiple time zones.\n\nOptions:\n* **Time Zone**: The time zone that should be used when finding the time. By default, Python will work this out by itself. Setting a value for time_zone will override that.\n\n```\ntime_zone=GMT\n```\n\n* **Long Format**: The text to display when there is a large amount of space. A full list of \nformat options can be found [here](http://docs.python.org/3/library/time.html#time.strftime)\n\n```\nlong_format=%d-%m-%Y %H:%M:%S\n```\n\n* **Short Format**: The text to be displayed when there is a smaller amount of bar space available.\n\n```\nshort_format=%H:%M:%S\n```\n\n##Reddit\nA plugin that can display information from Reddit, such as post titles and upvotes.\n\nOptions:\n* **Mode**: The mode that the plugin shall operate in. Front page will display threads from the \nfront page of Reddit or your personal front page (provided you have logged in).\n\n```\nmode=front\n```\n\n* **Subreddits**: The subreddits that should be displayed when the plugin is in subreddit mode. \nShould be in the form of a comma seperated list.\n\n```\nsubreddits=vim,python\n```\n\n* **Username**: Your Reddit username.\n\n```\nusername=segfaultless\n```\n\n* **Password**: Your Reddit password.\n\n```\npassword=lamepassword\n```\n\n* **Limit**: The amount of threads that should be requested from Reddit in one go.\n\n```\nlimit=25\n```\n\n* **Format**: The format that the plugin's output should be presented in. Keywords will \nbe replaced with actual data. For a full list of keywords, look [here](i3situation/plugins/reddit.py)\n\n```\nformat=subreddit title ups\n```\n\n* **Sort**: The method with which the Reddit threads are sorted.\n\n```\nsort=hot\n```\n\n* **Max Characters**: The maximum number of characters that a Reddit thread title is allowed to have. If the Reddit thread title is longer than this value, the thread will be removed from the queue.\n```\nmax_chars=140\n```\n\n## Run\nA plugin to run shell commands and send the output to i3bar.\n\n* **Command**: The command that is to be executed.\n\n```\ncommand=echo Hello\n```\n\n## Text\nA simple plugin to output text.\n\n* **Text**: The text that will be displayed.\n\n```\ntext=Hello World\n```\n\n## Conky\nA plugin to allow conky's output to be displayed. It is required that you have a valid .conkyrc\n\n* **Command**: The conky command to be executed.\n\n```\ncommand=$uptime\n```\n\n* **Config**: The path to the conkyrc file that shall be used.\n\n```\nconfig=~/.conkyrc\n```\n\n## Battery\nA plugin that displays information about the battery, such as charge level and status.\n\n* **format**: The format of the output. <status> will be replaced by the battery's current status\nand <charge> will be replaced by the current charge level.\n\n```\nformat=<charge>%\n```\n\n* **percentage**: Whether or not the charge should be calculated as a percentage.\n\n```\npercentage=True\n```\n\n* **low_threshold**: The value of charge below which the low_color will be displayed. Note: this value\nshould be from 0 to 1 when percentage isn't set and 0 to 100 when it is set.\n\n```\nlow_threshold=20\n```\n\n* **low_color**: The colour to be displayed when the battery charge level is classed as low.\n\n```\nlow_color=#FF0000\n```\n\n* **discharging_color**: The colour to be displayed when the battery is discharging.\n\n```\ndischarging_color=#FF6103\n```\n\n* **charging_color**: The colour to be displayed when the battery is charging.\n\n```\ncharging_color=#00F000\n```\n\n* **full_color**: The colour to be displayed when the battery is full.\n\n```\nfull_color=#FFFFFF\n```\n\n* **battery_path**: The path to the battery file- generally in the form /sys/class/power_supply/BATX.\n\n```\nbattery_path=/sys/class/power_supply/BAT0\n```\n\nCreating a Plugin\n=============\n\nCreating a plugin is a simple process, made easier by the Plugin base class.\nThe first step is to create a python\nfile in your plugin directory. Note: Files with a leading underscore will not\nbe loaded as a plugin but can be\nused for library files.\n\n    vim cool_feature.py\n\nThe Plugin base class needs to be imported from the plugins folder.\n\n```python\nfrom plugins._plugin import Plugin\n```    \n\nYou should then create a class that inherits the newly imported Plugin class.\n\n```python\nfrom plugins._plugin import Plugin\n\n\nclass cool_feature_plugin(Plugin):\n```    \n\nThe \\_\\_all\\_\\_ variable needs to be set to the name of your plugin class.\n\n```python\nfrom plugins._plugin import Plugin\n\n__all__ = 'CoolFeaturePlugin'\n\n\nclass CoolFeaturePlugin(Plugin):\n```\n\nThe \\_\\_init\\_\\_ function needs to accept two arguments- self and config. The\noptions that can be\nconfigured by the user need to be placed in a dictionary called self.options\nwith the format:\n\n```python\n{'option': 'default_value'}\n```\n\nOptions that can be configured by the user should be declared before calling\nthe super class'\n\\_\\_init\\_\\_ function.\n\nThe super class' \\_\\_init\\_\\_ function must be passed two arguments- config and\nthe user configurable\noptions. There is only one compulsary option- interval. This refers to how\noften (in seconds) the\nmain function of the plugin should be called.\n\n```python\nfrom plugins._plugin import Plugin\n\n__all__ = 'CoolFeaturePlugin'\n\n\nclass CoolFeaturePlugin(Plugin):\n\n    def __init__(self, config):\n        self.options = {'cool_option': 'cool_value', 'interval': 1}\n        super().__init__(config, self.options)\n```\n\nAll plugins must have a main() function that is called by the plugin loader.\nWithin this function,\nprogram logic should be executed and it should return a dictionary to the main\napplication. The \nPlugin base class provides a helper function called output that serves this\npurpose. Output should\nbe passed a string as the first argument that represents a detailed output of\nthe plugin and a shorter\nstring as the second argument. It is perfectly acceptable to pass the same\nvalue to each argument.\n\n```python\nfrom plugins._plugin import Plugin\n\n__all__ = 'CoolFeaturePlugin'\n\n\nclass CoolFeaturePlugin(Plugin):\n\n    def __init__(self, config):\n        self.options = {'cool_option': 'cool_value', 'interval': 1}\n        super().__init__(config, self.options)\n    \n    def main(self):\n        return self.output('This is a fabulous plugin', 'Cool plugin')\n```\n\nEvents\n-----------\n\nIt is also possible to create a function that gets executed whenever the plugin's output\nis clicked. The plugin must have an on_click() function that handles the event. The function\nmust accept an event dictionary as an argument- the layout of which is below:\n\n```\n{'button': 1, 'name': 'time', 'y': 1196, 'x': 1846}\n```\n\nThe button corresponds to which mouse button was used to click the text. The mouse buttons are \nnumbered as follows:\n\n1. Left Mouse Button\n2. Middle Mouse Button\n3. Right Mouse Button\n\nThe x and y variables refer to the position that the text was clicked at.\n\nThe name refers to the name of the plugin object that was clicked.\n\nIt is possible to do many things once the text has been clicked, but please bear in mind that\nthe on_click() code will be run in the same thread as the event handler. Therefore, it is important\nthat any code in on_click() isn't too intensive.\n\nAdding an on_click() function to the cool_feature_plugin looks as follows:\n\n```python\nfrom plugins._plugin import Plugin\n\n__all__ = 'CoolFeaturePlugin'\n\n\nclass CoolFeaturePlugin(Plugin):\n\n    def __init__(self, config):\n        self.options = {'cool_option': 'cool_value', 'interval': 1}\n        super().__init__(config, self.options)\n    \n    def main(self):\n        return self.output('This is a fabulous plugin', 'Cool plugin')\n    \n    def on_click(self, event):\n        if event['button'] == 1:\n            self.output_options['color'] = '#FF0000'\n        else:\n            self.output_options['color'] = '#0000FF'\n```\n\nThis is all the code required to create a plugin. There are lots of good\nexamples of how to write\nplugins in this [project's plugin\ndirectory](https://github.com/harvey_hunt/i3situation/tree/master/i3situation/plugins)\n\nAdvanced Plugin Options\n=============\n\nIt is also possible to manipulate many aspects of a plugin's output. The Plugin\nclass provides\na way to set the value of output options (blocks). Changing values in the\nfollowing dictionary\nwill affect the output options:\n\n```python\nself.output_options['color'] = '#FF00FF'\n```\n\nThe following is the internal representation of output options used in the\nPlugin class.\n\n```python\nself.output_options = {\n    'color': None,\n    'min_width': None,\n    'align': None,\n    'name': None,\n    'urgent': None,\n    'separator': None,\n    'separator_block_width': None}\n```\n\nFor a full explanation of each output option, please refer to section 2.2 of\nthe excellent \ni3bar documentation:\n[i3Bar Protocol](http://i3wm.org/docs/i3bar-protocol.html)",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/HarveyHunt/i3situation",
        "keywords": "python3 i3situation i3 i3wm i3status i3bar json",
        "license": "GPLv3",
        "maintainer": null,
        "maintainer_email": null,
        "name": "i3situation",
        "package_url": "https://pypi.org/project/i3situation/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/i3situation/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "https://github.com/HarveyHunt/i3situation"
        },
        "release_url": "https://pypi.org/project/i3situation/1.0.5/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "A replacement for i3status that allows for the use of plugins.",
        "version": "1.0.5"
    },
    "last_serial": 1301287,
    "releases": {
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cf1e6cf90956ee31ef35cca476610671",
                    "sha256": "5cfeb180093d066253959b08a9b871ea8468b9a50b8118743cda2a6fc6e47e48"
                },
                "downloads": -1,
                "filename": "i3situation-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "cf1e6cf90956ee31ef35cca476610671",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18809,
                "upload_time": "2014-02-10T20:46:56",
                "url": "https://files.pythonhosted.org/packages/86/b8/91f97caca4584ad1a6b8c6b579991400fe84ce2f819e3b0f22f0f6407bec/i3situation-1.0.1.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "affda5ed285bd88ccbd09111291dbe7a",
                    "sha256": "90a53e9eb2a9626a1fbe700e8e684483086eca3a1711ee710261f79700815cf6"
                },
                "downloads": -1,
                "filename": "i3situation-1.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "affda5ed285bd88ccbd09111291dbe7a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18882,
                "upload_time": "2014-02-10T20:59:42",
                "url": "https://files.pythonhosted.org/packages/83/3d/30a65ba7db00b90882ea1fad2ffa0da81b9788262e5e8fd360ce620204b4/i3situation-1.0.2.tar.gz"
            }
        ],
        "1.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2868b689454570559c9dce1330096751",
                    "sha256": "693ecc384922d21ed5d5e6469b5b495d82e637c555a6fc19b3b19c16ca898a56"
                },
                "downloads": -1,
                "filename": "i3situation-1.0.3.tar.gz",
                "has_sig": false,
                "md5_digest": "2868b689454570559c9dce1330096751",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 14947,
                "upload_time": "2014-03-26T17:58:20",
                "url": "https://files.pythonhosted.org/packages/88/34/bd50f6531ad382dadb9ba218c68bedf71c608304b8caae5328f290f76a78/i3situation-1.0.3.tar.gz"
            }
        ],
        "1.0.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "89144afa940c710dbc1b50b2e7c710ce",
                    "sha256": "216492ac0063764f68a5481c6ee6f0ad71b83b06abc1b3d1ea486e4df1fad7fb"
                },
                "downloads": -1,
                "filename": "i3situation-1.0.5.tar.gz",
                "has_sig": false,
                "md5_digest": "89144afa940c710dbc1b50b2e7c710ce",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19403,
                "upload_time": "2014-11-10T17:53:49",
                "url": "https://files.pythonhosted.org/packages/75/85/ffa62ffbeb637663be0bc5ed333ad127fb68cb313f69918599ddcff10f5d/i3situation-1.0.5.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "89144afa940c710dbc1b50b2e7c710ce",
                "sha256": "216492ac0063764f68a5481c6ee6f0ad71b83b06abc1b3d1ea486e4df1fad7fb"
            },
            "downloads": -1,
            "filename": "i3situation-1.0.5.tar.gz",
            "has_sig": false,
            "md5_digest": "89144afa940c710dbc1b50b2e7c710ce",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 19403,
            "upload_time": "2014-11-10T17:53:49",
            "url": "https://files.pythonhosted.org/packages/75/85/ffa62ffbeb637663be0bc5ed333ad127fb68cb313f69918599ddcff10f5d/i3situation-1.0.5.tar.gz"
        }
    ]
}