Changeset 633400d for doc/python_module.rst

Timestamp:

Dec 5, 2018, 10:34:39 PM (5 years ago)

Author:

Paul Brossier <piem@piem.org>

Branches:

feature/cnn, feature/crepe, feature/pitchshift, feature/timestretch, fix/ffmpeg5, master

Children:

283a619a

Parents:

5b46bc3 (diff), f19db54 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'master' into feature/pitchshift

File:

• doc/python_module.rst (modified) (1 diff)

doc/python_module.rst

@@ -1 @@
-.. _python:
+.. _python-install:
 
-Python module
-=============
+Installing aubio for Python
+===========================
 
-The aubio extension for Python is available for Python 2.7 and Python 3.
+aubio is available as a package for Python 2.7 and Python 3. The aubio
+extension is written C using the `Python/C`_ and the `Numpy/C`_ APIs.
+
+.. _Python/C: https://docs.python.org/c-api/index.html
+.. _Numpy/C: https://docs.scipy.org/doc/numpy/reference/c-api.html
+
+For general documentation on how to install Python packages, see `Installing
+Packages`_.
 
 Installing aubio with pip
 -------------------------
 
-aubio can now be installed using ``pip``:
+aubio can be installed from `PyPI`_ using ``pip``:
 
-.. code-block:: bash
+.. code-block:: console
 
     $ pip install aubio
 
-Building the module
--------------------
+See also `Installing from PyPI`_ for general documentation.
 
-From ``aubio`` source directory, run the following:
+.. note::
 
-.. code-block:: bash
+  aubio is currently a `source only`_ package, so you will need a compiler to
+  install it from `PyPI`_. See also `Installing aubio with conda`_ for
+  pre-compiled binaries.
+
+.. _PyPI: https://pypi.python.org/pypi/aubio
+.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
+.. _Installing from PyPI: https://packaging.python.org/tutorials/installing-packages/#installing-from-pypi
+.. _source only: https://packaging.python.org/tutorials/installing-packages/#source-distributions-vs-wheels
+
+Installing aubio with conda
+---------------------------
+
+`Conda packages`_ are available through the `conda-forge`_ channel for Linux,
+macOS, and Windows:
+
+.. code-block:: console
+
+    $ conda config --add channels conda-forge
+    $ conda install -c conda-forge aubio
+
+.. _Conda packages: https://anaconda.org/conda-forge/aubio
+.. _conda-forge: https://conda-forge.org/
+
+.. _py-doubleprecision:
+
+Double precision
+----------------
+
+This module can be compiled in double-precision mode, in which case the
+default type for floating-point samples will be 64-bit. The default is
+single precision mode (32-bit, recommended).
+
+To build the aubio module with double precision, use the option
+`--enable-double` of the `build_ext` subcommand:
+
+.. code:: bash
 
     $ ./setup.py clean
-    $ ./setup.py build
-    $ sudo ./setup.py install
+    $ ./setup.py build_ext --enable-double
+    $ pip install -v .
 
-Using aubio in python
----------------------
+**Note**: If linking against `libaubio`, make sure the library was also
+compiled in :ref:`doubleprecision` mode.
 
-Once you have python-aubio installed, you should be able to run ``python -c
-"import aubio"``.
 
-A simple example
-................
+Checking your installation
+--------------------------
 
-Here is a :download:`simple script <../python/demos/demo_source_simple.py>`
-that reads all the samples from a media file:
+Once the python module is installed, its version can be checked with:
 
-.. literalinclude:: ../python/demos/demo_source_simple.py
-   :language: python
+.. code-block:: console
 
-Filtering an input sound file
-.............................
+    $ python -c "import aubio; print(aubio.version, aubio.float_type)"
 
-Here is a more complete example, :download:`demo_filter.py
-<../python/demos/demo_filter.py>`. This files executes the following:
+The command line `aubio` is also installed:
 
-* read an input media file (``aubio.source``)
+.. code-block:: console
 
-* filter it using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
-  filter (``aubio.digital_filter``)
+    $ aubio -h
 
-* write result to a new file (``aubio.sink``)
-
-.. literalinclude:: ../python/demos/demo_filter.py
-   :language: python
-
-More demos
-..........
-
-Check out the `python demos folder`_ for more examples.
 
 Python tests
 ------------
 
-A number of `python tests`_ are provided. To run them, use
-``python/tests/run_all_tests``.
+A number of Python tests are provided in the `python tests`_. To run them,
+install `nose2`_ and run the script ``python/tests/run_all_tests``:
 
-.. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
+.. code-block:: console
+
+    $ pip install nose2
+    $ ./python/tests/run_all_tests
+
 .. _demo_filter.py: https://github.com/aubio/aubio/blob/master/python/demos/demo_filter.py
 .. _python tests: https://github.com/aubio/aubio/blob/master/python/tests
-
+.. _nose2: https://github.com/nose-devs/nose2