Overview
###########

`browse <http://pypi.python.org/pypi/browse>`_  provides a single command line
executable to open a document from a shell. For instance, you can open a web 
page into your default browser as follows::

    browse http://docs.python.org

or just::

    browse docs.python.org

Similarly, you can open an image (it uses the default image viewer)::

    browse image.png

Or a txt file (or any document provided there is a default executable to open it).
It works like a charm under Linux 

.. warning:: tested under linux only. Right now, browse uses the default
    applications used by your system. Note that under MacOSX, a tool called **open** can
    be used. When invoking **browse**, under MacOSX, it actually tries to call **open**
    first and then calls webbrowser, if unsuccessful only. Note tested under
    Windows but uses webbrowser, so it should work...

You can also look at a directory (starts nautilus under Fedora)::

    browse ~/Pictures

See more examples below. 

The interest of **browse** is that it can also be used programmatically::

    from browse import browse
    # open an image with the default image viewer:
    browse("image.png")
    # or a web page
    browse("http://www.uniprot.org")



.. _installation:

Installation
#################

**browse** is available on `PyPi <http://pypi.python.org/pypi/browser>`_. 

To install it, type this comamnd in a shell::

    pip install browse


Usage
#################

**browse** comes in two flavours: an executable and a Python function. The underlying code is based on the 
standard python module :mod:`webbrowser`. With webbrowser module istself, you can already open 
a URL as follows in a command line interface::

        python -m webbrowser -t "http://www.python.org"

However, with **browse**, you can simply type::

        browse http://www.python.org


You can open a global URL into your browser by providing its address. There is
no need to enter "http://" that will be added if missing.

::

    browse  thomas-cokelaer.info
    browse  http://thomas-cokelaer.info --verbose


You can also open a local html file::


    browse local/html/index.html


Or browse a directory (under Linux, konqueror opens the provided argument)::


    browse  .
    browse  /home/user


Alternatively, from a python shell, you can also open a HTML document (just a
wrapping of the standard python module :mod:`webbrowser`)::

    from browse import browse
    browse("http://docs.python.org/index.html")