doc/python_module.rst

   1 .. _python-install:
   2
   3 Installing aubio for Python
   4 ===========================
   5
   6 aubio is available as a package for Python 2.7 and Python 3. The aubio
   7 extension is written C using the `Python/C`_ and the `Numpy/C`_ APIs.
   8
   9 .. _Python/C: https://docs.python.org/c-api/index.html
  10 .. _Numpy/C: https://docs.scipy.org/doc/numpy/reference/c-api.html
  11
  12 For general documentation on how to install Python packages, see `Installing
  13 Packages`_.
  14
  15 Installing aubio with pip
  16 -------------------------
  17
  18 aubio can be installed from `PyPI`_ using ``pip``:
  19
  20 .. code-block:: console
  21
  22     $ pip install aubio
  23
  24 See also `Installing from PyPI`_ for general documentation.
  25
  26 .. note::
  27
  28   aubio is currently a `source only`_ package, so you will need a compiler to
  29   install it from `PyPI`_. See also `Installing aubio with conda`_ for
  30   pre-compiled binaries.
  31
  32 .. _PyPI: https://pypi.python.org/pypi/aubio
  33 .. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
  34 .. _Installing from PyPI: https://packaging.python.org/tutorials/installing-packages/#installing-from-pypi
  35 .. _source only: https://packaging.python.org/tutorials/installing-packages/#source-distributions-vs-wheels
  36
  37 Installing aubio with conda
  38 ---------------------------
  39
  40 `Conda packages`_ are available through the `conda-forge`_ channel for Linux,
  41 macOS, and Windows:
  42
  43 .. code-block:: console
  44
  45     $ conda config --add channels conda-forge
  46     $ conda install -c conda-forge aubio
  47
  48 .. _Conda packages: https://anaconda.org/conda-forge/aubio
  49 .. _conda-forge: https://conda-forge.org/
  50
  51 .. _py-doubleprecision:
  52
  53 Double precision
  54 ----------------
  55
  56 This module can be compiled in double-precision mode, in which case the
  57 default type for floating-point samples will be 64-bit. The default is
  58 single precision mode (32-bit, recommended).
  59
  60 To build the aubio module with double precision, use the option
  61 `--enable-double` of the `build_ext` subcommand:
  62
  63 .. code:: bash
  64
  65     $ ./setup.py clean
  66     $ ./setup.py build_ext --enable-double
  67     $ pip install -v .
  68
  69 **Note**: If linking against `libaubio`, make sure the library was also
  70 compiled in :ref:`doubleprecision` mode.
  71
  72
  73 Checking your installation
  74 --------------------------
  75
  76 Once the python module is installed, its version can be checked with:
  77
  78 .. code-block:: console
  79
  80     $ python -c "import aubio; print(aubio.version, aubio.float_type)"
  81
  82 The command line `aubio` is also installed:
  83
  84 .. code-block:: console
  85
  86     $ aubio -h
  87
  88
  89 Python tests
  90 ------------
  91
  92 A number of Python tests are provided in the `python/tests`_ folder. To run
  93 them, install `pytest`_ and run it from the aubio source directory:
  94
  95 .. code-block:: console
  96
  97     $ pip install pytest
  98     $ git clone https://git.aubio.org/aubio/aubio
  99     $ cd aubio
 100     $ pytest
 101
 102 .. _python/tests: https://github.com/aubio/aubio/blob/master/python/tests
 103 .. _pytest: https://pytest.org