[pyke] / pyke.h

/* -*-c-*-
 *
 * Pyke: the Python Kit for Extensions
 *
 * (c) 2019 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Pyke: the Python Kit for Extensions.
 *
 * Pyke is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 *
 * Pyke is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Pyke.  If not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef PYKE_H
#define PYKE_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#define PY_SSIZE_T_CLEAN

#include <Python.h>
#include <structmember.h>

/*----- Other preliminaries -----------------------------------------------*/

#define NOTHING
#define COMMA ,

/*----- Symbol visibility -------------------------------------------------*
 *
 * This library is very messy regarding symbol namespace.  Keep this mess
 * within our shared-object.
 */

#define GOBBLE_SEMI extern int notexist
#if defined(__GNUC__) && defined(__ELF__)
#  define PRIVATE_SYMBOLS _Pragma("GCC visibility push(hidden)") GOBBLE_SEMI
#  define PUBLIC_SYMBOLS _Pragma("GCC visibility pop") GOBBLE_SEMI
#  define EXPORT __attribute__((__visibility__("default")))
#else
#  define PRIVATE_SYMBOLS GOBBLE_SEMI
#  define PUBLIC_SYMBOLS GOBBLE_SEMI
#  define EXPORT
#endif

PRIVATE_SYMBOLS;

/*----- Utilities for returning values and exceptions ---------------------*/

/* Returning values. */
#define RETURN_OBJ(obj) do { Py_INCREF(obj); return (obj); } while (0)
#define RETURN_NONE RETURN_OBJ(Py_None)
#define RETURN_NOTIMPL RETURN_OBJ(Py_NotImplemented)
#define RETURN_TRUE RETURN_OBJ(Py_True)
#define RETURN_FALSE RETURN_OBJ(Py_False)
#define RETURN_ME RETURN_OBJ(me)

/* Returning exceptions.  (Note that `KeyError' is `MAPERR' here, because
 * Catacomb has its own kind of `KeyError'.)
 */
#define EXCERR(exc, str) do {						\
  PyErr_SetString(exc, str);						\
  goto end;								\
} while (0)
#define VALERR(str) EXCERR(PyExc_ValueError, str)
#define OVFERR(str) EXCERR(PyExc_OverflowError, str)
#define TYERR(str) EXCERR(PyExc_TypeError, str)
#define IXERR(str) EXCERR(PyExc_IndexError, str)
#define ZDIVERR(str) EXCERR(PyExc_ZeroDivisionError, str)
#define SYSERR(str) EXCERR(PyExc_SystemError, str)
#define NIERR(str) EXCERR(PyExc_NotImplementedError, str)
#define INDEXERR(idx) do {						\
  PyErr_SetObject(PyExc_KeyError, idx);					\
  goto end;								\
} while (0)
#define OSERR(name) do {						\
  PyErr_SetFromErrnoWithFilename(PyExc_OSError, name);			\
  goto end;								\
} while (0)

/* Saving and restoring exceptions. */
struct excinfo { PyObject *ty, *val, *tb; };
#define EXCINFO_INIT { 0, 0, 0 }
#define INIT_EXCINFO(exc) do {						\
  struct excinfo *_exc = (exc); _exc->ty = _exc->val = _exc->tb = 0;	\
} while (0)
#define RELEASE_EXCINFO(exc) do {					\
  struct excinfo *_exc = (exc);						\
  Py_XDECREF(_exc->ty);	 _exc->ty  = 0;					\
  Py_XDECREF(_exc->val); _exc->val = 0;					\
  Py_XDECREF(_exc->tb);	 _exc->tb  = 0;					\
} while (0)
#define STASH_EXCINFO(exc) do {						\
  struct excinfo *_exc = (exc);						\
  PyErr_Fetch(&_exc->ty, &_exc->val, &_exc->tb);			\
  PyErr_NormalizeException(&_exc->ty, &_exc->val, &_exc->tb);		\
} while (0)
#define RESTORE_EXCINFO(exc) do {					\
  struct excinfo *_exc = (exc);						\
  PyErr_Restore(_exc->ty, _exc->val, _exc->tb);				\
  _exc->ty = _exc->val = _exc->tb = 0;					\
} while (0)
extern void report_lost_exception(struct excinfo *, const char *, ...);
extern void report_lost_exception_v(struct excinfo *, const char *, va_list);
extern void stash_exception(struct excinfo *, const char *, ...);
extern void restore_exception(struct excinfo *, const char *, ...);

/*----- Conversions -------------------------------------------------------*/

/* Define an input conversion (`O&') function: check that the object has
 * Python type TY, and extract a C pointer to CTY by calling EXT on the
 * object (which may well be a macro).
 */
#define CONVFUNC(ty, cty, ext)						\
  int conv##ty(PyObject *o, void *p)					\
  {									\
    if (!PyObject_TypeCheck(o, ty##_pytype))				\
      TYERR("wanted a " #ty);						\
    *(cty *)p = ext(o);							\
    return (1);								\
  end:									\
    return (0);								\
  }

/* Input conversion functions for standard kinds of objects, with overflow
 * checking where applicable.
 */
extern int convulong(PyObject *, void *); /* unsigned long */
extern int convuint(PyObject *, void *); /* unsigned int */
extern int convszt(PyObject *, void *);	/* size_t */
extern int convbool(PyObject *, void *); /* bool */

/* Output conversions. */
extern PyObject *getbool(int);		/* bool */
extern PyObject *getulong(unsigned long); /* any kind of unsigned integer */

/*----- Miscellaneous utilities -------------------------------------------*/

#define FREEOBJ(obj)							\
  (((PyObject *)(obj))->ob_type->tp_free((PyObject *)(obj)))
  /* Actually free OBJ, e.g., in a deallocation function. */

extern PyObject *abstract_pynew(PyTypeObject *, PyObject *, PyObject *);
  /* A `tp_new' function which refuses to make the object. */

#define KWLIST (/*unconst*/ char **)kwlist
  /* Strip `const' qualifiers from the keyword list `kwlist'.  Useful when
   * calling `PyArg_ParseTupleAndKeywords', which isn't `const'-correct.
   */

/*----- Type definitions --------------------------------------------------*
 *
 * Pyke types are defined in a rather unusual way.
 *
 * The main code defines a `type skeleton' of type `PyTypeObject',
 * conventionally named `TY_pytype_skel'.  Unlike typical Python type
 * definitions in extensions, this can (and should) be read-only.  Also,
 * there's no point in setting the `tp_base' pointer here, because the actual
 * runtime base type object won't, in general, be known at compile time.
 * Instead, the type skeletons are converted into Python `heap types' by the
 * `INITTYPE' macro.  The main difference is that Python code can add
 * attributes to heap types, and we make extensive use of this ability.
 */

extern void *newtype(PyTypeObject */*meta*/,
		     const PyTypeObject */*skel*/, const char */*name*/);
  /* Make and return a new Python type object, of type META (typically
   * `PyType_Type', but may be a subclass), filled in from the skeleton SKEL
   * (null to inherit everything), and named NAME.  The caller can mess with
   * the type object further at this time: call `typeready' when it's set up
   * properly.
   */

extern void typeready(PyTypeObject *);
  /* The type object is now ready to be used. */

extern PyTypeObject *inittype(PyTypeObject */*skel*/,
			      PyTypeObject */*meta*/);
  /* All-in-one function to construct a working type from a type skeleton
   * SKEL, with metaclass META.  The caller is expected to have filled in the
   * direct superclass in SKEL->tp_base.
   */

/* Alias for built-in types, to fit in with Pyke naming conventions. */
#define root_pytype 0
#define type_pytype &PyType_Type

#define INITTYPE_META(ty, base, meta) do {				\
  ty##_pytype_skel.tp_base = base##_pytype;				\
  ty##_pytype = inittype(&ty##_pytype_skel, meta##_pytype);		\
} while (0)
#define INITTYPE(ty, base) INITTYPE_META(ty, base, type)
  /* Macros to initialize a type from its skeleton. */

/* Convenience wrappers for filling in `PyMethodDef' tables, following
 * Pyke naming convention.  Define `METHNAME' locally as
 *
 *	#define METHNAME(name) foometh_##func
 *
 * around the method table.
 */
#define METH(func, doc)							\
  { #func, METHNAME(func), METH_VARARGS, doc },
#define KWMETH(func, doc)						\
  { #func, (PyCFunction)METHNAME(func),					\
    METH_VARARGS | METH_KEYWORDS, doc },

/* Convenience wrappers for filling in `PyGetSetDef' tables, following Pyke
 * naming convention.  Define `GETSETNAME' locally as
 *
 *	#define GETSETNAME(op, name) foo##op##_##func
 *
 * around the get/set table.
 */
#define GET(func, doc)							\
  { #func, GETSETNAME(get, func), 0, doc },
#define GETSET(func, doc)						\
  { #func, GETSETNAME(get, func), GETSETNAME(set, func), doc },

/* Convenience wrapper for filling in `PyMemberDef' tables.  Define
 * `MEMBERSTRUCT' locally as
 *
 *	#define MEMBERSTRUCT foo_pyobj
 *
 * around the member table.
 */
#define MEMBER(name, ty, f, doc)					\
  { #name, ty, offsetof(MEMBERSTRUCT, name), f, doc },

/*----- Populating modules ------------------------------------------------*/

extern PyObject *modname;
  /* The overall module name.  Set this with `PyString_FromString'. */

extern PyObject *home_module;
  /* The overall module object. */

extern PyObject *mkexc(PyObject */*mod*/, PyObject */*base*/,
		       const char */*name*/, PyMethodDef */*methods*/);
  /* Make and return an exception class called NAME, which will end up in
   * module MOD (though it is not added at this time).  The new class is a
   * subclass of BASE.  Attach the METHODS to it.
   */

#define INSERT(name, ob) do {						\
  PyObject *_o = (PyObject *)(ob);					\
  Py_INCREF(_o);							\
  PyModule_AddObject(mod, name, _o);					\
} while (0)
  /* Insert a Python object OB into the module `mod' under the given NAME. */

/* Numeric constants. */
struct nameval { const char *name; unsigned f; unsigned long value; };
#define CF_SIGNED 1u
extern void setconstants(PyObject *, const struct nameval *);

#define INSEXC(name, var, base, meth)					\
  INSERT(name, var = mkexc(mod, base, name, meth))
  /* Insert an exception class into the module `mod'; other arguments are as
   * for `mkexc'.
   */

/*----- Submodules --------------------------------------------------------*
 *
 * It's useful to split the Python module up into multiple source files, and
 * have each one contribute its definitions into the main module.
 *
 * Define a list-macro `MODULES' in the master header file naming the
 * submodules to be processed, and run
 *
 *	MODULES(DECLARE_MODINIT)
 *
 * to declare the interface functions.
 *
 * Each submodule FOO defines two functions: `FOO_pyinit' initializes types
 * (see `INITTYPE' above) and accumulates methods (`addmethods' below), while
 * `FOO_pyinsert' populates the module with additional definitions
 * (especially types, though also constants).
 *
 * The top-level module initialization should call `INIT_MODULES' before
 * creating the Python module, and `INSERT_MODULES' afterwards to make
 * everything work.
 */

extern void addmethods(const PyMethodDef *);
extern PyMethodDef *donemethods(void);
  /* Accumulate method-table fragments, and return the combined table of all
   * of the fragments.
   */

#define DECLARE_MODINIT(m)						\
  extern void m##_pyinit(void);						\
  extern void m##_pyinsert(PyObject *);
  /* Declare submodule interface functions. */

#define DOMODINIT(m) m##_pyinit();
#define DOMODINSERT(m) m##_pyinsert(mod);
#define INIT_MODULES do { MODULES(DOMODINIT) } while (0)
#define INSERT_MODULES do { MODULES(DOMODINSERT) } while (0)
  /* Top-level dispatch to the various submodules. */

/*----- Generic mapping support -------------------------------------------*/

/* Mapping methods. */
#define GMAP_METH(func, doc) { #func, gmapmeth_##func, METH_VARARGS, doc },
#define GMAP_KWMETH(func, doc)						\
  { #func, (PyCFunction)gmapmeth_##func, METH_VARARGS|METH_KEYWORDS, doc },
#define GMAP_METHDECL(func, doc)					\
  extern PyObject *gmapmeth_##func(PyObject *, PyObject *);
#define GMAP_KWMETHDECL(func, doc)					\
  extern PyObject *gmapmeth_##func(PyObject *, PyObject *, PyObject *);

#define GMAP_DOROMETHODS(METH, KWMETH)					\
  METH	(has_key,	"D.has_key(KEY) -> BOOL")			\
  METH	(keys,		"D.keys() -> LIST")				\
  METH	(values,	"D.values() -> LIST")				\
  METH	(items,		"D.items() -> LIST")				\
  METH	(iterkeys,	"D.iterkeys() -> ITER")				\
  METH	(itervalues,	"D.itervalues() -> ITER")			\
  METH	(iteritems,	"D.iteritems() -> ITER")			\
  KWMETH(get,		"D.get(KEY, [default = None]) -> VALUE")

#define GMAP_DOMETHODS(METH, KWMETH)					\
  GMAP_DOROMETHODS(METH, KWMETH)					\
  METH	(clear,		"D.clear()")					\
  KWMETH(setdefault,	"D.setdefault(K, [default = None]) -> VALUE")	\
  KWMETH(pop,		"D.pop(KEY, [default = <error>]) -> VALUE")	\
  METH	(popitem,	"D.popitem() -> (KEY, VALUE)")			\
  METH	(update,	"D.update(MAP)")

GMAP_DOMETHODS(GMAP_METHDECL, GMAP_KWMETHDECL)
#define GMAP_ROMETHODS GMAP_DOROMETHODS(GMAP_METH, GMAP_KWMETH)
#define GMAP_METHODS GMAP_DOMETHODS(GMAP_METH, GMAP_KWMETH)

/* Mapping protocol implementation. */
extern Py_ssize_t gmap_pysize(PyObject *); /* for `mp_length' */
extern PySequenceMethods gmap_pysequence; /* for `tp_as_sequence' */
extern PyMethodDef gmap_pymethods[]; /* all the standard methods */

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif
Commit	Line	Data
c1756f78 MW	1	/* --c--
	2	*
	3	* Pyke: the Python Kit for Extensions
	4	*
	5	* (c) 2019 Straylight/Edgeware
	6	*/
	7
	8	/----- Licensing notice --------------------------------------------------
	9	*
	10	* This file is part of Pyke: the Python Kit for Extensions.
	11	*
	12	* Pyke is free software: you can redistribute it and/or modify it under
	13	* the terms of the GNU General Public License as published by the Free
	14	* Software Foundation; either version 2 of the License, or (at your
	15	* option) any later version.
	16	*
	17	* Pyke is distributed in the hope that it will be useful, but WITHOUT
	18	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	19	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	20	* for more details.
	21	*
	22	* You should have received a copy of the GNU General Public License
	23	* along with Pyke. If not, write to the Free Software Foundation, Inc.,
	24	* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
	25	*/
	26
	27	#ifndef PYKE_H
	28	#define PYKE_H
	29
	30	#ifdef __cplusplus
	31	extern "C" {
	32	#endif
	33
	34	/----- Header files ------------------------------------------------------/
	35
	36	#define PY_SSIZE_T_CLEAN
	37
	38	#include <Python.h>
	39	#include <structmember.h>
	40
	41	/----- Other preliminaries -----------------------------------------------/
	42
	43	#define NOTHING
	44	#define COMMA ,
	45
	46	/----- Symbol visibility -------------------------------------------------
	47	*
	48	* This library is very messy regarding symbol namespace. Keep this mess
	49	* within our shared-object.
	50	*/
	51
	52	#define GOBBLE_SEMI extern int notexist
	53	#if defined(__GNUC__) && defined(__ELF__)
	54	# define PRIVATE_SYMBOLS _Pragma("GCC visibility push(hidden)") GOBBLE_SEMI
	55	# define PUBLIC_SYMBOLS _Pragma("GCC visibility pop") GOBBLE_SEMI
	56	# define EXPORT __attribute__((__visibility__("default")))
	57	#else
	58	# define PRIVATE_SYMBOLS GOBBLE_SEMI
	59	# define PUBLIC_SYMBOLS GOBBLE_SEMI
	60	# define EXPORT
	61	#endif
	62
	63	PRIVATE_SYMBOLS;
	64
65	/----- Utilities for returning values and exceptions ---------------------/
66
67	/* Returning values. */
68	#define RETURN_OBJ(obj) do { Py_INCREF(obj); return (obj); } while (0)
69	#define RETURN_NONE RETURN_OBJ(Py_None)
70	#define RETURN_NOTIMPL RETURN_OBJ(Py_NotImplemented)
71	#define RETURN_TRUE RETURN_OBJ(Py_True)
72	#define RETURN_FALSE RETURN_OBJ(Py_False)
73	#define RETURN_ME RETURN_OBJ(me)
74
75	/* Returning exceptions. (Note that `KeyError' is `MAPERR' here, because
76	* Catacomb has its own kind of `KeyError'.)
77	*/
78	#define EXCERR(exc, str) do { \
79	PyErr_SetString(exc, str); \
80	goto end; \
81	} while (0)
82	#define VALERR(str) EXCERR(PyExc_ValueError, str)
83	#define OVFERR(str) EXCERR(PyExc_OverflowError, str)
84	#define TYERR(str) EXCERR(PyExc_TypeError, str)
85	#define IXERR(str) EXCERR(PyExc_IndexError, str)
86	#define ZDIVERR(str) EXCERR(PyExc_ZeroDivisionError, str)
87	#define SYSERR(str) EXCERR(PyExc_SystemError, str)
88	#define NIERR(str) EXCERR(PyExc_NotImplementedError, str)
89	#define INDEXERR(idx) do { \
90	PyErr_SetObject(PyExc_KeyError, idx); \
91	goto end; \
92	} while (0)
93	#define OSERR(name) do { \
94	PyErr_SetFromErrnoWithFilename(PyExc_OSError, name); \
95	goto end; \
96	} while (0)
97
98	/* Saving and restoring exceptions. */
99	struct excinfo { PyObject ty, val, *tb; };
100	#define EXCINFO_INIT { 0, 0, 0 }
101	#define INIT_EXCINFO(exc) do { \
102	struct excinfo *_exc = (exc); _exc->ty = _exc->val = _exc->tb = 0; \
103	} while (0)
104	#define RELEASE_EXCINFO(exc) do { \
105	struct excinfo *_exc = (exc); \
106	Py_XDECREF(_exc->ty); _exc->ty = 0; \
107	Py_XDECREF(_exc->val); _exc->val = 0; \
108	Py_XDECREF(_exc->tb); _exc->tb = 0; \
109	} while (0)
110	#define STASH_EXCINFO(exc) do { \
111	struct excinfo *_exc = (exc); \
112	PyErr_Fetch(&_exc->ty, &_exc->val, &_exc->tb); \
113	PyErr_NormalizeException(&_exc->ty, &_exc->val, &_exc->tb); \
114	} while (0)
115	#define RESTORE_EXCINFO(exc) do { \
116	struct excinfo *_exc = (exc); \
117	PyErr_Restore(_exc->ty, _exc->val, _exc->tb); \
118	_exc->ty = _exc->val = _exc->tb = 0; \
119	} while (0)
120	extern void report_lost_exception(struct excinfo , const char , ...);
121	extern void report_lost_exception_v(struct excinfo , const char , va_list);
122	extern void stash_exception(struct excinfo , const char , ...);
123	extern void restore_exception(struct excinfo , const char , ...);
124
125	/----- Conversions -------------------------------------------------------/
126
127	/* Define an input conversion (`O&') function: check that the object has
128	* Python type TY, and extract a C pointer to CTY by calling EXT on the
129	* object (which may well be a macro).
130	*/
131	#define CONVFUNC(ty, cty, ext) \
132	int conv##ty(PyObject o, void p) \
133	{ \
134	if (!PyObject_TypeCheck(o, ty##_pytype)) \
135	TYERR("wanted a " #ty); \
136	(cty )p = ext(o); \
137	return (1); \
138	end: \
139	return (0); \
140	}
141
142	/* Input conversion functions for standard kinds of objects, with overflow
143	* checking where applicable.
144	*/
145	extern int convulong(PyObject , void ); /* unsigned long */
146	extern int convuint(PyObject , void ); /* unsigned int */
147	extern int convszt(PyObject , void ); /* size_t */
148	extern int convbool(PyObject , void ); /* bool */
149
150	/* Output conversions. */
151	extern PyObject getbool(int); / bool */
152	extern PyObject getulong(unsigned long); / any kind of unsigned integer */
153
154	/----- Miscellaneous utilities -------------------------------------------/
155
156	#define FREEOBJ(obj) \
157	(((PyObject )(obj))->ob_type->tp_free((PyObject )(obj)))
158	/* Actually free OBJ, e.g., in a deallocation function. */
159
160	extern PyObject abstract_pynew(PyTypeObject , PyObject , PyObject );
161	/* A `tp_new' function which refuses to make the object. */
162
163	#define KWLIST (/unconst/ char **)kwlist
164	/* Strip `const' qualifiers from the keyword list `kwlist'. Useful when
165	* calling `PyArg_ParseTupleAndKeywords', which isn't `const'-correct.
166	*/
167
168	/----- Type definitions --------------------------------------------------
169	*
170	* Pyke types are defined in a rather unusual way.
171	*
172	* The main code defines a `type skeleton' of type `PyTypeObject',
173	* conventionally named `TY_pytype_skel'. Unlike typical Python type
174	* definitions in extensions, this can (and should) be read-only. Also,
175	* there's no point in setting the `tp_base' pointer here, because the actual
176	* runtime base type object won't, in general, be known at compile time.
177	* Instead, the type skeletons are converted into Python `heap types' by the
178	* `INITTYPE' macro. The main difference is that Python code can add
179	* attributes to heap types, and we make extensive use of this ability.
180	*/
181
182	extern void newtype(PyTypeObject /meta/,
183	const PyTypeObject /skel/, const char /name/);
184	/* Make and return a new Python type object, of type META (typically
185	* `PyType_Type', but may be a subclass), filled in from the skeleton SKEL
186	* (null to inherit everything), and named NAME. The caller can mess with
187	* the type object further at this time: call `typeready' when it's set up
188	* properly.
189	*/
190
191	extern void typeready(PyTypeObject *);
192	/* The type object is now ready to be used. */
193
194	extern PyTypeObject inittype(PyTypeObject /skel/,
195	PyTypeObject /meta*/);
196	/* All-in-one function to construct a working type from a type skeleton
197	* SKEL, with metaclass META. The caller is expected to have filled in the
198	* direct superclass in SKEL->tp_base.
199	*/
200
201	/* Alias for built-in types, to fit in with Pyke naming conventions. */
202	#define root_pytype 0
203	#define type_pytype &PyType_Type
204
205	#define INITTYPE_META(ty, base, meta) do { \
206	ty##_pytype_skel.tp_base = base##_pytype; \
207	ty##_pytype = inittype(&ty##_pytype_skel, meta##_pytype); \
208	} while (0)
209	#define INITTYPE(ty, base) INITTYPE_META(ty, base, type)
210	/* Macros to initialize a type from its skeleton. */
211
212	/* Convenience wrappers for filling in `PyMethodDef' tables, following
213	* Pyke naming convention. Define `METHNAME' locally as
214	*
215	* #define METHNAME(name) foometh_##func
216	*
217	* around the method table.
218	*/
219	#define METH(func, doc) \
220	{ #func, METHNAME(func), METH_VARARGS, doc },
221	#define KWMETH(func, doc) \
222	{ #func, (PyCFunction)METHNAME(func), \
223	METH_VARARGS \| METH_KEYWORDS, doc },
224
225	/* Convenience wrappers for filling in `PyGetSetDef' tables, following Pyke
226	* naming convention. Define `GETSETNAME' locally as
227	*
228	* #define GETSETNAME(op, name) foo##op##_##func
229	*
230	* around the get/set table.
231	*/
232	#define GET(func, doc) \
233	{ #func, GETSETNAME(get, func), 0, doc },
234	#define GETSET(func, doc) \
235	{ #func, GETSETNAME(get, func), GETSETNAME(set, func), doc },
236
237	/* Convenience wrapper for filling in `PyMemberDef' tables. Define
238	* `MEMBERSTRUCT' locally as
239	*
240	* #define MEMBERSTRUCT foo_pyobj
241	*
242	* around the member table.
243	*/
244	#define MEMBER(name, ty, f, doc) \
245	{ #name, ty, offsetof(MEMBERSTRUCT, name), f, doc },
246
247	/----- Populating modules ------------------------------------------------/
248
249	extern PyObject *modname;
250	/* The overall module name. Set this with `PyString_FromString'. */
251
252	extern PyObject *home_module;
253	/* The overall module object. */
254
255	extern PyObject mkexc(PyObject /mod/, PyObject /base*/,
256	const char /name/, PyMethodDef /methods/);
257	/* Make and return an exception class called NAME, which will end up in
258	* module MOD (though it is not added at this time). The new class is a
259	* subclass of BASE. Attach the METHODS to it.
260	*/
261
262	#define INSERT(name, ob) do { \
263	PyObject _o = (PyObject )(ob); \
264	Py_INCREF(_o); \
265	PyModule_AddObject(mod, name, _o); \
266	} while (0)
267	/* Insert a Python object OB into the module `mod' under the given NAME. */
268
269	/* Numeric constants. */
270	struct nameval { const char *name; unsigned f; unsigned long value; };
271	#define CF_SIGNED 1u
272	extern void setconstants(PyObject , const struct nameval );
273
274	#define INSEXC(name, var, base, meth) \
275	INSERT(name, var = mkexc(mod, base, name, meth))
276	/* Insert an exception class into the module `mod'; other arguments are as
277	* for `mkexc'.
278	*/
279
280	/----- Submodules --------------------------------------------------------
281	*
282	* It's useful to split the Python module up into multiple source files, and
283	* have each one contribute its definitions into the main module.
284	*
285	* Define a list-macro `MODULES' in the master header file naming the
286	* submodules to be processed, and run
287	*
288	* MODULES(DECLARE_MODINIT)
289	*
290	* to declare the interface functions.
291	*
292	* Each submodule FOO defines two functions: `FOO_pyinit' initializes types
293	* (see `INITTYPE' above) and accumulates methods (`addmethods' below), while
294	* `FOO_pyinsert' populates the module with additional definitions
295	* (especially types, though also constants).
296	*
297	* The top-level module initialization should call `INIT_MODULES' before
298	* creating the Python module, and `INSERT_MODULES' afterwards to make
299	* everything work.
300	*/
301
302	extern void addmethods(const PyMethodDef *);
303	extern PyMethodDef *donemethods(void);
304	/* Accumulate method-table fragments, and return the combined table of all
305	* of the fragments.
306	*/
307
308	#define DECLARE_MODINIT(m) \
309	extern void m##_pyinit(void); \
310	extern void m##_pyinsert(PyObject *);
311	/* Declare submodule interface functions. */
312
313	#define DOMODINIT(m) m##_pyinit();
314	#define DOMODINSERT(m) m##_pyinsert(mod);
315	#define INIT_MODULES do { MODULES(DOMODINIT) } while (0)
316	#define INSERT_MODULES do { MODULES(DOMODINSERT) } while (0)
317	/* Top-level dispatch to the various submodules. */
318
319	/----- Generic mapping support -------------------------------------------/
320
321	/* Mapping methods. */
322	#define GMAP_METH(func, doc) { #func, gmapmeth_##func, METH_VARARGS, doc },
323	#define GMAP_KWMETH(func, doc) \
324	{ #func, (PyCFunction)gmapmeth_##func, METH_VARARGS\|METH_KEYWORDS, doc },
325	#define GMAP_METHDECL(func, doc) \
326	extern PyObject gmapmeth_##func(PyObject , PyObject *);
327	#define GMAP_KWMETHDECL(func, doc) \
328	extern PyObject gmapmeth_##func(PyObject , PyObject , PyObject );
329
330	#define GMAP_DOROMETHODS(METH, KWMETH) \
331	METH (has_key, "D.has_key(KEY) -> BOOL") \
332	METH (keys, "D.keys() -> LIST") \
333	METH (values, "D.values() -> LIST") \
334	METH (items, "D.items() -> LIST") \
335	METH (iterkeys, "D.iterkeys() -> ITER") \
336	METH (itervalues, "D.itervalues() -> ITER") \
337	METH (iteritems, "D.iteritems() -> ITER") \
338	KWMETH(get, "D.get(KEY, [default = None]) -> VALUE")
339
340	#define GMAP_DOMETHODS(METH, KWMETH) \
341	GMAP_DOROMETHODS(METH, KWMETH) \
342	METH (clear, "D.clear()") \
343	KWMETH(setdefault, "D.setdefault(K, [default = None]) -> VALUE") \
344	KWMETH(pop, "D.pop(KEY, [default = <error>]) -> VALUE") \
345	METH (popitem, "D.popitem() -> (KEY, VALUE)") \
346	METH (update, "D.update(MAP)")
347
348	GMAP_DOMETHODS(GMAP_METHDECL, GMAP_KWMETHDECL)
349	#define GMAP_ROMETHODS GMAP_DOROMETHODS(GMAP_METH, GMAP_KWMETH)
350	#define GMAP_METHODS GMAP_DOMETHODS(GMAP_METH, GMAP_KWMETH)
351
352	/* Mapping protocol implementation. */
353	extern Py_ssize_t gmap_pysize(PyObject ); / for `mp_length' */
354	extern PySequenceMethods gmap_pysequence; /* for `tp_as_sequence' */
355	extern PyMethodDef gmap_pymethods[]; /* all the standard methods */
356
357	/----- That's all, folks -------------------------------------------------/
358
359	#ifdef __cplusplus
360	}
361	#endif
362
363	#endif