|
1 |
|
2 :mod:`ic` --- Access to the Mac OS X Internet Config |
|
3 ==================================================== |
|
4 |
|
5 .. module:: ic |
|
6 :platform: Mac |
|
7 :synopsis: Access to the Mac OS X Internet Config. |
|
8 :deprecated: |
|
9 |
|
10 |
|
11 This module provides access to various internet-related preferences set through |
|
12 :program:`System Preferences` or the :program:`Finder`. |
|
13 |
|
14 .. warning:: |
|
15 |
|
16 This module is removed in 3.0. |
|
17 |
|
18 |
|
19 .. index:: module: icglue |
|
20 |
|
21 There is a low-level companion module :mod:`icglue` which provides the basic |
|
22 Internet Config access functionality. This low-level module is not documented, |
|
23 but the docstrings of the routines document the parameters and the routine names |
|
24 are the same as for the Pascal or C API to Internet Config, so the standard IC |
|
25 programmers' documentation can be used if this module is needed. |
|
26 |
|
27 The :mod:`ic` module defines the :exc:`error` exception and symbolic names for |
|
28 all error codes Internet Config can produce; see the source for details. |
|
29 |
|
30 |
|
31 .. exception:: error |
|
32 |
|
33 Exception raised on errors in the :mod:`ic` module. |
|
34 |
|
35 The :mod:`ic` module defines the following class and function: |
|
36 |
|
37 |
|
38 .. class:: IC([signature[, ic]]) |
|
39 |
|
40 Create an Internet Config object. The signature is a 4-character creator code of |
|
41 the current application (default ``'Pyth'``) which may influence some of ICs |
|
42 settings. The optional *ic* argument is a low-level ``icglue.icinstance`` |
|
43 created beforehand, this may be useful if you want to get preferences from a |
|
44 different config file, etc. |
|
45 |
|
46 |
|
47 .. function:: launchurl(url[, hint]) |
|
48 parseurl(data[, start[, end[, hint]]]) |
|
49 mapfile(file) |
|
50 maptypecreator(type, creator[, filename]) |
|
51 settypecreator(file) |
|
52 |
|
53 These functions are "shortcuts" to the methods of the same name, described |
|
54 below. |
|
55 |
|
56 |
|
57 IC Objects |
|
58 ---------- |
|
59 |
|
60 :class:`IC` objects have a mapping interface, hence to obtain the mail address |
|
61 you simply get ``ic['MailAddress']``. Assignment also works, and changes the |
|
62 option in the configuration file. |
|
63 |
|
64 The module knows about various datatypes, and converts the internal IC |
|
65 representation to a "logical" Python data structure. Running the :mod:`ic` |
|
66 module standalone will run a test program that lists all keys and values in your |
|
67 IC database, this will have to serve as documentation. |
|
68 |
|
69 If the module does not know how to represent the data it returns an instance of |
|
70 the ``ICOpaqueData`` type, with the raw data in its :attr:`data` attribute. |
|
71 Objects of this type are also acceptable values for assignment. |
|
72 |
|
73 Besides the dictionary interface, :class:`IC` objects have the following |
|
74 methods: |
|
75 |
|
76 |
|
77 .. method:: IC.launchurl(url[, hint]) |
|
78 |
|
79 Parse the given URL, launch the correct application and pass it the URL. The |
|
80 optional *hint* can be a scheme name such as ``'mailto:'``, in which case |
|
81 incomplete URLs are completed with this scheme. If *hint* is not provided, |
|
82 incomplete URLs are invalid. |
|
83 |
|
84 |
|
85 .. method:: IC.parseurl(data[, start[, end[, hint]]]) |
|
86 |
|
87 Find an URL somewhere in *data* and return start position, end position and the |
|
88 URL. The optional *start* and *end* can be used to limit the search, so for |
|
89 instance if a user clicks in a long text field you can pass the whole text field |
|
90 and the click-position in *start* and this routine will return the whole URL in |
|
91 which the user clicked. As above, *hint* is an optional scheme used to complete |
|
92 incomplete URLs. |
|
93 |
|
94 |
|
95 .. method:: IC.mapfile(file) |
|
96 |
|
97 Return the mapping entry for the given *file*, which can be passed as either a |
|
98 filename or an :func:`FSSpec` result, and which need not exist. |
|
99 |
|
100 The mapping entry is returned as a tuple ``(version, type, creator, postcreator, |
|
101 flags, extension, appname, postappname, mimetype, entryname)``, where *version* |
|
102 is the entry version number, *type* is the 4-character filetype, *creator* is |
|
103 the 4-character creator type, *postcreator* is the 4-character creator code of |
|
104 an optional application to post-process the file after downloading, *flags* are |
|
105 various bits specifying whether to transfer in binary or ascii and such, |
|
106 *extension* is the filename extension for this file type, *appname* is the |
|
107 printable name of the application to which this file belongs, *postappname* is |
|
108 the name of the postprocessing application, *mimetype* is the MIME type of this |
|
109 file and *entryname* is the name of this entry. |
|
110 |
|
111 |
|
112 .. method:: IC.maptypecreator(type, creator[, filename]) |
|
113 |
|
114 Return the mapping entry for files with given 4-character *type* and *creator* |
|
115 codes. The optional *filename* may be specified to further help finding the |
|
116 correct entry (if the creator code is ``'????'``, for instance). |
|
117 |
|
118 The mapping entry is returned in the same format as for *mapfile*. |
|
119 |
|
120 |
|
121 .. method:: IC.settypecreator(file) |
|
122 |
|
123 Given an existing *file*, specified either as a filename or as an :func:`FSSpec` |
|
124 result, set its creator and type correctly based on its extension. The finder |
|
125 is told about the change, so the finder icon will be updated quickly. |