Download and Installation
=========================

Dependencies
------------
**python-discid** works with Python 3 >= 3.10.

The module :mod:`discid` cannot be imported
without `libdiscid`_ >= 0.2.2 installed.
If you want to use it as optional dependency,
import the module only when needed or catch the :exc:`OSError`
when libdiscid is not found.

Package Repositories (Linux)
----------------------------
If you are using Linux,
you might find **python-discid** in a repository used by your package manager.

These packages are known:

 * Arch Linux:
   `python-discid <https://archlinux.org/packages/extra/any/python-discid/>`_
 * Fedora:
   `python3-discid <https://packages.fedoraproject.org/pkgs/python3-discid/python3-discid/>`_
 * openSUSE:
   `python-discid <https://software.opensuse.org/package/python-discid>`_
 * Ubuntu:
   PPA (`musicbrainz-stable <https://launchpad.net/~musicbrainz-developers/+archive/stable>`_
   and `musicbrainz-daily <https://launchpad.net/~musicbrainz-developers/+archive/daily>`_)

Your package manager will also handle the *libdiscid* dependency automatically.

PyPI
----
The next-best option is to load the Package from
`pypi <https://pypi.org/project/discid/>`_
with `pip <https://pip.pypa.io/>`_::

 pip install discid

You still have to install `libdiscid`_.

Source Code
-----------
The code is available from `GitHub`_
as :source_download:`zip` and :source_download:`tar.gz`.

You can always get the latest code with :command:`git`::

 git clone https://github.com/metabrainz/python-discid.git

Installation
************
You can use **python-discid** already when you put the folder :file:`discid`
in the same location you run your script from
or somewhere in your :envvar:`PYTHONPATH`.

System-wide installation from local source can be done with pip::

 python -m pip install .

Running tests
*************

You can test your setup (including `libdiscid`_) with `pytest`_::

 pytest

Some additional tests can be run that require the presence of a CD drive with an
inserted audio CD. The exact audio CD does not matter, any valid audio CD should work.
To run those tests set the environment variable ``PYTHON_DISCID_TEST_DEVICE`` to a
non-empty value and run pytest::

 PYTHON_DISCID_TEST_DEVICE=1 pytest

.. _GitHub: https://github.com/metabrainz/python-discid
.. _pytest: https://pytest.org/

Libdiscid
---------
If you don't have a package manager
that takes care of the *libdiscid* dependency,
you have to download it manually.

You can find several builds and the source
at https://musicbrainz.org/doc/libdiscid.

If no build for your platform is available,
you have to build from source and install with::

 cmake .
 make
 make install

If the last step doesn't work for you,
you might have to place the files :file:`discid.DLL`, :file:`libdiscid.*.dylib`
or :file:`libdiscid.so.*`
(depending on your platform)
in the same directory as you start your script from
or somewhere in your :envvar:`PATH`.