Merge pull request #34 from homebysix/1.3.0-dev

1.3.0 merge to main

Author: homebysix

CHANGELOG.md

@@ -5,7 +5,40 @@ All notable changes to this project will be documented in this file. This projec
 
 ## [Unreleased]
 
-Nothing yet.
+The focus of this release is to make docklib functions less focused on dock item labels, since labels can change depending on the user's selected language. (See [#32](https://github.com/homebysix/docklib/issues/32) for details.)
+
+### Added
+
+- A new `findExistingEntry` function that can find dock items based on several attributes.
+
+    The default behavior of `findExistingEntry` is to match the provided string on (in order of preference):
+
+    1. label
+    2. path
+    3. filename with extension
+    4. filename without extension
+
+    The `match_on` parameter can be specified to select only one of those attributes to match, if desired. See the `findExistingEntry` function docstring for available parameters and values.
+
+### Changed
+
+- The `findExistingLabel` function is now simply a pointer to the new `findExistingEntry` function. `findExistingLabel` will be maintained for backward-compatibility.
+
+- The `removeDockEntry` function has a new `match_on` parameter that mirrors the same parameter in `findExistingEntry`. Default behavior is to match on the same attributes listed above, in the same order of preference. (This is a change in behavior from previous versions of docklib. If you prefer to continue removing items solely based on label, you should specify `match_on="label"` in your function call.)
+
+- The `replaceDockEntry` function has two new parameters:
+    - `match_str`, which allows specifying the item intended to be replaced in the dock (replaces the now deprecated `label` parameter).
+    - `match_on`, which mirrors the same parameter in `findExistingEntry`. Default behavior is to match on the same attributes listed above, in the same order of preference.
+
+### Deprecated
+
+- The `label` parameter of `replaceDockEntry` is deprecated, and it's encouraged to use `match_str` instead. This allows existing items to be replaced based on multiple attributes rather than just label. As stated above, this makes dock customization scripts more reliable in multilingual environments.
+
+    A warning has been added that alerts administrators to this deprecation.
+
+- **This is the last release of docklib that will support Python 2.** Future releases will only be tested in Python 3.
+
+    If you haven't started bundling a Python 3 runtime for your management tools, [this blog article from @scriptingosx](https://scriptingosx.com/2020/02/wrangling-pythons/) is a good read. Also: a reminder that docklib is already included in the "recommended" flavor of the [macadmins/python](https://github.com/macadmins/python) packages.
 
 ## [1.2.1] - 2021-03-01
 
@@ -15,7 +48,7 @@ Nothing yet.
 
 ### Fixed
 
-- Fixed issue preventing `findExistingLabel()` from finding URLs' labels
+- Fixed issue preventing `findExistingLabel` from finding URLs' labels
 
 ## [1.2.0] - 2020-10-15
 
@@ -25,7 +58,7 @@ Nothing yet.
 
 - Published docklib to PyPI so that administrators can manage it with `pip` and more easily bundle it in [custom Python frameworks](https://github.com/macadmins/python). Adjusted repo file structure to match Python packaging standards.
 - Created __build_pkg.sh__ script for creation of macOS package installer.
-- Added `findExistingURL()` and `removeDockURLEntry()` functions for handling URL items.
+- Added `findExistingURL` and `removeDockURLEntry` functions for handling URL items.
 - Created a few basic unit tests.
 
 ### Changed

README.md

@@ -32,6 +32,10 @@ pip install docklib
 
 This 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.
 
+### Managed Python
+
+Docklib 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.
+
 ### Manual
 
 Another 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.
@@ -109,7 +113,7 @@ import os
 from docklib import Dock
 
 dock = Dock()
-if dock.findExistingLabel("Documents", section="persistent-others") == -1:
+if dock.findExistingEntry("Documents", section="persistent-others") == -1:
     item = dock.makeDockOtherEntry(
         os.path.expanduser("~/Documents"), arrangement=3, displayas=1, showas=1
     )
@@ -125,7 +129,7 @@ import os
 from docklib import Dock
 
 dock = Dock()
-if dock.findExistingLabel("GitHub", section="persistent-others") == -1:
+if dock.findExistingEntry("GitHub", section="persistent-others") == -1:
     item = dock.makeDockOtherURLEntry("https://www.github.com/", label="GitHub")
     dock.items["persistent-others"] = [item] + dock.items["persistent-others"]
     dock.save()

RELEASING.md

@@ -17,7 +17,7 @@
 
 1. Run docklib unit tests and fix any errors:
 
-        /usr/local/munki/munki-python -m unittest -v tests/unit.py
+        managed_python3 -m unittest -v tests/unit.py
 
 1. Build a new distribution package:
 
@@ -30,9 +30,9 @@
 
 1. View resulting project on test.pypi.org and make sure it looks good.
 
-1. Install test docklib in Munki Python on a test Mac:
+1. Install test docklib in MacAdmins Python on a test Mac:
 
-        /usr/local/munki/Python.framework/Versions/Current/bin/python3 -m pip install --upgrade -i https://test.pypi.org/simple/ docklib
+        managed_python3 -m pip install --upgrade -i https://test.pypi.org/simple/ docklib
 
 1. Perform tests - manual for now.
 
@@ -42,9 +42,9 @@
 
 1. View resulting project on pypi.org and make sure it looks good.
 
-1. Install production docklib in Munki Python on a test Mac:
+1. Install production docklib in MacAdmins Python on a test Mac:
 
-        /usr/local/munki/Python.framework/Versions/Current/bin/python3 -m pip install --upgrade docklib
+        managed_python3 -m pip install --upgrade docklib
 
 1. Build new installer package using __build_pkg.sh__:
 

docklib/__init__.py

@@ -1,3 +1,3 @@
 from .docklib import *
 
-__version__ = "1.2.1"
+__version__ = "1.3.0"

docklib/docklib.py

@@ -2,13 +2,26 @@
 
 # pylint: disable=C0103
 
-"""Python module intended to assist IT administrators with manipulation of the macOS Dock."""
+"""Python module intended to assist IT administrators with manipulation of the macOS Dock.
+
+See project details on GitHub: https://github.com/homebysix/docklib
+"""
 
 import os
 import subprocess
 from distutils.version import LooseVersion
 from platform import mac_ver
 
+try:
+    # Python 3
+    from urllib.parse import unquote, urlparse
+except ImportError:
+    # Python 2
+    from urllib import unquote
+
+    from urlparse import urlparse
+
+
 # pylint: disable=E0611
 from Foundation import (
     NSURL,
@@ -17,7 +30,6 @@
     CFPreferencesSetAppValue,
 )
 
-
 # pylint: enable=E0611
 
 
@@ -34,6 +46,7 @@ class Dock:
     _DOCK_PLIST = os.path.expanduser("~/Library/Preferences/com.apple.dock.plist")
     _DOCK_LAUNCHAGENT_ID = "com.apple.Dock.agent"
     _DOCK_LAUNCHAGENT_FILE = "/System/Library/LaunchAgents/com.apple.Dock.plist"
+    # TODO: static-apps and static-others
     _SECTIONS = ["persistent-apps", "persistent-others"]
     _MUTABLE_KEYS = [
         "autohide",
@@ -97,6 +110,8 @@ def save(self):
             except Exception:
                 raise DockError
         for key in self._MUTABLE_KEYS:
+            # Python doesn't support hyphens in attribute names, so convert
+            # to/from underscores as needed.
             if getattr(self, key.replace("-", "_")) is not None:
                 try:
                     CFPreferencesSetAppValue(
@@ -113,39 +128,82 @@ def save(self):
         subprocess.call(["/bin/launchctl", "load", self._DOCK_LAUNCHAGENT_FILE])
         subprocess.call(["/bin/launchctl", "start", self._DOCK_LAUNCHAGENT_ID])
 
-    def findExistingLabel(self, test_label, section="persistent-apps"):
-        """Returns index of item with label matching test_label or -1 if not
-        found."""
+    def findExistingEntry(self, match_str, match_on="any", section="persistent-apps"):
+        """Returns index of a Dock item identified by match_str or -1 if no item
+        is found.
+
+        match_on values:
+            label: match dock items with this file-label or label
+                (e.g. Safari)
+                NOTE: Labels can vary depending on the user's selected language.
+            path: match dock items with this path on disk
+                (e.g. /System/Applications/Safari.app)
+            name_ext: match dock items with this file/folder basename
+                (e.g. Safari.app)
+            name_noext: match dock items with this basename, without extension
+                (e.g. Safari)
+            any: Try all the criteria above in order, and return the first result.
+        """
         section_items = self.items[section]
         if section_items:
-            # Most dock items use "file-label", but URLs use "label"
-            for label_key in ("file-label", "label"):
+            # Determine the order of attributes to match on.
+            if match_on == "any":
+                match_ons = ["label", "path", "name_ext", "name_noext"]
+            else:
+                match_ons = [match_on]
+
+            # Iterate through match criteria (ensures a full scan of the Dock
+            # for each criterion, if matching on "any").
+            for m in match_ons:
+                # Iterate through items in section
                 for index, item in enumerate(section_items):
-                    if item["tile-data"].get(label_key) == test_label:
+                    url = item["tile-data"].get("file-data", {}).get("_CFURLString", "")
+                    path = unquote(urlparse(url.rstrip("/")).path)
+                    name_ext = os.path.basename(path)
+                    name_noext = os.path.splitext(name_ext)[0]
+
+                    if m == "label":
+                        # Most dock items use "file-label", but URLs use "label"
+                        for label_key in ("file-label", "label"):
+                            if item["tile-data"].get(label_key) == match_str:
+                                return index
+                    elif m == "path" and path == match_str:
+                        return index
+                    elif m == "name_ext" and name_ext == match_str:
+                        return index
+                    elif m == "name_noext" and name_noext == match_str:
                         return index
 
         return -1
 
-    def findExistingURL(self, test_url):
-        """Returns index of item with URL matching test_url or -1 if not
+    def findExistingLabel(self, match_str, section="persistent-apps"):
+        """Points to findExistingEntry, maintained for compatibility."""
+        return self.findExistingEntry(match_str, match_on="label", section=section)
+
+    def findExistingURL(self, match_url):
+        """Returns index of item with URL matching match_url or -1 if not
         found."""
         section_items = self.items["persistent-others"]
         if section_items:
             for index, item in enumerate(section_items):
                 if item["tile-data"].get("url"):
-                    if item["tile-data"]["url"]["_CFURLString"] == test_url:
+                    if item["tile-data"]["url"]["_CFURLString"] == match_url:
                         return index
 
         return -1
 
-    def removeDockEntry(self, label, section=None):
-        """Removes a Dock entry with matching label, if any."""
+    def removeDockEntry(self, match_str, match_on="any", section=None):
+        """Removes a Dock entry identified by "match_str", if any. Defaults to
+        matching "match_str" by the "any" criteria order listed in the
+        findExistingEntry docstring."""
         if section:
             sections = [section]
         else:
             sections = self._SECTIONS
         for sect in sections:
-            found_index = self.findExistingLabel(label, section=sect)
+            found_index = self.findExistingEntry(
+                match_str, match_on=match_on, section=sect
+            )
             if found_index > -1:
                 del self.items[sect][found_index]
 
@@ -155,22 +213,45 @@ def removeDockURLEntry(self, url):
         if found_index > -1:
             del self.items["persistent-others"][found_index]
 
-    def replaceDockEntry(self, thePath, label=None, section="persistent-apps"):
+    def replaceDockEntry(
+        self,
+        newpath,
+        match_str=None,
+        match_on="any",
+        label=None,  # deprecated
+        section="persistent-apps",
+    ):
         """Replaces a Dock entry.
 
-        If label is None, then a label is derived from the item path.
-        The new entry replaces an entry with the given or derived label
+        If match_str is provided, it will be used to match the item to be replaced.
+        See the findExistingEntry function docstring for possible "match_on" values.
+
+        If match_str is not provided, the item to be replaced will be derived from
+        the newpath filename, without extension.
+
+        The "label" parameter is deprecated in favor of match_str and will be
+        removed someday.
         """
         if section == "persistent-apps":
-            new_item = self.makeDockAppEntry(thePath)
+            newitem = self.makeDockAppEntry(newpath)
         else:
-            new_item = self.makeDockOtherEntry(thePath)
-        if new_item:
-            if not label:
-                label = os.path.splitext(os.path.basename(thePath))[0]
-            found_index = self.findExistingLabel(label, section=section)
-            if found_index > -1:
-                self.items[section][found_index] = new_item
+            newitem = self.makeDockOtherEntry(newpath)
+        if not newitem:
+            return
+        if label:
+            print(
+                "WARNING: The label parameter is deprecated. Use match_str instead. "
+                "Details: https://github.com/homebysix/docklib/issues/32"
+            )
+            match_str = label
+            match_on = "label"
+        if not match_str:
+            match_str = os.path.splitext(os.path.basename(newpath))[0]
+        found_index = self.findExistingEntry(
+            match_str, match_on=match_on, section=section
+        )
+        if found_index > -1:
+            self.items[section][found_index] = newitem
 
     def makeDockAppSpacer(self, type="spacer-tile"):
         """Makes an empty space in the Dock."""