[pypy-commit] cffi default: Document the removal of FILE, add demos.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r1185:456ad2f4381b
Date: 2013-03-07 10:37 +0100
http://bitbucket.org/cffi/cffi/changeset/456ad2f4381b/

Log:	Document the removal of FILE, add demos.

diff --git a/demo/file1.py b/demo/file1.py
--- a/demo/file1.py
+++ b/demo/file1.py
@@ -1,10 +1,15 @@
 import cffi
 import os
 
+#
+# To access FILE objects in C that correspond directly to file descriptors
+# at the Python level, just define and use fdopen() and fclose().
+#
 
 ffi = cffi.FFI()
 
 ffi.cdef("""
+typedef ... FILE;   // this line is optional: FILE is predefined if missing
 FILE *fdopen(int, const char *);
 int fclose(FILE *);
 void dumpme(FILE *);
@@ -17,6 +22,7 @@
 }
 """)
 
+# ____________________________________________________________
 
 
 pipe_in, pipe_out = os.pipe()
diff --git a/demo/file2.py b/demo/file2.py
new file mode 100644
--- /dev/null
+++ b/demo/file2.py
@@ -0,0 +1,35 @@
+import cffi
+import sys, os
+
+#
+# To exchange Python-file <file> objects and C-level FILE objects,
+# you need to go via file descriptors and be careful about flushing.
+#
+
+ffi = cffi.FFI()
+
+ffi.cdef("""
+FILE *fdopen(int, const char *);
+int fclose(FILE *);
+
+int fprintf(FILE *, const char *, ...);
+""")
+
+lib = ffi.verify("")
+
+
+def make_FILE(file_like_object):
+    fd = file_like_object.fileno()
+    fd = os.dup(fd)
+    f = lib.fdopen(fd, file_like_object.mode)
+    if not f:
+        os.close(fd)
+        raise ValueError("fdopen() failed")
+    return f
+
+# ____________________________________________________________
+
+
+F = make_FILE(sys.stdout)
+lib.fprintf(F, "Hello, %s!\n", ffi.new("char[]", "world"))
+lib.fclose(F)
diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -395,11 +395,6 @@
 * *New in version 0.6:* bool.  In CFFI 0.4 or 0.5, you had to manually say
   ``typedef _Bool bool;``.  Now such a line is optional.
 
-* *New in version 0.4:* FILE.  You can declare C functions taking a
-  ``FILE *`` argument and call them with a Python file object.  If needed,
-  you can also do ``c_f = ffi.cast("FILE *", fileobj)`` and then pass around
-  ``c_f``.
-
 * *New in version 0.6:* all `common Windows types`_ are defined if you run
   on Windows (``DWORD``, ``LPARAM``, etc.).
 
@@ -407,7 +402,6 @@
 
 .. "versionadded:: 0.4": _Bool
 .. "versionadded:: 0.6": bool
-.. "versionadded:: 0.4": FILE
 .. "versionadded:: 0.6": Wintypes
 
 As we will see on `the verification step`_ below, the declarations can
@@ -423,6 +417,13 @@
    fail, notably with the error ``Multiple type specifiers with a type
    tag``.  Please report it as a bug if it does.)
 
+.. versionchanged:: 0.6
+   Special FILE support was removed.  See `demo/file1.py`_ and
+   `demo/file2.py`_.
+
+.. _`demo/file1.py`: https://bitbucket.org/cffi/cffi/src/default/demo/file1.py
+.. _`demo/file2.py`: https://bitbucket.org/cffi/cffi/src/default/demo/file2.py
+
 
 Loading libraries
 -----------------