michael@0: :mod:`mozprofile` --- Create and modify Mozilla application profiles
michael@0: ====================================================================
michael@0: 
michael@0: Mozprofile_ is a python tool for creating and managing profiles for Mozilla's
michael@0: applications (Firefox, Thunderbird, etc.). In addition to creating profiles,
michael@0: mozprofile can install addons_ and set preferences_ Mozprofile can be utilized
michael@0: from the command line or as an API.
michael@0: 
michael@0: The preferred way of setting up profile data (addons, permissions, preferences
michael@0: etc) is by passing them to the profile_ constructor.
michael@0: 
michael@0: Addons
michael@0: ------
michael@0: 
michael@0: .. automodule:: mozprofile.addons
michael@0:    :members:
michael@0: 
michael@0: Addons may be installed individually or from a manifest.
michael@0: 
michael@0: Example::
michael@0: 
michael@0: 	from mozprofile import FirefoxProfile
michael@0: 	
michael@0: 	# create new profile to pass to mozmill/mozrunner
michael@0: 	profile = FirefoxProfile(addons=["adblock.xpi"])
michael@0: 
michael@0: Command Line Interface
michael@0: ----------------------
michael@0: 
michael@0: .. automodule:: mozprofile.cli
michael@0:    :members:
michael@0: 
michael@0: The profile to be operated on may be specified with the ``--profile``
michael@0: switch. If a profile is not specified, one will be created in a
michael@0: temporary directory which will be echoed to the terminal::
michael@0: 
michael@0:     (mozmill)> mozprofile
michael@0:     /tmp/tmp4q1iEU.mozrunner
michael@0:     (mozmill)> ls /tmp/tmp4q1iEU.mozrunner
michael@0:     user.js
michael@0: 
michael@0: To run mozprofile from the command line enter:
michael@0: ``mozprofile --help`` for a list of options.
michael@0: 
michael@0: Permissions
michael@0: -----------
michael@0: 
michael@0: .. automodule:: mozprofile.permissions
michael@0:    :members:
michael@0: 
michael@0: You can set permissions by creating a ``ServerLocations`` object that you pass
michael@0: to the ``Profile`` constructor. Hosts can be added to it with
michael@0: ``add_host(host, port)``. ``port`` can be 0.
michael@0: 
michael@0: Preferences
michael@0: -----------
michael@0: 
michael@0: .. automodule:: mozprofile.prefs
michael@0:    :members:
michael@0: 
michael@0: Preferences can be set in several ways:
michael@0: 
michael@0: - using the API: You can make a dictionary with the preferences and pass it to
michael@0:   the ``Profile`` constructor. You can also add more preferences with the
michael@0:   ``Profile.set_preferences`` method.
michael@0: - using a JSON blob file: ``mozprofile --preferences myprefs.json``
michael@0: - using a ``.ini`` file: ``mozprofile --preferences myprefs.ini``
michael@0: - via the command line: ``mozprofile --pref key:value --pref key:value [...]``
michael@0: 
michael@0: When setting preferences from  an ``.ini`` file or the ``--pref`` switch,
michael@0: the value will be interpolated as an integer or a boolean
michael@0: (``true``/``false``) if possible.
michael@0: 
michael@0: Profile
michael@0: --------------------
michael@0: 
michael@0: .. automodule:: mozprofile.profile
michael@0:    :members:
michael@0: 
michael@0: Resources
michael@0: -----------
michael@0: Other Mozilla programs offer additional and overlapping functionality
michael@0: for profiles.  There is also substantive documentation on profiles and
michael@0: their management.
michael@0: 
michael@0: - ProfileManager_: XULRunner application for managing profiles. Has a GUI and CLI.
michael@0: - python-profilemanager_: python CLI interface similar to ProfileManager
michael@0: - profile documentation_ 
michael@0: 
michael@0: 
michael@0: .. _Mozprofile: https://github.com/mozilla/mozbase/tree/master/mozprofile
michael@0: .. _addons: https://developer.mozilla.org/en/addons
michael@0: .. _preferences: https://developer.mozilla.org/En/A_Brief_Guide_to_Mozilla_Preferences
michael@0: .. _mozprofile.profile: https://github.com/mozilla/mozbase/tree/master/mozprofile/mozprofile/profile.py
michael@0: .. _AddonManager: https://github.com/mozilla/mozbase/tree/master/mozprofile/mozprofile/addons.py
michael@0: .. _here: https://github.com/mozilla/mozbase/blob/master/mozprofile/mozprofile/permissions.py
michael@0: .. _ProfileManager: https://developer.mozilla.org/en/Profile_Manager
michael@0: .. _python-profilemanager: http://k0s.org/mozilla/hg/profilemanager/
michael@0: .. _documentation: http://support.mozilla.com/en-US/kb/Profiles