Quote from http://docs.python.org/3.0/c-api/arg.html, regarding the "s"
argument:

"""
s (string or Unicode object) [const char *]

    Convert a Python string or Unicode object to a C pointer to a
character string. You must not provide storage for the string itself; a
pointer to an existing string is stored into the character pointer
variable whose address you pass. 
"""

I guess the phrase "you must not provide storage" is a failed
translation and not meant like that. It should say "you are not required
to provide storage". It's confusing to have such strong wording without
reason.

Also, it isn't clear that the returned string must not be modified, 
and that the pointer lifetime is of the original string object itself.
(This applies to all string and unicode formats).

> I guess the phrase "you must not provide storage" is a failed
> translation and not meant like that. It should say "you are not required
> to provide storage". It's confusing to have such strong wording without
> reason.

It's stronger than "you are not required to": if you do provide storage
(by allocating memory), then this memory most likely will be garbage,
and you must not attempt to free it afterwards (as doing so would cause
a crash).

Whenever the documentation says "you must not" it really says "don't do
that or your application *will* crash, burn and die"... Of course I can
allocate storage for the string, copy it's content and then free or -
nothing will happen. How would it cause a crash - it's my own pointer.

That's exactly the line between "not required to", "should not" and
"must not": The current wording suggests that I may not even touch e.g.
malloc which is confusing and in fact to be ignored in it's current state.

For me, when I read "You must not provide storage for the string
itself", it obviously means I mustn't do so *before calling the
PyArg_ParseTuple function*. It is also obvious that I am allowed to copy
the returned contents wherever I want, and it should be obvious to any C
programmer. So I don't see how the wording is misleading.

> Whenever the documentation says "you must not" it really says "don't do
> that or your application *will* crash, burn and die"... Of course I can
> allocate storage for the string, copy it's content and then free or -
> nothing will happen. How would it cause a crash - it's my own pointer.

Suppose you do

  char *s = malloc(MAXPATH);
  if (!PyArg_ParseTuple("s", &s))return NULL;
  do_something_with(s);
  free(s);

then your application *will* crash, burn, and die - because s gets
changed in the call; the original malloc result is garbage, and the
free call will likely crash the malloc implementation (as the block
it points to wasn't malloc-allocated, and isn't the beginning of a
block).

I don't see a reason to keep this open any longer.