1  Cython usage
  2  ============
  3  
  4  The gmpy2 module provides a C-API that can be conveniently used from Cython.
  5  All types and functions are declared in the header gmpy2.pxd that is installed
  6  automatically in your Python path together with the library.
  7  
  8  Initialization
  9  --------------
 10  
 11  In order to use the C-API you need to make one call to the function **void import_gmpy2(void)**.
 12  
 13  Types
 14  -----
 15  
 16  The types **mpz**, **mpq**, **mpfr** and **mpc** are declared as extension
 17  types in gmpy2.pxd. They correspond respectively to the C structures
 18  **MPZ_Object**, **MPQ_Object**, **MPFR_Object** and **MPC_Object**.
 19  
 20  Fast type checking can be done with the following C functions
 21  
 22  **bint MPZ_Check(object)**
 23      equivalent to **isinstance(obj, mpz)**
 24  
 25  **bint MPQ_Check(object)**
 26      equivalent to **isinstance(obj, mpq)**
 27  
 28  **bint MPFR_Check(object)**
 29      equivalent to **isinstance(obj, mpfr)**
 30  
 31  **bint MPC_Check(object)**
 32      equivalent to **isinstance(obj, mpc)**
 33  
 34  Object creation
 35  ---------------
 36  
 37  To create a new gmpy2 types there are four basic functions
 38  
 39  **mpz GMPy_MPZ_New(void * ctx)**
 40      create a new mpz object from a given context ctx
 41  
 42  **mpq GMPy_MPQ_New(void * ctx)**
 43      create a new mpq object from a given context ctx
 44  
 45  **mpfr MPFR_New(void * ctx, mpfr_prec_t prec)**
 46      create a new mpfr object with given context ctx and precision prec
 47  
 48  **mpc MPC_New(void * ctx, mpfr_prec_t rprec, mpfr_prec_t iprec)**
 49      create a new mpc object with given context ctx, precisions rprec and iprec of
 50      respectively real and imaginary parts
 51  
 52  The context can be set to **NULL** and controls the default behavior (e.g. precision).
 53  
 54  The gmpy2.pxd header also provides convenience macro to wrap a (copy of) a mpz_t, mpq_t, mpfr_t
 55  or a mpc_t object into the corresponding gmpy2 type.
 56  
 57  **mpz GMPy_MPZ_From_mpz(mpz_srcptr z)**
 58      return a new mpz object with a given mpz_t value z
 59  
 60  **mpq GMPy_MPQ_From_mpq(mpq_srcptr q)**
 61      return a new mpq object from a given mpq_t value q
 62  
 63  **mpq GMPy_MPQ_From_mpz(mpz_srcptr num, mpz_srcptr den)**
 64      return a new mpq object with a given mpz_t numerator num and mpz_t denominator den
 65  
 66  **mpfr GMPy_MPFR_From_mpfr(mpfr_srcptr x)**
 67      return a new mpfr object with a given mpfr_t value x
 68  
 69  **mpc GMPy_MPC_From_mpc(mpc_srcptr c)**
 70      return a new mpc object with a given mpc_t value c
 71  
 72  **mpc GMPy_MPC_From_mpfr(mpfr_srcptr re, mpfr_srcptr im)**
 73      return a new mpc object with a given mpfr_t real part re and mpfr_t imaginary part im
 74  
 75  Access to the underlying C type
 76  --------------------------------
 77  
 78  Each of the gmpy2 objects has a field corresponding to the underlying C
 79  type. The following functions give access to this field
 80  
 81  **mpz_t MPZ(mpz)**
 82  
 83  **mpq_t MPQ(mpq)**
 84  
 85  **mpfr_t MPFR(mpfr)**
 86  
 87  **mpc_t MPC(mpc)**
 88  
 89  Compilation
 90  ------------
 91  
 92  The header gmpy2.pxd as well as the C header gmpy2.h from which it depends
 93  are installed in the Python path. In order to make Cython and the C compiler aware
 94  of the existence of these files, the Python path should be part of the include
 95  directories.
 96  
 97  Recall that **import_gmpy2()** needs to be called *before* any other function of
 98  the C-API.
 99  
100  Here is a minimal example of a Cython file test_gmpy2.pyx
101  
102  ::
103  
104      "A minimal cython file test_gmpy2.pyx"
105  
106      from gmpy2 cimport *
107  
108      cdef extern from "gmp.h":
109          void mpz_set_si(mpz_t, long)
110  
111      import_gmpy2()   # needed to initialize the C-API
112  
113      cdef mpz z = GMPy_MPZ_New(NULL)
114      mpz_set_si(MPZ(z), -7)
115  
116      print(z + 3)
117  
118  The corresponding setup.py is given below.
119  
120  ::
121  
122      "A minimal setup.py for compiling test_gmpy2.pyx"
123  
124      from distutils.core import setup
125      from distutils.extension import Extension
126      from Cython.Build import cythonize
127      import sys
128  
129      ext = Extension("test_gmpy2", ["test_gmpy2.pyx"], include_dirs=sys.path, libraries=['gmp', 'mpfr', 'mpc'])
130  
131      setup(
132          name="cython_gmpy_test",
133          ext_modules=cythonize([ext], include_path=sys.path)
134      )
135  
136  With these two files in the same repository, you should be able to compile your
137  module using
138  
139  ::
140  
141      $ python setup.py build_ext --inplace
142  
143  For more about compilation and installation of cython files and extension
144  modules, please refer to the official documentation of Cython and distutils.