1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/mozbase/docs/mozinfo.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,71 @@
1.4 +:mod:`mozinfo` --- Get system information
1.5 +=========================================
1.6 +
1.7 +Throughout `mozmill <https://developer.mozilla.org/en/Mozmill>`_
1.8 +and other Mozilla python code, checking the underlying
1.9 +platform is done in many different ways. The various checks needed
1.10 +lead to a lot of copy+pasting, leaving the reader to wonder....is this
1.11 +specific check necessary for (e.g.) an operating system? Because
1.12 +information is not consolidated, checks are not done consistently, nor
1.13 +is it defined what we are checking for.
1.14 +
1.15 +`mozinfo <https://github.com/mozilla/mozbase/tree/master/mozinfo>`_
1.16 +proposes to solve this problem. mozinfo is a bridge interface,
1.17 +making the underlying (complex) plethora of OS and architecture
1.18 +combinations conform to a subset of values of relevance to
1.19 +Mozilla software. The current implementation exposes relevant keys and
1.20 +values such as: ``os``, ``version``, ``bits``, and ``processor``. Additionally, the
1.21 +service pack in use is available on the windows platform.
1.22 +
1.23 +
1.24 +API Usage
1.25 +---------
1.26 +
1.27 +mozinfo is a python package. Downloading the software and running
1.28 +``python setup.py develop`` will allow you to do ``import mozinfo``
1.29 +from python.
1.30 +`mozinfo.py <https://raw.github.com/mozilla/mozbase/master/mozinfo/mozinfo/mozinfo.py>`_
1.31 +is the only file contained is this package,
1.32 +so if you need a single-file solution, you can just download or call
1.33 +this file through the web.
1.34 +
1.35 +The top level attributes (``os``, ``version``, ``bits``, ``processor``) are
1.36 +available as module globals::
1.37 +
1.38 + if mozinfo.os == 'win': ...
1.39 +
1.40 +In addition, mozinfo exports a dictionary, ``mozinfo.info``, that
1.41 +contain these values. mozinfo also exports:
1.42 +
1.43 +- ``choices``: a dictionary of possible values for os, bits, and
1.44 + processor
1.45 +- ``main``: the console_script entry point for mozinfo
1.46 +- ``unknown``: a singleton denoting a value that cannot be determined
1.47 +
1.48 +``unknown`` has the string representation ``"UNKNOWN"``.
1.49 +``unknown`` will evaluate as ``False`` in python::
1.50 +
1.51 + if not mozinfo.os: ... # unknown!
1.52 +
1.53 +
1.54 +Command Line Usage
1.55 +------------------
1.56 +
1.57 +mozinfo comes with a command line program, ``mozinfo`` which may be used to
1.58 +diagnose one's current system.
1.59 +
1.60 +Example output::
1.61 +
1.62 + os: linux
1.63 + version: Ubuntu 10.10
1.64 + bits: 32
1.65 + processor: x86
1.66 +
1.67 +Three of these fields, os, bits, and processor, have a finite set of
1.68 +choices. You may display the value of these choices using
1.69 +``mozinfo --os``, ``mozinfo --bits``, and ``mozinfo --processor``.
1.70 +``mozinfo --help`` documents command-line usage.
1.71 +
1.72 +
1.73 +.. automodule:: mozinfo
1.74 + :members:
