Commit 0a199877 authored by André Anjos's avatar André Anjos 💬
Browse files

Initial commit with base structure

parents
*~
*.swp
*.pyc
*.so
bin
eggs
parts
.installed.cfg
.mr.developer.cfg
*.egg-info
develop-eggs
sphinx
dist
.nfs*
.gdb_history
build
*.egg
src/
Copyright (c) 2013, Andre Anjos - Idiap Research Institute
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer. Redistributions in binary
form must reproduce the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials provided with
the distribution. Neither the name of the Idiap Research Institute nor the
names of its contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
include LICENSE README.rst bootstrap.py buildout.cfg
recursive-include doc conf.py *.rst
recursive-include xbob *.cpp *.h
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 29 Aug 2013 16:07:57 CEST
============================
Python bindings for bob.io
============================
This package contains a set of Pythonic bindings for Bob's io packages and
functionality.
Installation
------------
Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
the package and run test units.
Documentation
-------------
You can generate the documentation for this package, after installation, using
Sphinx::
$ sphinx-build -b html doc sphinx
This shall place in the directory ``sphinx``, the current version for the
documentation of the package.
Testing
-------
You can run a set of tests using the nose test runner::
$ nosetests -sv blitz
.. warning::
If Bob <= 1.2.1 is installed on your python path, nose will automatically
load the old version of the insulate plugin available in Bob, which will
trigger the loading of incompatible shared libraries (from Bob itself), in
to your working binary. This will cause a stack corruption. Either remove
the centrally installed version of Bob, or build your own version of Python
in which Bob <= 1.2.1 is not installed.
You can run our documentation tests using sphinx itself::
$ sphinx-build -b doctest doc sphinx
You can test overall test coverage with::
$ nosetests --with-coverage --cover-package=xbob.io
The ``coverage`` egg must be installed for this to work properly.
Development
-----------
To develop this package, install using ``zc.buildout``, using the buildout
configuration found on the root of the package:
$ python bootstrap.py
...
$ ./bin/buildout
Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
builds.
##############################################################################
#
# Copyright (c) 2006 Zope Foundation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Bootstrap a buildout-based project
Simply run this script in a directory containing a buildout.cfg.
The script accepts buildout command-line options, so you can
use the -c option to specify an alternate configuration file.
"""
import os
import shutil
import sys
import tempfile
from optparse import OptionParser
tmpeggs = tempfile.mkdtemp()
usage = '''\
[DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
Bootstraps a buildout-based project.
Simply run this script in a directory containing a buildout.cfg, using the
Python that you want bin/buildout to use.
Note that by using --find-links to point to local resources, you can keep
this script from going over the network.
'''
parser = OptionParser(usage=usage)
parser.add_option("-v", "--version", help="use a specific zc.buildout version")
parser.add_option("-t", "--accept-buildout-test-releases",
dest='accept_buildout_test_releases',
action="store_true", default=False,
help=("Normally, if you do not specify a --version, the "
"bootstrap script and buildout gets the newest "
"*final* versions of zc.buildout and its recipes and "
"extensions for you. If you use this flag, "
"bootstrap and buildout will get the newest releases "
"even if they are alphas or betas."))
parser.add_option("-c", "--config-file",
help=("Specify the path to the buildout configuration "
"file to be used."))
parser.add_option("-f", "--find-links",
help=("Specify a URL to search for buildout releases"))
options, args = parser.parse_args()
######################################################################
# load/install setuptools
to_reload = False
try:
import pkg_resources
import setuptools
except ImportError:
ez = {}
try:
from urllib.request import urlopen
except ImportError:
from urllib2 import urlopen
# XXX use a more permanent ez_setup.py URL when available.
exec(urlopen('https://bitbucket.org/pypa/setuptools/raw/0.7.2/ez_setup.py'
).read(), ez)
setup_args = dict(to_dir=tmpeggs, download_delay=0)
ez['use_setuptools'](**setup_args)
if to_reload:
reload(pkg_resources)
import pkg_resources
# This does not (always?) update the default working set. We will
# do it.
for path in sys.path:
if path not in pkg_resources.working_set.entries:
pkg_resources.working_set.add_entry(path)
######################################################################
# Try to best guess the version of buildout given setuptools
if options.version is None:
try:
from distutils.version import LooseVersion
package = pkg_resources.require('setuptools')[0]
v = LooseVersion(package.version)
if v < LooseVersion('0.7'):
options.version = '2.1.1'
except:
pass
######################################################################
# Install buildout
ws = pkg_resources.working_set
cmd = [sys.executable, '-c',
'from setuptools.command.easy_install import main; main()',
'-mZqNxd', tmpeggs]
find_links = os.environ.get(
'bootstrap-testing-find-links',
options.find_links or
('http://downloads.buildout.org/'
if options.accept_buildout_test_releases else None)
)
if find_links:
cmd.extend(['-f', find_links])
setuptools_path = ws.find(
pkg_resources.Requirement.parse('setuptools')).location
requirement = 'zc.buildout'
version = options.version
if version is None and not options.accept_buildout_test_releases:
# Figure out the most recent final version of zc.buildout.
import setuptools.package_index
_final_parts = '*final-', '*final'
def _final_version(parsed_version):
for part in parsed_version:
if (part[:1] == '*') and (part not in _final_parts):
return False
return True
index = setuptools.package_index.PackageIndex(
search_path=[setuptools_path])
if find_links:
index.add_find_links((find_links,))
req = pkg_resources.Requirement.parse(requirement)
if index.obtain(req) is not None:
best = []
bestv = None
for dist in index[req.project_name]:
distv = dist.parsed_version
if _final_version(distv):
if bestv is None or distv > bestv:
best = [dist]
bestv = distv
elif distv == bestv:
best.append(dist)
if best:
best.sort()
version = best[-1].version
if version:
requirement = '=='.join((requirement, version))
cmd.append(requirement)
import subprocess
if subprocess.call(cmd, env=dict(os.environ, PYTHONPATH=setuptools_path)) != 0:
raise Exception(
"Failed to execute command:\n%s",
repr(cmd)[1:-1])
######################################################################
# Import and run buildout
ws.add_entry(tmpeggs)
ws.require(requirement)
import zc.buildout.buildout
if not [a for a in args if '=' not in a]:
args.append('bootstrap')
# if -c was provided, we push it back into args for buildout' main function
if options.config_file is not None:
args[0:0] = ['-c', options.config_file]
zc.buildout.buildout.main(args)
shutil.rmtree(tmpeggs)
; vim: set fileencoding=utf-8 :
; Andre Anjos <andre.anjos@idiap.ch>
; Mon 16 Apr 08:29:18 2012 CEST
[buildout]
parts = blitz.array xbob.io scripts
eggs = xbob.io
ipdb
extensions = mr.developer
auto-checkout = *
prefixes = /Users/andre/work/bob/b/dbg
debug = true
verbose = true
[sources]
xbob.buildout = git git@github.com:bioidiap/xbob.buildout
pypkg = git git@github.com:anjos/pypkg
[blitz.array]
recipe = xbob.buildout:develop
setup = src/blitz.array
eggs = pypkg
[xbob.io]
recipe = xbob.buildout:develop
eggs = blitz.array pypkg
[scripts]
recipe = xbob.buildout:scripts
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Tue 15 Oct 14:59:05 2013
=========
C++ API
=========
The C++ API of ``xbob.core`` allows users to leverage from automatic converters
for classes in :py:class:`xbob.core.random`. To use the C API, clients should
first, include the header file ``<xbob.core/random.h>`` on their compilation
units and then, make sure to call once ``import_xbob_core_random()`` at their
module instantiation, as explained at the `Python manual
<http://docs.python.org/2/extending/extending.html#using-capsules>`_.
Here is a dummy C example showing how to include the header and where to call
the import function:
.. code-block:: c++
#include <xbob.core/random.h>
PyMODINIT_FUNC initclient(void) {
PyObject* m Py_InitModule("client", ClientMethods);
if (!m) return;
// imports the NumPy C-API
import_array();
// imports blitz.array C-API
import_blitz_array();
// imports xbob.core.random C-API
import_xbob_core_random();
}
.. note::
The include directory can be discovered using
:py:func:`xbob.core.get_include`.
Mersenne Twister Random Number Generator (mt19937)
--------------------------------------------------
This package contains bindings to ``boost::random::mt19937``, which is a
powerful random number generator available within the Boost_ C++ library.
.. cpp:type:: PyBoostMt19937Object
The pythonic object representation for a ``boost::random::mt19937`` object.
.. code-block:: c
typedef struct {
PyObject_HEAD
boost::random::mt19937* rng;
} PyBoostMt19937Object;
.. c:member:: boost::random::mt19937* rng
A direct pointer to the boost random number generator. You can use this
pointer in your C/C++ code if required.
.. cpp:function:: int PyBoostMt19937_Check(PyObject* o)
Checks if the input object ``o`` is a ``PyBoostMt19937Object``. Returns
``1`` if it is, and ``0`` otherwise.
.. cpp:function:: int PyBoostMt19937_Converter(PyObject* o, PyBoostMt19937Object** a)
This function is meant to be used with :c:func:`PyArg_ParseTupleAndKeywords`
family of functions in the Python C-API. It checks the input
object to be of type ``PyBoostMt19937Object`` and sets a **new
reference** to it (in ``*a``) if it is the case. Returns ``0`` in case of
failure, ``1`` in case of success.
.. cpp:function:: PyObject* PyBoostMt19937_SimpleNew()
Creates a new instance of :cpp:type:`PyBoostMt19937Object`, with the default
seed. Returns a **new reference**.
.. cpp:function:: PyObject* PyBoostMt19937_NewWithSeed(Py_ssize_t seed)
Creates a new instance of :cpp:type:`PyBoostMt19937Object`, with a user
given seed. Returns a **new reference**.
Distribution API
----------------
Together with the boost random number generator ``mt19937``, this package
provides bindings to these ``boost::random`` distributions:
* Uniform
* Normal (or Gaussian)
* Log-normal
* Gamma
* Binomial
Distributions wrap the random number generator, skewing the distribution of
numbers according to their parametrization. Distributions are *templated*
according to the scalar data types they produce. Different distributions
support a different set of scalar types:
============== =================================================
Distribution Scalars supported
============== =================================================
Uniform bool, int8/16/32/64, uint8/16/32/64, float32/64
Normal float32/64
Log-normal float32/64
Gamma float32/64
Binomial float32/64 (internally using int64)
============== =================================================
.. cpp:type:: PyBoostUniformObject
The pythonic object representation for a ``boost::random::uniform_*``
object.
.. code-block:: c
typedef struct {
PyObject_HEAD
int type_num;
boost::shared_ptr<void> distro;
} PyUniformObject;
.. c:member:: int type_num;
The NumPy type number of scalars produced by this distribution. Accepted
values match the scalar type produced:
============= ========================================
Scalar type NumPy scalar type number (enumeration)
============= ========================================
bool ``NPY_BOOL``
int8 ``NPY_INT8``
int16 ``NPY_INT16``
int32 ``NPY_INT32``
int64 ``NPY_INT64``
int8 ``NPY_INT8``
int16 ``NPY_INT16``
int32 ``NPY_INT32``
int64 ``NPY_INT64``
float32 ``NPY_FLOAT32``
float64 ``NPY_FLOAT64``
============= ========================================
.. c:member:: boost::shared_ptr<void> distro
A direct pointer to the boost distribution. The underlying allocated type
changes with the scalar that is produced by the distribution:
============= ==============================================
Scalar type C++ data type
============= ==============================================
bool ``boost::random::uniform_smallint<uint8_t>``
int8 ``boost::random::uniform_int<int8_t>``
int16 ``boost::random::uniform_int<int16_t>``
int32 ``boost::random::uniform_int<int32_t>``
int64 ``boost::random::uniform_int<int64_t>``
uint8 ``boost::random::uniform_int<uint8_t>``
uint16 ``boost::random::uniform_int<uint16_t>``
uint32 ``boost::random::uniform_int<uint32_t>``
uint64 ``boost::random::uniform_int<uint64_t>``
float32 ``boost::random::uniform_real<float>``
float64 ``boost::random::uniform_real<double>``
============= ==============================================
In order to use the distribution in your C/C++ code, you must first cast the
shared pointer using ``boost::static_pointer_cast<D>``, with ``D`` matching
one of the distributions listed above, depending on the value of
.. cpp:type:: PyBoostNormalObject
The pythonic object representation for a
``boost::random::normal_distribution`` object.
.. code-block:: c
typedef struct {
PyObject_HEAD
int type_num;
boost::shared_ptr<void> distro;
} PyUniformObject;
.. c:member:: int type_num;
The NumPy type number of scalars produced by this distribution. Accepted
values match the scalar type produced:
============= ========================================
Scalar type NumPy scalar type number (enumeration)
============= ========================================
float32 ``NPY_FLOAT32``
float64 ``NPY_FLOAT64``
============= ========================================
.. c:member:: boost::shared_ptr<void> distro
A direct pointer to the boost distribution. The underlying allocated type
changes with the scalar that is produced by the distribution:
============= ================================================
Scalar type C++ data type
============= ================================================
float32 ``boost::random::normal_distribution<float>``
float64 ``boost::random::normal_distribution<double>``
============= ================================================
.. cpp:type:: PyBoostLogNormalObject
The pythonic object representation for a
``boost::random::lognormal_distribution`` object.
.. code-block:: c
typedef struct {
PyObject_HEAD
int type_num;
boost::shared_ptr<void> distro;
} PyUniformObject;
.. c:member:: int type_num;
The NumPy type number of scalars produced by this distribution. Accepted
values match the scalar type produced:
============= ========================================
Scalar type NumPy scalar type number (enumeration)
============= ========================================
float32 ``NPY_FLOAT32``
float64 ``NPY_FLOAT64``
============= ========================================
.. c:member:: boost::shared_ptr<void> distro
A direct pointer to the boost distribution. The underlying allocated type
changes with the scalar that is produced by the distribution:
============= ===================================================
Scalar type C++ data type
============= ===================================================
float32 ``boost::random::lognormal_distribution<float>``
float64 ``boost::random::lognormal_distribution<double>``
============= ===================================================
.. cpp:type:: PyBoostGammaObject
The pythonic object representation for a
``boost::random::gamma_distribution`` object.
.. code-block:: c
typedef struct {
PyObject_HEAD
int type_num;
boost::shared_ptr<void> distro;
} PyUniformObject;
.. c:member:: int type_num;
The NumPy type number of scalars produced by this distribution. Accepted
values match the scalar type produced:
============= ========================================
Scalar type NumPy scalar type number (enumeration)
============= ========================================
float32 ``NPY_FLOAT32``
float64 ``NPY_FLOAT64``
============= ========================================
.. c:member:: boost::shared_ptr<void> distro
A direct pointer to the boost distribution. The underlying allocated type
changes with the scalar that is produced by the distribution:
============= ===============================================
Scalar type C++ data type
============= ===============================================
float32 ``boost::random::gamma_distribution<float>``
float64 ``boost::random::gamma_distribution<double>``
============= ===============================================
.. cpp:type:: PyBoostBinomialObject
The pythonic object representation for a
``boost::random::binomial_distribution`` object.
.. code-block:: c
typedef struct {
PyObject_HEAD
int type_num;
boost::shared_ptr<void> distro;
} PyUniformObject;
.. c:member:: int type_num;
The NumPy type number of scalars produced by this distribution. Accepted
values match the scalar type produced:
============= ========================================
Scalar type NumPy scalar type number (enumeration)
============= ========================================
float32 ``NPY_FLOAT32``
float64 ``NPY_FLOAT64``
============= ========================================
.. c:member:: boost::shared_ptr<void> distro
A direct pointer to the boost distribution. The underlying allocated type
changes with the scalar that is produced by the distribution: