Mercurial > pytave

changeset 425:14b134ffdc24

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update project docs, delete obsolete docs from legacy project (fixes issue #72) * README.md: Rewrite to describe the current project state. * CONTRIBUTORS.md: New file listing project contributors. * Makefile.am (DOC_FILES): Include CONTRIBUTORS.md, remove INSTALL.md. * AUTHORS, ChangeLog, INSTALL.md, NEWS: Delete.
author Mike Miller <mtmiller@octave.org>
date Fri, 05 May 2017 15:55:41 -0700
parents 9b34c17cb0fb
children 8a26a4e649ba
files AUTHORS CONTRIBUTORS.md ChangeLog INSTALL.md Makefile.am NEWS README.md
diffstat 7 files changed, 76 insertions(+), 667 deletions(-) [+]
line wrap: on
line diff
--- a/AUTHORS	Thu May 04 21:33:36 2017 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,4 +0,0 @@
--*- coding: utf-8; -*-
-David Grundberg
-Håkan Fors Nilsson
-Jaroslav Hájek
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CONTRIBUTORS.md	Fri May 05 15:55:41 2017 -0700
@@ -0,0 +1,18 @@
+Contributors
+============
+
+* Mike Miller
+* Colin Macdonald
+* Juan Pablo Carbajal
+* Abhinav Tripathi
+* NVS Abhilash
+* Vijay Krishnavanshi
+
+---
+
+Thanks to the authors of the original Pytave project, which served as
+the origin and inspiration of this project:
+
+* David Grundberg
+* Håkan Fors Nilsson
+* Jaroslav Hájek
--- a/ChangeLog	Thu May 04 21:33:36 2017 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,329 +0,0 @@
-2012-04-09  David Grundberg  <individ@acc.umu.se>
-
-	* configure.ac: Remove ability to select Numeric array library.
-	* octave_to_python.cc: Assume we use numpy, remove ifdefs for
-	numeric.
-	* python_to_octave.cc: Assume we use numpy.
-	* ax_python_numpy.m4: Remove file.
-	* arrayobjectdefs.h: Remove numeric specific code.
-	* pytave.cc (pytave::get_module_name): Remove function.
-	* package/pytave.py: Use only numpy.
-
-2012-04-09  David Grundberg  <individ@acc.umu.se>
-
-	* octave_to_python.cc, python_to_octave.cc, pytave.cc: Undef
-	HAVE_STAT and HAVE_FSTAT consistently through-out all files.
-
-2012-04-09  David Grundberg  <individ@acc.umu.se>
-
-	* m4/ax_python_numpy.m4: Add missing link flags to test.
-
-2009-11-19  Jaroslav Hajek  <highegg@gmail.com>
-
-	* pytave.cc (func_eval): Catch & rethrow std::bad_alloc.
-	(str_eval): Likewise.
-
-2009-09-27  David Grundberg  <individ@acc.umu.se>
-
-	* configure.ac: Fix typo.
-
-2009-09-26  David Grundberg  <individ@acc.umu.se>
-
-	* configure.ac: Make NumPy default. Replace --enable flags with
-	--with-type flags. Rework output.
-	* m4/ax_python_numeric.m4 (AX_PYTHON_NUMERIC): Check for Numeric
-	extentions for Python.
-
-2009-09-26  David Grundberg  <individ@acc.umu.se>
-
-	* m4/ax_python_numpy.m4 (AX_PYTHON_NUMPY): Restore CPPFLAGS.
-
-2009-09-26  David Grundberg  <individ@acc.umu.se>
-
-	* configure.ac: Look for NumPy. List which dependencies that are
-	missing.
-	* pytave.cc (init): One-line comment about NumPy.
-	* m4/ax_python_numpy.m4: New file.
-	* m4/ax_octave.m4: Send output variable by name.
-	* Makefile.am (_pytave_la_CPPFLAGS): Substitute NumPy include
-	directory from configuration.
-	* setup.py.in: Ditto.
-	* Jamfile.in: Add warning against using bjam.
-
-2009-09-21  Jaroslav Hajek  <highegg@gmail.com>
-
-	* python_to_octave.cc (copy_pyarrobj_to_octarray_boot,
-	pyarr_to_octvalue): Support NumPy string arrays.
-
-2009-09-18  Jaroslav Hajek  <highegg@gmail.com>
-
-	* package/pytave.py: Safer check for interactive (mod_wsgi in
-	Apache!)
-	
-2009-09-18  Jaroslav Hajek  <highegg@gmail.com>
-	
-	* python_to_octave.cc (copy_pyarrobj_to_octarray,
-	pyarr_to_octvalue): Support 0D case.
-
-2009-09-18  Jaroslav Hajek  <highegg@gmail.com>
-
-	* package/pytave.py (simplify): Improve NumPy compatibility.
-
-2009-09-17  Jaroslav Hajek  <highegg@gmail.com>
-
-	* pytave.cc: Move #include of arrayobjectdefs after pytavedefs to
-	ensure config.h is included.
-
-2009-09-16  Jaroslav Hajek  <highegg@gmail.com>
-
-	* package/pytave.py (load_package, unload_package): New funcs.
-	* octave_to_python.cc: Workaround for return values bug in 
-	Octave <= 3.2.3.
-
-2009-09-15  Jaroslav Hajek  <highegg@gmail.com>
-
-	* octave_to_python.cc: Move #include of arrayobjectdefs after
-	pytavedefs to ensure config.h is included.
-	* python_to_octave.cc: Ditto.
-	* setup.py.in: Undo leaked local paths.
-
-2009-07-03  David Grundberg  <individ@acc.umu.se>
-
-	* pytave.cc: Sorted includes.
-	(atexit): New function. Call do_octave_atexit before Python
-	unloads shared libraries.
-	* package/pytave.py (_atexit): New function.
-
-2009-07-01  David Grundberg  <individ@acc.umu.se>
-
-	* pytave.cc [HAVE_USELOCALE] (init, func_eval, str_eval): Run
-	Octave interpreter in C locale.
-	* configure.ac: Define HAVE_USELOCALE. Substitute @PYTHON@. Added
-	checks for integer typedefs.  Make setup.py executable.  Friendly
-	message on configuration completion.
-	* setup.py.in: Let setup.py be interpreted by the same version of
-	Python we configured for.
-
-2009-06-19  Jaroslav Hajek  <highegg@gmail.com>
-
-	* configure.ac: Support --enable-numpy
-	* setup.py.in: Dynamically determine NumPy include path.
-	* pytave.cc (get_module_name): New function.
-	* octave_to_python.cc (octvalue_to_pyarrobj): 
-	Support bool arrays with NumPy.
-	* python_to_octave.cc (pyarr_to_octvalue, 
-	copy_pyarrobj_to_octarray_boot): Likewise.
-	* package/pytave.py: Dynamically import Numeric,
-	forward to numpy.oldnumeric if run with NumPy.
-	* test/test.py: Update some tests.
-
-2009-06-17  Jaroslav Hajek  <highegg@gmail.com>
-
-	* package/pytave.py (stripdict): New function.
-	(narrowlist): New function.
-	(simplify): New function.
-
-2009-06-16  Jaroslav Hajek  <highegg@gmail.com>
-
-	* octave_to_python.cc 
-	(createPyArr): Don't simplify row vectors to 1D arrays.
-	(octvalue_to_pyarrobj): Simplify, don't special-case scalars.
-	(octcell_to_pyobject): Remove.
-	(octmap_to_pyobject): Simplify, return uniform results.
-	(is_1xn_or_0x0): Remove.
-	* python_to_octave.cc
-	(pydict_to_octmap): Revert to the former behaviour aka Octave's
-	`struct'.
-	* package/pytave.py (canonicalize): Remove.
-	* test/test.py: Update tests.
-
-2009-06-09  Jaroslav Hajek  <highegg@gmail.com>
-
-	* package/pytave.py (canonicalize): New function.
-	(feval): Update doc string.
-
-2009-06-08  David Grundberg  <individ@acc.umu.se>
-
-	* pytave.cc (func_eval, str_eval): Reread changed files.
-
-2009-06-08  David Grundberg  <individ@acc.umu.se>
-
-	* test/test.py: New tests for pytave.globals and pytave.locals.
-	(testsetget, testexception): Call fail() instead of print.
-
-2009-06-03  Jaroslav Hajek  <highegg@gmail.com>
-
-	* pytave.cc (delvar): New function.
-	* package/pytave.py (_VariablesDict.__delitem__): New method.
-
-2009-06-03  Jaroslav Hajek  <highegg@gmail.com>
-
-	* pytave.cc (isvar): Fix tests.
-
-2009-06-08  Jaroslav Hajek  <highegg@gmail.com>, David Grundberg  <individ@acc.umu.se>
-
-	* octave_to_python.cc (copy_octarray_to_pyarrobj<PyObject *,
-	Cell>): New template specialization.
-	(createPyArr): Simplify row vectors to 1D arrays.
-	(octvalue_to_pyarrobj): Add string and cell cases.
-	(octcell_to_pyobject): Create a PyObject array if not row vector.
-	(octmap_to_pyobject): Create a simple dict if scalar struct.
-	(octvalue_to_pyobj): Allow converting arbitrary character matrices.
-	* python_to_octave.cc (pydict_to_octmap): Make scalar structs by
-	default, detect matching dimensions.
-	* package/pytave.py (feval): Update doc string.
-	(getvar, setvar, isvar): Remove.
-	(_VariablesDict): New class.
-	(locals, globals): Default instances.
-	(_local_scope): Rename to _LocalScope
-	* test/test.py: New tests. Update old tests.
-	(testsetget, testexception): New functions.
-
-2009-06-03  Jaroslav Hajek  <highegg@gmail.com>
-
-	* python_to_octave.cc (copy_pyarrobj_to_octarray<PyObject *,
-	Cell>): New template specialization.
-	(matching_type<PyObject *, octave_value>): Ditto.
-	(copy_pyarrobj_to_octarray_boot): Include PyArray_CHAR
-	and PyArray_Object cases.
-	(pyarr_to_octvalue): Likewise.
-	* test/test.py: Add tests for the new conversions.
-
-2009-06-03  David Grundberg  <individ@acc.umu.se>
-
-	* octave_to_python.cc (create_uint_array, create_sint_array):
-	Prefer int to other datatypes of identical size.
-	(is_1xn_or_0x0): Whitespace.
-	* python_to_octave.cc (copy_pyarrobj_to_octarray_dispatch): Prefer
-	int to other datatypes of identical size.
-
-2009-05-28  Jaroslav Hajek  <highegg@gmail.com>
-
-	* configure.ac: Remove --enable-float-matrices option.
-	* octave_to_python.cc: Remove uses of PYTAVE_USE_OCTAVE_FLOAT.
-	* python_to_octave.cc: Ditto.
-
-2009-05-26  Jaroslav Hajek  <highegg@gmail.com>
-
-	* octave_to_python.cc (octvalue_to_pyarrobj): Support Complex
-	and FloatComplex values.
-	(octvalue_to_pyobj): Support complex scalars.
-	* python_to_octave.cc (copy_pyarrobj_to_octarray_dispatch):
-	New template function.
-	(matching_type): New helper traits class.
-	(copy_pyarrobj_to_octarray_dispatch): Support complex types.
-	(pyarrobj_to_octvalue): Support complex scalars.
-	* test/test.py: Add tests for complex values.
-
-2009-05-26  Jaroslav Hajek  <highegg@gmail.com>
-
-	* octave_to_python.cc: New #include (boost/type_traits).
-	(copy_octarray_to_pyarrobj): Don't use .value(); don't	specialize.
-	(create_array (..., boost::true_type)): New overload (forward).
-	(create_array (..., boost::false_type)): New overload (dummy).
-	(create_uint_array): Pick proper overload.
-	(create_sint_array): Pick proper overload.
-
-2009-05-25  Jaroslav Hajek  <highegg@gmail.com>
-
-	* python_to_octave.cc (pydict_to_octmap): Save key and val in an
-	array, to avoid doing duplicate conversions.
-
-2009-05-25  Jaroslav Hajek  <highegg@gmail.com>
-
-	* pytave.cc (init): Add parameter; only display Octave banner if
-	requested.
-	* package/pytave.cc: Determine whether the interpreter is
-	interactive.
-
-2009-05-25  Jaroslav Hajek  <highegg@gmail.com>
-
-	* octave_to_python.cc (is_1xn_or_0x0): New inline func.
-	(octcell_to_pyobject): Use it.
-	(octvalue_to_pyobj): Use it.
-	* test/test.py: Update & fix tests.
-
-2009-05-13  Jaroslav Hajek  <highegg@gmail.com>
-
-	* exceptions.h (variable_name_exception): New exception class.
-	* exceptions.cc: Initialize it.
-	* octave_to_python.h (octvalue_to_pyobj): Declare prototype.
-	* pytave.cc (init): Init variable_name_exception.
-	(getvar): New function.
-	(setvar): New function.
-	(isvar): New function.
-	(push_scope): New function.
-	(pop_scope): New function.
-	* package/pytave.py (__init__): Init VarNameError.
-	(getvar): New function.
-	(setvar): New function.
-	(isvar): New function.
-	(push_scope): New function.
-	(pop_scope): New function.
-	(_local_scope): New decorator helper class.
-	(local_scope): New decorator.
-	* test/test.py: Include new tests.
-
-2009-05-09  David Grundberg  <individ@acc.umu.se>
-
-	* ax_octave_float.m4: New file.
-	* configure.ac: Added --enable-float-matrices configure option.
-
-2009-05-07  Jaroslav Hajek  <highegg@gmail.com>
-
-	* exceptions.h (octave_parse_exception): New class.
-	* package/pytave.py: Added ParseError exception.
-	(eval): New function.
-	* pytave.cc (func_eval, make_error_message): Extracted
-	make_error_message from func_eval.
-	(str_eval): New function.
-
-2009-05-05  David Grundberg  <individ@acc.umu.se>
-
-	* python_to_octave.cc (pydict_to_octmap): Improved semantics and
-	error control.
-	* m4/ax_octave.m4, m4/ax_python_devel.m4: New files.
-	* m4/ax_python.m4: Removed.
-	* m4/ax_boost_python.m4, README, INSTALL: Rewritten.
-	* configure.ac, setup.py.in, Jamfile.in, Makefile.am: Adjusted to
-	new Autoconf macros.
-
-2008-11-17  Håkan Fors Nilsson  <c04hfn@cs.umu.se>
-
-	* octave_to_python.cc (octcell_to_pyobject, octmap_to_pyobject):
-	New functions.
-	* python_to_octave.cc (pylist_to_cellarray, pydict_to_octmap):
-	New functions.
-
-2008-11-17  David Grundberg  <individ@acc.umu.se>
-
-	* pytave.cc (func_eval): Improved pytave.OctaveError messages, now
-	includes filename, function and line of offending m-file.
-
-2008-11-10  David Grundberg  <individ@acc.umu.se>
-
-	* octave_to_python.cc: Remove static storage class on explicitely
-	specialized templates.
-
-2008-10-23  David Grundberg  <individ@acc.umu.se>
-
-	* pytave.cc: Use octave_main() to initialize Octave. Introduces
-	readline history clashes with interactive Python interpreter.
-	* configure.ac: Better testing for Python dependencies.
-	* configure.ac: Renamed my_ to pytave_
-	* configure.ac: Fixed whitespace.
-
-2008-10-20  David Grundberg  <individ@acc.umu.se>
-
-	* Makefile.am: added test/exceptions.py to extra dist.
-	* Jamfile.in: corrected dependencies
-
-
-2008-10-18  David Grundberg  <individ@acc.umu.se>
-
-	Changed license to correct one (GPLv3).
-
-2008-10-17  David Grundberg  <c04dgg@cs.umu.se>
-
-	First launchpad.net check in.
-
--- a/INSTALL.md	Thu May 04 21:33:36 2017 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,97 +0,0 @@
-Pytave Building Instructions
-============================
-
-Pytave is built using GNU autotools.
-
-Use the configure script to detect Octave and Boost::Python paths.
-
-Run `./configure --help` for more info.
-
-Dependencies
-------------
-
-Configuring:
-
-  * a shell capable of running `configure`
-
-Building:
-
-  * GNU make
-
-Linked and tested with:
-
-  * Python 2.7
-  * Boost::Python 1.58
-  * Octave 4.1 (development version)
-
-Bootstrapping from Mercurial
-----------------------------
-
-  1. `hg clone https://bitbucket.org/mtmiller/pytave`
-
-  2. `autoreconf --install`
-
-Building
---------
-
-  1. `./configure`
-
-     or
-
-     `./configure --prefix=/directory/where/you/want/the/module/file`
-
-  2. Run `make` to build the extension module
-
-  3. To copy the pytave dynamic library to the prefix, run
-     `make install`
-
-Running from build directory
-----------------------------
-
-Pytave is made up of three parts. The `pytave` package, the
-`pytave/pytave` module and the `pytave/_pytave` extension. When the user
-uses `import pytave`, the pytave package `__init__` script loads both
-the module and the extension. It is important that they both can be
-found.
-
-  1. Follow the build instructions to compile the extension.
-
-  2. Start the Python interpreter with a Python path set to a path
-     containing `_pytave.so` and the `package` directory. A common way
-     to do this with the bash shell is to execute this command:
-
-        PYTHONPATH=.libs:package python
-
-  3. In the interpreter you can now access Octave through Python:
-
-        import numpy
-        import pytave
-        pytave.feval(1, "cos", 0)
-        b = pytave.addpath(".")
-        pytave.feval(1, "testfile", 42)
-
-Note that there is no `testfile.m` file in the distribution. This is
-simply a demonstration of how to execute an arbitrary Octave m-file.
-
-Running test suite in build directory
--------------------------------------
-
-  1. Run `make check`
-
-There are known errors in the test suite.
-
-Creating a source dist
-----------------------
-
-  1. Run `make distcheck`
-
-Hint about foreign systems
---------------------------
-
-If you are running on a system incapable of executing the configure
-scripts (e.g. a Microsoft Windows system), you may want to try
-installing the MinGW and MSYS packages, and build everything inside that
-environment. This isn't for the faint of heart though, since you
-need/want to build Octave too. It is probably easier than trying to
-build without configure scripts, that's all. There are no guarantees
-that it will build at all, it has not been tested.
--- a/Makefile.am	Thu May 04 21:33:36 2017 -0700
+++ b/Makefile.am	Fri May 05 15:55:41 2017 -0700
@@ -36,7 +36,7 @@
   oct-py-util.cc
 
 DOC_FILES = \
-  INSTALL.md \
+  CONTRIBUTORS.md \
   README.md
 
 M_FILES = \
--- a/NEWS	Thu May 04 21:33:36 2017 -0700
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,73 +0,0 @@
-Version 0.1.1-bzr 
-
-2012-04-09
-
-* Removed Numeric array support.  The Numeric array Python library is
-  deprecated.  Pytave has used numpy and its extensions since several
-  years ago and it was time to reduce the effort to support both
-  libraries.
-
-2009-05-25
-
-* Added functionality for explicit manipulation of variables.
-  getvar, setvar, isvar can be used to get, set and query variables
-  in the current Octave scope.
-  Example:
-    pytave.setvar("x", 1)
-    pytave.eval(0,"x += 1")
-    x = pytave.getvar("x")
-
-* Added functionality to push/pop anonymous scopes on the Octave call 
-  stack. push_scope and pop_scope are provided to create an anonymous scope
-  and push it on Octave's call stack, to prevent cluttering other variables if
-  nested calls to pytave are in effect.
-
-  Example:
-    pytave.push_scope()
-    pytave.setvar("x", something)
-    pytave.eval(0, "... do something with x)
-    pytave.pop_scope() # wipes out x and restores its previous value, if any
-
-  Of course, for proper safety, try/finally block should be used to ensure the
-  cleanup. For convenience, a local_scope decorator is provided that encloses a
-  whole function in a push_scope/try/finally/pop_scope sequence:
-
-    @pytave.local_scope
-    def my_oct_add(x,y):
-        pytave.setvar("x",x)
-        pytave.setvar("y",y)
-        result, = pytave.eval(1, "x + y")
-        return result
-
-  this function, when called, will not affect the top-level values of x and y, if
-  any.
-
-* The Octave welcome banner is now only displayed if Python is run interactively.
-
-* {}, "" and '' are now accepted as return values and converted to an empty list/string.
-
-2009-05-07
-
-* Added an eval function. A string of Octave code can be executed
-  through this function. The returned values are converted to Python
-  objects as with the feval function.
-
-  In principle, this could be achieved simply using feval("eval", but
-  the advantages to this implementation are:
-
-  1. faster (avoids double call and double conversion of code string)
-
-  2. explicit control of printing rather than implicitly with nargout
-  (as in eval)
-
-  3. separate exception classes for parse error / execution error
-
-2009-05-05
-
-* Added functionality for one-row cell arrays.  The Python list is
-  converted to a one-row cell array and vice versa.
-
-* Added functionality for structs.  The Python dictionary is converted
-  to a Octave struct and vice versa.  The implementation tries to be
-  as true as possible to Octave's struct constructor.
-
--- a/README.md	Thu May 04 21:33:36 2017 -0700
+++ b/README.md	Fri May 05 15:55:41 2017 -0700
@@ -1,190 +1,84 @@
-Pytave README
-=============
-
-For installation instructions specific for Pytave, please see the
-[INSTALL.md](INSTALL.md) file.
-
-Contents of this document
--------------------------
-
-  1. What is Pytave?
-  2. Gotchas
-  3. Pytave and multi-threading
-  4. Python/Octave cheat sheet
+Octave Python Interface
+=======================
 
-What is Pytave?
-===============
-
-Pytave enables Python scripts to use existing m-files (Octave/Matlab
-scripts) for numerical calculations. The Octave language interpreter is
-embedded as a module to Python.
-
-Example use
------------
-
-Calling Octave code in the interactive Python interpreter:
-
-    >>> import pytave
-    >>> pytave.feval(1, "cos", 0)
-    (1.0,)
+This project is for development of a native Python calling interface for
+[GNU Octave](http://www.octave.org).
 
 Goals
 -----
 
-Pytave strives to uphold these points
+The goals of this extension include
 
-  * Good out of the box experience
-  * Good-natured implicit type conversions, no strange PyApple ->
-    octave_orange -> PyBanana chains
+* call any loadable Python modules, classes, and functions
+* automatic translation of certain Octave data types into Python
+  arguments
+* hold reference to and performing operations on any Python data type as
+  Octave variables
+* automatic translation of certain Python data types into Octave return
+  values
+* be as compatible as possible with Matlab's own Python calling
+  interface
 
-Features
+Examples
 --------
 
-A short list of what Pytave is capable of
-
-  * Implicit type conversions between Python and Octave. Supports all
-    NumPy integer and floating point matrices
-  * Architecture independent - no assumption on endian type or integer
-    sizes
-  * Supports cell <-> list and struct <-> dict conversions.
+A few examples are listed here to give a brief introduction to how the
+Python runtime is translated to Octave.
 
-Project homepage
-----------------
-
-[https://bitbucket.org/mtmiller/pytave](https://bitbucket.org/mtmiller/pytave)
-
-Using/hacking
--------------
+Add a directory to the Python module search path
 
-You need the Mercurial version control software (hg). Clone the repo
-with:
+    py.sys.path.insert (int32 (0), "/path/to/module");
 
-    $ hg clone https://bitbucket.org/mtmiller/pytave
-
-You will now have a directory called `pytave` with source code for the
-module. Read the [INSTALL.md](INSTALL.md) file for building instructions.
+Use a vectorized NumPy function
 
-Gotchas
-=======
+    x = py.numpy.sqrt (1:10);
 
-Unfortunately, the implicit conversion is not bijective (there is not a
-one-to-one relation between Octave and Python values). Pytave users
-should be aware of the following cases.
-
-Numeric row vectors to Octave matrices
---------------------------------------
+Call a function with keyword arguments
 
-Numeric row vectors are converted to Octave 1xN matrices; returned 1xN
-matrices will become 1xN numerical arrays, not row vectors. As an
-example, a NumPy array with shape == (3,) will become (1, 3) when
-converted back and forth.
-
-Octave cells to Python lists
-----------------------------
-
-Only row cell arrays can be converted to Python lists.
+    a = py.int ("5ba0", pyargs ("base", int32 (16)));
 
-Python dictionaries to Octave structures
-----------------------------------------
+Read an entire text file into a string
 
-Dictionaries converted to structures must only have string keys. This is
-because Octave structures only allow string keys. Keys must also be
-valid Octave identifiers.
-
-As Octave structures are built using cells, simple variables are
-upgraded to cells when a dictionary is converted. A dictionary
+    s = py.str ().join (py.open ("/etc/passwd").readlines ());
 
-    {"name": "Pytave"}
-
-thus will become
-
-    ans =
-    {
-      name = Pytave
-    }
+Installation
+------------
 
-in Octave. In this listing, Octave is hiding the fact that the value is
-wrapped in a cell. Converted back, cells are converted to Python lists.
-The re-converted Python dictionary will read
-
-    {"name": ["Pytave"]}
-
-which is natural effect because of the way Octave handles structures.
-
-The list values in dictionaries to be converted must be of equal length.
-All restrictions demanded by the Octave `struct` built-in applies.
+There is currently no support for installing this project as an Octave
+package or in a system or user directory for regular use. This is
+intentional, since the project is still being developed and is not
+stable enough for actual use yet.
 
-Pytave and multi-threading
-==========================
-
-Pytave does not handle reentrant calls. It is not thread-safe, and you
-cannot make several Pytave calls in parallel. There are no safety
-harnesses in Pytave (unlike e.g. PySqlite), and Pytave will not stop you
-if you try to make concurrent calls. The behavior is undefined. It is
-not possible to run several calculations in parallel.
-
-That being said, it is possible to do other things while one Pytave call
-is running. Pytave is aware of the Global Interpreter Lock. The lock
-will be released while the Octave interpreter is running, allowing you
-to have other Python threads to run in parallel with the one Octave
-call.
-
-Python/Octave cheat sheet
-=========================
+What is supported is building and running the project from the build
+directory. Building requires Octave and Python development libraries and
+GNU autotools.
 
-Octave and Python share some syntax elements, which unfortunately makes
-it harder to distinguish between the languages. Here are some examples
-in both languages, showing how to build related constructs.
-
-Create a 2x3 matrix
--------------------
+1. `hg clone https://bitbucket.org/mtmiller/pytave`
+2. `cd pytave`
+3. `autoreconf -i`
+4. `./configure`
+5. `make`
+6. Run Octave with the build directory added to the load path
 
-    octave:1> [1, 1, 1; 2, 2, 2]
-    python>>> array([[1, 1, 1], [2, 2, 2]])
-
-Create a 3x2 matrix
--------------------
-
-    octave:1> [1, 1; 2, 2; 3, 3]
-    python>>> array([[1, 1], [2, 2], [3, 3]])
-
-Create a 1x3 matrix
--------------------
+Development
+-----------
 
-    octave:1> [1, 1, 1]
-    python>>> array([[1, 1, 1]])
-
-Create a row vector
--------------------
-
-Not applicable to Octave.
-
-    python>>> array([1, 1, 1])
-
-Note: Python row vectors will be converted to Octave 1xN matrices.
-
-Create a 3x1 matrix
--------------------
-
-    octave:1> [1; 2; 3]
-    python>>> array([[1], [2], [3]])
+We welcome all contributors, bug reports, test results, and ideas for
+improvement. Contributions in any of the following forms, in no
+particular order, are needed and appreciated.
 
-Create a 1x1 structure/dictionary
----------------------------------
-
-    octave:1> struct("x", 1, "y", 2)
-    python>>> {"x": 1, "y": 2}
-
-Create a 1x2 structure array/dictionary containing lists of length 2
---------------------------------------------------------------------
+* Testing on different operating systems and in different environments
+* Testing for full functionality with a variety of Python libraries
+* Bug reports detailing problems encountered or unexpected behavior
+* Code contributions
+* Documentation in the form of examples, improvements to help texts, or
+  some sort of user manual
 
-    octave:1> struct("firstname", {"David", "Håkan"}, ...
-                     "lastname", {"Grundberg", "Fors Nilsson"})
-    python>>> {"firstname": ["David", "Håkan"], \
-               "lastname": ["Grundberg", "Fors Nilsson"]}
+Other Resources
+---------------
 
-Create a 1x3 cell array/list
-----------------------------
+Please discuss or ask questions about this project on the Octave
+[maintainers mailing list](https://lists.gnu.org/mailman/listinfo/octave-maintainers).
 
-    octave:1> {"foo", "bar", "baz"}
-    python>>> ["foo", "bar", "baz"]
+The [wiki page](http://wiki.octave.org/Python_interface) contains more
+examples and ideas about the project.