# Lemonbar API
## Goal
Provide a simple to use, modern asynchronous Pythonic API for [Lemonbar](https://github.com/drscream/lemonbar-xft).
Grow upon the primitives that Lemonbar provides, to provide the end-user
of this library with extensive features.
## Getting Started
TODO
## How to use
### Creating a Lemonbar instance.
Firstly, you must create an instance of the Lemonbar class.
This class manages the low-level interactions with Lemonbar CLI and
abstracts them for you.
```python
from lemonbar import Lemonbar
from lemonbar.models import BarGeometry
from lemonbar.models.bar_placement import BarPlacement
async def main():
lemonbar = Lemonbar(
[
# modules... (Talked about later)
],
geometry=BarGeometry.build(height=50),
placement=BarPlacement.BOTTOM,
background_color="#111111",
foreground_color="#B2B2B2",
underline_color="#D8AD4C"
)
lemonbar.open()
await lemonbar.attach()
```
Above, you see how you create the Lemonbar instance.
As you can see all the passing of CLI arguments is abstracted away from you
in a nice and clean fashion. To add on to that, all types passed are validated
using Pydantic - Including colors and screen outputs.
Unfortunately, validation could not be made for font names.
#### Arguments
Default values are passed according to Lemonbar specification.
All you need to do to have Lemonbar running is define modules!
`modules: List[Module]`
Modules are an interface that the `Lemonbar` class knows how to communicate with.
They allow you to efficiently render data on to a bar.
`geometry: BarGeometry = None`
Allows you to define the size and offsets of the bar on the screen.
`outputs: Optional[List[MonitorId]] = None`
Allows you to define the monitors which you'd like the Lemonbar to be
displayed on. If nothing is passed, it will display on all screens.
`placement: BarPlacement = BarPlacement.TOP`
Allows you to define whether you want the bar to be placed on the top
of your screen or on the bottom.
`force_dock: bool = False`
Force docking without asking the window manager.
This is needed if the window manager isn't EWMH compliant.
`fonts: Optional[List[str]] = None`
Define the font to load into one of the five slots
See: [Lemonbar Options](https://github.com/drscream/lemonbar-xft#options)
`permanent: bool = False`
Make the bar permanent, don't exit after the standard input is closed.
`title: Optional[str] = ""`
Defines the WM_NAME of the bar. Meaning the title of the window.
`underline_width: int = 1`
Sets the underline width in pixels. The default is 1.
`background_color: Optional[str] = None`
Set the background color of the bar.
Since Pydantic is used, any of the following is valid:
[Pydantic Color Extension](https://docs.pydantic.dev/latest/usage/types/extra_types/color_types/)
1. name (e.g. "Black", "azure")
2. hexadecimal value (e.g. "0x000", "#FFFFFF", "7fffd4")
3. RGB/RGBA tuples (e.g. (255, 255, 255), (255, 255, 255, 0.5))
4. RGB/RGBA strings (e.g. "rgb(255, 255, 255)", "rgba(255, 255, 255, 0.5)")
5. HSL strings (e.g. "hsl(270, 60%, 70%)", "hsl(270, 60%, 70%, .5)")
`foreground_color: Optional[str] = None`
Same as background color but for the foreground.
`underline_color: Optional[str] = None`
Same as background color but for underlines.
`logger: logging.Logger = _DEFAULT_LOGGER`
The logger the Lemonbar class should use when logging information about
the execution of modules.
## Modules
A module is simply a class which defines the following:
1. What string to render
2. When to render
3. How to handle events (stdout from Lemonbar)
4. When to handle events
See one of the predefined modules for an example.
For example: [Clock](https://github.com/Heknon/lemonbar-api/blob/master/modules/clock.py)
Modules also have the option to define a `Module Configuration`, a configuration
is made up of the following fields:
`minimum_render_interval: datetime.timedelta = datetime.timedelta(seconds=1)`
The minimum amount of time to wait before calling `render()` on the
module again.
This is a guarantee that after **at least** `timedelta`, in the
next render cycle, the `render` method is called.
`force_render_on_event: bool = True`
Allows you to override `minimum_render_interval`
if the module processed an event. Meaning, if `minimum_render_interval` has not
passed but the module processed an event, `render` will be called.
`cache_exceptions: bool = True`
If true and an exception is raised in the module,
do not try immediately on the next render cycle to re-render but
wait `minimum_render_interval`.
## Formatters
This library also provides formatters for those defined
[here](https://github.com/drscream/lemonbar-xft#formatting) under
the `formatters` package.
You are more than welcome to take a look at it!
Raw data
{
"_id": null,
"home_page": "https://github.com/Heknon/lemonbar-api",
"name": "lemonbar",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "lemonbar,api,lemonbar-api,arch,linux",
"author": "Ori Harel",
"author_email": "oeharel@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/57/43/28373ac70feb3408038ab05b288cbc42cae22fdd2415f77b5b184c50fe2d/lemonbar-0.7.2.tar.gz",
"platform": null,
"description": "# Lemonbar API\n\n## Goal\n\nProvide a simple to use, modern asynchronous Pythonic API for [Lemonbar](https://github.com/drscream/lemonbar-xft).\n\nGrow upon the primitives that Lemonbar provides, to provide the end-user\nof this library with extensive features.\n\n## Getting Started\n\nTODO\n\n## How to use\n\n### Creating a Lemonbar instance.\n\nFirstly, you must create an instance of the Lemonbar class.\n\nThis class manages the low-level interactions with Lemonbar CLI and\nabstracts them for you.\n\n```python\nfrom lemonbar import Lemonbar\nfrom lemonbar.models import BarGeometry\nfrom lemonbar.models.bar_placement import BarPlacement\n\n\nasync def main():\n lemonbar = Lemonbar(\n [\n # modules... (Talked about later)\n ],\n geometry=BarGeometry.build(height=50),\n placement=BarPlacement.BOTTOM,\n background_color=\"#111111\",\n foreground_color=\"#B2B2B2\",\n underline_color=\"#D8AD4C\"\n )\n lemonbar.open()\n await lemonbar.attach()\n```\n\nAbove, you see how you create the Lemonbar instance.\n\nAs you can see all the passing of CLI arguments is abstracted away from you\nin a nice and clean fashion. To add on to that, all types passed are validated\nusing Pydantic - Including colors and screen outputs.\nUnfortunately, validation could not be made for font names.\n\n#### Arguments\n\nDefault values are passed according to Lemonbar specification.\n\nAll you need to do to have Lemonbar running is define modules!\n\n`modules: List[Module]`\n\nModules are an interface that the `Lemonbar` class knows how to communicate with.\n\nThey allow you to efficiently render data on to a bar.\n\n`geometry: BarGeometry = None`\n\nAllows you to define the size and offsets of the bar on the screen.\n\n`outputs: Optional[List[MonitorId]] = None`\n\nAllows you to define the monitors which you'd like the Lemonbar to be\ndisplayed on. If nothing is passed, it will display on all screens.\n\n`placement: BarPlacement = BarPlacement.TOP`\n\nAllows you to define whether you want the bar to be placed on the top\nof your screen or on the bottom.\n\n`force_dock: bool = False`\n\nForce docking without asking the window manager.\nThis is needed if the window manager isn't EWMH compliant.\n\n`fonts: Optional[List[str]] = None`\n\nDefine the font to load into one of the five slots\nSee: [Lemonbar Options](https://github.com/drscream/lemonbar-xft#options)\n\n`permanent: bool = False`\n\nMake the bar permanent, don't exit after the standard input is closed.\n\n`title: Optional[str] = \"\"`\n\nDefines the WM_NAME of the bar. Meaning the title of the window.\n\n`underline_width: int = 1`\n\nSets the underline width in pixels. The default is 1.\n\n`background_color: Optional[str] = None`\n\nSet the background color of the bar.\n\nSince Pydantic is used, any of the following is valid:\n[Pydantic Color Extension](https://docs.pydantic.dev/latest/usage/types/extra_types/color_types/)\n\n1. name (e.g. \"Black\", \"azure\")\n2. hexadecimal value (e.g. \"0x000\", \"#FFFFFF\", \"7fffd4\")\n3. RGB/RGBA tuples (e.g. (255, 255, 255), (255, 255, 255, 0.5))\n4. RGB/RGBA strings (e.g. \"rgb(255, 255, 255)\", \"rgba(255, 255, 255, 0.5)\")\n5. HSL strings (e.g. \"hsl(270, 60%, 70%)\", \"hsl(270, 60%, 70%, .5)\")\n\n`foreground_color: Optional[str] = None`\n\nSame as background color but for the foreground.\n\n`underline_color: Optional[str] = None`\n\nSame as background color but for underlines.\n\n`logger: logging.Logger = _DEFAULT_LOGGER`\n\nThe logger the Lemonbar class should use when logging information about\nthe execution of modules.\n\n## Modules\n\nA module is simply a class which defines the following:\n\n1. What string to render\n2. When to render\n3. How to handle events (stdout from Lemonbar)\n4. When to handle events\n\nSee one of the predefined modules for an example.\n\nFor example: [Clock](https://github.com/Heknon/lemonbar-api/blob/master/modules/clock.py)\n\nModules also have the option to define a `Module Configuration`, a configuration\nis made up of the following fields:\n\n`minimum_render_interval: datetime.timedelta = datetime.timedelta(seconds=1)`\n\nThe minimum amount of time to wait before calling `render()` on the\nmodule again.\n\nThis is a guarantee that after **at least** `timedelta`, in the\nnext render cycle, the `render` method is called.\n\n`force_render_on_event: bool = True`\n\nAllows you to override `minimum_render_interval`\nif the module processed an event. Meaning, if `minimum_render_interval` has not\npassed but the module processed an event, `render` will be called.\n\n`cache_exceptions: bool = True`\n\nIf true and an exception is raised in the module,\ndo not try immediately on the next render cycle to re-render but\nwait `minimum_render_interval`.\n\n## Formatters\n\nThis library also provides formatters for those defined\n[here](https://github.com/drscream/lemonbar-xft#formatting) under\nthe `formatters` package.\n\nYou are more than welcome to take a look at it!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python API for interacting with Lemonbar",
"version": "0.7.2",
"project_urls": {
"Download": "https://github.com/Heknon/lemonbar-api/archive/refs/tags/v0.7.2.tar.gz",
"Homepage": "https://github.com/Heknon/lemonbar-api"
},
"split_keywords": [
"lemonbar",
"api",
"lemonbar-api",
"arch",
"linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "574328373ac70feb3408038ab05b288cbc42cae22fdd2415f77b5b184c50fe2d",
"md5": "2505167734033b6b28817fd160d37a75",
"sha256": "0a417690494c9618f7ad35101df428dd446e8a5d364aa23ab9d5ce96f3cf8a63"
},
"downloads": -1,
"filename": "lemonbar-0.7.2.tar.gz",
"has_sig": false,
"md5_digest": "2505167734033b6b28817fd160d37a75",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13197,
"upload_time": "2023-07-22T13:44:10",
"upload_time_iso_8601": "2023-07-22T13:44:10.702674Z",
"url": "https://files.pythonhosted.org/packages/57/43/28373ac70feb3408038ab05b288cbc42cae22fdd2415f77b5b184c50fe2d/lemonbar-0.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-22 13:44:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Heknon",
"github_project": "lemonbar-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "lemonbar"
}
JSON
