Read preferences from a property list within a Mac OS X Python script

I had a need to read some settings from a Python script on Mac OS X recently. I wanted to be able to change selected parameters for the script — some of which could be site or implementation specific — without embedding them directly in the code. Since the script was Mac OS X-only, using a property list seemed like a good idea.

With customizable settings from a property list, a script could become useful and more customizable for a wider community — or even different internal audiences.

I thought reading preferences was going to take a lot of effort. I was, however, pleasantly surprised at how easily I was able to accomplish it.

Asking others who had been down this route before resulted in some links to Apple docs. I wanted a more concrete example of how it was done in Python, and I got a great one.

That example came from reading the source to munkilib from the open source project, Munki. Since Munki had its own preference file, it needed to read from it, and its example was very enlightening.

Frogor directed me to a specific spot in the Munki code. That spot demonstrated how to read a preferences file with CoreFoundation.

Munki also has its own internal defaults for preferences. The munkilib/munkicommon.py example showed how to implement default settings in their absence in a property list. That provides a fallback position so that you always have some value available. In Munki, setting the defaults was done within a function. It seemed that it would be more generic if those defaults were separated out of the preference-reading function.

My own example of how to read a plist is outlined below. This focuses on just what you need in order to read the preferences and provide default settings for a larger script. A single set of preferences can be shared between scripts, and each script can encode its set own defaults. While you can create your own keys and values, for the example below, I will use the keys “StringPreference,” “BooleanPreference,” “ArrayPreference,” and “DictionaryPreference.”

1. Create a new property list. There are several ways to do this, including the property list editor that has been rolled into Xcode (and is no longer a standalone application) in v4.
2. Save the file. The name will be used later.
3. Set up the basic shell of the script that will read the plist and import CoreFoundation.
   
   #!/usr/bin/env python
   
   from Foundation import CFPreferencesCopyAppValue
4. Add in a variable for the script’s bundle ID. The bundle ID uniquely identifies your script’s preferences. It is written in reverse DNS notation, which should be familiar to almost anyone who has dealt with property lists before. It’s handy to have this defined globally for your script so that you can refer back to it as needed.
   
   #!/usr/bin/env python
   
   from Foundation import CFPreferencesCopyAppValue
   
   this_bundle_id = ‘com.example.your-script-here’
5. Create a function to read a preference by its bundle ID. The business end of the function is the use of CFPreferencesCopyAppValue get a value for a key.
   
   #!/usr/bin/env python
   
   from Foundation import CFPreferencesCopyAppValue
   
   this_bundle_id = ‘com.example.your-script-here’
   
   def get_preference(preference_key, bundle_id=this_bundle_id):
       """
       Get the preference value for a given combination of preference
       key and bundle ID. Returns the requested preference value.
       """
       # Get the specified preference key from the specified preference
       # bundle ID using CoreFoundation
       preference_value = CFPreferencesCopyAppValue(preference_key, bundle_id)
       return preference_value
6. Tie the get_preferences function together with a default_preferences object. This way, any missing preferences will fall back to the defaults encoded in your script. Any preferences that are set in a property list will override the defaults.
   
   #!/usr/bin/env python
   
   from Foundation import CFPreferencesCopyAppValue
   
   this_bundle_id = ‘com.example.your-script-here’
   default_preferences = {
       ‘StringPreference’: False,
       ‘BooleanPreference’: False,
       ‘ArrayPreference’: list(),
       ‘DictionaryPreference’: dict(),
   }
   
   def get_preference(preference_key, bundle_id=this_bundle_id):
       """
       Get the preference value for a given combination of preference
       key and bundle ID. Returns the preference value.
       """
       # Get the specified preference key from the specified preference
       # bundle ID using CoreFoundation
       preference_value = CFPreferencesCopyAppValue(preference_key, bundle_id)
       # If the value is not set in the property list, get a default value
       # from the default_preferences objects
       if preference_value == None:
           preference_value = default_preferences.get(preference_key)
       return preference_value

The script won’t do anything yet, until we create a main() or other functions to call the get_preferences function. Since you’d be reading preferences as part of a larger script, this is fine for now. However, with what’s written already, you can test out reading preferences interactively with the shell and Python interpreter.

1. Start by checking the property list in the shell. In my case, I created an example property list that sets two of the four preferences.
   
   $ defaults read com.example.your-script-here
   {
       BooleanPreference = True;
       StringPreference = abc;
   }
2. Open Terminal, run “python” at the command prompt, and paste the script code above at the interactive Python “>>>” prompt.
3. Run the get_preferences function and print its output.
   
   >>> print(get_preference(‘StringPreference’))
   abc
   >>> print(get_preference(‘BooleanPreference’))
   True
   >>> print(get_preference(‘ArrayPreference’))
   []
   >>> print(get_preference(‘DictionaryPreference’))
   {}

That’s it, the expected results were returned. Notice that the output for StringPreference and BooleanPreference are taken from the property list, while the empty array and dictionary come from the default_preferences in the script.

Update: Greg pointed out that there is a certain degree of danger using #!/usr/bin/env python as the shebang line in the script. Should a system have a non-Apple installation of Python, then /usr/bin/env python might return that. Another Python is probably less likely to be able to bridge CoreFoundation, and thus wouldn’t be able to use the CFPreferencesCopyAppValue call to read preferences.

I think the overall shebang danger is small because few Mac OS X systems will have an alternative Python installed, but clearly your chances of that increase in certain situations. To eliminate this risk, do what Munki does and insert the #!/usr/bin/python shebang instead.