[pypy-commit] cffi default: Attempt to improve intro text for people not familiar with problem
techtonik
noreply at buildbot.pypy.org
Sat Jun 21 21:33:34 CEST 2014
Author: anatoly techtonik <techtonik at gmail.com>
Branch:
Changeset: r1515:8d721cd75852
Date: 2014-05-30 14:10 +0300
http://bitbucket.org/cffi/cffi/changeset/8d721cd75852/
Log: Attempt to improve intro text for people not familiar with problem
diff --git a/doc/source/index.rst b/doc/source/index.rst
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,31 +1,32 @@
CFFI documentation
================================
-Foreign Function Interface for Python calling C code. The aim of this project
-is to provide a convenient and reliable way of calling C code from Python.
-The interface is based on `LuaJIT's FFI`_ and follows a few principles:
+C Foreign Function Interface for Python. The goal is to provide a
+convenient and reliable way to call compiled C code from Python using
+interface declarations written in C.
-* The goal is to call C code from Python. You should be able to do so
- without learning a 3rd language: every alternative requires you to learn
- their own language (Cython_, SWIG_) or API (ctypes_). So we tried to
- assume that you know Python and C and minimize the extra bits of API that
- you need to learn.
+The interface is based on `LuaJIT's FFI`_, and follows a few principles:
+
+* The goal is to call C code from Python without learning a 3rd language:
+ existing alternatives require to learn domain specific language
+ (Cython_, SWIG_) or API (ctypes_). CFFI design requires users to know
+ only C and Python, minimizing extra bits of API that need to be learned.
* Keep all the Python-related logic in Python so that you don't need to
write much C code (unlike `CPython native C extensions`_).
-* Work either at the level of the ABI (Application Binary Interface)
- or the API (Application Programming Interface). Usually, C
- libraries have a specified C API but often not an ABI (e.g. they may
+* Support level of the ABI (Application Binary Interface) calling system
+ functions directly (the way ctypes_ works) and level of the API
+ (Application Programming Interface) using compiler to validate and link
+ C language constructs. Usually, C libraries have a specified C API,
+ bt often not an ABI (e.g. they may
document a "struct" as having at least these fields, but maybe more).
- (ctypes_ works at the ABI level, whereas Cython_ and `native C extensions`_
- work at the API level.)
-* We try to be complete. For now some C99 constructs are not supported,
+* Try to be complete. For now some C99 constructs are not supported,
but all C89 should be, including macros (and including macro "abuses",
which you can `manually wrap`_ in saner-looking C functions).
-* We attempt to support both PyPy and CPython, with a reasonable path
+* Attempt to support both PyPy and CPython, with a reasonable path
for other Python implementations like IronPython and Jython.
* Note that this project is **not** about embedding executable C code in
More information about the pypy-commit
mailing list