py-appscript

3. The File class

The File class represents a fixed filesystem location. This may be deterministic (i.e. existing locations only) or non-deterministic depending on how the object is created.

Methods

File -- A reference to a fixed filesystem location. May be
        deterministic/non-deterministic depending on the type of
        object it's constructed from. Provides a variety of
        properties and constructors for converting to and from
        other Python types.

    Constructors:

        File(path) -- make File object from POSIX path

	File.makewithhfspath(path) -- make File object from HFS path

        File.makewithurl(url) -- make File object from file URL

        File.makewithdesc(desc) -- make File object from
                aem.ae.AEDesc of typeFSS, typeFSRef, typeFileURL

    Properties:

        path : unicode -- POSIX path

	hfspath : unicode -- HFS path

        url : string -- file URL

        file : mactypes.File -- a new File object

        alias : mactypes.Alias

        desc : aem.ae.AEDesc

Examples

from appscript import *
from mactypes import *

f = File('/Users/foo/some file')

print f
# mactypes.File("/Users/foo/some file")

print f.path
# /Users/foo/some file

print f.url
# file://localhost/Users/foo/some%20file

app('TextEdit').documents[1].save(in_=f)
# saves front TextEdit document at the given location

Notes

When creating a File instance, POSIX paths may be either relative or absolute and are automatically normalised using os.path.abspath.

When comparing File objects for equality, File.__eq__ will perform a case-sensitive comparison of their file paths. Client that need to perform (for example) case-insensitive comparisons should obtain path strings from each File object, then normalise and compare those values as necessary.

Unlike the Alias class which represents typeAlias values only, the File class provides a uniform wrapper for several file-related types that may be returned by applications:

When used in an application command, a File object returned by appscript will always pack into the same typeFSRef, typeFileURL or typeFSS AEDesc it was created from. A File object created using the default constructor or the Alias.file or File.file methods will always pack into an AEDesc of typeFileURL.

When passing File values to applications, you should not normally need to worry about which value type a File object contains as well-designed applications will ask the Apple Event Manager to coerce the given value to the desired type as necessary. If dealing with a not-so-well-designed application that only accepts an AEDesc of a specific type (typeFSRef, typeFSS or typeFileURL), first obtain an AEDesc via the File object's desc method, then coerce it to the desired type before using it in an application command. For example:

from appscript import *
from aem import kae

fileurl = mactypes.File('/Users/foo/some file')
fssdesc = fileurl.desc.coerce(kae.typeFSS)

app('older app').documents[1].save(in_=fssdesc)