libmacfs.tex 8.54 KB
Newer Older
Fred Drake's avatar
Fred Drake committed
1
\section{\module{macfs} ---
2
         Various file system services}
3

4 5
\declaremodule{builtin}{macfs}
  \platform{Mac}
Fred Drake's avatar
Fred Drake committed
6 7
\modulesynopsis{Support for FSSpec, the Alias Manager,
                \program{finder} aliases, and the Standard File package.}
8

Jack Jansen's avatar
Jack Jansen committed
9

10
This module provides access to Macintosh FSSpec handling, the Alias
Fred Drake's avatar
Fred Drake committed
11 12 13 14
Manager, \program{finder} aliases and the Standard File package.
\index{Macintosh Alias Manager}
\index{Alias Manager, Macintosh}
\index{Standard File}
Jack Jansen's avatar
Jack Jansen committed
15 16

Whenever a function or method expects a \var{file} argument, this
17
argument can be one of three things:\ (1) a full or partial Macintosh
18 19 20 21 22 23 24
pathname, (2) an \pytype{FSSpec} object or (3) a 3-tuple
\code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in
\citetitle{Inside Macintosh:\ Files}. A description of aliases and the
Standard File package can also be found there.

\strong{Note:} A module, \refmodule{macfsn}, is auto-imported to replace
StandardFile calls in macfs with NavServices calls.
Jack Jansen's avatar
Jack Jansen committed
25 26

\begin{funcdesc}{FSSpec}{file}
Fred Drake's avatar
Fred Drake committed
27
Create an \pytype{FSSpec} object for the specified file.
Jack Jansen's avatar
Jack Jansen committed
28 29 30
\end{funcdesc}

\begin{funcdesc}{RawFSSpec}{data}
Fred Drake's avatar
Fred Drake committed
31 32 33
Create an \pytype{FSSpec} object given the raw data for the \C{}
structure for the \pytype{FSSpec} as a string.  This is mainly useful
if you have obtained an \pytype{FSSpec} structure over a network.
Jack Jansen's avatar
Jack Jansen committed
34 35 36
\end{funcdesc}

\begin{funcdesc}{RawAlias}{data}
Fred Drake's avatar
Fred Drake committed
37 38 39
Create an \pytype{Alias} object given the raw data for the \C{}
structure for the alias as a string.  This is mainly useful if you
have obtained an \pytype{FSSpec} structure over a network.
Jack Jansen's avatar
Jack Jansen committed
40 41
\end{funcdesc}

42
\begin{funcdesc}{FInfo}{}
Fred Drake's avatar
Fred Drake committed
43
Create a zero-filled \pytype{FInfo} object.
44 45
\end{funcdesc}

Jack Jansen's avatar
Jack Jansen committed
46
\begin{funcdesc}{ResolveAliasFile}{file}
Fred Drake's avatar
Fred Drake committed
47 48 49 50 51 52
Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
\pytype{FSSpec} object, \var{isfolder} is true if \var{fsspec} points
to a folder and \var{aliased} is true if the file was an alias in the
first place (otherwise the \pytype{FSSpec} object for the file itself
is returned).
Jack Jansen's avatar
Jack Jansen committed
53 54
\end{funcdesc}

55
\begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
56
Present the user with a standard ``open input file''
Fred Drake's avatar
Fred Drake committed
57 58
dialog. Optionally, you can pass up to four 4-character file types to limit
the files the user can choose from. The function returns an \pytype{FSSpec}
Jack Jansen's avatar
Jack Jansen committed
59 60 61 62
object and a flag indicating that the user completed the dialog
without cancelling.
\end{funcdesc}

63
\begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
Fred Drake's avatar
Fred Drake committed
64
Similar to \function{StandardGetFile()} but allows you to specify a
65
prompt which will be displayed at the top of the dialog.
66 67
\end{funcdesc}

68
\begin{funcdesc}{StandardPutFile}{prompt\optional{, default}}
Jack Jansen's avatar
Jack Jansen committed
69 70
Present the user with a standard ``open output file''
dialog. \var{prompt} is the prompt string, and the optional
71
\var{default} argument initializes the output file name. The function
Fred Drake's avatar
Fred Drake committed
72 73
returns an \pytype{FSSpec} object and a flag indicating that the user
completed the dialog without cancelling.
Jack Jansen's avatar
Jack Jansen committed
74 75
\end{funcdesc}

76
\begin{funcdesc}{GetDirectory}{\optional{prompt}}
77 78 79 80 81
Present the user with a non-standard ``select a directory'' dialog.  You
have to first open the directory before clicking on the ``select current
directory'' button. \var{prompt} is the prompt string which will be
displayed at the top of the dialog. Return an \pytype{FSSpec} object and
a success-indicator.
Jack Jansen's avatar
Jack Jansen committed
82 83
\end{funcdesc}

Guido van Rossum's avatar
Guido van Rossum committed
84 85
\begin{funcdesc}{SetFolder}{\optional{fsspec}}
Set the folder that is initially presented to the user when one of
Fred Drake's avatar
Fred Drake committed
86
the file selection dialogs is presented. \var{fsspec} should point to
Guido van Rossum's avatar
Guido van Rossum committed
87 88
a file in the folder, not the folder itself (the file need not exist,
though). If no argument is passed the folder will be set to the
Fred Drake's avatar
Fred Drake committed
89
current directory, i.e. what \function{os.getcwd()} returns.
Guido van Rossum's avatar
Guido van Rossum committed
90 91

Note that starting with system 7.5 the user can change Standard File
92
behaviour with the ``general controls'' control panel, thereby making
Guido van Rossum's avatar
Guido van Rossum committed
93 94 95
this call inoperative.
\end{funcdesc}

96
\begin{funcdesc}{FindFolder}{where, which, create}
97
Locates one of the ``special'' folders that MacOS knows about, such as
Fred Drake's avatar
Fred Drake committed
98 99
the trash or the Preferences folder. \var{where} is the disk to
search, \var{which} is the 4-character string specifying which folder to
100
locate. Setting \var{create} causes the folder to be created if it
Fred Drake's avatar
Fred Drake committed
101
does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
102
\end{funcdesc}
103

104
\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
Fred Drake's avatar
Fred Drake committed
105
Return a minimal \pytype{alias} object that points to the given file, which
106
must be specified as a full pathname. This is the only way to create an
Fred Drake's avatar
Fred Drake committed
107
\pytype{Alias} pointing to a non-existing file.
108

109 110
The constants for \var{where} and \var{which} can be obtained from the
standard module \var{MACFS}.
111 112
\end{funcdesc}

113
\begin{funcdesc}{FindApplication}{creator}
114
Locate the application with 4-character creator code \var{creator}. The
Fred Drake's avatar
Fred Drake committed
115
function returns an \pytype{FSSpec} object pointing to the application.
116 117
\end{funcdesc}

118 119

\subsection{FSSpec objects \label{fsspec-objects}}
Jack Jansen's avatar
Jack Jansen committed
120

Fred Drake's avatar
Fred Drake committed
121
\begin{memberdesc}[FSSpec]{data}
Jack Jansen's avatar
Jack Jansen committed
122 123
The raw data from the FSSpec object, suitable for passing
to other applications, for instance.
Fred Drake's avatar
Fred Drake committed
124
\end{memberdesc}
Jack Jansen's avatar
Jack Jansen committed
125

Fred Drake's avatar
Fred Drake committed
126 127 128 129
\begin{methoddesc}[FSSpec]{as_pathname}{}
Return the full pathname of the file described by the \pytype{FSSpec}
object.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
130

Fred Drake's avatar
Fred Drake committed
131 132 133 134
\begin{methoddesc}[FSSpec]{as_tuple}{}
Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
the file described by the \pytype{FSSpec} object.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
135

Fred Drake's avatar
Fred Drake committed
136
\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
Jack Jansen's avatar
Jack Jansen committed
137
Create an Alias object pointing to the file described by this
138
FSSpec. If the optional \var{file} parameter is present the alias
Jack Jansen's avatar
Jack Jansen committed
139
will be relative to that file, otherwise it will be absolute.
Fred Drake's avatar
Fred Drake committed
140
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
141

Fred Drake's avatar
Fred Drake committed
142
\begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
Jack Jansen's avatar
Jack Jansen committed
143
Create a minimal alias pointing to this file.
Fred Drake's avatar
Fred Drake committed
144
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
145

Fred Drake's avatar
Fred Drake committed
146 147 148
\begin{methoddesc}[FSSpec]{GetCreatorType}{}
Return the 4-character creator and type of the file.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
149

Fred Drake's avatar
Fred Drake committed
150 151 152
\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
Set the 4-character creator and type of the file.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
153

Fred Drake's avatar
Fred Drake committed
154 155 156
\begin{methoddesc}[FSSpec]{GetFInfo}{}
Return a \pytype{FInfo} object describing the finder info for the file.
\end{methoddesc}
157

Fred Drake's avatar
Fred Drake committed
158 159 160 161
\begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
Set the finder info for the file to the values given as \var{finfo}
(an \pytype{FInfo} object).
\end{methoddesc}
162

Fred Drake's avatar
Fred Drake committed
163
\begin{methoddesc}[FSSpec]{GetDates}{}
164 165
Return a tuple with three floating point values representing the
creation date, modification date and backup date of the file.
Fred Drake's avatar
Fred Drake committed
166
\end{methoddesc}
167

Fred Drake's avatar
Fred Drake committed
168
\begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
169 170 171
Set the creation, modification and backup date of the file. The values
are in the standard floating point format used for times throughout
Python.
Fred Drake's avatar
Fred Drake committed
172 173
\end{methoddesc}

174

175
\subsection{Alias Objects \label{alias-objects}}
Jack Jansen's avatar
Jack Jansen committed
176

Fred Drake's avatar
Fred Drake committed
177
\begin{memberdesc}[Alias]{data}
Jack Jansen's avatar
Jack Jansen committed
178 179
The raw data for the Alias record, suitable for storing in a resource
or transmitting to other programs.
Fred Drake's avatar
Fred Drake committed
180
\end{memberdesc}
Jack Jansen's avatar
Jack Jansen committed
181

Fred Drake's avatar
Fred Drake committed
182
\begin{methoddesc}[Alias]{Resolve}{\optional{file}}
Jack Jansen's avatar
Jack Jansen committed
183
Resolve the alias. If the alias was created as a relative alias you
184
should pass the file relative to which it is. Return the FSSpec for
Fred Drake's avatar
Fred Drake committed
185
the file pointed to and a flag indicating whether the \pytype{Alias} object
186 187 188
itself was modified during the search process. If the file does
not exist but the path leading up to it does exist a valid fsspec
is returned.
Fred Drake's avatar
Fred Drake committed
189
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
190

Fred Drake's avatar
Fred Drake committed
191 192 193
\begin{methoddesc}[Alias]{GetInfo}{num}
An interface to the \C{} routine \cfunction{GetAliasInfo()}.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
194

195
\begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
Jack Jansen's avatar
Jack Jansen committed
196 197
Update the alias to point to the \var{file} given. If \var{file2} is
present a relative alias will be created.
Fred Drake's avatar
Fred Drake committed
198
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
199

Fred Drake's avatar
Fred Drake committed
200 201 202 203
Note that it is currently not possible to directly manipulate a
resource as an \pytype{Alias} object. Hence, after calling
\method{Update()} or after \method{Resolve()} indicates that the alias
has changed the Python program is responsible for getting the
Fred Drake's avatar
Fred Drake committed
204 205
\member{data} value from the \pytype{Alias} object and modifying the
resource.
Jack Jansen's avatar
Jack Jansen committed
206 207


208
\subsection{FInfo Objects \label{finfo-objects}}
209

210
See \citetitle{Inside Macintosh: Files} for a complete description of what
Fred Drake's avatar
Fred Drake committed
211
the various fields mean.
212

Fred Drake's avatar
Fred Drake committed
213 214 215
\begin{memberdesc}[FInfo]{Creator}
The 4-character creator code of the file.
\end{memberdesc}
216

Fred Drake's avatar
Fred Drake committed
217 218 219
\begin{memberdesc}[FInfo]{Type}
The 4-character type code of the file.
\end{memberdesc}
220

Fred Drake's avatar
Fred Drake committed
221
\begin{memberdesc}[FInfo]{Flags}
222
The finder flags for the file as 16-bit integer. The bit values in
Fred Drake's avatar
Fred Drake committed
223 224
\var{Flags} are defined in standard module \module{MACFS}.
\end{memberdesc}
225

Fred Drake's avatar
Fred Drake committed
226
\begin{memberdesc}[FInfo]{Location}
227
A Point giving the position of the file's icon in its folder.
Fred Drake's avatar
Fred Drake committed
228
\end{memberdesc}
229

Fred Drake's avatar
Fred Drake committed
230
\begin{memberdesc}[FInfo]{Fldr}
231
The folder the file is in (as an integer).
Fred Drake's avatar
Fred Drake committed
232
\end{memberdesc}