The Tor Browser: testing/mozbase/docs/mozinfo.rst@6474c204b198

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

     1 :mod:`mozinfo` --- Get system information

     2 =========================================

     4 Throughout `mozmill <https://developer.mozilla.org/en/Mozmill>`_

     5 and other Mozilla python code, checking the underlying

     6 platform is done in many different ways.  The various checks needed

     7 lead to a lot of copy+pasting, leaving the reader to wonder....is this

     8 specific check necessary for (e.g.) an operating system?  Because

     9 information is not consolidated, checks are not done consistently, nor

    10 is it defined what we are checking for.

    12 `mozinfo <https://github.com/mozilla/mozbase/tree/master/mozinfo>`_

    13 proposes to solve this problem.  mozinfo is a bridge interface,

    14 making the underlying (complex) plethora of OS and architecture

    15 combinations conform to a subset of values of relevance to

    16 Mozilla software. The current implementation exposes relevant keys and

    17 values such as: ``os``, ``version``, ``bits``, and ``processor``.  Additionally, the

    18 service pack in use is available on the windows platform.

    21 API Usage

    22 ---------

    24 mozinfo is a python package.  Downloading the software and running

    25 ``python setup.py develop`` will allow you to do ``import mozinfo``

    26 from python.

    27 `mozinfo.py <https://raw.github.com/mozilla/mozbase/master/mozinfo/mozinfo/mozinfo.py>`_

    28 is the only file contained is this package,

    29 so if you need a single-file solution, you can just download or call

    30 this file through the web.

    32 The top level attributes (``os``, ``version``, ``bits``, ``processor``) are

    33 available as module globals::

    35     if mozinfo.os == 'win': ...

    37 In addition, mozinfo exports a dictionary, ``mozinfo.info``, that

    38 contain these values.  mozinfo also exports:

    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

    45 ``unknown`` has the string representation ``"UNKNOWN"``.

    46 ``unknown`` will evaluate as ``False`` in python::

    48     if not mozinfo.os: ... # unknown!

    51 Command Line Usage

    52 ------------------

    54 mozinfo comes with a command line program, ``mozinfo`` which may be used to

    55 diagnose one's current system.

    57 Example output::

    59     os: linux

    60     version: Ubuntu 10.10

    61     bits: 32

    62     processor: x86

    64 Three of these fields, os, bits, and processor, have a finite set of

    65 choices.  You may display the value of these choices using

    66 ``mozinfo --os``, ``mozinfo --bits``, and ``mozinfo --processor``.

    67 ``mozinfo --help`` documents command-line usage.

    70 .. automodule:: mozinfo

    71    :members:

The Tor Browser / file revision