Add README.in - thanks to Todd Zullinger

git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@1343 f01d2545-417e-4e96-918e-98f8d0dbbcb6

2 files changed, 54 insertions, 0 deletions

diff --git a/bindings/python/Makefile.am b/bindings/python/Makefile.am
index ceaa1fa..642bdca 100644
--- a/bindings/python/Makefile.am
+++ b/bindings/python/Makefile.am
@@ -14,6 +14,9 @@ CLEANFILES =		\
 	gpod_wrap.c	\
 	gpod_wrap.o
 
+MAINTAINERCLEANFILES =	\
+	README
+
 if HAVE_PYTHON
 MODULE_CFLAGS	= `$(PKG_CONFIG) --cflags $(top_srcdir)/libgpod-1.0.pc` $(PYTHON_INCLUDES)
 MODULE_LIBS	= `$(PKG_CONFIG) --libs $(top_srcdir)/libgpod-1.0.pc` -L$(top_srcdir)/src/.libs
@@ -41,6 +44,14 @@ install-pythonDATA: $(python_DATA)
 uninstall-pythonDATA: $(python_DATA)
 	rm -rf $(DESTDIR)$(pythondir)/gpod
 
+README: README.in gpod.i
+	WRAPPER_LIST=`grep 'PyObject\* sw_[^_].*;' gpod.i | awk -F "[ (]" '{ print $$2 }' | tr '\n' ' ' | sort -u`; \
+	sed \
+	    -e "s/@WRAPPER_LIST@/$${WRAPPER_LIST}/" \
+	    -e "/^sw_/ s/ $$//" \
+	    -e "/^sw_/ s/ /\n/g" \
+	    $< > $@
+
 test:
 	cd tests && python tests.py
 endif
diff --git a/bindings/python/README.in b/bindings/python/README.in
new file mode 100644
index 0000000..f5c4501
--- /dev/null
+++ b/bindings/python/README.in
@@ -0,0 +1,43 @@
+There are two ways to use the python libgpod bindings.  Both methods use the
+same namespace (gpod) for convenience.  Just "import gpod" to get started using
+either of them.
+
+The first method provides a 'Pythonic' API.  Most uses of this API will start by
+opening the database with gpod.Database() and then calling methods on the
+returned object.  For example, to read an iTunesDB from an iPod at /mnt/ipod
+and print the title for the tracks in the database:
+
+    import gpod
+    db = gpod.Database('/mnt/ipod')
+    for track in db:
+        print track['title']
+
+Please see ipod.py for the implementation details and the scripts in the
+examples directory for some ideas on how to use the bindings.
+
+
+The second method uses the same API as the C implementation.  Prefix the C
+function names with gpod.  For example, to read an iTunesDB from an iPod at
+/mnt/ipod and display the titles for each track:
+
+    import gpod
+    db = gpod.itdb_parse('/mnt/ipod', None)
+    tracks = gpod.sw_get_tracks(db)
+    for track in tracks:
+        print track.title
+
+See the libgpod C API documentation for the details and available functions.
+
+Note: The C API is translated to Python using SWIG (Simplified Wrapper and
+Interface Generator).  This automated translation sometimes exposes functions
+which return data types that are not useful in Python and require helper
+functions in the bindings.  An example is listing playlists; the C API would
+return a GList which means nothing to Python, so a helper function is provided
+that returns a Python list.  These helper functions are prefixed with sw_ to
+denote that they are not native libgpod functions.
+
+The current helper functions are:
+
+@WRAPPER_LIST@
+
+Please see the example scripts for ideas on how to use these functions.