Home | History | Annotate | Download | only in library 
      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.
      7    :deprecated:
      8 
      9 
     10 This module provides access to various internet-related preferences set through
     11 :program:`System Preferences` or the :program:`Finder`.
     12 
     13 .. note::
     14 
     15    This module has been removed in Python 3.x.
     16 
     17 
     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 a 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.
    125