osx_paths.py

# Copyright (c) 2015 Andrew Durdin
# 
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
# 
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
# 
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

import ctypes, os, os.path

def NSIterateSearchPaths(directory, domain):
    """Return an iterable of the search paths matching the directory and domain.

        >>> for path in NSIterateSearchPaths(NSApplicationDirectory, NSAllDomainsMask):
        ...   path
        ... 
        '/Users/andy/Applications'
        '/Applications'
        '/Network/Applications'
    """
    CoreFoundation = ctypes.cdll.LoadLibrary("/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation")
    NSStartSearchPathEnumeration = CoreFoundation.NSStartSearchPathEnumeration
    NSGetNextSearchPathEnumeration = CoreFoundation.NSGetNextSearchPathEnumeration
    PATH_MAX = os.pathconf('/', os.pathconf_names['PC_PATH_MAX'])
    PATH_ENCODING = 'utf8'
    path_buffer = ctypes.create_string_buffer(PATH_MAX)
    paths = []
    state = NSStartSearchPathEnumeration(directory, domain)
    while True:
        state = NSGetNextSearchPathEnumeration(state, path_buffer)
        if state == 0: break
        path = os.path.expanduser(path_buffer.value.decode(PATH_ENCODING))
        yield path

def NSGetSearchPath(directory, domain):
    """Return the first path matching the directory and domain, or None if there are no matches.

        >>> NSGetSearchPath(NSDocumentDirectory, NSUserDomainMask)
        '/Users/andy/Documents'
    """
    for path in NSIterateSearchPaths(directory, domain):
        return path
    return None

# Directory constants (NSSearchPathDirectory enumeration)

NSApplicationDirectory = 1              # supported applications (Applications)
NSDemoApplicationDirectory = 2          # unsupported applications, demonstration versions (Applications/GrabBag)
NSDeveloperApplicationDirectory = 3     # developer applications (Developer/Applications)
NSAdminApplicationDirectory = 4         # system and network administration applications (Applications/Utilities)
NSLibraryDirectory = 5                  # various user-visible documentation, support, and configuration files, resources (Library)
NSDeveloperDirectory = 6                # developer resources (Developer)
NSUserDirectory = 7                     # user home directories (Users)
NSDocumentationDirectory = 8            # documentation (Library/Documentation)
NSDocumentDirectory = 9                 # documents (Documents)
NSCoreServiceDirectory = 10             # location of core services (System/Library/CoreServices)
NSAutosavedInformationDirectory = 11    # location of user's directory for use with autosaving (Library/Autosave Information)
NSDesktopDirectory = 12                 # location of user's Desktop (Desktop)
NSCachesDirectory = 13                  # location of discardable cache files (Library/Caches)
NSApplicationSupportDirectory = 14      # location of application support files (plug-ins, etc) (Library/Application Support)
NSDownloadsDirectory = 15               # location of user's Downloads directory (Downloads)
NSInputMethodsDirectory = 16            # input methods (Library/Input Methods)
NSMoviesDirectory = 17                  # location of user's Movies directory (~/Movies)
NSMusicDirectory = 18                   # location of user's Music directory (~/Music)
NSPicturesDirectory = 19                # location of user's Pictures directory (~/Pictures)
NSPrinterDescriptionDirectory = 20      # location of system's PPDs directory (Library/Printers/PPDs)
NSSharedPublicDirectory = 21            # location of user's Public sharing directory (~/Public)
NSPreferencePanesDirectory = 22         # location of the PreferencePanes directory for use with System Preferences (Library/PreferencePanes)
NSAllApplicationsDirectory = 100        # all directories where applications can occur (Applications, Applications/Utilities, Developer/Applications, ...)
NSAllLibrariesDirectory = 101           # all directories where resources can occur (Library, Developer)

# Domain constants (NSSearchPathDomainMask enumeration)

NSUserDomainMask = 1         # user's home directory --- place to install user's personal items (~)
NSLocalDomainMask = 2        # local to the current machine --- place to install items available to everyone on this machine
NSNetworkDomainMask = 4      # publically available location in the local area network --- place to install items available on the network (/Network)
NSSystemDomainMask = 8       # provided by Apple
NSAllDomainsMask = 0x0ffff   # all domains: all of the above and more, future items

If you only want the user's Documents directory, then thus suffices and is unlikely to change:

os.path.expanduser('~/Documents')