xapian-bindings/python/python.i

   1 %module(directors="1") xapian
   2 %{
   3 /* python.i: SWIG interface file for the Python bindings
   4  *
   5  * Copyright (C) 2011,2012,2013,2015 Olly Betts
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  20  * USA
  21  */
  22 %}
  23
  24 %pythonbegin %{
  25 """
  26 Xapian is a highly adaptable toolkit which allows developers to easily
  27 add advanced indexing and search facilities to their own
  28 applications. It supports the Probabilistic Information Retrieval
  29 model and also supports a rich set of boolean query operators.
  30
  31 In addition to the doc strings provided by this python library, you
  32 may wish to look at the library's overall documentation, either
  33 installed along with the bindings or online at
  34 <https://xapian.org/docs/bindings/python/>, as well as the library's
  35 documentation, possibly installed with the library or with its
  36 development files, or again online at <https://xapian.org/docs/>.
  37 """
  38 %}
  39
  40 %begin %{
  41 #include <config.h>
  42 #include <Python.h>
  43
  44 /* Override SWIG's standard GIL locking machinery - we want to avoid the
  45  * overhead of thread locking when the user's code isn't using threads,
  46  * and to handle the GIL in a way which also works in sub-interpreters.
  47  */
  48 #define SWIG_PYTHON_NO_USE_GIL
  49
  50 #ifdef THREAD_LOCAL
  51
  52 static THREAD_LOCAL PyThreadState * swig_pythreadstate = NULL;
  53
  54 inline void swig_pythreadstate_ensure_init() { }
  55
  56 inline PyThreadState * swig_pythreadstate_reset() {
  57     PyThreadState * v = swig_pythreadstate;
  58     if (v) swig_pythreadstate = NULL;
  59     return v;
  60 }
  61
  62 inline PyThreadState * swig_pythreadstate_set(PyThreadState * v) {
  63     PyThreadState * old = swig_pythreadstate;
  64     swig_pythreadstate = v;
  65     return old;
  66 }
  67
  68 #else
  69
  70 #include <pthread.h>
  71
  72 static pthread_key_t swig_pythreadstate_key;
  73 static pthread_once_t swig_pythreadstate_key_once = PTHREAD_ONCE_INIT;
  74
  75 static void swig_pythreadstate_make_key()
  76 {
  77     if (pthread_key_create(&swig_pythreadstate_key, NULL) != 0)
  78         Py_FatalError("pthread_key_create failed");
  79 }
  80
  81 inline void swig_pythreadstate_ensure_init() {
  82     pthread_once(&swig_pythreadstate_key_once, swig_pythreadstate_make_key);
  83 }
  84
  85 inline PyThreadState * swig_pythreadstate_reset() {
  86     PyThreadState * v = (PyThreadState*)pthread_getspecific(swig_pythreadstate_key);
  87     if (v) pthread_setspecific(swig_pythreadstate_key, NULL);
  88     return v;
  89 }
  90
  91 inline PyThreadState* swig_pythreadstate_set(PyThreadState * v) {
  92     PyThreadState * old = (PyThreadState*)pthread_getspecific(swig_pythreadstate_key);
  93     pthread_setspecific(swig_pythreadstate_key, (void*)v);
  94     return old;
  95 }
  96
  97 #endif
  98
  99 class XapianSWIG_Python_Thread_Block {
 100     bool status;
 101   public:
 102     XapianSWIG_Python_Thread_Block() : status(false) {
 103         if (PyEval_ThreadsInitialized()) {
 104             swig_pythreadstate_ensure_init();
 105             PyThreadState * ts = swig_pythreadstate_reset();
 106             if (ts) {
 107                 status = true;
 108                 PyEval_RestoreThread(ts);
 109             }
 110         }
 111     }
 112     void end() {
 113         if (status) {
 114             if (swig_pythreadstate_set(PyEval_SaveThread()))
 115                 Py_FatalError("swig_pythreadstate set in XapianSWIG_Python_Thread_Block::end()");
 116             status = false;
 117         }
 118     }
 119     ~XapianSWIG_Python_Thread_Block() { end(); }
 120 };
 121
 122 class XapianSWIG_Python_Thread_Allow {
 123     bool status;
 124   public:
 125     XapianSWIG_Python_Thread_Allow() : status(PyEval_ThreadsInitialized()) {
 126         if (status) {
 127             swig_pythreadstate_ensure_init();
 128             if (swig_pythreadstate_set(PyEval_SaveThread()))
 129                 Py_FatalError("swig_pythreadstate set in XapianSWIG_Python_Thread_Allow ctor");
 130         }
 131     }
 132     void end() {
 133         if (status) {
 134             PyThreadState * ts = swig_pythreadstate_reset();
 135             if (!ts)
 136                 Py_FatalError("swig_pythreadstate unset in XapianSWIG_Python_Thread_Block::end()");
 137             PyEval_RestoreThread(ts);
 138             status = false;
 139         }
 140     }
 141     ~XapianSWIG_Python_Thread_Allow() { end(); }
 142 };
 143
 144 #define SWIG_PYTHON_THREAD_BEGIN_BLOCK   XapianSWIG_Python_Thread_Block _xapian_swig_thread_block
 145 #define SWIG_PYTHON_THREAD_END_BLOCK     _xapian_swig_thread_block.end()
 146 #define SWIG_PYTHON_THREAD_BEGIN_ALLOW   XapianSWIG_Python_Thread_Allow _xapian_swig_thread_allow
 147 #define SWIG_PYTHON_THREAD_END_ALLOW     _xapian_swig_thread_allow.end()
 148 %}
 149
 150 // Use SWIG directors for Python wrappers.
 151 #define XAPIAN_SWIG_DIRECTORS
 152
 153 %include version.i
 154 %include ../xapian-head.i
 155
 156 // Doccomments from Doxgyen-generated XML from C++ API docs.
 157 %include doccomments.i
 158
 159 // Manually added exceptions for cases where the automatic comments aren't
 160 // helpful, or are missing.
 161 %include extracomments.i
 162
 163 %include util.i
 164
 165 #define XAPIAN_MIXED_SUBQUERIES_BY_ITERATOR_TYPEMAP
 166
 167 // Don't release the GIL for this method since we use Python C API calls to do
 168 // the iteration.
 169 %nothreadallow Xapian::Query::Query(op op_, XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend, Xapian::termcount parameter = 0);
 170
 171 %typemap(typecheck, precedence=500) (XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend) {
 172     // Checking for a sequence is enough to disambiguate currently.
 173     $1 = PySequence_Check($input);
 174 }
 175
 176 %{
 177 class XapianSWIGQueryItor {
 178     mutable PyObject * seq;
 179
 180     int i;
 181
 182     /// str_obj must be a string object (or bytes object for Python 3.x).
 183     Xapian::Query str_obj_to_query(PyObject * str_obj) const {
 184         char * p;
 185         Py_ssize_t len;
 186 #if PY_VERSION_HEX >= 0x03000000
 187         (void)PyBytes_AsStringAndSize(str_obj, &p, &len);
 188 #else
 189         (void)PyString_AsStringAndSize(str_obj, &p, &len);
 190 #endif
 191         return Xapian::Query(string(p, len));
 192     }
 193
 194   public:
 195     typedef std::random_access_iterator_tag iterator_category;
 196     typedef Xapian::Query value_type;
 197     typedef Xapian::termcount_diff difference_type;
 198     typedef Xapian::Query * pointer;
 199     typedef Xapian::Query & reference;
 200
 201     XapianSWIGQueryItor() : seq(NULL), i(0) { }
 202
 203     void begin(PyObject * seq_) {
 204         seq = seq_;
 205     }
 206
 207     void end(PyObject * seq_) {
 208         i = PySequence_Fast_GET_SIZE(seq_);
 209     }
 210
 211     void free_seq() {
 212         Py_CLEAR(seq);
 213     }
 214
 215     XapianSWIGQueryItor & operator++() {
 216         ++i;
 217         return *this;
 218     }
 219
 220     Xapian::Query operator*() const {
 221         PyObject * obj = PySequence_Fast_GET_ITEM(seq, i);
 222
 223         // Unicode object.
 224         if (PyUnicode_Check(obj)) {
 225             PyObject *s = PyUnicode_EncodeUTF8(PyUnicode_AS_UNICODE(obj),
 226                                                PyUnicode_GET_SIZE(obj),
 227                                                "ignore");
 228             if (!s) goto fail;
 229             Xapian::Query result = str_obj_to_query(s);
 230             Py_DECREF(s);
 231             return result;
 232         }
 233
 234         // String.
 235 #if PY_VERSION_HEX >= 0x03000000
 236         if (PyBytes_Check(obj))
 237 #else
 238         if (PyString_Check(obj))
 239 #endif
 240             return str_obj_to_query(obj);
 241
 242         // xapian.Query object (or unexpected object type).
 243         {
 244             Xapian::Query * result_ptr = Xapian::get_py_query(obj);
 245             if (result_ptr) return *result_ptr;
 246         }
 247
 248     fail:
 249         throw Xapian::InvalidArgumentError("Expected Query object or string");
 250     }
 251
 252     bool operator==(const XapianSWIGQueryItor & o) {
 253         return i == o.i;
 254     }
 255
 256     bool operator!=(const XapianSWIGQueryItor & o) {
 257         return !(*this == o);
 258     }
 259
 260     difference_type operator-(const XapianSWIGQueryItor &o) const {
 261         return i - o.i;
 262     }
 263 };
 264
 265 %}
 266
 267 %typemap(in) (XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend) {
 268     PyObject * seq;
 269     seq = PySequence_Fast($input,
 270                           "expected sequence of Query objects and/or strings");
 271     if (!seq) SWIG_fail;
 272     $1.begin(seq);
 273     $2.end(seq);
 274 }
 275
 276 %typemap(freearg) (XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend)
 277 %{ $1.free_seq(); %}
 278
 279 %include except.i
 280 %include ../xapian-headers.i
 281 %include extra.i