1:mod:`mozinfo` --- Get system information
2=========================================
3
4Throughout `mozmill <https://developer.mozilla.org/en/Mozmill>`_
5and other Mozilla python code, checking the underlying
6platform is done in many different ways.  The various checks needed
7lead to a lot of copy+pasting, leaving the reader to wonder....is this
8specific check necessary for (e.g.) an operating system?  Because
9information is not consolidated, checks are not done consistently, nor
10is it defined what we are checking for.
11
12`mozinfo <https://github.com/mozilla/mozbase/tree/master/mozinfo>`_
13proposes to solve this problem.  mozinfo is a bridge interface,
14making the underlying (complex) plethora of OS and architecture
15combinations conform to a subset of values of relevance to
16Mozilla software. The current implementation exposes relevant keys and
17values such as: ``os``, ``version``, ``bits``, and ``processor``.  Additionally, the
18service pack in use is available on the windows platform.
19
20
21API Usage
22---------
23
24mozinfo is a python package.  Downloading the software and running
25``python setup.py develop`` will allow you to do ``import mozinfo``
26from python.
27`mozinfo.py <https://raw.github.com/mozilla/mozbase/master/mozinfo/mozinfo/mozinfo.py>`_
28is the only file contained is this package,
29so if you need a single-file solution, you can just download or call
30this file through the web.
31
32The top level attributes (``os``, ``version``, ``bits``, ``processor``) are
33available as module globals::
34
35    if mozinfo.os == 'win': ...
36
37In addition, mozinfo exports a dictionary, ``mozinfo.info``, that
38contain these values.  mozinfo also exports:
39
40- ``choices``: a dictionary of possible values for os, bits, and
41  processor
42- ``main``: the console_script entry point for mozinfo
43- ``unknown``: a singleton denoting a value that cannot be determined
44
45``unknown`` has the string representation ``"UNKNOWN"``.
46``unknown`` will evaluate as ``False`` in python::
47
48    if not mozinfo.os: ... # unknown!
49
50
51Command Line Usage
52------------------
53
54mozinfo comes with a command line program, ``mozinfo`` which may be used to
55diagnose one's current system.
56
57Example output::
58
59    os: linux
60    version: Ubuntu 10.10
61    bits: 32
62    processor: x86
63
64Three of these fields, os, bits, and processor, have a finite set of
65choices.  You may display the value of these choices using
66``mozinfo --os``, ``mozinfo --bits``, and ``mozinfo --processor``.
67``mozinfo --help`` documents command-line usage.
68
69
70.. automodule:: mozinfo
71   :members:
72