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