{"id":19639004,"url":"https://github.com/homebysix/docklib","last_synced_at":"2025-04-09T12:09:46.773Z","repository":{"id":31708838,"uuid":"128664866","full_name":"homebysix/docklib","owner":"homebysix","description":"Python module intended to assist IT administrators with manipulation of the macOS Dock.","archived":false,"fork":false,"pushed_at":"2024-04-13T23:01:32.000Z","size":109,"stargazers_count":112,"open_issues_count":1,"forks_count":16,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-14T08:52:20.599Z","etag":null,"topics":["defaults","dock","docklib","dockutil","hacktoberfest","macadmin","macadmins","macos","plistbuddy","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/homebysix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2018-04-08T17:22:46.000Z","updated_at":"2024-06-21T15:21:35.912Z","dependencies_parsed_at":"2024-06-21T15:35:58.068Z","dependency_job_id":null,"html_url":"https://github.com/homebysix/docklib","commit_stats":{"total_commits":101,"total_committers":7,"mean_commits":"14.428571428571429","dds":"0.39603960396039606","last_synced_commit":"9045fe65ba42a314424d153528040f9f4f3db852"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebysix%2Fdocklib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebysix%2Fdocklib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebysix%2Fdocklib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebysix%2Fdocklib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/homebysix","download_url":"https://codeload.github.com/homebysix/docklib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036067,"owners_count":21037092,"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":["defaults","dock","docklib","dockutil","hacktoberfest","macadmin","macadmins","macos","plistbuddy","python"],"created_at":"2024-11-11T12:43:32.060Z","updated_at":"2025-04-09T12:09:46.756Z","avatar_url":"https://github.com/homebysix.png","language":"Python","readme":"# docklib\n\nThis is a Python module intended to assist IT administrators with manipulation of the macOS Dock.\n\nOriginally created as a [Gist](https://gist.github.com/gregneagle/5c422d709c93615341a21009f800222e) by @gregneagle, this fork has been modified to include support for some additional Dock features, and has been packaged for multiple distribution options.\n\n## docklib or dockutil?\n\nThe very capable [dockutil](https://github.com/kcrawford/dockutil) tool serves a similar function to docklib. Why would Mac admins choose one over the other?\n\nThe primary benefit of **docklib** is that it allows the Dock to be manipulated in a \"Pythonic\" way. By parsing the Dock configuration into an object with attributes and data structures that can be modified using familiar functions like `.append()` and `.insert()`, docklib aims to make Python scripters feel at home.\n\nIn contrast, **dockutil** behaves more like a shell command-line utility and is written in Swift. This makes dockutil a good choice if you don't have a 'management python' or you're more comfortable writing user setup scripts in bash or zsh. Dockutil also has an `--allhomes` argument that allows Dock configuration for all users to be modified at the same time. Docklib isn't designed for this, instead focusing on configuring the Dock for the user that is currently logged in (for example, via an [outset](https://github.com/macadmins/outset) `login-once` or `login-every` script). [Here's](https://appleshare.it/posts/use-dockutil-in-a-script/) a great article to get you started with dockutil, if that sounds like what you're after.\n\n## Installation\n\nThere are multiple methods of installing docklib, depending on how you plan to use it.\n\n### Package installer\n\nYou can use the included __build_pkg.sh__ script to build a macOS installer .pkg file. You can use this package to install docklib on your own Mac, or deploy the package using a tool like Jamf or Munki to install docklib on managed devices.\n\nTo run the script, `cd` to a local clone of this repository, then run:\n\n```\n./build_pkg.sh\n```\n\nThe resulting pkg will be built in a temporary folder and shown in the Finder.\n\n__NOTE__: The default install destination is __/Library/Python/2.7/site-packages/docklib__, which makes docklib available to the built-in macOS Python 2.7 framework. If you leverage a different Python installation, you'll need to modify this path in the __build_pkg.sh__ script prior to building the installer package.\n\n### Pip\n\nDocklib has been published to PyPI in order to make it available for installation using pip.\n\n```\npip install docklib\n```\n\nThis method is not intended to be used directly on managed devices, but it could be leveraged alongside a custom Python framework (like one built with [macadmins/python](https://github.com/macadmins/python) or [relocatable-python](https://github.com/gregneagle/relocatable-python)) using a requirements file.\n\n### Managed Python\n\nDocklib is included in the \"recommended\" flavor of the [macadmins/python](https://github.com/macadmins/python) release package. Installing this package and using `#!/usr/local/managed_python3` for your docklib script shebang may be the most self-contained and future-proof way to deploy docklib.\n\n### Manual\n\nAnother method of using docklib is to simply place the docklib.py file in the same location as the Python script(s) you use to manipulate the macOS dock. Some examples of such scripts are included below.\n\n## Examples\n\n### Add Microsoft Word to the right side of the Dock\n\n```python\nfrom docklib import Dock\n\ndock = Dock()\nitem = dock.makeDockAppEntry(\"/Applications/Microsoft Word.app\")\ndock.items[\"persistent-apps\"].append(item)\ndock.save()\n```\n\n### Add Microsoft Word to the left side of the Dock\n\n```python\nfrom docklib import Dock\n\ndock = Dock()\nitem = dock.makeDockAppEntry(\"/Applications/Microsoft Word.app\")\ndock.items[\"persistent-apps\"] = [item] + dock.items[\"persistent-apps\"]\ndock.save()\n```\n\n### Replace Mail.app with Outlook in the Dock\n\n```python\nfrom docklib import Dock\n\ndock = Dock()\ndock.replaceDockEntry(\"/Applications/Microsoft Outlook.app\", \"Mail\")\ndock.save()\n```\n\n### Remove Calendar from the Dock\n\n```python\nfrom docklib import Dock\n\ndock = Dock()\ndock.removeDockEntry(\"Calendar\")\ndock.save()\n```\n\n### Display the current orientation of the Dock\n\n```python\nfrom docklib import Dock\n\ndock = Dock()\nprint(dock.orientation)\n```\n\n### Make the Dock display on the left, and enable autohide\n\n```python\nfrom docklib import Dock\n\ndock = Dock()\ndock.orientation = \"left\"\ndock.autohide = True\ndock.save()\n```\n\n### Add the Documents folder to the right side of the Dock\n\nDisplays as a stack to the right of the Dock divider, sorted by modification date, that expands into a fan when clicked. This example checks for the existence of the Documents item and only adds it if it's not already present.\n\n```python\nimport os\nfrom docklib import Dock\n\ndock = Dock()\nif dock.findExistingEntry(\"Documents\", section=\"persistent-others\") == -1:\n    item = dock.makeDockOtherEntry(\n        os.path.expanduser(\"~/Documents\"), arrangement=3, displayas=1, showas=1\n    )\n    dock.items[\"persistent-others\"] = [item] + dock.items[\"persistent-others\"]\n    dock.save()\n```\n### Add a URL to the right side of the Dock\n\nDisplays as a globe to the right of the Dock divider, that launches a URL in the default browser when clicked. This example checks for the existence of the Documents item and only adds it if it's not already present.\n\n```python\nimport os\nfrom docklib import Dock\n\ndock = Dock()\nif dock.findExistingEntry(\"GitHub\", section=\"persistent-others\") == -1:\n    item = dock.makeDockOtherURLEntry(\"https://www.github.com/\", label=\"GitHub\")\n    dock.items[\"persistent-others\"] = [item] + dock.items[\"persistent-others\"]\n    dock.save()\n```\n\n### Specify a custom Dock for the local IT technician account\n\n```python\nimport os\nfrom docklib import Dock\n\ntech_dock = [\n    \"/Applications/Google Chrome.app\",\n    \"/Applications/App Store.app\",\n    \"/Applications/Managed Software Center.app\",\n    \"/Applications/System Preferences.app\",\n    \"/Applications/Utilities/Activity Monitor.app\",\n    \"/Applications/Utilities/Console.app\",\n    \"/Applications/Utilities/Disk Utility.app\",\n    \"/Applications/Utilities/Migration Assistant.app\",\n    \"/Applications/Utilities/Terminal.app\",\n]\ndock = Dock()\ndock.items[\"persistent-apps\"] = []\nfor item in tech_dock:\n    if os.path.exists(item):\n        item = dock.makeDockAppEntry(item)\n        dock.items[\"persistent-apps\"].append(item)\ndock.save()\n```\n\nOr if you prefer using a [list comprehension](https://www.pythonforbeginners.com/basics/list-comprehensions-in-python):\n\n```python\nimport os\nfrom docklib import Dock\n\ntech_dock = [\n    \"/Applications/Google Chrome.app\",\n    \"/Applications/App Store.app\",\n    \"/Applications/Managed Software Center.app\",\n    \"/Applications/System Preferences.app\",\n    \"/Applications/Utilities/Activity Monitor.app\",\n    \"/Applications/Utilities/Console.app\",\n    \"/Applications/Utilities/Disk Utility.app\",\n    \"/Applications/Utilities/Migration Assistant.app\",\n    \"/Applications/Utilities/Terminal.app\",\n]\ndock = Dock()\ndock.items[\"persistent-apps\"] = [\n    dock.makeDockAppEntry(item) for item in tech_dock if os.path.exists(item)\n]\ndock.save()\n```\n\n## More information\n\nFor more examples and tips for creating your docklib script, see my guides on:\n\n- [Writing Resilient Docklib Scripts](https://www.elliotjordan.com/posts/resilient-docklib/)\n- [Deploying and running docklib scripts using Outset](https://www.elliotjordan.com/posts/docklib-outset/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomebysix%2Fdocklib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhomebysix%2Fdocklib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomebysix%2Fdocklib/lists"}