.. -*- rst -*-

============
GetMediumURL
============

`GetMediumURL`_ is a simple Python package to get URLs of downloadable
media (usually audio or video) and their metadata knowing their main
URLs on websites using Flash-based players.

.. _`GetMediumURL`: http://savannah.nongnu.org/projects/getmediumurl/

License
=======

Copyright © 2010  Michał Masłowski  <mtjm@mtjm.eu>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Requirements
============

- Python 2.5 or later (some plugins don’t support Python 3 currently)

- Distribute

Most plugins require ``lxml`` or ``html5lib``.  Performance of other
plugins may be improved when ``lxml`` is installed (and not using it
is less tested).

Some plugins when used with Python 2.5 require the ``simplejson``
package (a derived one is included in newer Python releases).

Documentation is compiled using Sphinx.  There is also API
documentation generated using Epydoc.

For development these tools are recommended and called by included
``check.sh`` POSIX shell script:

- pyflakes

- pylint

- pep8

- coverage (version 3.4b1 or newer)

Obtaining the source
====================

GetMediumURL uses the `Mercurial version control system`_ to store its
source code.  Mercurial is available in many GNU/Linux distributions
as a package named ``mercurial``.

To get the source of GetMediumURL, use the following command::

  hg clone http://hg.savannah.nongnu.org/hgweb/getmediumurl/

It will make a ``getmediumurl`` directory, a different name can be
specified as an additional argument to the ``hg clone`` command.

To update it, run ``hg pull -u`` in this directory.

.. _`Mercurial version control system`: http://mercurial.selenic.com/

Installing
==========

Just run the following command::

    python setup.py install

``setup.py`` has many options listed using the ``--help`` option.  To
install in non-default directory, use the ``--prefix`` option to the
install command.

Before installing it is encouraged to use the following command to
test parts of GetMediumURL which do not make HTTP requests to external
servers::

    python setup.py test

All tests should pass.

Building documentation
======================

Documentation is formatted by the following command::

   python setup.py build_sphinx

An optional argument of ``-b`` can be used to specify different format
than HTML.

API documentation can be generated running the command::

    epydoc --config epydoc.cfg

Reporting bugs
==============

Report bugs on the `tracker`_ at Savannah.  If you are unsure if a
given behaviour of the package is a bug, please post it to the
`mailing list`_.

.. _`tracker`: https://savannah.nongnu.org/bugs/?group=getmediumurl

.. _`mailing list`: http://lists.nongnu.org/mailman/listinfo/getmediumurl-dev

Programs using it
=================

* `WatchVideo`_

.. _`WatchVideo`: http://www.nongnu.org/watchvideo/
