[ python-Bugs-980925 ] Possible contradiction in "extending" and PyArg_ParseTuple()

[SourceForge.net]

Bugs item #980925, was opened at 2004-06-27 17:02
Message generated for change (Comment added) made by bcannon
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=980925&group_id=5470

Category: Documentation
Group: Python 2.4
>Status: Closed
>Resolution: Fixed
Priority: 5
Submitted By: Brett Cannon (bcannon)
Assigned to: Nobody/Anonymous (nobody)
Summary: Possible contradiction in "extending" and PyArg_ParseTuple()

Initial Comment:
In section 1.3 of the "extending" tutorial (http://www.python.org/
dev/doc/devel/ext/backToExample.html), in the discussion of the 
use of PyArg_ParseTuple() for a string argument, it says that "in 
Standard C, the variable ... should properly be declared as "const 
char *" ".  But if you look at any example code (such as in section 
1.7, which covers parsing arguments; http://www.python.org/dev/
doc/devel/ext/parseTuple.html) and the docs for 
PyArg_ParseTuple() (found at http://www.python.org/dev/doc/
devel/api/arg-parsing.html) just use ``char *`` as the type for the 
argument for a string.

Which is correct?  I suspect that it is not required but more correct 
to have the variables declared ``const char *`` since you are not 
supposed to play with the string that is being pointed to (which is 
probably why the Unicode arguments in the docs for 
PyArg_ParseTuple() say it is ``const char *`` instead of just 
``char *``).  If this is true I will change the docs and the tutorial 
to use ``const char *``.  But if it isn't, I will rip out the line saying 
that you should ``const char *`` since this is a contradiction at the 
moment of recommended practice.

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

>Comment By: Brett Cannon (bcannon)
Date: 2004-07-01 13:58

Message:
Logged In: YES 
user_id=357491

My youth caused rev. 1.15 on Doc/api/utilities.tex to help move us 
forward to a more correct ISO C89 programming world.

Now we just need to move CPython over to C99 before I start telling 
people *their* youth is *my* future and everything will be set.  =)

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

Comment By: Tim Peters (tim_one)
Date: 2004-06-30 21:37

Message:
Logged In: YES 
user_id=31435

"const char *" is best C practice, so the docs should 
encourage it, and that should be the officially documented 
signature.  All the standard C library functions to which it's 
safe to pass a string gotten via PyArg_ParseTuple already 
have const char* prototypes, so the danger of const 
poisoning (needing to supply a cascading number of casts) is 
minimal here.  Most of the likely Python C API functions to 
which we'd pass one of these things are already prototyped 
with const char* too (e.g., PyDict_GetItemString and 
PyString_InternFromString).  Some others should be.  Fighting 
a hopeless rear-guard reactionary battle isn't like Raymond -- 
don't listen to old farts, Brett, our youth is our future <wink>.

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

Comment By: Brett Cannon (bcannon)
Date: 2004-06-28 20:50

Message:
Logged In: YES 
user_id=357491

Perhaps a comment about it then?  So it would still say ``char *`` in 
bold, but in the body mention that ``const char *`` is more proper, but 
could lead to extra casting.  Would that bump you to >= +0?

Regardless of that issue I went ahead and changed Doc/ext/extending.tex 
sans section 1.8 where the example is accredited to someone specific.

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

Comment By: Raymond Hettinger (rhettinger)
Date: 2004-06-28 08:51

Message:
Logged In: YES 
user_id=80475

-0 on changing anything here.  While technically correct,
the proposed revisions can potentially create issues where
none currently exist.  I ignore const and things work find.
 The last thing I want to see are coercions like (const char
*) sprouting-up here and there.  --my two cents

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

Comment By: Brett Cannon (bcannon)
Date: 2004-06-27 21:59

Message:
Logged In: YES 
user_id=357491

OK, I will definitely change the code examples.  How about the docs for 
PyArg_ParseTuple() for "s" and friends?  Should that stay ``char *`` as 
its listed argument type, or should I change that as well (Unicode 
arguments already say ``const char *`` so there is precedence).

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

Comment By: Tim Peters (tim_one)
Date: 2004-06-27 17:33

Message:
Logged In: YES 
user_id=31435

Most of Python, and its docs, were written before C89 
("Standard C") was required.  const is used sporadically as a 
result, mostly just in newer code and docs.

Changing examples to use const char * should be fine, as 
that is best C practice.  Just make sure the examples still 
work <wink -- but sticking "const" in has a way of 
propagating; e.g., once you have a const char *, you can't 
pass it directly to a function taking a (non-const) char * 
argument anymore>.

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

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