From 6a328514d29989087672030aabe783b6a72803b9 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Fri, 24 May 2013 22:10:26 -0400
Subject: [PATCH] Docs and more.

---
 doc/index.rst         |  2 +-
 doc/utilities.rst     | 41 +++++++++++++++++++++++++++++++++++++++++
 pymbolic/compiler.py  | 11 ++++++++---
 setup.py              | 16 +++++++++++++++-
 test/test_pymbolic.py |  3 +--
 5 files changed, 66 insertions(+), 7 deletions(-)
 create mode 100644 doc/utilities.rst

diff --git a/doc/index.rst b/doc/index.rst
index d59ae5f..ad8d411 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -17,9 +17,9 @@ Contents
    :maxdepth: 2
 
    primitives
+   mappers
    utilities
    algorithms
-   mappers
    geometric-algebra
    misc
 
diff --git a/doc/utilities.rst b/doc/utilities.rst
new file mode 100644
index 0000000..4879478
--- /dev/null
+++ b/doc/utilities.rst
@@ -0,0 +1,41 @@
+Utilities for dealing with exressions
+=====================================
+
+Parser
+------
+
+.. currentmodule:: pymbolic
+
+.. function:: parse(expr_str)
+
+    Return a :class:`pymbolic.primitives.Expression` tree corresponding to *expr_str*.
+
+The parser is also relatively easy to extend. See the source code of the following
+class.
+
+.. automodule:: pymbolic.parser
+
+.. autoclass:: Parser
+
+Compiler
+--------
+
+.. automodule:: pymbolic.compiler
+
+.. autoclass:: CompiledExpression
+
+    .. method:: __call__(*args)
+
+
+:mod:`sympy` interface
+----------------------
+
+.. automodule:: pymbolic.sympy_interface
+
+.. class:: SympyToPymbolicMapper
+
+    .. method:: __call__(expr)
+
+.. class:: PymbolicToSympyMapper
+
+    .. method:: __call__(expr)
diff --git a/pymbolic/compiler.py b/pymbolic/compiler.py
index 466554c..b3fa626 100644
--- a/pymbolic/compiler.py
+++ b/pymbolic/compiler.py
@@ -99,13 +99,18 @@ class CompileMapper(StringifyMapper):
 
 
 class CompiledExpression:
-    """This class encapsulates a compiled expression.
+    """This class encapsulates an expression compiled into Python bytecode
+    for faster evaluation.
 
-    The main reason for its existence is the fact that a dynamically-constructed
-    lambda function is not picklable.
+    Its instances (unlike plain lambdas) are pickleable.
     """
 
     def __init__(self, expression, variables = []):
+        """
+        :arg variables: The first arguments to be used for the compiled function.
+            All variables used by the expression and not present here are added
+            in alphabetical order.
+        """
         import pymbolic.primitives as primi
 
         self._Expression = expression
diff --git a/setup.py b/setup.py
index 137ef88..3288524 100644
--- a/setup.py
+++ b/setup.py
@@ -6,6 +6,12 @@ distribute_setup.use_setuptools()
 
 from setuptools import setup
 
+try:
+    from distutils.command.build_py import build_py_2to3 as build_py
+except ImportError:
+    # 2.x
+    from distutils.command.build_py import build_py
+
 ver_dic = {}
 version_file = open("pymbolic/version.py")
 try:
@@ -27,6 +33,13 @@ setup(name="pymbolic",
         'License :: OSI Approved :: MIT License',
         'Natural Language :: English',
         'Programming Language :: Python',
+        'Programming Language :: Python :: 3',
+        # We use conditional expressions, so 2.5 is the bare minimum.
+        'Programming Language :: Python :: 2.5',
+        'Programming Language :: Python :: 2.6',
+        'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3.2',
+        'Programming Language :: Python :: 3.3',
         'Topic :: Scientific/Engineering',
         'Topic :: Scientific/Engineering :: Mathematics',
         'Topic :: Software Development :: Libraries',
@@ -43,4 +56,5 @@ setup(name="pymbolic",
           'pytest>=2.3',
           ],
 
-     )
+      # 2to3 invocation
+      cmdclass={'build_py': build_py})
diff --git a/test/test_pymbolic.py b/test/test_pymbolic.py
index 684fc83..b9b9a80 100644
--- a/test/test_pymbolic.py
+++ b/test/test_pymbolic.py
@@ -245,8 +245,7 @@ def test_geometric_algebra(dims):
                 a*(b*c))
         assert ((a^b)^c).close_to(
                 a^(b^c))
-        #assert ((a|b)|c).close_to(
-                #a|(b|c))
+        # The inner product is not associative.
 
         # scalar product
         assert ( (c*b).project(0) ) .close_to( b.scalar_product(c) )
-- 
GitLab