[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?

[Fredrik Lundh]

Robin writes:

> A Framemaker standard would apply to the primary printed format and
> doesn't limit the methods/formats used in the authoring
> phase. There's nothing to say that we can't do just what Fredrik
> states. Once the text is written/generated then it would be imported
> into Frame to generate the printed/indexed/postscript version.

Which is exactly what I tried to say :-)

Okay, I couldn't resist trying out my own little concept.  Here's a
somewhat terse (and incomplete) version of the PyArg group of
functions.

So, what do you think?  What more need to be described for each
function?  Is the formatting ok?  Etc, etc...

	/F

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

Source (for one function):

int
PyArg_GetChar(PyObject* args, int nargs, int i, char* p_arg)

	If _args[i]_ can be interpreted as a character, extract it to
	_p_arg[0]_ and return 1.  Otherwise, raise an exception
	and return 0.

	_Args[i]_ should be a string of length 1.

	Old name: _getichararg_

Formatted result (more functions):

<a name=PyArg_GetChar><h2>PyArg_GetChar</h2></a>
<i>int</i><br>
<b>PyArg_GetChar</b><i>(PyObject* args, int nargs, int i, char* p_arg)</i><p>
<p>
<ul>
If <i>args[i]</i> can be interpreted as a character, extract it to
<i>p_arg[0]</i> and return 1. Otherwise, raise an exception
and return 0.
<p>
<i>Args[i]</i> should be a string of length 1.
<p>
Old name: <i>getichararg</i>
<p>
</ul>
<a name=PyArg_GetDoubleArray><h2>PyArg_GetDoubleArray</h2></a>
<i>int</i><br>
<b>PyArg_GetDoubleArray</b><i>(PyObject* args, int nargs, int i, int n, double* p_arg)</i><p>
<p>
<ul>
If <i>args[i]</i> can be interpreted as an array of floating
point values of length <i>n</i>, extract it to <i>p_arg[0..n-1]</i>
and return 1. Otherwise, raise an exception and return
0.
<p>
<i>Args[i]</i> can be either a tuple or a sequence, of length <i>n</i>.
<p>
Old name: <i>getidoublearray</i>
<p>
</ul>
<a name=PyArg_GetFloat><h2>PyArg_GetFloat</h2></a>
<i>int</i><br>
<b>PyArg_GetFloat</b><i>(PyObject* args, int nargs, int i, float* p_arg)</i><p>
<p>
<ul>
If <i>args[i]</i> can be interpreted as a floating point value,
extract it to <i>p_arg[0]</i> and return 1. Otherwise, raise an
exception and return 0.
<p>
Old name: <i>getifloatarg</i>
<p>
</ul>
<a name=PyArg_GetFloatArray><h2>PyArg_GetFloatArray</h2></a>
<i>int</i><br>
<b>PyArg_GetFloatArray</b><i>(PyObject* args, int nargs, int i, int n, float* p_arg)</i><p>
<p>
<ul>
Same as <i>PyArg_GetDoubleArg</i>, but extracts data to a
float array instead.
<p>
Old name: <i>getifloatarray</i>
<p>
</ul>
<a name=PyArg_GetLong><h2>PyArg_GetLong</h2></a>
<i>int</i><br>
<b>PyArg_GetLong</b><i>(PyObject* args, int nargs, int i, long* p_arg)</i><p>
<p>
<ul>
If <i>args[i]</i> can be interpreted as an integer, extract it
to <i>p_arg[0]</i> and return 1. Otherwise, raise an exception
and return 0.
<p>
Old name: <i>getilongarg</i>
<p>
</ul>
<a name=PyArg_GetLongArray><h2>PyArg_GetLongArray</h2></a>
<i>int</i><br>
<b>PyArg_GetLongArray</b><i>(PyObject* args, int nargs, int i, int n, long* p_arg)</i><p>
<p>
<ul>
Same as <a href=#PyArg_GetDoubleArray><b>PyArg_GetDoubleArray</b></a>, but extracts data to a
long array instead.
<p>
Old name: <i>getilongarray</i>
<p>
</ul>
<a name=PyArg_GetLongArraySize><h2>PyArg_GetLongArraySize</h2></a>
<i>int</i><br>
<b>PyArg_GetLongArraySize</b><i>(PyObject* args, int nargs, int i, long* p_arg)</i><p>
<p>
<ul>
If <i>args[i]</i> can interpreted as a sequence, extract the
length to <i>p_arg[0]</i> and return 1. Otherwise, raise an
exception and return 0.
<p>
<i>Args[i]</i> can be either a list or a tuple.
<p>
Old name: <i>getilongarraysize</i>
<p>
</ul>
<a name=PyArg_GetObject><h2>PyArg_GetObject</h2></a>
<i>int</i><br>
<b>PyArg_GetObject</b><i>(PyObject* args, int nargs, int i, PyObject** p_arg)</i><p>
<p>
<ul>
Copy <i>args[i]</i> into <i>p_arg[0]</i>, and return 1. If the argument
does not exist, raise an exception and return 0. Note that
<i>args</i> is either a single object (_n_ = 1), or a tuple of
arguments.
<p>
Old name: <i>getiobjectarg</i>
<p>
</ul>
<a name=PyArg_GetShort><h2>PyArg_GetShort</h2></a>
<i>int</i><br>
<b>PyArg_GetShort</b><i>(PyObject* args, int nargs, int i, int n, float* p_arg)</i><p>
<p>
<ul>
If <i>args[i]</i> can be interpreted as an integer, extract it
to <i>p_arg[0]</i> and return 1. Otherwise, raise an exception
and return 0.
<p>
Old name: <i>getishortarg</i>
<p>
</ul>
<a name=PyArg_GetShortArray><h2>PyArg_GetShortArray</h2></a>
<i>int</i><br>
<b>PyArg_GetShortArray</b><i>(PyObject* args, int nargs, int i, int n, float* p_arg)</i><p>
<p>
<ul>
Same as <a href=#PyArg_GetDoubleArray><b>PyArg_GetDoubleArray</b></a>, but extracts data to a
short array instead.
<p>
Old name: <i>getishortarray</i>
<p>
</ul>
<a name=PyArg_GetShortArraySize><h2>PyArg_GetShortArraySize</h2></a>
<i>int</i><br>
<b>PyArg_GetShortArraySize</b><i>(PyObject* args, int nargs, int i, short* p_arg)</i><p>
<p>
<ul>
Same a <a href=#PyArg_GetLongArraySize><b>PyArg_GetLongArraySize</b></a>, but returns the length
as a short instead.
<p>
FIXME: what happens if the size exceeds 32k?
<p>
Old name: <i>getishortarraysize</i>
<p>
</ul>
<a name=PyArg_GetString><h2>PyArg_GetString</h2></a>
<b>PyArg_GetString</b><i>()</i><p>
<p>
<ul>
FIXME
<p>
Old name: <i>getistringarg</i>
<p>
</ul>
<a name=PyArg_NoArgs><h2>PyArg_NoArgs</h2></a>
<b>PyArg_NoArgs</b><i>()</i><p>
<p>
<ul>
FIXME
<p>
Old name: <i>getnoarg</i>
<p>
</ul>
<a name=PyArg_Parse><h2>PyArg_Parse</h2></a>
<b>PyArg_Parse</b><i>()</i><p>
<p>
<ul>
FIXME
<p>
Old name: <i>getargs</i>
<p>
</ul>
<a name=PyArg_ParseTuple><h2>PyArg_ParseTuple</h2></a>
<b>PyArg_ParseTuple</b><i>()</i><p>
<p>
<ul>
FIXME
<p>
Old name: <i>newgetargs</i>

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================