Commit 6038dd19 authored by Manuel Günther's avatar Manuel Günther
Browse files

New README and documentation strategy.

parent 79a59bc9
......@@ -2,8 +2,7 @@
*.swp
*.pyc
*.so
*.so.*
CMakeLists.txt
*.dylib
bin
eggs
parts
......@@ -18,4 +17,3 @@ dist
build
*.egg
src/
opsnr.stt
language: python
matrix:
include:
- python: 2.6
- python: 2.7
env:
- secure: Mjicore21483fMCADQLzOqhWQ9jWlfoppAMK+8cHYrz6pluK8cv/lBou4JXdE5Y/1z8svn44boMpCSldppDImqFfJGLFE0mvAl8CiSHtXp3mxQxpS2yDd4pCAfxMzr+K4M0/bfOrhAviI/3itKG5GiwCviLeTIiQ7dAJJrnU1C8=
- secure: QgHg0wGSy8ZGRELq7nXAAdv17q2/NDinAoFA3aNjJ5ZAUsi9ymKJGtwa1HbJN6npQgMDAew+joj85VeKMEDv7dCcNp2ySm2q23qIppoAutdBH23tvaMmvzgKsSvtFqq7SL52vcx9HY13mVXhhUenr1XeGlxRV2RFTeQz276arsg=
- python: 3.2
env:
- NUMPYSPEC===1.7.1
- python: 3.3
env:
- NUMPYSPEC===1.8.0
- python: 2.6
- python: 2.7
env:
- secure: Mjicore21483fMCADQLzOqhWQ9jWlfoppAMK+8cHYrz6pluK8cv/lBou4JXdE5Y/1z8svn44boMpCSldppDImqFfJGLFE0mvAl8CiSHtXp3mxQxpS2yDd4pCAfxMzr+K4M0/bfOrhAviI/3itKG5GiwCviLeTIiQ7dAJJrnU1C8=
- secure: QgHg0wGSy8ZGRELq7nXAAdv17q2/NDinAoFA3aNjJ5ZAUsi9ymKJGtwa1HbJN6npQgMDAew+joj85VeKMEDv7dCcNp2ySm2q23qIppoAutdBH23tvaMmvzgKsSvtFqq7SL52vcx9HY13mVXhhUenr1XeGlxRV2RFTeQz276arsg=
- BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
- python: 3.2
env:
- NUMPYSPEC===1.7.1
- python: 3.3
env:
- NUMPYSPEC===1.8.0
before_install:
- sudo add-apt-repository -y ppa:biometrics/bob
- sudo apt-get update -qq
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libatlas-dev libatlas-base-dev liblapack-dev libhdf5-serial-dev;
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libatlas-dev libatlas-base-dev liblapack-dev libhdf5-serial-dev texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
- if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq gfortran; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --upgrade pip setuptools; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel numpy$NUMPYSPEC; fi
......
......@@ -2,78 +2,34 @@
.. Andre Anjos <andre.anjos@idiap.ch>
.. Thu 29 Aug 2013 16:07:57 CEST
.. image:: https://travis-ci.org/bioidiap/bob.io.base.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.io.base
.. image:: http://img.shields.io/badge/docs-stable-yellow.png
:target: http://pythonhosted.org/bob.io.base/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
:target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.base/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.io.base.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.io.base
.. image:: https://coveralls.io/repos/bioidiap/bob.io.base/badge.png
:target: https://coveralls.io/r/bioidiap/bob.io.base
.. image:: http://img.shields.io/github/tag/bioidiap/bob.io.base.png
:target: https://github.com/bioidiap/bob.io.base
.. image:: http://img.shields.io/pypi/v/bob.io.base.png
:target: https://pypi.python.org/pypi/bob.io.base
.. image:: http://img.shields.io/pypi/dm/bob.io.base.png
:target: https://pypi.python.org/pypi/bob.io.base
=============================
Python bindings for bob::io
=============================
=========================================
Basic Input/Output functionality of Bob
=========================================
This package contains a set of Pythonic bindings for core Bob I/O functionality.
This package contains Bob's basic I/O functionality.
Installation
------------
Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
the package and run test units.
To install this package -- alone or together with other `Packages of Bob <https://github.com/idiap/bob/wiki/Packages>`_ -- please read the `Installation Instructions <https://github.com/idiap/bob/wiki/Installation>`_.
For Bob_ to be able to work properly, some dependent packages are required to be installed.
Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
Documentation
-------------
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.io.base/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.base/master/index.html>`_ of the documentation.
For a list of tutorials on this or the other packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
The latest version of the documentation can be found `here <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.io.base/master/index.html>`_.
Otherwise, you can generate the documentation for this package yourself, 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
.. 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=bob.io.base
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.
.. _bob: https://www.idiap.ch/software/bob
......@@ -52,7 +52,7 @@ def create_directories_safe(directory, dryrun=False):
def load(inputs):
"""Loads the contents of a file, an iterable of files, or an iterable of
:py:class:`bob.io.File`'s into a :py:class:`numpy.ndarray`.
:py:class:`bob.io.base.File`'s into a :py:class:`numpy.ndarray`.
Parameters:
......@@ -67,11 +67,11 @@ def load(inputs):
would assume that each file contains a single 1D sample or a set of 1D
samples, load them in memory and concatenate them into a single and
returned 2D numpy ndarray.
3. An iterable of :py:class:`bob.io.File`. In this case, this would assume
that each :py:class:`bob.io.File` contains a single 1D sample or a set
3. An iterable of :py:class:`bob.io.base.File`. In this case, this would assume
that each :py:class:`bob.io.base.File` contains a single 1D sample or a set
of 1D samples, load them in memory if required and concatenate them into
a single and returned 2D numpy ndarray.
4. An iterable with mixed filenames and :py:class:`bob.io.File`. In this
4. An iterable with mixed filenames and :py:class:`bob.io.base.File`. In this
case, this would returned a 2D :py:class:`numpy.ndarray`, as described
by points 2 and 3 above.
"""
......@@ -88,14 +88,14 @@ def load(inputs):
elif isinstance(obj, File):
retval.append(obj.read())
else:
raise TypeError("Iterable contains an object which is not a filename nor a bob.io.File.")
raise TypeError("Iterable contains an object which is not a filename nor a bob.io.base.File.")
return numpy.vstack(retval)
else:
raise TypeError("Unexpected input object. This function is expecting a filename, or an iterable of filenames and/or bob.io.File's")
raise TypeError("Unexpected input object. This function is expecting a filename, or an iterable of filenames and/or bob.io.base.File's")
def merge(filenames):
"""Converts an iterable of filenames into an iterable over read-only
bob.io.File's.
bob.io.base.File's.
Parameters:
......@@ -104,9 +104,9 @@ def merge(filenames):
This might represent:
1. A single filename. In this case, an iterable with a single
:py:class:`bob.io.File` is returned.
:py:class:`bob.io.base.File` is returned.
2. An iterable of filenames to be converted into an iterable of
:py:class:`bob.io.File`'s.
:py:class:`bob.io.base.File`'s.
"""
from collections import Iterable
......@@ -121,9 +121,9 @@ def merge(filenames):
def save(array, filename, create_directories = False):
"""Saves the contents of an array-like object to file.
Effectively, this is the same as creating a :py:class:`bob.io.File` object
Effectively, this is the same as creating a :py:class:`bob.io.base.File` object
with the mode flag set to `w` (write with truncation) and calling
:py:meth:`bob.io.File.write` passing `array` as parameter.
:py:meth:`bob.io.base.File.write` passing `array` as parameter.
Parameters:
......@@ -149,9 +149,9 @@ read = load
def append(array, filename):
"""Appends the contents of an array-like object to file.
Effectively, this is the same as creating a :py:class:`bob.io.File` object
Effectively, this is the same as creating a :py:class:`bob.io.base.File` object
with the mode flag set to `a` (append) and calling
:py:meth:`bob.io.File.append` passing `array` as parameter.
:py:meth:`bob.io.base.File.append` passing `array` as parameter.
Parameters:
......@@ -166,9 +166,9 @@ def append(array, filename):
def peek(filename):
"""Returns the type of array (frame or sample) saved in the given file.
Effectively, this is the same as creating a :py:class:`bob.io.File` object
Effectively, this is the same as creating a :py:class:`bob.io.base.File` object
with the mode flag set to `r` (read-only) and returning
:py:attr:`bob.io.File.describe()`.
:py:func:`bob.io.base.File.describe`.
Parameters:
......@@ -180,9 +180,9 @@ def peek(filename):
def peek_all(filename):
"""Returns the type of array (for full readouts) saved in the given file.
Effectively, this is the same as creating a :py:class:`bob.io.File` object
Effectively, this is the same as creating a :py:class:`bob.io.base.File` object
with the mode flag set to `r` (read-only) and returning
:py:attr:`bob.io.File.describe(all=True)`.
``bob.io.base.File.describe(all=True)``.
Parameters:
......
......@@ -478,7 +478,7 @@ Parameters:\n\
\n\
array\n\
[array] The array to be written into the file. It can be a\n\
numpy, a bob.blitz.array or any other object which can be\n\
:py:class:`numpy.array`, a :py:class:`bob.blitz.array` or any other object which can be\n\
converted to either of them, as long as the number of\n\
dimensions and scalar type are supported by\n\
:py:class:`bob.blitz.array`.\n\
......@@ -531,7 +531,7 @@ Parameters:\n\
\n\
array\n\
[array] The array to be added into the file. It can be a\n\
numpy, a bob.blitz.array or any other object which can be\n\
:py:class:`numpy.ndarray`, a :py:class`bob.blitz.array` or any other object which can be\n\
converted to either of them, as long as the number of\n\
dimensions and scalar type are supported by\n\
:py:class:`bob.blitz.array`.\n\
......
......@@ -299,7 +299,7 @@ path. ``'..'`` and ``'.'`` are supported. This object should\n\
be an :py:class:`str` object. If the value is relative, it is\n\
added to the current path. If it is absolute, it causes the\n\
prefix to be reset. Note all operations taking a relative path,\n\
following a ``cd()``, will be considered relative to the value\n\
following a :py:func:`cd`, will be considered relative to the value\n\
defined by the ``cwd`` property of this object.\n\
");
......@@ -386,7 +386,7 @@ path\n\
Creates a new directory (i.e., a *group* in HDF5 parlance) inside\n\
the file. A relative path is taken w.r.t. to the current\n\
directory. If the directory already exists (check it with\n\
:py:meth:`HDF5File.has_group()`, an exception will be raised.\n\
:py:meth:`bob.io.base.HDF5File.has_group`, an exception will be raised.\n\
");
static PyObject* PyBobIoHDF5File_HasDataset(PyBobIoHDF5FileObject* self, PyObject *args, PyObject* kwds) {
......@@ -1946,18 +1946,18 @@ Parameters:\n\
\n\
name\n\
[str] The name of the attribute to retrieve. If the attribute\n\
is not available, a :py:class:`RuntimeError` is raised.\n\
is not available, a ``RuntimeError`` is raised.\n\
\n\
path\n\
[str, optional] The path leading to the resource (dataset or\n\
group|directory) you would like to get an attribute from.\n\
If the path does not exist, a :py:class:`RuntimeError` is\n\
If the path does not exist, a ``RuntimeError`` is\n\
raised.\n\
\n\
This method returns a single value corresponding to what is\n\
stored inside the attribute container for the given resource.\n\
If you would like to retrieve all attributes at once, use\n\
:py:meth:`HDF5File.get_attributes()` instead.\n\
:py:meth:`bob.io.base.HDF5File.get_attributes` instead.\n\
");
static PyObject* PyBobIoHDF5File_GetAttributes(PyBobIoHDF5FileObject* self, PyObject *args, PyObject* kwds) {
......@@ -2011,13 +2011,13 @@ Parameters:\n\
path\n\
[str, optional] The path leading to the resource (dataset or\n\
group|directory) you would like to get all attributes from.\n\
If the path does not exist, a :py:class:`RuntimeError` is\n\
If the path does not exist, a ``RuntimeError`` is\n\
raised.\n\
\n\
Attributes are returned in a dictionary in which each key\n\
corresponds to the attribute name and each value corresponds\n\
to the value stored inside the HDF5 file. To retrieve only\n\
a specific attribute, use :py:meth:`HDF5File.get_attribute()`.\n\
a specific attribute, use :py:meth:`bob.io.base.HDF5File.get_attribute`.\n\
");
template <typename T> PyObject* PyBobIoHDF5File_WriteScalarAttribute
......@@ -2334,14 +2334,14 @@ Parameters:\n\
\n\
name\n\
[str] The name of the attribute to delete. A\n\
:py:class:`RuntimeError` is raised if the attribute does\n\
``RuntimeError`` is raised if the attribute does\n\
not exist.\n\
\n\
\n\
path\n\
[str, optional] The path leading to the resource (dataset or\n\
group|directory) you would like to set an attribute at.\n\
If the path does not exist, a :py:class:`RuntimeError` is\n\
If the path does not exist, a ``RuntimeError`` is\n\
raised.\n\
\n\
");
......@@ -2430,13 +2430,13 @@ Parameters:\n\
\n\
attrs\n\
[list] An iterable containing the names of the attributes to\n\
be removed. If not given or set to :py:class:`None`, then\n\
be removed. If not given or set to ``None``, then\n\
remove all attributes at the named resource.\n\
\n\
path\n\
[str, optional] The path leading to the resource (dataset or\n\
group|directory) you would like to set attributes at.\n\
If the path does not exist, a :py:class:`RuntimeError` is\n\
If the path does not exist, a ``RuntimeError`` is\n\
raised.\n\
\n\
");
......@@ -2482,7 +2482,7 @@ name\n\
path\n\
[str, optional] The path leading to the resource (dataset or\n\
group|directory) you would like to set an attribute at.\n\
If the path does not exist, a :py:class:`RuntimeError` is\n\
If the path does not exist, a ``RuntimeError`` is\n\
raised.\n\
\n\
");
......
......@@ -249,36 +249,10 @@ autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
def smaller_than(v1, v2):
"""Compares scipy/numpy version numbers"""
c1 = v1.split('.')
c2 = v2.split('.')[:len(c1)] #clip to the compared version
for i, k in enumerate(c2):
n1 = c1[i]
n2 = c2[i]
try:
n1 = int(n1)
n2 = int(n2)
except ValueError:
n1 = str(n1)
n2 = str(n2)
if n1 > n2: return False
return True
# Some name mangling to find the correct sphinx manuals for some packages
numpy_version = __import__('numpy').version.version
if smaller_than(numpy_version, '1.5.z'):
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
else:
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version
# For inter-documentation mapping:
intersphinx_mapping = {
'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None,
numpy_manual: None,
}
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation()
def setup(app):
pass
......@@ -145,7 +145,7 @@ as it was defined.
If you need to place lots of variables in a subfolder, it may be better to
setup the prefix folder before starting the writing operations on the
:py:class:`bob.io.base.HDF5File` object. You can do this using the method
:py:meth:`HDF5File.cd`. Look up its help for more information and usage
:py:meth:`bob.io.base.HDF5File.cd`. Look up its help for more information and usage
instructions.
Writing arrays is a little simpler as the :py:class:`numpy.ndarray` objects
......@@ -175,8 +175,8 @@ The result of running ``h5dump`` on the file ``testfile3.hdf5`` should be:
...
You don't need to limit yourself to single variables, you can also save lists
of scalars and arrays using the function :py:meth:`bob.io.base.HDF5.append`
instead of :py:meth:`bob.io.base.HDF5.set`.
of scalars and arrays using the function :py:meth:`bob.io.base.HDF5File.append`
instead of :py:meth:`bob.io.base.HDF5File.set`.
Reading operations
------------------
......@@ -264,7 +264,7 @@ What we have shown so far is the generic API to read and write data using HDF5.
You will use it when you want to import or export data from |project| into
other software frameworks, debug your data or just implement your own classes
that can serialize and de-serialize from HDF5 file containers. In |project|,
most of the time you will be working with :py:class:`numpy.ndarrays`\s. In
most of the time you will be working with :py:class:`numpy.ndarray`\s. In
special situations though, you may be asked to handle
:py:class:`bob.io.base.File`\s. :py:class:`bob.io.base.File` objects create a
transparent connection between C++ (`Blitz++`_) / Python (`NumPy`_) arrays and
......@@ -323,7 +323,7 @@ through the :py:class:`bob.io.base.File` container:
[ 0., 3., 6., 9., 12., 15., 18., 21., 24., 27.]])
You can also directly save :py:class:`numpy.ndarray`\s without going through
the :py:class:`bob.io.base.Array` container:
the :py:class:`bob.io.base.File` container:
.. doctest::
......
......@@ -133,7 +133,7 @@ setup(
name='bob.io.base',
version=version,
description='Base bindings for bob.io',
description='Basic IO for Bob',
url='http://github.com/bioidiap/bob.io.base',
license='BSD',
author='Andre Anjos',
......@@ -222,7 +222,8 @@ setup(
},
classifiers = [
'Development Status :: 3 - Alpha',
'Framework :: Bob',
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Natural Language :: English',
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment