[pypy-commit] cffi default: Drop the ".. versionchanged" and ".. versionadded", which was not very
arigo
noreply at buildbot.pypy.org
Thu Jul 9 17:10:21 CEST 2015
Author: Armin Rigo <arigo at tunes.org>
Branch:
Changeset: r2218:1223303164c1
Date: 2015-07-09 16:35 +0200
http://bitbucket.org/cffi/cffi/changeset/1223303164c1/
Log: Drop the ".. versionchanged" and ".. versionadded", which was not
very essential and seems not to work on bitbucket's wiki
diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -180,8 +180,6 @@
.. _`common Windows types`: http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751%28v=vs.85%29.aspx
-.. "versionadded:: 0.9.3": intmax_t etc.
-
The declarations can also contain "``...``" at various places; these are
placeholders that will be completed by the compiler. More information
about it below in `Letting the C compiler fill the gaps`_.
@@ -198,17 +196,16 @@
slow to call ``ffi.cdef()`` a lot of times, a consideration that is
important mainly in in-line mode.
-.. versionadded:: 0.8.2
- The ``ffi.cdef()`` call takes an optional
- argument ``packed``: if True, then all structs declared within
- this cdef are "packed". If you need both packed and non-packed
- structs, use several cdefs in sequence.) This
- has a meaning similar to ``__attribute__((packed))`` in GCC. It
- specifies that all structure fields should have an alignment of one
- byte. (Note that the packed attribute has no effect on bit fields so
- far, which mean that they may be packed differently than on GCC.
- Also, this has no effect on structs declared with ``"...;"``---next
- section.)
+The ``ffi.cdef()`` call takes an optional
+argument ``packed``: if True, then all structs declared within
+this cdef are "packed". If you need both packed and non-packed
+structs, use several cdefs in sequence.) This
+has a meaning similar to ``__attribute__((packed))`` in GCC. It
+specifies that all structure fields should have an alignment of one
+byte. (Note that the packed attribute has no effect on bit fields so
+far, which mean that they may be packed differently than on GCC.
+Also, this has no effect on structs declared with ``"...;"``---next
+section.)
.. _`ffi.set_unicode()`:
@@ -233,8 +230,6 @@
``TCHAR`` and friends where hard-coded as unicode, but ``UNICODE`` was,
inconsistently, not defined by default.)
-.. "versionadded:: 0.9" --- inlined in the previous paragraph
-
ffi.dlopen(): loading libraries in ABI mode
-------------------------------------------
@@ -565,7 +560,7 @@
* Function pointers with non-default calling conventions (e.g. on
Windows, "stdcall").
-Note that since version 0.8, declarations like ``int field[];`` in
+Note that declarations like ``int field[];`` in
structures are interpreted as variable-length structures. Declarations
like ``int field[...];`` on the other hand are arrays whose length is
going to be completed by the compiler. You can use ``int field[];``
@@ -575,10 +570,10 @@
get reduced safety checks: for example, you risk overwriting the
following fields by passing too many array items in the constructor.
-.. versionadded:: 1.2
- Thread-local variables (``__thread``) can be accessed, as well as
- variables defined as dynamic macros (``#define myvar (*fetchme())``).
- Before version 1.2, you need to write getter/setter functions.
+*New in version 1.2:*
+Thread-local variables (``__thread``) can be accessed, as well as
+variables defined as dynamic macros (``#define myvar (*fetchme())``).
+Before version 1.2, you need to write getter/setter functions.
Debugging dlopen'ed C libraries
diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -41,13 +41,16 @@
Example::
- >>> ffi.new("char *")
- <cdata 'char *' owning 1 bytes>
>>> ffi.new("int *")
<cdata 'int *' owning 4 bytes>
>>> ffi.new("int[10]")
<cdata 'int[10]' owning 40 bytes>
+ >>> ffi.new("char *") # allocates only one char---not a C string!
+ <cdata 'char *' owning 1 bytes>
+ >>> ffi.new("char[]", "foobar") # this allocates a C string, ending in \0
+ <cdata 'char[]' owning 7 bytes>
+
Unlike C, the returned pointer object has *ownership* on the allocated
memory: when this exact object is garbage-collected, then the memory is
freed. If, at the level of C, you store a pointer to the memory
@@ -514,34 +517,32 @@
discouraged: using this a style, we are more likely to forget the
callback object too early, when it is still in use.
-.. versionadded:: 1.2
+*New in version 1.2:* If you want to be sure to catch all exceptions, use
+``ffi.callback(..., onerror=func)``. If an exception occurs and
+``onerror`` is specified, then ``onerror(exception, exc_value,
+traceback)`` is called. This is useful in some situations where
+you cannot simply write ``try: except:`` in the main callback
+function, because it might not catch exceptions raised by signal
+handlers: if a signal occurs while in C, it will be called after
+entering the main callback function but before executing the
+``try:``.
- If you want to be sure to catch all exceptions, use
- ``ffi.callback(..., onerror=func)``. If an exception occurs and
- ``onerror`` is specified, then ``onerror(exception, exc_value,
- traceback)`` is called. This is useful in some situations where
- you cannot simply write ``try: except:`` in the main callback
- function, because it might not catch exceptions raised by signal
- handlers: if a signal occurs while in C, it will be called after
- entering the main callback function but before executing the
- ``try:``.
+If ``onerror`` returns normally, then it is assumed that it handled
+the exception on its own and nothing is printed to stderr. If
+``onerror`` raises, then both tracebacks are printed. Finally,
+``onerror`` can itself provide the result value of the callback in
+C, but doesn't have to: if it simply returns None---or if
+``onerror`` itself fails---then the value of ``error`` will be
+used, if any.
- If ``onerror`` returns normally, then it is assumed that it handled
- the exception on its own and nothing is printed to stderr. If
- ``onerror`` raises, then both tracebacks are printed. Finally,
- ``onerror`` can itself provide the result value of the callback in
- C, but doesn't have to: if it simply returns None---or if
- ``onerror`` itself fails---then the value of ``error`` will be
- used, if any.
-
- Note the following hack: in ``onerror``, you can access the original
- callback arguments as follows. First check if ``traceback`` is not
- None (it is None e.g. if the whole function ran successfully but
- there was an error converting the value returned: this occurs after
- the call). If ``traceback`` is not None, then ``traceback.tb_frame``
- is the frame of the outermost function, i.e. directly the one invoked
- by the callback handler. So you can get the value of ``argname`` in
- that frame by reading ``traceback.tb_frame.f_locals['argname']``.
+Note the following hack: in ``onerror``, you can access the original
+callback arguments as follows. First check if ``traceback`` is not
+None (it is None e.g. if the whole function ran successfully but
+there was an error converting the value returned: this occurs after
+the call). If ``traceback`` is not None, then ``traceback.tb_frame``
+is the frame of the outermost function, i.e. directly the one invoked
+by the callback handler. So you can get the value of ``argname`` in
+that frame by reading ``traceback.tb_frame.f_locals['argname']``.
FFI Interface
@@ -580,12 +581,10 @@
calls. This function returns this error code as a tuple ``(code,
message)``, adding a readable message like Python does when raising
WindowsError. If the argument ``code`` is given, format that code into
-a message instead of using ``GetLastError()``. *New in version 0.8.*
+a message instead of using ``GetLastError()``.
(Note that it is also possible to declare and call the ``GetLastError()``
function as usual.)
-.. "versionadded:: 0.8" --- inlined in the previous paragraph
-
**ffi.string(cdata, [maxlen])**: return a Python string (or unicode
string) from the 'cdata'.
@@ -637,14 +636,10 @@
``cdata`` object: if it was originally an owning cdata, then its
owned memory will not be freed as long as the buffer is alive.
-.. versionchanged:: 0.8.2
- Before version 0.8.2, ``bytes(buf)`` was supported in Python 3 to get
- the content of the buffer, but on Python 2 it would return the repr
- ``<_cffi_backend.buffer object>``. This has been fixed. But you
- should avoid using ``str(buf)``: it gives inconsistent results
- between Python 2 and Python 3 (this is similar to how ``str()``
- gives inconsistent results on regular byte strings). Use ``buf[:]``
- instead.
+Python 2/3 compatibility note: you should avoid using ``str(buf)``,
+because it gives inconsistent results between Python 2 and Python 3.
+This is similar to how ``str()`` gives inconsistent results on regular
+byte strings). Use ``buf[:]`` instead.
**ffi.from_buffer(python_buffer)**: return a ``<cdata 'char[]'>`` that
points to the data of the given Python object, which must support the
@@ -659,8 +654,6 @@
of memoryview, locked) as long as the cdata object returned by
``ffi.from_buffer()`` is alive. *New in version 0.9.*
-.. "versionadded:: 0.9" --- inlined in the previous paragraph
-
**ffi.typeof("C type" or cdata object)**: return an object of type
``<ctype>`` corresponding to the parsed string, or to the C type of the
@@ -711,11 +704,11 @@
offset within the struct of the given field. Corresponds to ``offsetof()``
in C.
-.. versionchanged:: 0.9
- You can give several field names in case of nested structures. You
- can also give numeric values which correspond to array items, in case
- of a pointer or array type. For example, ``ffi.offsetof("int[5]", 2)``
- is equal to the size of two integers, as is ``ffi.offsetof("int *", 2)``.
+*New in version 0.9:*
+You can give several field names in case of nested structures. You
+can also give numeric values which correspond to array items, in case
+of a pointer or array type. For example, ``ffi.offsetof("int[5]", 2)``
+is equal to the size of two integers, as is ``ffi.offsetof("int *", 2)``.
**ffi.getctype("C type" or <ctype>, extra="")**: return the string
@@ -828,8 +821,6 @@
``ffi.new()`` but uses the provided low-level ``alloc`` and ``free``
functions. *New in version 1.2.*
-.. "versionadded:: 1.2" --- inlined in the previous paragraph
-
``alloc()`` is invoked with the size as sole argument. If it returns
NULL, a MemoryError is raised. Later, if ``free`` is not None, it will
be called with the result of ``alloc()`` as argument. Both can be either
More information about the pypy-commit
mailing list