.. image:: ./logo.png
:align: center
:alt: Logo
.. image:: https://readthedocs.org/projects/mybar/badge/?version=latest
:target: https://mybar.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
######
mybar
######
*Craft highly customizable status bars with ease.*
Documentation
==============
Find all of **mybar**'s documentation `here <https://mybar.readthedocs.io>`_.
Introduction
=============
**mybar** is a code library and command line tool written in Python for making
status bars.
It aims to aid users in creating custom status bars with intuitive
controls that allow for the customization of every element.
.. code:: bash
$ python -m mybar --template '{uptime} [{cpu_usage}/{cpu_temp}] | {battery}'
Up 4d:14h:19m [CPU 03%/36C] | Bat 100CHG
Install mybar
==============
**mybar** supports Python 3.12+.
It can be installed from the `Python Package Index <https://pypi.org/project/mybar/>`_:
.. code:: bash
$ python -m pip install mybar
Use mybar in the command line
==============================
By default, **mybar** looks at config files to load its options.
**mybar** uses the `Scuff <https://github.com/akyuute/scuff>`_
language to process data from and write config files.
The default config file location is ``~/.config/mybar/mybar.conf``
Running the **mybar** command line tool using your default config file is as simple as:
.. code:: bash
$ python -m mybar
The first time you run **mybar**, it will check if you have a config file in the default location::
-- mybar --
The default config file at '/home/me/.config/mybar/mybar.conf' does not exist.
Would you like to make it now? [Y/n] y
Wrote new config file to '/home/me/.config/mybar/mybar.conf'
You can also skip writing a config file and **mybar** will start running a bar with default
parameters::
Would you like to make it now? [Y/n] n
mymachine|Up 4d:14h:54m|CPU 04%|36C|Mem 3.8G|/:50.8G|Bat 100CHG|wifi|2023-08-01 17:06:04
Note that any options passed to the command on the first run will be written to the new config file.
Command line examples
~~~~~~~~~~~~~~~~~~~~~~
See the `Documentation <https://mybar.readthedocs.io/en/latest/cli.html>`_
for details on all the command line arguments **mybar** accepts.
Let's see some examples of how to use **mybar** from the command line.
``--fields/-f`` Specify which Fields to show:
.. code:: bash
$ python -m mybar -f hostname disk_usage cpu_temp datetime
mymachine|/:88.3G|43C|2023-08-01 23:18:22
``--template/-t`` Use a custom format template:
.. code:: bash
$ python -m mybar -t '@{hostname}: ({uptime} | {cpu_usage}, {cpu_temp}) [{datetime}]'
@mymachine: (Up 1d:12h:17m | CPU 02%, 44C) [2023-08-01 23:31:26]
``--separator/-s`` Change the Field separator:
.. code:: bash
$ python -m mybar -f hostname uptime cpu_usage -s ' ][ '
mymachine ][ Up 1d:12h:11m ][ CPU 00%
``--count/-n`` Run the Bar a specific number of times:
.. code:: bash
$ python -m mybar -f hostname cpu_usage datetime -n 3 --break-lines
mymachine|CPU 00%|2023-08-01 23:40:26
mymachine|CPU 00%|2023-08-01 23:40:27
mymachine|CPU 00%|2023-08-01 23:40:28
$
``--refresh/-r`` Set the Bar's refresh rate:
.. code:: bash
$ python -m mybar -f hostname cpu_usage datetime -n 3 -r 10 --break-lines
mymachine|CPU 00%|2023-11-24 04:25:31
mymachine|CPU 00%|2023-11-24 04:25:41
mymachine|CPU 00%|2023-11-24 04:25:51
$
``--icons/-i`` Set new icons for each Field:
.. code:: bash
$ python -m mybar -i uptime='⏱️' cpu_temp='🔥' mem_usage='🧠' battery='🔋'
mymachine|⏱️4d:15h:7m|CPU 00%|🔥50C|🧠8.7G|/:80.7G|🔋100CHG|wifi|2023-11-10 17:19:20
``--options/-o`` Set arbitrary options for the bar or any Field:
.. code:: bash
$ python -m mybar -t 'Time: {datetime}' -o datetime.kwargs.fmt='%H:%M:%S.%f'
Time: 01:19:55.000229
``--config/-c`` Use a specific config file:
.. code:: bash
$ python -m mybar -c ~/.config/mybar/my_other_config_file.conf
Use mybar in a Python project
==============================
.. code:: python
>>> import mybar
Python API examples
~~~~~~~~~~~~~~~~~~~~
See the documentation for in-depth Python API usage.
Let's see some examples of how to use **mybar** using the Python API.
Get started with some default Fields:
.. code:: python
>>> some_default_fields = ['uptime', 'cpu_temp', 'battery', 'datetime']
>>> sep = ' ][ '
>>> using_defaults = mybar.Bar(fields=some_default_fields, separator=sep)
>>> using_defaults
Bar(fields=['uptime', 'cpu_temp', 'battery', ...])
>>> using_defaults.run()
Up 1d:10h:31m ][ 43C ][ Bat 100CHG ][ 2023-08-01 21:43:40
Load a Bar from a config file:
.. code:: python
>>> mybar.Bar.from_file('~/mycustombar.conf')
Bar(fields=['hostname', 'custom_field1', 'disk_usage', ...])
Use your own functions to bring your Bar to life:
.. code:: python
>>> def database_reader(query: str) -> str:
return read_from_database(query)
>>> my_field = mybar.Field(func=database_reader, kwargs={'query': '...'}, interval=60)
>>> my_field
Field(name='database_reader')
>>> bar = mybar.Bar(fields=[my_field, 'hostname', 'datetime'], refresh_rate=2)
Append new Fields to your Bar, as if it were a list:
.. code:: python
>>> bar.fields
(Field(name='database_reader'), Field(name='hostname'), Field(name='datetime'))
>>> bar.append(Field.from_default('uptime'))
Bar(fields=['database_reader', 'hostname', 'datetime', ...])
>>> bar.fields
(Field(name='database_reader'), Field(name='hostname'), Field(name='datetime'), Field(name='uptime'))
To customize **mybar** to your liking without using the `Python API`,
you can use `config file options <https://mybar.readthedocs.io/en/latest/configuration.html>`_
or `command line arguments <https://mybar.readthedocs.io/en/latest/cli.html>`_.
Concepts
=========
This section introduces the core concepts that aid in customizing **mybar**.
- *Bar*
The status bar.
- *Field*
A part of the `Bar` containing information, often called a "module"
by other status bar frameworks.
- *Field function*
The function a `Field` runs to determine what it should contain.
- *Refresh cycle*
The time it takes the `Bar` to run all its Fields and update its contents once.
- *Refresh rate*
How often the `Bar` updates what it says, in seconds per refresh.
- *Interval*
How often a `Field` runs its Field function, in seconds per cycle.
- *Separator*
A string that separates one `Field` from another
- *Format string*
A special string that controls how `Fields` and their contents are displayed.
- *Icon*
A string appearing with each `Field`, usually unique to each.
Raw data
{
"_id": null,
"home_page": "https://github.com/akyuute/mybar",
"name": "mybar",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "status bar, bar, command line, i3, threads, async, API",
"author": "akyuute",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7a/a9/605e9172d56249f8e84cec1653bc0f6645d9d7e9db70852f9508ca3e9ed7/mybar-0.14.1.tar.gz",
"platform": "Platform Independent",
"description": ".. image:: ./logo.png\n :align: center\n :alt: Logo\n\n.. image:: https://readthedocs.org/projects/mybar/badge/?version=latest\n :target: https://mybar.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n\n\n######\nmybar\n######\n\n*Craft highly customizable status bars with ease.*\n\n\nDocumentation\n==============\n\nFind all of **mybar**'s documentation `here <https://mybar.readthedocs.io>`_.\n\n\n\nIntroduction\n=============\n\n**mybar** is a code library and command line tool written in Python for making\nstatus bars.\n\nIt aims to aid users in creating custom status bars with intuitive\ncontrols that allow for the customization of every element.\n\n.. code:: bash\n\n $ python -m mybar --template '{uptime} [{cpu_usage}/{cpu_temp}] | {battery}'\n Up 4d:14h:19m [CPU 03%/36C] | Bat 100CHG\n\n\n\nInstall mybar\n==============\n\n**mybar** supports Python 3.12+.\n\nIt can be installed from the `Python Package Index <https://pypi.org/project/mybar/>`_:\n\n.. code:: bash\n\n $ python -m pip install mybar\n\n\n\nUse mybar in the command line\n==============================\n\nBy default, **mybar** looks at config files to load its options.\n**mybar** uses the `Scuff <https://github.com/akyuute/scuff>`_\nlanguage to process data from and write config files.\n\nThe default config file location is ``~/.config/mybar/mybar.conf``\n\nRunning the **mybar** command line tool using your default config file is as simple as:\n\n.. code:: bash\n\n $ python -m mybar\n\nThe first time you run **mybar**, it will check if you have a config file in the default location::\n\n -- mybar --\n The default config file at '/home/me/.config/mybar/mybar.conf' does not exist.\n Would you like to make it now? [Y/n] y\n Wrote new config file to '/home/me/.config/mybar/mybar.conf'\n\nYou can also skip writing a config file and **mybar** will start running a bar with default\nparameters::\n\n Would you like to make it now? [Y/n] n\n mymachine|Up 4d:14h:54m|CPU 04%|36C|Mem 3.8G|/:50.8G|Bat 100CHG|wifi|2023-08-01 17:06:04\n\nNote that any options passed to the command on the first run will be written to the new config file.\n\n\nCommand line examples\n~~~~~~~~~~~~~~~~~~~~~~\n\nSee the `Documentation <https://mybar.readthedocs.io/en/latest/cli.html>`_\nfor details on all the command line arguments **mybar** accepts.\n\nLet's see some examples of how to use **mybar** from the command line.\n\n\n``--fields/-f`` Specify which Fields to show:\n\n.. code:: bash\n\n $ python -m mybar -f hostname disk_usage cpu_temp datetime\n mymachine|/:88.3G|43C|2023-08-01 23:18:22\n\n\n``--template/-t`` Use a custom format template:\n\n.. code:: bash\n\n $ python -m mybar -t '@{hostname}: ({uptime} | {cpu_usage}, {cpu_temp}) [{datetime}]'\n @mymachine: (Up 1d:12h:17m | CPU 02%, 44C) [2023-08-01 23:31:26]\n\n\n``--separator/-s`` Change the Field separator:\n\n.. code:: bash\n\n $ python -m mybar -f hostname uptime cpu_usage -s ' ][ '\n mymachine ][ Up 1d:12h:11m ][ CPU 00%\n\n\n``--count/-n`` Run the Bar a specific number of times:\n\n.. code:: bash\n\n $ python -m mybar -f hostname cpu_usage datetime -n 3 --break-lines\n mymachine|CPU 00%|2023-08-01 23:40:26\n mymachine|CPU 00%|2023-08-01 23:40:27\n mymachine|CPU 00%|2023-08-01 23:40:28\n $\n\n\n``--refresh/-r`` Set the Bar's refresh rate:\n\n.. code:: bash\n\n $ python -m mybar -f hostname cpu_usage datetime -n 3 -r 10 --break-lines\n mymachine|CPU 00%|2023-11-24 04:25:31\n mymachine|CPU 00%|2023-11-24 04:25:41\n mymachine|CPU 00%|2023-11-24 04:25:51\n $\n\n\n``--icons/-i`` Set new icons for each Field:\n\n.. code:: bash\n\n $ python -m mybar -i uptime='\u23f1\ufe0f' cpu_temp='\ud83d\udd25' mem_usage='\ud83e\udde0' battery='\ud83d\udd0b'\n mymachine|\u23f1\ufe0f4d:15h:7m|CPU 00%|\ud83d\udd2550C|\ud83e\udde08.7G|/:80.7G|\ud83d\udd0b100CHG|wifi|2023-11-10 17:19:20\n\n\n``--options/-o`` Set arbitrary options for the bar or any Field:\n\n.. code:: bash\n\n $ python -m mybar -t 'Time: {datetime}' -o datetime.kwargs.fmt='%H:%M:%S.%f'\n Time: 01:19:55.000229\n\n\n``--config/-c`` Use a specific config file:\n\n.. code:: bash\n\n $ python -m mybar -c ~/.config/mybar/my_other_config_file.conf\n\n\n\nUse mybar in a Python project\n==============================\n\n.. code:: python\n\n >>> import mybar\n\n\nPython API examples\n~~~~~~~~~~~~~~~~~~~~\n\nSee the documentation for in-depth Python API usage.\n\nLet's see some examples of how to use **mybar** using the Python API.\n\nGet started with some default Fields:\n\n.. code:: python\n\n >>> some_default_fields = ['uptime', 'cpu_temp', 'battery', 'datetime']\n >>> sep = ' ][ '\n >>> using_defaults = mybar.Bar(fields=some_default_fields, separator=sep)\n >>> using_defaults\n Bar(fields=['uptime', 'cpu_temp', 'battery', ...])\n >>> using_defaults.run()\n Up 1d:10h:31m ][ 43C ][ Bat 100CHG ][ 2023-08-01 21:43:40\n\n\nLoad a Bar from a config file:\n\n.. code:: python\n\n >>> mybar.Bar.from_file('~/mycustombar.conf')\n Bar(fields=['hostname', 'custom_field1', 'disk_usage', ...])\n\n\nUse your own functions to bring your Bar to life:\n\n.. code:: python\n\n >>> def database_reader(query: str) -> str:\n return read_from_database(query)\n\n >>> my_field = mybar.Field(func=database_reader, kwargs={'query': '...'}, interval=60)\n >>> my_field\n Field(name='database_reader')\n >>> bar = mybar.Bar(fields=[my_field, 'hostname', 'datetime'], refresh_rate=2)\n\n\nAppend new Fields to your Bar, as if it were a list:\n\n.. code:: python\n\n >>> bar.fields\n (Field(name='database_reader'), Field(name='hostname'), Field(name='datetime'))\n >>> bar.append(Field.from_default('uptime'))\n Bar(fields=['database_reader', 'hostname', 'datetime', ...])\n >>> bar.fields\n (Field(name='database_reader'), Field(name='hostname'), Field(name='datetime'), Field(name='uptime'))\n\n\nTo customize **mybar** to your liking without using the `Python API`,\nyou can use `config file options <https://mybar.readthedocs.io/en/latest/configuration.html>`_\nor `command line arguments <https://mybar.readthedocs.io/en/latest/cli.html>`_.\n\n\n\nConcepts\n=========\n\nThis section introduces the core concepts that aid in customizing **mybar**.\n\n- *Bar*\n The status bar.\n- *Field*\n A part of the `Bar` containing information, often called a \"module\"\n by other status bar frameworks.\n- *Field function*\n The function a `Field` runs to determine what it should contain.\n- *Refresh cycle*\n The time it takes the `Bar` to run all its Fields and update its contents once.\n- *Refresh rate*\n How often the `Bar` updates what it says, in seconds per refresh.\n- *Interval*\n How often a `Field` runs its Field function, in seconds per cycle.\n- *Separator*\n A string that separates one `Field` from another\n- *Format string*\n A special string that controls how `Fields` and their contents are displayed.\n- *Icon*\n A string appearing with each `Field`, usually unique to each.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Craft highly customizable status bars with ease.",
"version": "0.14.1",
"project_urls": {
"GitHub: repo": "https://github.com/akyuute/mybar",
"Homepage": "https://github.com/akyuute/mybar",
"ReadTheDocs: documentation": "https://mybar.readthedocs.io"
},
"split_keywords": [
"status bar",
" bar",
" command line",
" i3",
" threads",
" async",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6766e0ca5e747e729a1ab6863c52ddf8c60404b432fd895f8a9d70acccad189a",
"md5": "d4f992bc3d412b771ad3c87f6eae8644",
"sha256": "ab86d81a331af19708b9fa20a91abea3528cdea7ae0315f1ec7e6c3caf9919e7"
},
"downloads": -1,
"filename": "mybar-0.14.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4f992bc3d412b771ad3c87f6eae8644",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 52620,
"upload_time": "2024-10-20T11:21:38",
"upload_time_iso_8601": "2024-10-20T11:21:38.668991Z",
"url": "https://files.pythonhosted.org/packages/67/66/e0ca5e747e729a1ab6863c52ddf8c60404b432fd895f8a9d70acccad189a/mybar-0.14.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7aa9605e9172d56249f8e84cec1653bc0f6645d9d7e9db70852f9508ca3e9ed7",
"md5": "705b823381a6ca6031e64c37db7a3d47",
"sha256": "1887722bf13fce08756f77f90f243789c415d0693ca68b9ab2a91413c28b4123"
},
"downloads": -1,
"filename": "mybar-0.14.1.tar.gz",
"has_sig": false,
"md5_digest": "705b823381a6ca6031e64c37db7a3d47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 50109,
"upload_time": "2024-10-20T11:21:39",
"upload_time_iso_8601": "2024-10-20T11:21:39.890336Z",
"url": "https://files.pythonhosted.org/packages/7a/a9/605e9172d56249f8e84cec1653bc0f6645d9d7e9db70852f9508ca3e9ed7/mybar-0.14.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 11:21:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akyuute",
"github_project": "mybar",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "psutil",
"specs": []
},
{
"name": "scuff",
"specs": []
}
],
"lcname": "mybar"
}
JSON
