[pypy-commit] pypy default: Rewrite parts of objspace.rst's "Object types" now that the xxxtype.py files have mostly disappeared.

Sat Apr 5 09:56:53 CEST 2014

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r70463:b0013db39761
Date: 2014-04-05 09:56 +0200
http://bitbucket.org/pypy/pypy/changeset/b0013db39761/

Log:	Rewrite parts of objspace.rst's "Object types" now that the
	xxxtype.py files have mostly disappeared. Other fixes in order to
	run pypy/doc/tool/makeref.py.

diff --git a/pypy/doc/_ref.txt b/pypy/doc/_ref.txt
--- a/pypy/doc/_ref.txt
+++ b/pypy/doc/_ref.txt
@@ -4,7 +4,6 @@
 .. _`lib-python/2.7/dis.py`: https://bitbucket.org/pypy/pypy/src/default/lib-python/2.7/dis.py
 .. _`lib_pypy/`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/
 .. _`lib_pypy/greenlet.py`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/greenlet.py
-.. _`lib_pypy/pypy_test/`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/pypy_test/
 .. _`lib_pypy/tputil.py`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/tputil.py
 .. _`pypy/bin/`: https://bitbucket.org/pypy/pypy/src/default/pypy/bin/
 .. _`pypy/bin/pyinteractive.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/bin/pyinteractive.py
@@ -35,7 +34,6 @@
 .. _`pypy/interpreter/gateway.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/gateway.py
 .. _`pypy/interpreter/mixedmodule.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/mixedmodule.py
 .. _`pypy/interpreter/module.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/module.py
-.. _`pypy/interpreter/nestedscope.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/nestedscope.py
 .. _`pypy/interpreter/pyframe.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyframe.py
 .. _`pypy/interpreter/pyopcode.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyopcode.py
 .. _`pypy/interpreter/pyparser`:
@@ -49,21 +47,21 @@
 .. _`pypy/module`:
 .. _`pypy/module/`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/
 .. _`pypy/module/__builtin__/__init__.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/__builtin__/__init__.py
+.. _`pypy/module/cppyy/capi/__init__.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/cppyy/capi/__init__.py
+.. _`pypy/module/cppyy/capi/builtin_capi.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/cppyy/capi/builtin_capi.py
+.. _`pypy/module/cppyy/include/capi.h`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/cppyy/include/capi.h
+.. _`pypy/module/test_lib_pypy/`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/test_lib_pypy/
 .. _`pypy/objspace/`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/
-.. _`pypy/objspace/flow/`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/flow/
 .. _`pypy/objspace/std`:
 .. _`pypy/objspace/std/`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/
-.. _`pypy/objspace/std/listtype.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/listtype.py
+.. _`pypy/objspace/std/bytesobject.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/bytesobject.py
 .. _`pypy/objspace/std/multimethod.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/multimethod.py
 .. _`pypy/objspace/std/objspace.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/objspace.py
 .. _`pypy/objspace/std/proxy_helpers.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/proxy_helpers.py
 .. _`pypy/objspace/std/proxyobject.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/proxyobject.py
-.. _`pypy/objspace/std/stringtype.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/stringtype.py
+.. _`pypy/objspace/std/strbufobject.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/strbufobject.py
 .. _`pypy/objspace/std/transparent.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/transparent.py
-.. _`pypy/objspace/std/tupleobject.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/tupleobject.py
-.. _`pypy/objspace/std/tupletype.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/tupletype.py
 .. _`pypy/tool/`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/
-.. _`pypy/tool/algo/`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/algo/
 .. _`pypy/tool/pytest/`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/pytest/
 .. _`rpython/annotator`:
 .. _`rpython/annotator/`: https://bitbucket.org/pypy/pypy/src/default/rpython/annotator/
@@ -75,6 +73,11 @@
 .. _`rpython/config/translationoption.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/config/translationoption.py
 .. _`rpython/flowspace/`: https://bitbucket.org/pypy/pypy/src/default/rpython/flowspace/
 .. _`rpython/flowspace/model.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/flowspace/model.py
+.. _`rpython/memory/`: https://bitbucket.org/pypy/pypy/src/default/rpython/memory/
+.. _`rpython/memory/gc/generation.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/memory/gc/generation.py
+.. _`rpython/memory/gc/hybrid.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/memory/gc/hybrid.py
+.. _`rpython/memory/gc/minimarkpage.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/memory/gc/minimarkpage.py
+.. _`rpython/memory/gc/semispace.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/memory/gc/semispace.py
 .. _`rpython/rlib`:
 .. _`rpython/rlib/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/
 .. _`rpython/rlib/listsort.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/listsort.py
@@ -93,16 +96,12 @@
 .. _`rpython/rtyper/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/
 .. _`rpython/rtyper/lltypesystem/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/lltypesystem/
 .. _`rpython/rtyper/lltypesystem/lltype.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/lltypesystem/lltype.py
-.. _`rpython/rtyper/memory/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/
-.. _`rpython/rtyper/memory/gc/generation.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/generation.py
-.. _`rpython/rtyper/memory/gc/hybrid.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/hybrid.py
-.. _`rpython/rtyper/memory/gc/minimarkpage.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/minimarkpage.py
-.. _`rpython/rtyper/memory/gc/semispace.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/semispace.py
 .. _`rpython/rtyper/rint.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rint.py
 .. _`rpython/rtyper/rlist.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rlist.py
 .. _`rpython/rtyper/rmodel.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rmodel.py
 .. _`rpython/rtyper/rtyper.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rtyper.py
 .. _`rpython/rtyper/test/test_llinterp.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/test/test_llinterp.py
+.. _`rpython/tool/algo/`: https://bitbucket.org/pypy/pypy/src/default/rpython/tool/algo/
 .. _`rpython/translator`:
 .. _`rpython/translator/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/
 .. _`rpython/translator/backendopt/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/backendopt/
diff --git a/pypy/doc/cppyy_backend.rst b/pypy/doc/cppyy_backend.rst
--- a/pypy/doc/cppyy_backend.rst
+++ b/pypy/doc/cppyy_backend.rst
@@ -51,3 +51,6 @@
 to ``PATH``).
 In case of the former, include files are expected under ``$ROOTSYS/include``
 and libraries under ``$ROOTSYS/lib``.
+
+
+.. include:: _ref.txt
diff --git a/pypy/doc/dir-reference.rst b/pypy/doc/dir-reference.rst
--- a/pypy/doc/dir-reference.rst
+++ b/pypy/doc/dir-reference.rst
@@ -47,7 +47,7 @@
 `pypy/tool/`_                      various utilities and hacks used
                                    from various places
 
-`pypy/tool/algo/`_                 general-purpose algorithmic and mathematic
+`rpython/tool/algo/`_              general-purpose algorithmic and mathematic
                                    tools
 
 `pypy/tool/pytest/`_               support code for our `testing methods`_
@@ -129,3 +129,4 @@
 .. _Mono: http://www.mono-project.com/
 .. _`"standard library"`: rlib.html
 .. _`graph viewer`: getting-started-dev.html#try-out-the-translator
+.. include:: _ref.txt
diff --git a/pypy/doc/objspace.rst b/pypy/doc/objspace.rst
--- a/pypy/doc/objspace.rst
+++ b/pypy/doc/objspace.rst
@@ -339,44 +339,35 @@
 Object types
 ------------
 
-The larger part of the `pypy/objspace/std/`_ package defines and implements the
-library of Python's standard built-in object types.  Each type (int, float,
-list, tuple, str, type, etc.) is typically implemented by two modules:
+The larger part of the `pypy/objspace/std/`_ package defines and
+implements the library of Python's standard built-in object types.  Each
+type ``xxx`` (int, float, list, tuple, str, type, etc.) is typically
+implemented in the module ``xxxobject.py``.
 
-* the *type specification* module, which for a type ``xxx`` is called ``xxxtype.py``;
+The ``W_AbstractXxxObject`` class, when present, is the abstract base
+class, which mainly defines what appears on the Python-level type
+object.  There are then actual implementations as subclasses, which are
+called ``W_XxxObject`` or some variant for the cases where we have
+several different implementations.  For example,
+`pypy/objspace/std/bytesobject.py`_ defines ``W_AbstractBytesObject``,
+which contains everything needed to build the ``str`` app-level type;
+and there are subclasses ``W_BytesObject`` (the usual string) and
+``W_StringBufferObject`` (a special implementation tweaked for repeated
+additions, in `pypy/objspace/std/strbufobject.py`_).  For mutable data
+types like lists and dictionaries, we have a single class
+``W_ListObject`` or ``W_DictMultiObject`` which has an indirection to
+the real data and a strategy; the strategy can change as the content of
+the object changes.
 
-* the *implementation* module, called ``xxxobject.py``.
-
-The ``xxxtype.py`` module basically defines the type object itself.  For
-example, `pypy/objspace/std/listobject.py`_ contains the specification of the object you get when
-you type ``list`` in a PyPy prompt.  `pypy/objspace/std/listobject.py`_ enumerates the methods
-specific to lists, like ``append()``.
-
-A particular method implemented by all types is the ``__new__()`` special
-method, which in Python's new-style-classes world is responsible for creating
-an instance of the type.  In PyPy, ``__new__()`` locates and imports the module
-implementing *instances* of the type, and creates such an instance based on the
-arguments the user supplied to the constructor.  For example, `pypy/objspace/std/tupleobject.py`_
-defines ``__new__()`` to import the class ``W_TupleObject`` from
-`pypy/objspace/std/tupleobject.py`_ and instantiate it.  The `pypy/objspace/std/tupleobject.py`_ then contains a
-"real" implementation of tuples: the way the data is stored in the
-``W_TupleObject`` class, how the operations work, etc.
-
-The goal of the above module layout is to cleanly separate the Python
-type object, visible to the user, and the actual implementation of its
-instances.  It is possible to provide *several* implementations of the
-instances of the same Python type, by writing several ``W_XxxObject``
-classes.  Every place that instantiates a new object of that Python type
-can decide which ``W_XxxObject`` class to instantiate.
-
-From the user's point of view, the multiple internal ``W_XxxObject``
-classes are not visible: they are still all instances of exactly the
-same Python type.  PyPy knows that (e.g.) the application-level type of
-its interpreter-level ``W_StringObject`` instances is str because
-there is a ``typedef`` class attribute in ``W_StringObject`` which
-points back to the string type specification from `pypy/objspace/std/stringobject.py`_; all
-other implementations of strings use the same ``typedef`` from
-`pypy/objspace/std/stringobject.py`_.
+From the user's point of view, even when there are several
+``W_AbstractXxxObject`` subclasses, this is not visible: at the
+app-level, they are still all instances of exactly the same Python type.
+PyPy knows that (e.g.) the application-level type of its
+interpreter-level ``W_BytesObject`` instances is str because there is a
+``typedef`` class attribute in ``W_BytesObject`` which points back to
+the string type specification from `pypy/objspace/std/bytesobject.py`_;
+all other implementations of strings use the same ``typedef`` from
+`pypy/objspace/std/bytesobject.py`_.
 
 For other examples of multiple implementations of the same Python type,
 see `Standard Interpreter Optimizations`_.
@@ -387,6 +378,9 @@
 Multimethods
 ------------
 
+*Note: multimethods are on the way out.  Although they look cool,
+they failed to provide enough benefits.*
+
 The Standard Object Space allows multiple object implementations per
 Python type - this is based on multimethods_.  For a description of the
 multimethod variant that we implemented and which features it supports,
diff --git a/pypy/doc/stm.rst b/pypy/doc/stm.rst
--- a/pypy/doc/stm.rst
+++ b/pypy/doc/stm.rst
@@ -194,9 +194,9 @@
 unchanged.  This capability can be hidden in a library or in the
 framework you use; the end user's code does not need to be explicitly
 aware of using threads.  For a simple example of this, see
-`lib_pypy/transaction.py`_.  The idea is that if you have a program
-where the function ``f(key, value)`` runs on every item of some big
-dictionary, you can replace the loop with::
+`transaction.py`_ in ``lib_pypy``.  The idea is that if you have a
+program where the function ``f(key, value)`` runs on every item of some
+big dictionary, you can replace the loop with::
 
     for key, value in bigdict.items():
         transaction.add(f, key, value)
@@ -217,7 +217,7 @@
 is likely to be found, and communicates it to the system, using for
 example the ``transaction.add()`` scheme.
 
-.. _`lib_pypy/transaction.py`: https://bitbucket.org/pypy/pypy/raw/stmgc-c7/lib_pypy/transaction.py
+.. _`transaction.py`: https://bitbucket.org/pypy/pypy/raw/stmgc-c7/lib_pypy/transaction.py
 .. _OpenMP: http://en.wikipedia.org/wiki/OpenMP
 
 ==================
