[Python-bugs-list] [ python-Bugs-440037 ] Extending: need import examples

[noreply@sourceforge.net]

Bugs item #440037, was opened at 2001-07-10 06:26
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=440037&group_id=5470

Category: Documentation
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Nobody/Anonymous (nobody)
Assigned to: Fred L. Drake, Jr. (fdrake)
>Summary: Extending: need import examples

Initial Comment:
Hello,

I have been writing a code generator to call functions
in a Python script from C. The code seems to be working
fine.
In the process, I found some things in the C API manual
that can be improved:

- I would expect 7.4 (numeric objects) before 7.2
(sequence objects)
- PyList_SetItem() does not specify return value
(probably the same as PyTuple_SetItem() "It returns 0
on success.")
- PyList_SET_ITEM() returns a borrowed reference
without specifying to what it refers.
- PyDict_SetItem() doesnot use 'p' in the description
(same for PyDict_SetItemString())
- Return value of both functions is also not specified.
- In PyLong_AsLong(), a stray 'OverflowError' is at the
end of the description.
- Also at PyLong_AsUnsignedLong() (next entry)

What I found lacking in the embedding and extending
manual is the importing of modules, and finding a
function with a specific name from C.  Is this
something that should be included in the EE manual ?
(I'd be willing to give it some thought)

Also, I found 2 'problems' in the interface at code
level. I will add this seperately to the bug report
data base.

Albert (a.t.hofkamp@tue.nl)


----------------------------------------------------------------------

>Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2001-07-11 13:42

Message:
Logged In: YES 
user_id=3066

The recommended re-ordering of sections has been implemented
in Doc/api/api.tex revisions 1.130 and 1.117.2.9.  The
change was included in the 2.1 maintenance branch since this
is a readability bug.

All that remains for this issue are the additions to the
Extending & Embedding manual, so I'm changing the summary as
well.

----------------------------------------------------------------------

Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2001-07-10 09:14

Message:
Logged In: YES 
user_id=3066

The corrections and additions to the API manual have been
committed as Doc/api/api.tex revisions 1.129 and 1.117.2.8.
 Re-ordering of sections will be considered separately.

----------------------------------------------------------------------

Comment By: Nobody/Anonymous (nobody)
Date: 2001-07-10 09:06

Message:
Logged In: NO 

Regarding the order of numeric and sequence objects:

My idea is that numeric objects are easier to understand
than sequence objects. So when browsing through the
documentation (I know the docs are not supposed to be
browsed, but before being able to work with it, one has to
read the EE manual, and probably browse the API manual to
get a feel for the API calls available), the interface for
the numeric objects are relatively easy to understand. With
that knowledge, the next sections become easier, because the
api's for the other objects have a similar structure.

Albert

----------------------------------------------------------------------

Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2001-07-10 08:23

Message:
Logged In: YES 
user_id=3066

I don't understand the comment on the ordering of the
Numeric and Sequence object sections; what is the motivation
for changing the ordering?

Regarding the issue of import & function lookup:  Yes, the
EE manual should cover this.  Suggested text would be
greatly appreciated (without markup is fine), or I can work
on it when time permits.

I've fixed the other issues in my working copy; these should
be checked in before too long.

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=440037&group_id=5470