abstract.h: remove long outdated comment

Issue #28838: The documentation is of the Python C API is more complete and
more up to date than this old comment.

Removal suggested by Antoine Pitrou.

Include/abstract.h

@@ -1,127 +1,11 @@
+/* Abstract Object Interface (many thanks to Jim Fulton) */
+
 #ifndef Py_ABSTRACTOBJECT_H
 #define Py_ABSTRACTOBJECT_H
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* Abstract Object Interface (many thanks to Jim Fulton) */
-
-/*
-   PROPOSAL: A Generic Python Object Interface for Python C Modules
-
-Problem
-
-  Python modules written in C that must access Python objects must do
-  so through routines whose interfaces are described by a set of
-  include files.  Unfortunately, these routines vary according to the
-  object accessed.  To use these routines, the C programmer must check
-  the type of the object being used and must call a routine based on
-  the object type.  For example, to access an element of a sequence,
-  the programmer must determine whether the sequence is a list or a
-  tuple:
-
-    if (is_tupleobject(o))
-      e = gettupleitem(o, i)
-    else if (is_listitem(o))
-      e = getlistitem(o, i)
-
-  If the programmer wants to get an item from another type of object
-  that provides sequence behavior, there is no clear way to do it
-  correctly.
-
-  The persistent programmer may peruse object.h and find that the
-  _typeobject structure provides a means of invoking up to (currently
-  about) 41 special operators.  So, for example, a routine can get an
-  item from any object that provides sequence behavior. However, to
-  use this mechanism, the programmer must make their code dependent on
-  the current Python implementation.
-
-  Also, certain semantics, especially memory management semantics, may
-  differ by the type of object being used.  Unfortunately, these
-  semantics are not clearly described in the current include files.
-  An abstract interface providing more consistent semantics is needed.
-
-Proposal
-
-  I propose the creation of a standard interface (with an associated
-  library of routines and/or macros) for generically obtaining the
-  services of Python objects.  This proposal can be viewed as one
-  components of a Python C interface consisting of several components.
-
-  From the viewpoint of C access to Python services, we have (as
-  suggested by Guido in off-line discussions):
-
-  - "Very high level layer": two or three functions that let you exec or
-    eval arbitrary Python code given as a string in a module whose name is
-    given, passing C values in and getting C values out using
-    mkvalue/getargs style format strings.  This does not require the user
-    to declare any variables of type "PyObject *".  This should be enough
-    to write a simple application that gets Python code from the user,
-    execs it, and returns the output or errors.  (Error handling must also
-    be part of this API.)
-
-  - "Abstract objects layer": which is the subject of this proposal.
-    It has many functions operating on objects, and lest you do many
-    things from C that you can also write in Python, without going
-    through the Python parser.
-
-  - "Concrete objects layer": This is the public type-dependent
-    interface provided by the standard built-in types, such as floats,
-    strings, and lists.  This interface exists and is currently
-    documented by the collection of include files provided with the
-    Python distributions.
-
-  From the point of view of Python accessing services provided by C
-  modules:
-
-  - "Python module interface": this interface consist of the basic
-    routines used to define modules and their members.  Most of the
-    current extensions-writing guide deals with this interface.
-
-  - "Built-in object interface": this is the interface that a new
-    built-in type must provide and the mechanisms and rules that a
-    developer of a new built-in type must use and follow.
-
-  This proposal is a "first-cut" that is intended to spur
-  discussion. See especially the lists of notes.
-
-  The Python C object interface will provide four protocols: object,
-  numeric, sequence, and mapping.  Each protocol consists of a
-  collection of related operations.  If an operation that is not
-  provided by a particular type is invoked, then a standard exception,
-  NotImplementedError is raised with an operation name as an argument.
-  In addition, for convenience this interface defines a set of
-  constructors for building objects of built-in types.  This is needed
-  so new objects can be returned from C functions that otherwise treat
-  objects generically.
-
-Memory Management
-
-  For all of the functions described in this proposal, if a function
-  retains a reference to a Python object passed as an argument, then the
-  function will increase the reference count of the object.  It is
-  unnecessary for the caller to increase the reference count of an
-  argument in anticipation of the object's retention.
-
-  All Python objects returned from functions should be treated as new
-  objects.  Functions that return objects assume that the caller will
-  retain a reference and the reference count of the object has already
-  been incremented to account for this fact.  A caller that does not
-  retain a reference to an object that is returned from a function
-  must decrement the reference count of the object (using
-  DECREF(object)) to prevent memory leaks.
-
-  Note that the behavior mentioned here is different from the current
-  behavior for some objects (e.g. lists and tuples) when certain
-  type-specific routines are called directly (e.g. setlistitem).  The
-  proposed abstraction layer will provide a consistent memory
-  management interface, correcting for inconsistent behavior for some
-  built-in types.
-
-Protocols
-*/
-
-
 /* === Object Protocol ================================================== */
 
 /* Implemented elsewhere: