Merge pull request #28 from homebysix/pypi

v1.2.0 - Reconfigure docklib repo structure to support publication of releases to PyPI

.gitignore

@@ -1,3 +1,6 @@
 .DS_Store
+*.egg-info
 *.pyc
 build/
+dist/
+venv/

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v2.4.0
+  rev: v3.2.0
   hooks:
   - id: check-added-large-files
     args: [--maxkb=100]
@@ -14,16 +14,12 @@ repos:
   - id: trailing-whitespace
     args: [--markdown-linebreak-ext=md]
 - repo: https://github.com/ambv/black
-  rev: 19.10b0
+  rev: 20.8b1
   hooks:
   - id: black
     language_version: python3.7
 - repo: https://github.com/asottile/blacken-docs
-  rev: v1.5.0-1
+  rev: v1.8.0
   hooks:
   - id: blacken-docs
-    additional_dependencies: [black==19.3b0]
-- repo: https://github.com/homebysix/pre-commit-macadmin
-  rev: v1.6.2
-  hooks:
-  - id: check-munkipkg-buildinfo
+    additional_dependencies: [black==20.8b1]

CHANGELOG.md

@@ -8,6 +8,22 @@ All notable changes to this project will be documented in this file. This projec
 Nothing yet.
 
 
+## [1.2.0] - 2020-10-15
+
+(Includes changes from briefly-published versions 1.1.0 and 1.1.1.)
+
+### Added
+
+- 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.
+- Created a few basic unit tests.
+
+### Changed
+
+- Updated pre-commit configuration.
+
+
 ## [1.0.5] - 2020-01-29
 
 ### Fixed
@@ -70,7 +86,9 @@ Nothing yet.
 - Initial release
 
 
-[Unreleased]: https://github.com/homebysix/docklib/compare/v1.0.4...HEAD
+[Unreleased]: https://github.com/homebysix/docklib/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/homebysix/docklib/compare/v1.0.5...v1.2.0
+[1.0.5]: https://github.com/homebysix/docklib/compare/v1.0.4...v1.0.5
 [1.0.4]: https://github.com/homebysix/docklib/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/homebysix/docklib/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/homebysix/docklib/compare/v1.0.1...v1.0.2

README.md

@@ -2,13 +2,39 @@
 
 This is a Python module intended to assist IT administrators with manipulation of the macOS Dock.
 
-Originally 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.
+Originally 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.
 
 ## Installation
 
-Place the docklib.py file in your Python path so its contents can be imported into scripts you create. Or, include the file in the same directory as your script.
+There are multiple methods of installing docklib, depending on how you plan to use it.
 
-The packages available in the [Releases](https://github.com/homebysix/docklib/releases) section will place the docklib.py file into /Library/Python/2.7/site-packages.
+### Package installer
+
+You 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.
+
+To run the script, `cd` to a local clone of this repository, then run:
+
+```
+./build_pkg.sh
+```
+
+The resulting pkg will be built in a temporary folder and shown in the Finder.
+
+__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.
+
+### Pip
+
+Docklib has been published to PyPI in order to make it available for installation using pip.
+
+```
+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.
+
+### 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.
 
 ## Examples
 
@@ -154,5 +180,3 @@ dock.items["persistent-apps"] = [
 ]
 dock.save()
 ```
-
-

RELEASING.md

@@ -0,0 +1,46 @@
+# Releasing new versions of docklib
+
+1. Ensure the version in __\_\_init\_\_.py__ has been updated.
+
+1. Ensure the change log has been updated and reflects actual release date.
+
+1. Merge development branch to main/master branch.
+
+1. Run docklib unit tests and fix any errors:
+
+        /usr/local/munki/munki-python -m unittest -v tests/unit.py
+
+1. Build a new distribution package:
+
+        rm -fv dist/*
+        python3 setup.py sdist bdist_wheel
+
+1. Upload package to test.pypi.org:
+
+        twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+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:
+
+        /usr/local/munki/Python.framework/Versions/Current/bin/python3 -m pip install --upgrade -i https://test.pypi.org/simple/ docklib
+
+1. Perform tests - manual for now.
+
+1. Upload package to pypi.org:
+
+        twine upload dist/*
+
+1. View resulting project on pypi.org and make sure it looks good.
+
+1. Install production docklib in Munki Python on a test Mac:
+
+        /usr/local/munki/Python.framework/Versions/Current/bin/python3 -m pip install --upgrade docklib
+
+1. Build new installer package using __build_pkg.sh__:
+
+        ./build_pkg.sh
+
+1. Create new release on GitHub. Add notes from change log. Attach built installer package.
+
+1. Announce to [dock-management](https://macadmins.slack.com/archives/C17NRH534) and other relevant channels, if desired.

build_pkg.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+cd "$(dirname "$0")" || exit 1
+
+echo "Preparing source folder..."
+rm -rfv ./docklib/__pycache__
+rm -fv ./docklib/*.pyc
+
+echo "Preparing pkgroot and output folders..."
+PKGROOT=$(mktemp -d /tmp/docklib-build-root-XXXXXXXXXXX)
+OUTPUTDIR=$(mktemp -d /tmp/docklib-output-XXXXXXXXXXX)
+mkdir -p "$PKGROOT/Library/Python/2.7/site-packages/"
+
+echo "Copying docklib into pkgroot..."
+# Customize this path if you're not using the macOS built-in Python 2.7 with docklib.
+cp -R ./docklib "$PKGROOT/Library/Python/2.7/site-packages/docklib"
+
+echo "Determining version..."
+VERSION=$(awk -F \" '/version/{print $2}' docklib/__init__.py)
+echo "  Version: $VERSION"
+
+echo "Building package..."
+OUTFILE="$OUTPUTDIR/docklib-$VERSION.pkg"
+pkgbuild --root "$PKGROOT" --identifier com.elliotjordan.docklib --version "$VERSION" "$OUTFILE"
+echo "$OUTFILE"
+open "$OUTPUTDIR"

docklib/__init__.py

@@ -0,0 +1,3 @@
+from .docklib import *
+
+__version__ = "1.2.0"

payload/Library/Python/2.7/site-packages/docklib.py → docklib/docklib.py

@@ -1,9 +1,8 @@
-#!/usr/bin/python
 # -*- coding: utf-8 -*-
 
 # pylint: disable=C0103
 
-"""Routines for manipulating the Dock."""
+"""Python module intended to assist IT administrators with manipulation of the macOS Dock."""
 
 import os
 import subprocess
@@ -18,6 +17,7 @@
     CFPreferencesSetAppValue,
 )
 
+
 # pylint: enable=E0611
 
 
@@ -124,6 +124,18 @@ def findExistingLabel(self, test_label, section="persistent-apps"):
 
         return -1
 
+    def findExistingURL(self, test_url):
+        """Returns index of item with URL matching test_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:
+                        return index
+
+        return -1
+
     def removeDockEntry(self, label, section=None):
         """Removes a Dock entry with matching label, if any."""
         if section:
@@ -135,6 +147,12 @@ def removeDockEntry(self, label, section=None):
             if found_index > -1:
                 del self.items[sect][found_index]
 
+    def removeDockURLEntry(self, url):
+        """Removes a Dock entry with matching url, if any."""
+        found_index = self.findExistingURL(url)
+        if found_index > -1:
+            del self.items["persistent-others"][found_index]
+
     def replaceDockEntry(self, thePath, label=None, section="persistent-apps"):
         """Replaces a Dock entry.
 

setup.py

@@ -0,0 +1,51 @@
+"""setup.py for docklib"""
+
+import pathlib
+
+from setuptools import setup
+
+# The directory containing this file
+HERE = pathlib.Path(__file__).parent
+
+# The text of the README file
+README = (HERE / "README.md").read_text()
+
+
+def get_version(rel_path):
+    """Given a path to a Python init file, return the version string."""
+    with open(rel_path, "r") as openfile:
+        lines = openfile.readlines()
+    for line in lines:
+        if line.startswith("__version__"):
+            delim = '"' if '"' in line else "'"
+            return line.split(delim)[1]
+    raise RuntimeError("Unable to find version string.")
+
+
+setup(
+    name="docklib",
+    version=get_version("docklib/__init__.py"),
+    description=(
+        "Python module intended to assist IT "
+        "administrators with manipulation of the macOS Dock."
+    ),
+    long_description=README,
+    long_description_content_type="text/markdown",
+    url="https://github.com/homebysix/docklib",
+    author="Elliot Jordan",
+    author_email="[email protected]",
+    license="Apache 2.0",
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Environment :: MacOS X",
+        "Intended Audience :: Information Technology",
+        "Intended Audience :: System Administrators",
+        "License :: OSI Approved :: Apache Software License",
+        "Programming Language :: Python :: 2",
+        "Programming Language :: Python :: 3",
+        "Topic :: System :: Systems Administration",
+        "Topic :: Utilities",
+    ],
+    packages=["docklib"],
+    include_package_data=True,
+)