[Python-Dev] Where is PyMarshal_ReadShortFromFile() ?

[Fred L. Drake, Jr.]

James C. Ahlstrom writes:
 > Yes, I think PyMarshal_ReadLongFromFile() and PyMarshal_ReadShortFromFile()
 > are indeed part of Python's public C API, and that is why they were in
 > marshal.c with public declarations.

  I think my "should they be?" question remains valid.

 > But they can't be tested by Lib/test_marshal.py because they are not
 > available in the marshal module.  I don't know of an existing C API
 > tester, and the names are highly descriptive in lieu of documentation.

  Modules/_testcapimodule.c.
  The long names we use for the C API make reading code that uses the
API very comfortable, but doesn't help with discoverability.  The
reference documentation could use some improvements for that, but
generally does much better than the headers, if only because you don't
need to be familiar with the arrangement of all the different headers.
(API users should not need to be familiar with all the headers; they
should only need to know to #include Python.h.)

 > And marshal.c has been relegated to supporting module.c anyway.
 > In short, I think we are getting a bit carried away.

  Is this a comment on the testing or the documentation requirements?
If the function is being sufficiently covered by other tests, then we
don't need to add new tests.  Since it was missing, I have to presume
it wasn't being called.  That tells me that it either isn't needed at
all or some test needs to exercise it.
  As for the documentation, I think the discoverability issue I
brought up indicates that we're doing the right thing -- its a lot
easier to learn the public API with documentation than without it.  I
don't know about the rest of the PythonLabs group, but I certainly
find the C API documentaiton useful.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation