testing/mozbase/docs/mozprofile.rst

   1 :mod:`mozprofile` --- Create and modify Mozilla application profiles
   2 ====================================================================
   3
   4 Mozprofile_ is a python tool for creating and managing profiles for Mozilla's
   5 applications (Firefox, Thunderbird, etc.). In addition to creating profiles,
   6 mozprofile can install addons_ and set preferences. Mozprofile can be utilized
   7 from the command line or as an API.
   8
   9 The preferred way of setting up profile data (addons, permissions, preferences
  10 etc) is by passing them to the profile_ constructor.
  11
  12 Addons
  13 ------
  14
  15 .. automodule:: mozprofile.addons
  16    :members:
  17
  18 Addons may be installed individually or from a manifest.
  19
  20 Example::
  21
  22         from mozprofile import FirefoxProfile
  23
  24         # create new profile to pass to mozmill/mozrunner
  25         profile = FirefoxProfile(addons=["adblock.xpi"])
  26
  27 Command Line Interface
  28 ----------------------
  29
  30 .. automodule:: mozprofile.cli
  31    :members:
  32
  33 The profile to be operated on may be specified with the ``--profile``
  34 switch. If a profile is not specified, one will be created in a
  35 temporary directory which will be echoed to the terminal::
  36
  37     (mozmill)> mozprofile
  38     /tmp/tmp4q1iEU.mozrunner
  39     (mozmill)> ls /tmp/tmp4q1iEU.mozrunner
  40     user.js
  41
  42 To run mozprofile from the command line enter:
  43 ``mozprofile --help`` for a list of options.
  44
  45 Permissions
  46 -----------
  47
  48 .. automodule:: mozprofile.permissions
  49    :members:
  50
  51 You can set permissions by creating a ``ServerLocations`` object that you pass
  52 to the ``Profile`` constructor. Hosts can be added to it with
  53 ``add_host(host, port)``. ``port`` can be 0.
  54
  55 Preferences
  56 -----------
  57
  58 .. automodule:: mozprofile.prefs
  59    :members:
  60
  61 Preferences can be set in several ways:
  62
  63 - using the API: You can make a dictionary with the preferences and pass it to
  64   the ``Profile`` constructor. You can also add more preferences with the
  65   ``Profile.set_preferences`` method.
  66 - using a JSON blob file: ``mozprofile --preferences myprefs.json``
  67 - using a ``.ini`` file: ``mozprofile --preferences myprefs.ini``
  68 - via the command line: ``mozprofile --pref key:value --pref key:value [...]``
  69
  70 When setting preferences from  an ``.ini`` file or the ``--pref`` switch,
  71 the value will be interpolated as an integer or a boolean
  72 (``true``/``false``) if possible.
  73
  74 Profile
  75 --------------------
  76
  77 .. automodule:: mozprofile.profile
  78    :members:
  79
  80 Resources
  81 -----------
  82 Other Mozilla programs offer additional and overlapping functionality
  83 for profiles.  There is also substantive documentation on profiles and
  84 their management.
  85
  86 - profile documentation_
  87
  88
  89 .. _Mozprofile: https://hg.mozilla.org/mozilla-central/file/tip/testing/mozbase/mozprofile
  90 .. _addons: https://developer.mozilla.org/en/addons
  91 .. _mozprofile.profile: https://hg.mozilla.org/mozilla-central/file/tip/testing/mozbase/mozprofile/mozprofile/profile.py
  92 .. _AddonManager: https://hg.mozilla.org/mozilla-central/file/tip/testing/mozbase/mozprofile/mozprofile/addons.py
  93 .. _here: https://hg.mozilla.org/mozilla-central/file/tip/testing/mozbase/mozprofile/mozprofile/permissions.py
  94 .. _documentation: http://support.mozilla.com/en-US/kb/Profiles