[pypy-svn] r20428 - pypy/dist/pypy/doc
cfbolz at codespeak.net
cfbolz at codespeak.net
Wed Nov 30 13:05:31 CET 2005
Author: cfbolz
Date: Wed Nov 30 13:05:29 2005
New Revision: 20428
Modified:
pypy/dist/pypy/doc/architecture.txt
pypy/dist/pypy/doc/coding-guide.txt
pypy/dist/pypy/doc/getting-started-0.8.txt
pypy/dist/pypy/doc/getting-started.txt
pypy/dist/pypy/doc/interpreter.txt
pypy/dist/pypy/doc/translation.txt
Log:
move the section about app/interp-level from architecture to coding guide. fix
links etc.
Modified: pypy/dist/pypy/doc/architecture.txt
==============================================================================
--- pypy/dist/pypy/doc/architecture.txt (original)
+++ pypy/dist/pypy/doc/architecture.txt Wed Nov 30 13:05:29 2005
@@ -194,120 +194,8 @@
in the directory `objspace/`_.
.. _`objspace document`: objspace.html
-
-
-.. _`application-level`:
-.. _`interpreter-level`:
-
-Application-level and interpreter-level execution and objects
-=============================================================
-
-Since Python is used for implementing all of our code base, there is a
-crucial distinction to be aware of: that between *interpreter-level* objects and
-*application-level* objects. The latter are the ones that you deal with
-when you write normal python programs. Interpreter-level code, however,
-cannot invoke operations nor access attributes from application-level
-objects. You will immediately recognize any interpreter level code in
-PyPy, because half the variable and object names start with a ``w_``, which
-indicates that they are `wrapped`_ application-level values.
-
-Let's show the difference with a simple example. To sum the contents of
-two variables ``a`` and ``b``, one would write the simple application-level
-``a+b`` -- in contrast, the equivalent interpreter-level code is
-``space.add(w_a, w_b)``, where ``space`` is an instance of an object space,
-and ``w_a`` and ``w_b`` are typical names for the wrapped versions of the
-two variables.
-
-It helps to remember how CPython deals with the same issue: interpreter
-level code, in CPython, is written in C and thus typical code for the
-addition is ``PyNumber_Add(p_a, p_b)`` where ``p_a`` and ``p_b`` are C
-variables of type ``PyObject*``. This is conceptually similar to how we write
-our interpreter-level code in Python.
-
-Moreover, in PyPy we have to make a sharp distinction between
-interpreter- and application-level *exceptions*: application exceptions
-are always contained inside an instance of ``OperationError``. This
-makes it easy to distinguish failures (or bugs) in our interpreter-level code
-from failures appearing in a python application level program that we are
-interpreting.
-
-
-.. _`app-preferable`:
-
-Application level is often preferable
--------------------------------------
-
-Application-level code is substantially higher-level, and therefore
-correspondingly easier to write and debug. For example, suppose we want
-to implement the ``update`` method of dict objects. Programming at
-application level, we can write an obvious, simple implementation, one
-that looks like an **executable definition** of ``update``, for
-example::
-
- def update(self, other):
- for k in other.keys():
- self[k] = other[k]
-
-If we had to code only at interpreter level, we would have to code
-something much lower-level and involved, say something like::
-
- def update(space, w_self, w_other):
- w_keys = space.call_method(w_other, 'keys')
- w_iter = space.iter(w_keys)
- while True:
- try:
- w_key = space.next(w_iter)
- except OperationError, e:
- if not e.match(space, space.w_StopIteration):
- raise # re-raise other app-level exceptions
- break
- w_value = space.getitem(w_other, w_key)
- space.setitem(w_self, w_key, w_value)
-
-This interpreter-level implementation looks much more similar to the C
-source code. It is still more readable than its C counterpart because
-it doesn't contain memory management details and can use Python's native
-exception mechanism.
-
-In any case, it should be obvious that the application-level implementation
-is definitely more readable, more elegant and more maintainable than the
-interpreter-level one.
-
-In fact, in almost all parts of PyPy, you find application level code in
-the middle of interpreter-level code. Apart from some bootstrapping
-problems (application level functions need a certain initialization
-level of the object space before they can be executed), application
-level code is usually preferable. We have an abstraction (called the
-'Gateway') which allows the caller of a function to remain ignorant of
-whether a particular function is implemented at application or
-interpreter level.
-
-
-.. _`wrapped`:
-
-Wrapping
----------
-
-The ``w_`` prefixes so lavishly used in the previous example indicate,
-by PyPy coding convention, that we are dealing with *wrapped* (or *boxed*) objects,
-that is, interpreter-level objects which the object space constructs
-to implement corresponding application-level objects. Each object
-space supplies ``wrap``, ``unwrap``, ``int_w``, ``interpclass_w``,
-etc. operations that move between the two levels for objects of simple
-built-in types; each object space also implements other Python types
-with suitable interpreter-level classes with some amount of internal
-structure.
-
-For example, an application-level Python ``list``
-is implemented by the `standard object space`_ as an
-instance of ``W_ListObject``, which has an instance attribute
-``wrappeditems`` (an interpreter-level list which contains the
-application-level list's items as wrapped objects).
-
-The rules are described in more details `in the coding guide`_.
-
-.. _`in the coding guide`: coding-guide.html#wrapping-rules
-
+.. _`application-level`: coding-guide.html#application-level
+.. _`interpreter-level`: coding-guide.html#interpreter-level
.. _`translation process in more details`:
.. _`later in this document`:
Modified: pypy/dist/pypy/doc/coding-guide.txt
==============================================================================
--- pypy/dist/pypy/doc/coding-guide.txt (original)
+++ pypy/dist/pypy/doc/coding-guide.txt Wed Nov 30 13:05:29 2005
@@ -12,11 +12,11 @@
.. _`RPython`:
-Restricted Python
-==================
+Overview and motivation
+========================
We are writing a Python interpreter in Python, using Python's well known
-ability to step behind the algorithmic problems as language. At first glance,
+ability to step behind the algorithmic problems as a language. At first glance,
one might think this achieves nothing but a better understanding how the
interpreter works. This alone would make it worth doing, but we have much
larger goals.
@@ -41,12 +41,100 @@
interpreter and create a C source, again. There are many other ways,
but let's stick with this somewhat canonical approach.
+
+.. _`application-level`:
+.. _`interpreter-level`:
+
+Application-level and interpreter-level execution and objects
+-------------------------------------------------------------
+
+Since Python is used for implementing all of our code base, there is a
+crucial distinction to be aware of: that between *interpreter-level* objects and
+*application-level* objects. The latter are the ones that you deal with
+when you write normal python programs. Interpreter-level code, however,
+cannot invoke operations nor access attributes from application-level
+objects. You will immediately recognize any interpreter level code in
+PyPy, because half the variable and object names start with a ``w_``, which
+indicates that they are `wrapped`_ application-level values.
+
+Let's show the difference with a simple example. To sum the contents of
+two variables ``a`` and ``b``, one would write the simple application-level
+``a+b`` -- in contrast, the equivalent interpreter-level code is
+``space.add(w_a, w_b)``, where ``space`` is an instance of an object space,
+and ``w_a`` and ``w_b`` are typical names for the wrapped versions of the
+two variables.
+
+It helps to remember how CPython deals with the same issue: interpreter
+level code, in CPython, is written in C and thus typical code for the
+addition is ``PyNumber_Add(p_a, p_b)`` where ``p_a`` and ``p_b`` are C
+variables of type ``PyObject*``. This is conceptually similar to how we write
+our interpreter-level code in Python.
+
+Moreover, in PyPy we have to make a sharp distinction between
+interpreter- and application-level *exceptions*: application exceptions
+are always contained inside an instance of ``OperationError``. This
+makes it easy to distinguish failures (or bugs) in our interpreter-level code
+from failures appearing in a python application level program that we are
+interpreting.
+
+
+.. _`app-preferable`:
+
+Application level is often preferable
+-------------------------------------
+
+Application-level code is substantially higher-level, and therefore
+correspondingly easier to write and debug. For example, suppose we want
+to implement the ``update`` method of dict objects. Programming at
+application level, we can write an obvious, simple implementation, one
+that looks like an **executable definition** of ``update``, for
+example::
+
+ def update(self, other):
+ for k in other.keys():
+ self[k] = other[k]
+
+If we had to code only at interpreter level, we would have to code
+something much lower-level and involved, say something like::
+
+ def update(space, w_self, w_other):
+ w_keys = space.call_method(w_other, 'keys')
+ w_iter = space.iter(w_keys)
+ while True:
+ try:
+ w_key = space.next(w_iter)
+ except OperationError, e:
+ if not e.match(space, space.w_StopIteration):
+ raise # re-raise other app-level exceptions
+ break
+ w_value = space.getitem(w_other, w_key)
+ space.setitem(w_self, w_key, w_value)
+
+This interpreter-level implementation looks much more similar to the C
+source code. It is still more readable than its C counterpart because
+it doesn't contain memory management details and can use Python's native
+exception mechanism.
+
+In any case, it should be obvious that the application-level implementation
+is definitely more readable, more elegant and more maintainable than the
+interpreter-level one.
+
+In fact, in almost all parts of PyPy, you find application level code in
+the middle of interpreter-level code. Apart from some bootstrapping
+problems (application level functions need a certain initialization
+level of the object space before they can be executed), application
+level code is usually preferable. We have an abstraction (called the
+'Gateway') which allows the caller of a function to remain ignorant of
+whether a particular function is implemented at application or
+interpreter level.
+
our runtime interpreter is "restricted python"
----------------------------------------------
-In order to make a C code generator feasible we restrict ourselves to a
-subset of the Python language, and we adhere to some rules which make
-translation to lower level languages more obvious.
+In order to make a C code generator feasible all code on interpreter level has
+to restrict itself to a subset of the Python language, and we adhere to some
+rules which make translation to lower level languages feasible. Code on
+application level can still use the full expressivity of Python.
Unlike source-to-source translations (like e.g. Starkiller_) we start
translation from live python code objects which constitute our Python
@@ -79,6 +167,9 @@
.. _`pyopcode.py`: http://codespeak.net/svn/pypy/dist/pypy/interpreter/pyopcode.py
+Restricted Python
+=================
+
RPython Definition, not
-----------------------
@@ -340,10 +431,14 @@
adhere to our implicit assertions.
.. _`wrapping rules`:
+.. _`wrapped`:
Wrapping rules
==============
+Wrapping
+---------
+
PyPy is made of Python source code at two levels: there is on the one hand
*application-level code* that looks like normal Python code, and that
implements some functionalities as one would expect from Python code (e.g. one
@@ -358,6 +453,24 @@
sequel is only about interpreter-level code. (Ideally, no application-level
variable should be called ``space`` or ``w_xxx`` to avoid confusion.)
+The ``w_`` prefixes so lavishly used in the example above indicate,
+by PyPy coding convention, that we are dealing with *wrapped* (or *boxed*) objects,
+that is, interpreter-level objects which the object space constructs
+to implement corresponding application-level objects. Each object
+space supplies ``wrap``, ``unwrap``, ``int_w``, ``interpclass_w``,
+etc. operations that move between the two levels for objects of simple
+built-in types; each object space also implements other Python types
+with suitable interpreter-level classes with some amount of internal
+structure.
+
+For example, an application-level Python ``list``
+is implemented by the `standard object space`_ as an
+instance of ``W_ListObject``, which has an instance attribute
+``wrappeditems`` (an interpreter-level list which contains the
+application-level list's items as wrapped objects).
+
+The rules are described in more details below.
+
Naming conventions
------------------
Modified: pypy/dist/pypy/doc/getting-started-0.8.txt
==============================================================================
--- pypy/dist/pypy/doc/getting-started-0.8.txt (original)
+++ pypy/dist/pypy/doc/getting-started-0.8.txt Wed Nov 30 13:05:29 2005
@@ -197,7 +197,7 @@
You may be interested in reading more about the distinction between
`interpreter-level and app-level`_.
-.. _`interpreter-level and app-level`: architecture.html#interpreter-level
+.. _`interpreter-level and app-level`: coding-guide.html#interpreter-level
.. _`trace example`:
Modified: pypy/dist/pypy/doc/getting-started.txt
==============================================================================
--- pypy/dist/pypy/doc/getting-started.txt (original)
+++ pypy/dist/pypy/doc/getting-started.txt Wed Nov 30 13:05:29 2005
@@ -188,7 +188,7 @@
You may be interested in reading more about the distinction between
`interpreter-level and app-level`_.
-.. _`interpreter-level and app-level`: architecture.html#interpreter-level
+.. _`interpreter-level and app-level`: coding-guide.html#interpreter-level
.. _`trace example`:
Modified: pypy/dist/pypy/doc/interpreter.txt
==============================================================================
--- pypy/dist/pypy/doc/interpreter.txt (original)
+++ pypy/dist/pypy/doc/interpreter.txt Wed Nov 30 13:05:29 2005
@@ -92,7 +92,7 @@
.. _`how-to guide for descriptors`: http://users.rcn.com/python/download/Descriptor.htm
.. _`annotation pass`: translation.html#the-annotation-pass
.. _`initialization time`: architecture.html#initialization-time
-.. _`interpreter-level and application-level`: architecture.html#interpreter-level
+.. _`interpreter-level and application-level`: coding-guide.html#interpreter-level
.. _`wrapped`: coding-guide.html#wrapping-rules
.. _`object space`: architecture.html#objectspace
.. _`application level exceptions`: coding-guide.html#applevel-exceptions
@@ -366,7 +366,7 @@
implementation at interpreter-level and we would not have
to modify the calling side at all.
-.. _`often preferable`: architecture.html#app-preferable
+.. _`often preferable`: coding-guide.html#app-preferable
.. _`interpreter descriptors`:
Introspection and Descriptors
Modified: pypy/dist/pypy/doc/translation.txt
==============================================================================
--- pypy/dist/pypy/doc/translation.txt (original)
+++ pypy/dist/pypy/doc/translation.txt Wed Nov 30 13:05:29 2005
@@ -1046,7 +1046,7 @@
corresponding interpreted code, but no interpreter is needed
any longer to execute this code.
-.. _`application-level`: architecture.html#app-preferable
+.. _`application-level`: coding-guide.html#app-preferable
.. _exceptions: http://codespeak.net/pypy/dist/pypy/lib/_exceptions.py
.. _oldstyle: http://codespeak.net/pypy/dist/pypy/lib/_classobj.py
More information about the Pypy-commit
mailing list