{"id":25231387,"url":"https://github.com/dimentium/sketchybar-py","last_synced_at":"2025-10-26T07:32:48.509Z","repository":{"id":274705903,"uuid":"923810070","full_name":"Dimentium/sketchybar-py","owner":"Dimentium","description":"A Python library for configuring SketchyBar","archived":false,"fork":false,"pushed_at":"2025-02-08T22:30:49.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T23:20:25.376Z","etag":null,"topics":["sketchybar"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dimentium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-28T21:25:38.000Z","updated_at":"2025-02-08T22:30:52.000Z","dependencies_parsed_at":"2025-01-28T22:37:07.867Z","dependency_job_id":null,"html_url":"https://github.com/Dimentium/sketchybar-py","commit_stats":null,"previous_names":["dimentium/sketchybar-py"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimentium%2Fsketchybar-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimentium%2Fsketchybar-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimentium%2Fsketchybar-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dimentium%2Fsketchybar-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dimentium","download_url":"https://codeload.github.com/Dimentium/sketchybar-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238292419,"owners_count":19447977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["sketchybar"],"created_at":"2025-02-11T12:28:35.351Z","updated_at":"2025-10-26T07:32:43.161Z","avatar_url":"https://github.com/Dimentium.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sketchybar-py\n\nA Python library for configuring [SketchyBar](https://github.com/FelixKratz/SketchyBar) - a highly customizable macOS status bar replacement. This library allows you to configure your SketchyBar using Python instead of traditional bash scripting, making the configuration process more intuitive and maintainable.\n\n## Features\n\n- Configure SketchyBar using Python syntax instead of bash\n- Define bar items as functions, combining creation and behavior in one place\n- More structured and maintainable configuration approach\n- Native Python integration with SketchyBar's functionality\n- No external dependencies\n\n## Prerequisites\n\n- macOS\n- [SketchyBar](https://github.com/FelixKratz/SketchyBar) installed\n- Python 3.10+ or [uv](https://github.com/astral-sh/uv)\n\n## Installation\n\n### Option 1: Using with uv shebang (Recommended)\n\nAdd the following shebang declaration to the top of your script:\n\n```python\n#!/usr/bin/env -S uv run -q\n# /// script\n# requires-python = \"\u003e=3.10\"\n# dependencies = [\n#     \"sketchybar-py\"\n# ]\n# ///\n```\n\n### Option 2: Manual Import\n\n`pip install sketchybar-py`\n\n## Usage\n\nAdd the following line to your `sketchybarrc`:\n```bash\n$CONFIG_DIR/sketchybar.py\n```\n\nMake the Python configuration file executable:\n```bash\nchmod +x sketchybar.py\n```\n\n## Example\n\nHere's a complete example of `sketchybar.py` showing how to configure SketchyBar using sketchybar-py (with uv):\n\n```python\n#!/usr/bin/env -S uv run -q\n# /// script\n# requires-python = \"\u003e=3.10\"\n# dependencies = [\n#     \"sketchybar-py\"\n# ]\n# ///\n\nfrom sketchybar_py import Sketchybar\n\nglobal_bar_properties = {\n    \"position\": \"top\",\n    \"height\": \"24\",\n    \"blur_radius\": \"0\",\n    \"color\": \"0x44444444\",\n}\n\ndefault_settings_for_new_items = {\n    \"padding_left\": 5,\n    \"padding_right\": 5,\n    \"icon.font\": \"FiraCode Nerd Font:Bold:12.0\",\n    \"label.font\": \"FiraCode Nerd Font:Bold:12.0\",\n    \"icon.color\": \"0xffffffff\",\n    \"label.color\": \"0xffffffff\",\n    \"icon.padding_left\": 4,\n    \"icon.padding_right\": 4,\n    \"label.padding_left\": 4,\n    \"label.padding_right\": 4,\n}\n\n\nclass MyAwesomeSketchyBar(Sketchybar):\n    def post_init(self):\n        print(\"Init...\")\n        self.do(\"--bar\", global_bar_properties)\n        self.do(\"--default\", default_settings_for_new_items)\n        self.do(\"--hotload\", \"true\")\n        self.autoload()\n\n    @Sketchybar.item(\n        enabled=True,\n        position=\"left\",\n        icon=\"\",\n        properties={\"label.drawing\": \"off\"}\n    )\n    def l0_chevron(self):\n        pass\n\n    @Sketchybar.item(\n        position=\"left\",\n        icon=\"++\",\n        subscribe=[\"front_app_switched\"],\n        properties={\"icon.drawing\": \"off\"},\n    )\n    def l1_front_app(self):\n        if self.sender == \"front_app_switched\":\n            self.label = self.info\n\n    @Sketchybar.item(\n        position=\"right\",\n        update_freq=60,\n        subscribe=[\"system_woke\", \"power_source_change\"],\n    )\n    def r2_battery(self):\n        percentage = (\n            self.run(\"pmset -g batt | grep -Eo '\\\\d+%'\").stdout.strip().rstrip(\"%\")\n        )\n        charging = \"AC Power\" in self.run(\"pmset -g batt\").stdout\n        self.icon = \"\" if charging else \"󱟟\"\n        self.label = percentage + \"%\"\n\n    @Sketchybar.item(\n        position=\"right\",\n        update_freq=10,\n        properties={\"icon.drawing\": \"off\"}\n    )\n    def r1_clock(self):\n        now = self.run(\"date '+%d/%m %H:%M'\").stdout\n        self.label = now\n\n    @Sketchybar.item(\n        position=\"center\",\n        properties={\"icon.drawing\": \"off\"},\n        label=\"notch_placeholder_0\",\n    )\n    def c0_notch(self):\n        pass\n\n\nif __name__ == \"__main__\":\n    sb = MyAwesomeSketchyBar()\n```\n\n## API Reference\n\n### Sketchybar Class\nMain class for configuring SketchyBar.\n\n#### Methods\n- `post_init()`: Contains initial configuration settings and setup. Also item initialization occurs here.\n- `do()`: Executes sketchybar with provided arguments.\n- `run()`: Executes any shell command with arguments.\n- `autoload()`: Finds *all* decorated methods in the class and runs them in *alphabetical* order.\n  Alternatively, you can call them manually in `post_init()` in your preferred order.\n\n### Decorators\n- `@Sketchybar.item`: Define a new bar item with properties\n\n#### Item Properties\nCommon properties that can be used in item definitions:\n- `enabled`: True or False - used for `autoload()` control\n- `position`: \"left\", \"right\", or \"center\".\n- `update_freq`: Update frequency in seconds.\n- `subscribe`: List of events to subscribe to.\n- `properties`: Dictionary of additional properties.\n- You can use any sketchybar item properties.\n\n## License\n\nThis project is licensed under the MIT License\n\n## Author\n\nDmitry Kuznetsov\n- GitHub: [@dimentium](https://github.com/dimentium)\n\n## Related\n\n- [SketchyBar](https://github.com/FelixKratz/SketchyBar) - The original SketchyBar project\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimentium%2Fsketchybar-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimentium%2Fsketchybar-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimentium%2Fsketchybar-py/lists"}