michael@0: :mod:`mozinfo` --- Get system information
michael@0: =========================================
michael@0: 
michael@0: Throughout `mozmill <https://developer.mozilla.org/en/Mozmill>`_
michael@0: and other Mozilla python code, checking the underlying
michael@0: platform is done in many different ways.  The various checks needed
michael@0: lead to a lot of copy+pasting, leaving the reader to wonder....is this
michael@0: specific check necessary for (e.g.) an operating system?  Because
michael@0: information is not consolidated, checks are not done consistently, nor
michael@0: is it defined what we are checking for.
michael@0: 
michael@0: `mozinfo <https://github.com/mozilla/mozbase/tree/master/mozinfo>`_
michael@0: proposes to solve this problem.  mozinfo is a bridge interface,
michael@0: making the underlying (complex) plethora of OS and architecture
michael@0: combinations conform to a subset of values of relevance to
michael@0: Mozilla software. The current implementation exposes relevant keys and
michael@0: values such as: ``os``, ``version``, ``bits``, and ``processor``.  Additionally, the
michael@0: service pack in use is available on the windows platform.
michael@0: 
michael@0: 
michael@0: API Usage
michael@0: ---------
michael@0: 
michael@0: mozinfo is a python package.  Downloading the software and running
michael@0: ``python setup.py develop`` will allow you to do ``import mozinfo``
michael@0: from python.
michael@0: `mozinfo.py <https://raw.github.com/mozilla/mozbase/master/mozinfo/mozinfo/mozinfo.py>`_
michael@0: is the only file contained is this package,
michael@0: so if you need a single-file solution, you can just download or call
michael@0: this file through the web.
michael@0: 
michael@0: The top level attributes (``os``, ``version``, ``bits``, ``processor``) are
michael@0: available as module globals::
michael@0: 
michael@0:     if mozinfo.os == 'win': ...
michael@0: 
michael@0: In addition, mozinfo exports a dictionary, ``mozinfo.info``, that
michael@0: contain these values.  mozinfo also exports:
michael@0: 
michael@0: - ``choices``: a dictionary of possible values for os, bits, and
michael@0:   processor
michael@0: - ``main``: the console_script entry point for mozinfo
michael@0: - ``unknown``: a singleton denoting a value that cannot be determined
michael@0: 
michael@0: ``unknown`` has the string representation ``"UNKNOWN"``.
michael@0: ``unknown`` will evaluate as ``False`` in python::
michael@0: 
michael@0:     if not mozinfo.os: ... # unknown!
michael@0: 
michael@0: 
michael@0: Command Line Usage
michael@0: ------------------
michael@0: 
michael@0: mozinfo comes with a command line program, ``mozinfo`` which may be used to
michael@0: diagnose one's current system.
michael@0: 
michael@0: Example output::
michael@0: 
michael@0:     os: linux
michael@0:     version: Ubuntu 10.10
michael@0:     bits: 32
michael@0:     processor: x86
michael@0: 
michael@0: Three of these fields, os, bits, and processor, have a finite set of
michael@0: choices.  You may display the value of these choices using
michael@0: ``mozinfo --os``, ``mozinfo --bits``, and ``mozinfo --processor``.
michael@0: ``mozinfo --help`` documents command-line usage.
michael@0: 
michael@0: 
michael@0: .. automodule:: mozinfo
michael@0:    :members: