Merge branch 'master' into broken_and_redirect_links

CHANGES.rst

@@ -70,6 +70,9 @@ Bugs fixed
   generated an invalid C function call to the (non-existent) base type implementation.
   (Github issue #2309)
 
+* Exception catching based on a non-literal (runtime) tuple could fail to match the
+  exception.  (Github issue #2425)
+
 
 0.28.3 (2018-05-27)
 ===================
@@ -2180,9 +2183,9 @@ Features added
 
 * GDB support. http://docs.cython.org/src/userguide/debugging.html
 
-* A new build system with support for inline distutils directives, correct dependency tracking, and parallel compilation. http://wiki.cython.org/enhancements/distutils_preprocessing
+* A new build system with support for inline distutils directives, correct dependency tracking, and parallel compilation. https://github.com/cython/cython/wiki/enhancements-distutils_preprocessing
 
-* Support for dynamic compilation at runtime via the new cython.inline function and cython.compile decorator. http://wiki.cython.org/enhancements/inline
+* Support for dynamic compilation at runtime via the new cython.inline function and cython.compile decorator. https://github.com/cython/cython/wiki/enhancements-inline
 
 * "nogil" blocks are supported when compiling pure Python code by writing "with cython.nogil".
 

Cython/Build/Dependencies.py

@@ -809,8 +809,7 @@ def create_extension_list(patterns, exclude=None, ctx=None, aliases=None, quiet=
             elif name:
                 module_name = name
 
-            if module_name == 'cython':
-                raise ValueError('cython is a special module, cannot be used as a module name')
+            Utils.raise_error_if_module_name_forbidden(module_name)
 
             if module_name not in seen:
                 try:

Cython/Compiler/Lexicon.py

@@ -3,7 +3,7 @@
 #   Cython Scanner - Lexical Definitions
 #
 
-from __future__ import absolute_import
+from __future__ import absolute_import, unicode_literals
 
 raw_prefixes = "rR"
 bytes_prefixes = "bB"

Cython/Compiler/Main.py

@@ -469,6 +469,8 @@ def run_pipeline(source, options, full_module_name=None, context=None):
     abs_path = os.path.abspath(source)
     full_module_name = full_module_name or context.extract_module_name(source, options)
 
+    Utils.raise_error_if_module_name_forbidden(full_module_name)
+
     if options.relative_path_in_code_position_comments:
         rel_path = full_module_name.replace('.', os.sep) + source_ext
         if not abs_path.endswith(rel_path):

Cython/Compiler/Optimize.py

@@ -3260,9 +3260,6 @@ class OptimizeBuiltinCalls(Visitor.NodeRefCleanupMixin,
             return node
 
         if node.type.is_pyobject:
-            if operator in ('Eq', 'Ne'):
-                ret_type = PyrexTypes.c_bint_type
-            else:
             ret_type = PyrexTypes.py_object_type
         elif node.type is PyrexTypes.c_bint_type and operator in ('Eq', 'Ne'):
             ret_type = PyrexTypes.c_bint_type

Cython/Compiler/Scanning.pxd

@@ -14,13 +14,15 @@ cdef class Method:
     cdef dict kwargs
     cdef readonly object __name__  # for tracing the scanner
 
+## methods commented with '##' out are used by Parsing.py when compiled.
+
 @cython.final
 cdef class CompileTimeScope:
     cdef public dict entries
     cdef public CompileTimeScope outer
-    cdef declare(self, name, value)
-    cdef lookup_here(self, name)
-    cpdef lookup(self, name)
+    ##cdef declare(self, name, value)
+    ##cdef lookup_here(self, name)
+    ##cpdef lookup(self, name)
 
 @cython.final
 cdef class PyrexScanner(Scanner):
@@ -51,15 +53,15 @@ cdef class PyrexScanner(Scanner):
     @cython.locals(current_level=cython.long, new_level=cython.long)
     cpdef indentation_action(self, text)
     #cpdef eof_action(self, text)
-    cdef next(self)
-    cdef peek(self)
+    ##cdef next(self)
+    ##cdef peek(self)
     #cpdef put_back(self, sy, systring)
     #cdef unread(self, token, value)
-    cdef bint expect(self, what, message = *) except -2
-    cdef expect_keyword(self, what, message = *)
-    cdef expected(self, what, message = *)
-    cdef expect_indent(self)
-    cdef expect_dedent(self)
-    cdef expect_newline(self, message=*, bint ignore_semicolon=*)
-    cdef int enter_async(self) except -1
-    cdef int exit_async(self) except -1
+    ##cdef bint expect(self, what, message = *) except -2
+    ##cdef expect_keyword(self, what, message = *)
+    ##cdef expected(self, what, message = *)
+    ##cdef expect_indent(self)
+    ##cdef expect_dedent(self)
+    ##cdef expect_newline(self, message=*, bint ignore_semicolon=*)
+    ##cdef int enter_async(self) except -1
+    ##cdef int exit_async(self) except -1

Cython/Includes/cpython/exc.pxd

@@ -153,6 +153,13 @@ cdef extern from "Python.h":
     # PyErr_SetFromErrno(type);" when the system call returns an
     # error.
 
+    PyObject* PyErr_SetFromErrnoWithFilenameObject(object type, object filenameObject) except NULL
+    # Similar to PyErr_SetFromErrno(), with the additional behavior
+    # that if filenameObject is not NULL, it is passed to the
+    # constructor of type as a third parameter.
+    # In the case of OSError exception, this is used to define
+    # the filename attribute of the exception instance.
+
     PyObject* PyErr_SetFromErrnoWithFilename(object type, char *filename) except NULL
     # Return value: Always NULL.  Similar to PyErr_SetFromErrno(),
     # with the additional behavior that if filename is not NULL, it is

Cython/Includes/libcpp/forward_list.pxd

+cdef extern from "<forward_list>" namespace "std" nogil:
+    cdef cppclass forward_list[T,ALLOCATOR=*]:
+        ctypedef T value_type
+        ctypedef ALLOCATOR allocator_type
+
+        # these should really be allocator_type.size_type and
+        # allocator_type.difference_type to be true to the C++ definition
+        # but cython doesn't support deferred access on template arguments
+        ctypedef size_t size_type
+        ctypedef ptrdiff_t difference_type
+
+        cppclass iterator:
+            iterator()
+            iterator(iterator &)
+            T& operator*()
+            iterator operator++()
+            bint operator==(iterator)
+            bint operator!=(iterator)
+        cppclass const_iterator(iterator):
+            pass
+        forward_list() except +
+        forward_list(forward_list&) except +
+        forward_list(size_t, T&) except +
+        #forward_list& operator=(forward_list&)
+        bint operator==(forward_list&, forward_list&)
+        bint operator!=(forward_list&, forward_list&)
+        bint operator<(forward_list&, forward_list&)
+        bint operator>(forward_list&, forward_list&)
+        bint operator<=(forward_list&, forward_list&)
+        bint operator>=(forward_list&, forward_list&)
+        void assign(size_t, T&)
+        T& front()
+        iterator before_begin()
+        const_iterator const_before_begin "before_begin"()
+        iterator begin()
+        const_iterator const_begin "begin"()
+        iterator end()
+        const_iterator const_end "end"()
+        bint empty()
+        size_t max_size()
+        void clear()
+        iterator insert_after(iterator, T&)
+        void insert_after(iterator, size_t, T&)
+        iterator erase_after(iterator)
+        iterator erase_after(iterator, iterator)
+        void push_front(T&)
+        void pop_front()
+        void resize(size_t)
+        void resize(size_t, T&)
+        void swap(forward_list&)
+        void merge(forward_list&)
+        void merge[Compare](forward_list&, Compare)
+        void splice_after(iterator, forward_list&)
+        void splice_after(iterator, forward_list&, iterator)
+        void splice_after(iterator, forward_list&, iterator, iterator)
+        void remove(const T&)
+        void remove_if[Predicate](Predicate)
+        void reverse()
+        void unique()
+        void unique[Predicate](Predicate)
+        void sort()
+        void sort[Compare](Compare)

Cython/Plex/Scanners.pxd

@@ -28,18 +28,23 @@ cdef class Scanner:
 
     cdef public level
 
+    @cython.final
     @cython.locals(input_state=long)
     cdef next_char(self)
     @cython.locals(action=Action)
     cpdef tuple read(self)
+    @cython.final
     cdef tuple scan_a_token(self)
-    cdef tuple position(self)
+    ##cdef tuple position(self)  # used frequently by Parsing.py
 
+    @cython.final
     @cython.locals(cur_pos=Py_ssize_t, cur_line=Py_ssize_t, cur_line_start=Py_ssize_t,
                    input_state=long, next_pos=Py_ssize_t, state=dict,
                    buf_start_pos=Py_ssize_t, buf_len=Py_ssize_t, buf_index=Py_ssize_t,
                    trace=bint, discard=Py_ssize_t, data=unicode, buffer=unicode)
     cdef run_machine_inlined(self)
 
+    @cython.final
     cdef begin(self, state)
+    @cython.final
     cdef produce(self, value, text = *)

Cython/Utility/ModuleSetupCode.c

@@ -796,15 +796,48 @@ static CYTHON_INLINE int __Pyx_inner_PyErr_GivenExceptionMatches2(PyObject *err,
 // so far, we only call PyErr_GivenExceptionMatches() with an exception type (not instance) as first argument
 // => optimise for that case
 
+static int __Pyx_PyErr_GivenExceptionMatchesTuple(PyObject *exc_type, PyObject *tuple) {
+    Py_ssize_t i, n;
+    assert(PyExceptionClass_Check(exc_type));
+    n = PyTuple_GET_SIZE(tuple);
+#if PY_MAJOR_VERSION >= 3
+    // the tighter subtype checking in Py3 allows faster out-of-order comparison
+    for (i=0; i<n; i++) {
+        if (exc_type == PyTuple_GET_ITEM(tuple, i)) return 1;
+    }
+#endif
+    for (i=0; i<n; i++) {
+        PyObject *t = PyTuple_GET_ITEM(tuple, i);
+        #if PY_MAJOR_VERSION < 3
+        if (likely(exc_type == t)) return 1;
+        #endif
+        if (likely(PyExceptionClass_Check(t))) {
+            if (__Pyx_inner_PyErr_GivenExceptionMatches2(exc_type, NULL, t)) return 1;
+        } else {
+            // FIXME: Py3: PyErr_SetString(PyExc_TypeError, "catching classes that do not inherit from BaseException is not allowed");
+        }
+    }
+    return 0;
+}
+
 static CYTHON_INLINE int __Pyx_PyErr_GivenExceptionMatches(PyObject *err, PyObject* exc_type) {
     if (likely(err == exc_type)) return 1;
     if (likely(PyExceptionClass_Check(err))) {
+        if (likely(PyExceptionClass_Check(exc_type))) {
             return __Pyx_inner_PyErr_GivenExceptionMatches2(err, NULL, exc_type);
+        } else if (likely(PyTuple_Check(exc_type))) {
+            return __Pyx_PyErr_GivenExceptionMatchesTuple(err, exc_type);
+        } else {
+            // FIXME: Py3: PyErr_SetString(PyExc_TypeError, "catching classes that do not inherit from BaseException is not allowed");
+        }
     }
     return PyErr_GivenExceptionMatches(err, exc_type);
 }
 
 static CYTHON_INLINE int __Pyx_PyErr_GivenExceptionMatches2(PyObject *err, PyObject *exc_type1, PyObject *exc_type2) {
+    // Only used internally with known exception types => pure safety check assertions.
+    assert(PyExceptionClass_Check(exc_type1));
+    assert(PyExceptionClass_Check(exc_type2));
     if (likely(err == exc_type1 || err == exc_type2)) return 1;
     if (likely(PyExceptionClass_Check(err))) {
         return __Pyx_inner_PyErr_GivenExceptionMatches2(err, exc_type1, exc_type2);

Cython/Utility/Optimize.c

@@ -713,7 +713,7 @@ static CYTHON_INLINE {{c_ret_type}} __Pyx_PyInt_{{'' if ret_type.is_pyobject els
 {{py: c_op = {'Eq': '==', 'Ne': '!='}[op] }}
 {{py:
 return_compare = (
-    (lambda a,b,c_op: "if ({a} {c_op} {b}) {return_true}; else {return_false};".format(
+    (lambda a,b,c_op, return_true=return_true, return_false=return_false: "if ({a} {c_op} {b}) {return_true}; else {return_false};".format(
         a=a, b=b, c_op=c_op, return_true=return_true, return_false=return_false))
     if ret_type.is_pyobject else
     (lambda a,b,c_op: "return ({a} {c_op} {b});".format(a=a, b=b, c_op=c_op))

Cython/Utils.py

@@ -487,3 +487,9 @@ def add_metaclass(metaclass):
         orig_vars.pop('__weakref__', None)
         return metaclass(cls.__name__, cls.__bases__, orig_vars)
     return wrapper
+
+
+def raise_error_if_module_name_forbidden(full_module_name):
+    #it is bad idea to call the pyx-file cython.pyx, so fail early
+    if full_module_name == 'cython'  or full_module_name.endswith('.cython'):
+        raise ValueError('cython is a special module, cannot be used as a module name')

docs/conf.py

@@ -127,7 +127,7 @@ pygments_style = 'sphinx'
 todo_include_todos = True
 
 # intersphinx for standard :keyword:s (def, for, etc.)
-intersphinx_mapping = {'python': ('http://docs.python.org/3/', None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False

docs/examples/tutorial/external/atoi.pyx

 from libc.stdlib cimport atoi
 
-cdef parse_charptr_to_py_int(char*s):
+cdef parse_charptr_to_py_int(char* s):
     assert s is not NULL, "byte string value is NULL"
     return atoi(s)  # note: atoi() has no error detection!

docs/examples/tutorial/external/keyword_args_call.pyx

@@ -4,4 +4,4 @@ cdef extern from "string.h":
 cdef char* data = "hfvcakdfagbcffvschvxcdfgccbcfhvgcsnfxjh"
 
 cdef char* pos = strstr(needle='akd', haystack=data)
-print(pos != NULL)
+print(pos is not NULL)

docs/examples/tutorial/profiling_tutorial/often_called.pyx

+cimport cython
+
+@cython.profile(False)
+def my_often_called_function():
+    pass

docs/examples/tutorial/pure/mymodule.pxd

+# mymodule.pxd
+
+# declare a C function as "cpdef" to export it to the module
+cdef extern from "math.h":
+    cpdef double sin(double x)

docs/examples/tutorial/pure/mymodule.py

+# mymodule.py
+
+import cython
+
+# override with Python import if not in compiled code
+if not cython.compiled:
+    from math import sin
+
+# calls sin() from math.h when compiled with Cython and math.sin() in Python
+print(sin(0))

docs/examples/userguide/extension_types/my_module.pxd

+cdef class Shrubbery:
+    cdef int width, height

docs/examples/userguide/extension_types/my_module.pyx

+from __future__ import print_function
+
+cdef class Shrubbery:
+
+    def __init__(self, w, h):
+        self.width = w
+        self.height = h
+
+    def describe(self):
+        print("This shrubbery is", self.width,
+              "by", self.height, "cubits.")

docs/examples/userguide/extension_types/shrubbery_2.pyx

+from my_module cimport Shrubbery
+
+cdef Shrubbery another_shrubbery(Shrubbery sh1):
+    cdef Shrubbery sh2
+    sh2 = Shrubbery()
+    sh2.width = sh1.width
+    sh2.height = sh1.height
+    return sh2

docs/examples/userguide/extension_types/widen_shrubbery.pyx

+from my_module cimport Shrubbery
+
+cdef widen_shrubbery(Shrubbery sh, extra_width):
+    sh.width = sh.width + extra_width

docs/examples/userguide/external_C_code/delorean.pyx

+# delorean.pyx
+
+cdef public struct Vehicle:
+    int speed
+    float power
+
+cdef api void activate(Vehicle *v):
+    if v.speed >= 88 and v.power >= 1.21:
+        print("Time travel achieved")
\ No newline at end of file

docs/examples/userguide/external_C_code/marty.c

+# marty.c
+#include "delorean_api.h"
+
+Vehicle car;
+
+int main(int argc, char *argv[]) {
+	Py_Initialize();
+	import_delorean();
+	car.speed = atoi(argv[1]);
+	car.power = atof(argv[2]);
+	activate(&car);
+	Py_Finalize();
+}

docs/examples/userguide/language_basics/casting_python.pyx

+from cpython.ref cimport PyObject
+from libc.stdint cimport uintptr_t
+
+python_string = "foo"
+
+cdef void* ptr = <void*>python_string
+cdef uintptr_t adress_in_c = <uintptr_t>ptr
+address_from_void = adress_in_c        # address_from_void is a python int
+
+cdef PyObject* ptr2 = <PyObject*>python_string
+cdef uintptr_t address_in_c2 = <uintptr_t>ptr2
+address_from_PyObject = address_in_c2  # address_from_PyObject is a python int
+
+assert address_from_void == address_from_PyObject == id(python_string)
+
+print(<object>ptr)                     # Prints "foo"
+print(<object>ptr2)                    # prints "foo"

docs/examples/userguide/language_basics/cdef_block.pyx

+from __future__ import print_function
+
+cdef:
+    struct Spam:
+        int tons
+
+    int i
+    float a
+    Spam *p
+
+    void f(Spam *s):
+        print(s.tons, "Tons of spam")

docs/examples/userguide/language_basics/compile_time.pyx

+from __future__ import print_function
+
+DEF FavouriteFood = u"spam"
+DEF ArraySize = 42
+DEF OtherArraySize = 2 * ArraySize + 17
+
+cdef int a1[ArraySize]
+cdef int a2[OtherArraySize]
+print("I like", FavouriteFood)
\ No newline at end of file

docs/examples/userguide/language_basics/kwargs_1.pyx

+def f(a, b, *args, c, d = 42, e, **kwds):
+    ...
+
+
+# We cannot call f with less verbosity than this.
+foo = f(4, "bar", c=68, e=1.0)

docs/examples/userguide/language_basics/kwargs_2.pyx

+def g(a, b, *, c, d):
+    ...
+
+# We cannot call g with less verbosity than this.
+foo = g(4.0, "something", c=68, d="other")

docs/examples/userguide/language_basics/open_file.pyx

+from libc.stdio cimport FILE, fopen
+from libc.stdlib cimport malloc, free
+from cpython.exc cimport PyErr_SetFromErrnoWithFilenameObject
+
+def open_file():
+    cdef FILE* p
+    p = fopen("spam.txt", "r")
+    if p is NULL:
+        PyErr_SetFromErrnoWithFilenameObject(OSError, "spam.txt")
+    ...
+
+
+def allocating_memory(number=10):
+    cdef double *my_array = <double *> malloc(number * sizeof(double))
+    if not my_array:  # same as 'is NULL' above
+        raise MemoryError()
+    ...
+    free(my_array)

docs/examples/userguide/language_basics/optional_subclassing.pxd

+cdef class A:
+    cdef foo(self)
+
+cdef class B(A):
+    cdef foo(self, x=*)
+
+cdef class C(B):
+    cpdef foo(self, x=*, int k=*)

docs/examples/userguide/language_basics/optional_subclassing.pyx

+from __future__ import print_function
+
+cdef class A:
+    cdef foo(self):
+        print("A")
+
+cdef class B(A):
+    cdef foo(self, x=None):
+        print("B", x)
+
+cdef class C(B):
+    cpdef foo(self, x=True, int k=3):
+        print("C", x, k)

docs/examples/userguide/language_basics/override.pyx

+from __future__ import print_function
+
+cdef class A:
+    cdef foo(self):
+        print("A")
+
+cdef class B(A):
+    cpdef foo(self):
+        print("B")
+
+class C(B):  # NOTE: not cdef class
+    def foo(self):
+        print("C")

docs/examples/userguide/memoryviews/add_one.pyx

+import numpy as np
+
+def add_one(int[:,:] buf):
+    for x in range(buf.shape[0]):
+        for y in range(buf.shape[1]):
+            buf[x, y] += 1
+
+# exporting_object must be a Python object
+# implementing the buffer interface, e.g. a numpy array.
+exporting_object = np.zeros((10, 20), dtype=np.intc)
+
+add_one(exporting_object)

docs/examples/userguide/memoryviews/copy.pyx

+import numpy as np
+
+cdef int[:, :, :] to_view, from_view
+to_view = np.empty((20, 15, 30), dtype=np.intc)
+from_view = np.ones((20, 15, 30), dtype=np.intc)
+
+# copy the elements in from_view to to_view
+to_view[...] = from_view
+# or
+to_view[:] = from_view
+# or
+to_view[:, :, :] = from_view

docs/examples/userguide/memoryviews/memory_layout.pyx

+from cython cimport view
+
+# direct access in both dimensions, strided in the first dimension, contiguous in the last
+cdef int[:, ::view.contiguous] a
+
+# contiguous list of pointers to contiguous lists of ints
+cdef int[::view.indirect_contiguous, ::1] b
+
+# direct or indirect in the first dimension, direct in the second dimension
+# strided in both dimensions
+cdef int[::view.generic, :] c

docs/examples/userguide/memoryviews/memory_layout_2.pyx

+from cython cimport view
+
+# VALID
+cdef int[::view.indirect, ::1, :] a
+cdef int[::view.indirect, :, ::1] b
+cdef int[::view.indirect_contiguous, ::1, :] c

docs/examples/userguide/memoryviews/not_none.pyx

+import numpy as np
+
+def process_buffer(int[:,:] input_view not None,
+                   int[:,:] output_view=None):
+
+   if output_view is None:
+       # Creating a default view, e.g.
+       output_view = np.empty_like(input_view)
+
+   # process 'input_view' into 'output_view'
+   return output_view

docs/examples/userguide/memoryviews/np_flag_const.pyx

+import numpy as np
+
+cdef const double[:] myslice   # const item type => read-only view
+
+a = np.linspace(0, 10, num=50)
+a.setflags(write=False)
+myslice = a

docs/examples/userguide/memoryviews/slicing.pyx

+import numpy as np
+
+exporting_object = np.arange(0, 15 * 10 * 20, dtype=np.intc).reshape((15, 10, 20))
+
+cdef int[:, :, :] my_view = exporting_object
+
+# These are all equivalent
+my_view[10]
+my_view[10, :, :]
+my_view[10, ...]

docs/examples/userguide/memoryviews/transpose.pyx

+import numpy as np
+
+array = np.arange(20, dtype=np.intc).reshape((2, 10))
+
+cdef int[:, ::1] c_contig = array
+cdef int[::1, :] f_contig = c_contig.T

docs/examples/userguide/memoryviews/view_string.pyx

+cdef bint is_y_in(const unsigned char[:] string_view):
+    cdef int i
+    for i in range(string_view.shape[0]):
+        if string_view[i] == b'y':
+            return True
+    return False
+
+print(is_y_in(b'hello world'))   # False
+print(is_y_in(b'hello Cython'))  # True

docs/examples/userguide/sharing_declarations/c_lunch.pxd

+cdef extern from "lunch.h":
+    void eject_tomato(float)

docs/examples/userguide/sharing_declarations/dishes.pxd

+cdef enum otherstuff:
+    sausage, eggs, lettuce
+
+cdef struct spamdish:
+    int oz_of_spam
+    otherstuff filler

docs/examples/userguide/sharing_declarations/landscaping.pyx

+cimport shrubbing
+import shrubbing
+
+def main():
+    cdef shrubbing.Shrubbery sh
+    sh = shrubbing.standard_shrubbery()
+    print("Shrubbery size is", sh.width, 'x', sh.length)

docs/examples/userguide/sharing_declarations/lunch.h

+void eject_tomato(float speed);

docs/examples/userguide/sharing_declarations/lunch.pyx

+cimport c_lunch
+
+def eject_tomato(float speed):
+    c_lunch.eject_tomato(speed)

docs/examples/userguide/sharing_declarations/restaurant.pyx

+from __future__ import print_function
+cimport dishes
+from dishes cimport spamdish
+
+cdef void prepare(spamdish *d):
+    d.oz_of_spam = 42
+    d.filler = dishes.sausage
+
+def serve():
+    cdef spamdish d
+    prepare(&d)
+    print(f'{d.oz_of_spam} oz spam, filler no. {d.filler}')

docs/examples/userguide/sharing_declarations/setup.py

+from distutils.core import setup
+from Cython.Build import cythonize
+
+setup(ext_modules=cythonize(["landscaping.pyx", "shrubbing.pyx"]))

docs/examples/userguide/sharing_declarations/shrubbing.pxd

+cdef class Shrubbery:
+    cdef int width
+    cdef int length

docs/examples/userguide/sharing_declarations/shrubbing.pyx

+cdef class Shrubbery:
+    def __cinit__(self, int w, int l):
+        self.width = w
+        self.length = l
+
+def standard_shrubbery():
+    return Shrubbery(3, 7)

docs/examples/userguide/sharing_declarations/spammery.pyx

+from __future__ import print_function
+
+from volume cimport cube
+
+def menu(description, size):
+    print(description, ":", cube(size),
+          "cubic metres of spam")
+
+menu("Entree", 1)
+menu("Main course", 3)
+menu("Dessert", 2)

docs/examples/userguide/sharing_declarations/volume.pxd

+cdef float cube(float)

docs/examples/userguide/sharing_declarations/volume.pyx

+cdef float cube(float x):
+    return x * x * x

docs/examples/userguide/wrapping_CPlusPlus/Rectangle.pxd

@@ -8,5 +8,5 @@ cdef extern from "Rectangle.h" namespace "shapes":
         Rectangle(int, int, int, int) except +
         int x0, y0, x1, y1
         int getArea()
-        void getSize(int*width, int*height)
+        void getSize(int* width, int* height)
         void move(int, int)

docs/examples/userguide/wrapping_CPlusPlus/function_templates.pyx

+# distutils: language = c++
+
+cdef extern from "<algorithm>" namespace "std":
+    T max[T](T a, T b)
+
+print(max[long](3, 4))
+print(max(1.5, 2.5))  # simple template argument deduction

docs/examples/userguide/wrapping_CPlusPlus/iterate.pyx

+# distutils: language = c++
+
+from libcpp.vector cimport vector
+
+def main():
+    cdef vector[int] v = [4, 6, 5, 10, 3]
+
+    cdef int value
+    for value in v:
+        print(value)
+
+    return [x*x for x in v if x % 2 == 0]

docs/examples/userguide/wrapping_CPlusPlus/nested_class.pyx

+# distutils: language = c++
+
+cdef extern from "<vector>" namespace "std":
+    cdef cppclass vector[T]:
+        cppclass iterator:
+            T operator*()
+            iterator operator++()
+            bint operator==(iterator)
+            bint operator!=(iterator)
+        vector()
+        void push_back(T&)
+        T& operator[](int)
+        T& at(int)
+        iterator begin()
+        iterator end()
+
+cdef vector[int].iterator iter  #iter is declared as being of type vector<int>::iterator

docs/examples/userguide/wrapping_CPlusPlus/python_to_cpp.pyx

+# distutils: language = c++
+
+from libcpp.string cimport string
+from libcpp.vector cimport vector
+
+py_bytes_object = b'The knights who say ni'
+py_unicode_object = u'Those who hear them seldom live to tell the tale.'
+
+cdef string s = py_bytes_object
+print(s)  # b'The knights who say ni'
+
+cdef string cpp_string = <string> py_unicode_object.encode('utf-8')
+print(cpp_string)  # b'Those who hear them seldom live to tell the tale.'
+
+cdef vector[int] vect = range(1, 10, 2)
+print(vect)  # [1, 3, 5, 7, 9]
+
+cdef vector[string] cpp_strings = b'It is a good shrubbery'.split()
+print(cpp_strings[1])   # b'is'

docs/examples/userguide/wrapping_CPlusPlus/templates.pyx

+# distutils: language = c++
+
+# import dereference and increment operators
+from cython.operator cimport dereference as deref, preincrement as inc
+
+cdef extern from "<vector>" namespace "std":
+    cdef cppclass vector[T]:
+        cppclass iterator:
+            T operator*()
+            iterator operator++()
+            bint operator==(iterator)
+            bint operator!=(iterator)
+        vector()
+        void push_back(T&)
+        T& operator[](int)
+        T& at(int)
+        iterator begin()
+        iterator end()
+
+cdef vector[int] *v = new vector[int]()
+cdef int i
+for i in range(10):
+    v.push_back(i)
+
+cdef vector[int].iterator it = v.begin()
+while it != v.end():
+    print(deref(it))
+    inc(it)
+
+del v

docs/examples/userguide/wrapping_CPlusPlus/vector_demo.pyx

+# distutils: language = c++
+
+from libcpp.vector cimport vector
+
+cdef vector[int] vect
+cdef int i, x
+
+for i in range(10):
+    vect.push_back(i)
+
+for i in range(10):
+    print(vect[i])
+
+for x in vect:
+    print(x)

docs/examples/userguide/wrapping_CPlusPlus/wrapper_vector.pyx

+# distutils: language = c++
+
+from libcpp.vector cimport vector
+
+
+cdef class VectorStack:
+    cdef vector[int] v
+
+    def push(self, x):
+        self.v.push_back(x)
+
+    def pop(self):
+        if self.v.empty():
+            raise IndexError()
+        x = self.v.back()
+        self.v.pop_back()
+        return x

docs/src/reference/Makefile

-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html web htmlhelp latex changes linkcheck
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  web       to make files usable by Sphinx.web"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview over all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-
-clean:
-	-rm -rf build/*
-
-html:
-	mkdir -p build/html build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
-	@echo
-	@echo "Build finished. The HTML pages are in build/html."
-
-web:
-	mkdir -p build/web build/doctrees
-	$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) build/web
-	@echo
-	@echo "Build finished; now you can run"
-	@echo "  python -m sphinx.web build/web"
-	@echo "to start the server."
-
-htmlhelp:
-	mkdir -p build/htmlhelp build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in build/htmlhelp."
-
-latex:
-	mkdir -p build/latex build/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	mkdir -p build/changes build/doctrees
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
-	@echo
-	@echo "The overview file is in build/changes."
-
-linkcheck:
-	mkdir -p build/linkcheck build/doctrees
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in build/linkcheck/output.txt."

docs/src/reference/compilation.rst

@@ -51,7 +51,8 @@ system, for example, it might look similar to this::
 (``gcc`` will need to have paths to your included header files and paths
 to libraries you want to link with.)
 
-After compilation, a ``yourmod.so`` file is written into the target directory
+After compilation, a ``yourmod.so`` (:file:`yourmod.pyd` for Windows)
+file is written into the target directory
 and your module, ``yourmod``, is available for you to import as with any other
 Python module.  Note that if you are not relying on ``cythonize`` or distutils,
 you will not automatically benefit from the platform specific file extension
@@ -104,7 +105,13 @@ the necessary include files, e.g. for NumPy::
 
     include_path = [numpy.get_include()]
 
-Note for Numpy users.  Despite this, you will still get warnings like the
+.. note::
+
+    Using memoryviews or importing NumPy with ``import numpy`` does not mean that
+    you have to add the path to NumPy include files. You need to add this path only
+    if you use ``cimport numpy``.
+
+Despite this, you will still get warnings like the
 following from the compiler, because Cython is using a deprecated Numpy API::
 
    .../include/numpy/npy_1_7_deprecated_api.h:15:2: warning: #warning "Using deprecated NumPy API, disable it by " "#defining NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" [-Wcpp]
@@ -462,6 +469,7 @@ C-compiling the module C files.
 Also take a look at the `cython_freeze
 <https://github.com/cython/cython/blob/master/bin/cython_freeze>`_ tool.
 
+.. _pyximport:
 
 Compiling with :mod:`pyximport`
 ===============================

docs/src/tutorial/clibraries.rst

@@ -158,7 +158,7 @@ We can thus change the init function as follows:
    exception instance in order to raise it may actually fail because
    we are running out of memory.  Luckily, CPython provides a C-API
    function ``PyErr_NoMemory()`` that safely raises the right
-   exception for us.  Since version 0.14.1, Cython automatically
+   exception for us.  Cython automatically
    substitutes this C-API call whenever you write ``raise
    MemoryError`` or ``raise MemoryError()``.  If you use an older
    version, you have to cimport the C-API function from the standard

docs/src/tutorial/cython_tutorial.rst

@@ -77,7 +77,7 @@ It is shipped and installed with Cython and can be used like this::
     >>> import helloworld
     Hello World
 
-Since Cython 0.11, the :ref:`Pyximport<pyximport>` module also has experimental
+The :ref:`Pyximport<pyximport>` module also has experimental
 compilation support for normal Python modules.  This allows you to
 automatically run Cython on every .pyx and .py module that Python
 imports, including the standard library and installed packages.

docs/src/tutorial/external.rst

@@ -92,7 +92,7 @@ names like this::
       char* strstr(const char*, const char*)
 
 However, this prevents Cython code from calling it with keyword
-arguments (supported since Cython 0.19).  It is therefore preferable
+arguments.  It is therefore preferable
 to write the declaration like this instead:
 
 .. literalinclude:: ../../examples/tutorial/external/keyword_args.pyx

docs/src/tutorial/numpy.rst

@@ -23,7 +23,8 @@ the Cython version -- Cython uses ".pyx" as its file suffix.
 
 .. literalinclude:: ../../examples/tutorial/numpy/convolve_py.py
 
-This should be compiled to produce :file:`yourmod.so` (for Linux systems). We
+This should be compiled to produce :file:`yourmod.so` (for Linux systems, on Windows
+systems, it will be :file:`yourmod.pyd`). We
 run a Python session to test both the Python version (imported from
 ``.py``-file) and the compiled Cython module.
 

docs/src/tutorial/profiling_tutorial.rst

@@ -44,14 +44,9 @@ If your profiling is messed up because of the call overhead to some small
 functions that you rather do not want to see in your profile - either because
 you plan to inline them anyway or because you are sure that you can't make them
 any faster - you can use a special decorator to disable profiling for one
-function only::
-
-   cimport cython
-
-   @cython.profile(False)
-   def my_often_called_function():
-      pass
+function only (regardless of whether it is globally enabled or not):
 
+.. literalinclude:: ../../examples/tutorial/profiling_tutorial/often_called.pyx
 
 Enabling line tracing
 ---------------------

docs/src/tutorial/pure.rst

@@ -299,25 +299,11 @@ Calling C functions
 Normally, it isn't possible to call C functions in pure Python mode as there
 is no general way to support it in normal (uncompiled) Python.  However, in
 cases where an equivalent Python function exists, this can be achieved by
-combining C function coercion with a conditional import as follows::
+combining C function coercion with a conditional import as follows:
 
-    # in mymodule.pxd:
+.. literalinclude:: ../../examples/tutorial/pure/mymodule.pxd
 
-    # declare a C function as "cpdef" to export it to the module
-    cdef extern from "math.h":
-        cpdef double sin(double x)
-
-
-    # in mymodule.py:
-
-    import cython
-
-    # override with Python import if not in compiled code
-    if not cython.compiled:
-        from math import sin
-
-    # calls sin() from math.h when compiled with Cython and math.sin() in Python
-    print(sin(0))
+.. literalinclude:: ../../examples/tutorial/pure/mymodule.py
 
 Note that the "sin" function will show up in the module namespace of "mymodule"
 here (i.e. there will be a ``mymodule.sin()`` function).  You can mark it as an
@@ -334,7 +320,7 @@ to make the names match again.
 Using C arrays for fixed size lists
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Since Cython 0.22, C arrays can automatically coerce to Python lists or tuples.
+C arrays can automatically coerce to Python lists or tuples.
 This can be exploited to replace fixed size Python lists in Python code by C
 arrays when compiled.  An example:
 

docs/src/tutorial/strings.rst

@@ -164,7 +164,7 @@ the assignment in a try-finally construct:
 To convert the byte string back into a C :c:type:`char*`, use the
 opposite assignment::
 
-    cdef char* other_c_string = py_string
+    cdef char* other_c_string = py_string  # other_c_string is a 0-terminated string.
 
 This is a very fast operation after which ``other_c_string`` points to
 the byte string buffer of the Python string itself.  It is tied to the
@@ -260,7 +260,7 @@ not modify a string they return, for example:
 
 .. literalinclude:: ../../examples/tutorial/string/someheader.h
 
-Since version 0.18, Cython has support for the ``const`` modifier in
+Cython has support for the ``const`` modifier in
 the language, so you can declare the above functions straight away as
 follows:
 
@@ -296,7 +296,7 @@ bytes most of which tend to be 0.
 
 Again, no bounds checking is done if slice indices are provided, so
 incorrect indices lead to data corruption and crashes.  However, using
-negative indices is possible since Cython 0.17 and will inject a call
+negative indices is possible and will inject a call
 to :c:func:`strlen()` in order to determine the string length.
 Obviously, this only works for 0-terminated strings without internal
 null bytes.  Text encoded in UTF-8 or one of the ISO-8859 encodings is
@@ -467,7 +467,7 @@ supports the ``__future__`` import ``unicode_literals`` that instructs
 the parser to read all unprefixed :obj:`str` literals in a source file as
 unicode string literals, just like Python 3.
 
-.. _`CEP 108`: http://wiki.cython.org/enhancements/stringliterals
+.. _`CEP 108`: https://github.com/cython/cython/wiki/enhancements-stringliterals
 
 Single bytes and characters
 ---------------------------
@@ -475,7 +475,7 @@ Single bytes and characters
 The Python C-API uses the normal C :c:type:`char` type to represent
 a byte value, but it has two special integer types for a Unicode code
 point value, i.e. a single Unicode character: :c:type:`Py_UNICODE`
-and :c:type:`Py_UCS4`.  Since version 0.13, Cython supports the
+and :c:type:`Py_UCS4`.  Cython supports the
 first natively, support for :c:type:`Py_UCS4` is new in Cython 0.15.
 :c:type:`Py_UNICODE` is either defined as an unsigned 2-byte or
 4-byte integer, or as :c:type:`wchar_t`, depending on the platform.

docs/src/userguide/extension_types.rst

@@ -105,21 +105,23 @@ will be very inefficient. If the attribute is private, it will not work at all
 -- the code will compile, but an attribute error will be raised at run time.
 
 The solution is to declare ``sh`` as being of type :class:`Shrubbery`, as
-follows::
+follows:
 
-    cdef widen_shrubbery(Shrubbery sh, extra_width):
-        sh.width = sh.width + extra_width
+.. literalinclude:: ../../examples/userguide/extension_types/widen_shrubbery.pyx
 
 Now the Cython compiler knows that ``sh`` has a C attribute called
 :attr:`width` and will generate code to access it directly and efficiently.
-The same consideration applies to local variables, for example,::
+The same consideration applies to local variables, for example:
+
+.. literalinclude:: ../../examples/userguide/extension_types/shrubbery_2.pyx
+
+.. note::
 
-    cdef Shrubbery another_shrubbery(Shrubbery sh1):
-        cdef Shrubbery sh2
-        sh2 = Shrubbery()
-        sh2.width = sh1.width
-        sh2.height = sh1.height
-        return sh2
+    We here ``cimport`` the class :class:`Shrubbery`, and this is necessary
+    to declare the type at compile time. To be able to ``cimport`` an extension type,
+    we split the class definition into two parts, one in a definition file and
+    the other in the corresponding implementation file. You should read
+    :ref:`sharing_extension_types` to learn to do that.
 
 
 Type Testing and Casting
@@ -347,7 +349,7 @@ inherit from multiple extension types provided that the usual Python rules for
 multiple inheritance are followed (i.e. the C layouts of all the base classes
 must be compatible).
 
-Since Cython 0.13.1, there is a way to prevent extension types from
+There is a way to prevent extension types from
 being subtyped in Python.  This is done via the ``final`` directive,
 usually set on an extension type using a decorator::
 
@@ -419,7 +421,7 @@ compatible types.::
         cdef void* ptr
 
         def __dealloc__(self):
-            if self.ptr != NULL:
+            if self.ptr is not NULL:
                 free(self.ptr)
 
         @staticmethod

docs/src/userguide/external_C_code.rst

@@ -458,32 +458,12 @@ contains the api call which is generating the segmentation fault does not call
 the :func:`import_modulename` function before the api call which crashes.
 
 Any public C type or extension type declarations in the Cython module are also
-made available when you include :file:`modulename_api.h`.::
+made available when you include :file:`modulename_api.h`.:
 
-    # delorean.pyx
-    cdef public struct Vehicle:
-        int speed
-        float power
+.. literalinclude:: ../../examples/userguide/external_C_code/delorean.pyx
 
-    cdef api void activate(Vehicle *v):
-        if v.speed >= 88 and v.power >= 1.21:
-            print("Time travel achieved")
-
-.. sourcecode:: c
-
-    # marty.c
-    #include "delorean_api.h"
-
-    Vehicle car;
-
-    int main(int argc, char *argv[]) {
-        Py_Initialize();
-        import_delorean();
-        car.speed = atoi(argv[1]);
-        car.power = atof(argv[2]);
-        activate(&car);
-        Py_Finalize();
-    }
+.. literalinclude:: ../../examples/userguide/external_C_code/marty.c
+    :language: C
 
 .. note::
 
@@ -587,7 +567,7 @@ header::
 
 If the callback may be called from another non-Python thread,
 care must be taken to initialize the GIL first, through a call to
-`PyEval_InitThreads() <http://docs.python.org/dev/c-api/init.html#PyEval_InitThreads>`_.
+`PyEval_InitThreads() <https://docs.python.org/dev/c-api/init.html#c.PyEval_InitThreads>`_.
 If you're already using  :ref:`cython.parallel <parallel>` in your module, this will already have been taken care of.
 
 The GIL may also be acquired through the ``with gil`` statement::

docs/src/userguide/language_basics.rst

@@ -107,21 +107,9 @@ You can declare classes with :keyword:`cdef`, making them :ref:`extension-types`
 have a behavior very close to python classes, but are faster because they use a ``struct``
 internally to store attributes.
 
-Here is a simple example::
+Here is a simple example:
 
-    from __future__ import print_function
-
-    cdef class Shrubbery:
-
-        cdef int width, height
-
-        def __init__(self, w, h):
-            self.width = w
-            self.height = h
-
-        def describe(self):
-            print("This shrubbery is", self.width,
-                  "by", self.height, "cubits.")
+.. literalinclude:: ../../examples/userguide/extension_types/shrubbery.pyx
 
 You can read more about them in :ref:`extension-types`.
 
@@ -179,20 +167,9 @@ Grouping multiple C declarations
 --------------------------------
 
 If you have a series of declarations that all begin with :keyword:`cdef`, you
-can group them into a :keyword:`cdef` block like this::
-
-    from __future__ import print_function
+can group them into a :keyword:`cdef` block like this:
 
-    cdef:
-        struct Spam:
-            int tons
-
-        int i
-        float a
-        Spam *p
-
-        void f(Spam *s):
-            print(s.tons, "Tons of spam")
+.. literalinclude:: ../../examples/userguide/language_basics/cdef_block.pyx
 
 .. _cpdef:
 .. _cdef:
@@ -311,35 +288,15 @@ To avoid repetition (and potential future inconsistencies), default argument val
 not visible in the declaration (in ``.pxd`` files) but only in
 the implementation (in ``.pyx`` files).
 
-When in a ``.pyx`` file, the signature is the same as it is in Python itself::
-
-    from __future__ import print_function
-
-    cdef class A:
-        cdef foo(self):
-            print("A")
-
-    cdef class B(A):
-        cdef foo(self, x=None):
-            print("B", x)
-            
-    cdef class C(B):
-        cpdef foo(self, x=True, int k=3):
-            print("C", x, k)
+When in a ``.pyx`` file, the signature is the same as it is in Python itself:
 
+.. literalinclude:: ../../examples/userguide/language_basics/optional_subclassing.pyx
 
 When in a ``.pxd`` file, the signature is different like this example: ``cdef foo(x=*)``.
 This is because the program calling the function just needs to know what signatures are
-possible in C, but doesn't need to know the value of the default arguments.::
-
-    cdef class A:
-        cdef foo(self)
-    cdef class B(A):
-        cdef foo(self, x=*)
-    cdef class C(B):
-        cpdef foo(self, x=*, int k=*)
-
+possible in C, but doesn't need to know the value of the default arguments.:
 
+.. literalinclude:: ../../examples/userguide/language_basics/optional_subclassing.pxd
 
 .. note::
     The number of arguments may increase when subclassing,
@@ -355,13 +312,9 @@ Keyword-only Arguments
 ----------------------
 
 As in Python 3, ``def`` functions can have keyword-only arguments
-listed after a ``"*"`` parameter and before a ``"**"`` parameter if any::
+listed after a ``"*"`` parameter and before a ``"**"`` parameter if any:
 
-    def f(a, b, *args, c, d = 42, e, **kwds):
-        ...
-
-    # We cannot call f with less verbosity than this.
-    foo = f(4, "bar", c=68, e=1.0)
+.. literalinclude:: ../../examples/userguide/language_basics/kwargs_1.pyx
 
 As shown above, the ``c``, ``d`` and ``e`` arguments can not be
 passed as positional arguments and must be passed as keyword arguments.
@@ -369,16 +322,12 @@ Furthermore, ``c`` and ``e`` are **required** keyword arguments
 since they do not have a default value.
 
 A single ``"*"`` without argument name can be used to
-terminate the list of positional arguments::
-
-    def g(a, b, *, c, d):
-        ...
+terminate the list of positional arguments:
 
-    # We cannot call g with less verbosity than this.
-    foo = g(4.0, "something", c=68, d="other")
+.. literalinclude:: ../../examples/userguide/language_basics/kwargs_2.pyx
 
 Shown above, the signature takes exactly two positional
-parameters and has two required keyword parameters
+parameters and has two required keyword parameters.
 
 Function Pointers
 -----------------
@@ -479,12 +428,9 @@ returns ``NULL``. The except clause doesn't work that way; its only purpose is
 for propagating Python exceptions that have already been raised, either by a Cython
 function or a C function that calls Python/C API routines. To get an exception
 from a non-Python-aware function such as :func:`fopen`, you will have to check the
-return value and raise it yourself, for example,::
+return value and raise it yourself, for example:
 
-    cdef FILE* p
-    p = fopen("spam.txt", "r")
-    if p == NULL:
-        raise SpamError("Couldn't open the spam file")
+.. literalinclude:: ../../examples/userguide/language_basics/open_file.pyx
 
 .. _overriding_in_extension_types:
 
@@ -492,39 +438,15 @@ Overriding in extension types
 -----------------------------
 
 
-``cpdef`` methods can override ``cdef`` methods::
+``cpdef`` methods can override ``cdef`` methods:
 
-    from __future__ import print_function
-
-    cdef class A:
-        cdef foo(self):
-            print("A")
-
-    cdef class B(A):
-        cdef foo(self, x=None):
-            print("B", x)
-
-    cdef class C(B):
-        cpdef foo(self, x=True, int k=3):
-            print("C", x, k)
+.. literalinclude:: ../../examples/userguide/language_basics/optional_subclassing.pyx
 
 When subclassing an extension type with a Python class,
 ``def`` methods can override ``cpdef`` methods but not ``cdef``
-methods::
-
-    from __future__ import print_function
-
-    cdef class A:
-        cdef foo(self):
-            print("A")
+methods:
 
-    cdef class B(A):
-        cpdef foo(self):
-            print("B")
-
-    class C(B):         # NOTE: not cdef class
-        def foo(self):
-            print("C")
+.. literalinclude:: ../../examples/userguide/language_basics/override.pyx
 
 If ``C`` above would be an extension type (``cdef class``),
 this would not work correctly.
@@ -556,6 +478,8 @@ possibilities.
 +----------------------------+--------------------+------------------+
 | char*                      | str/bytes          | str/bytes [#]_   |
 +----------------------------+--------------------+------------------+
+| C array                    | iterable           | list [#2]_       |
++----------------------------+--------------------+------------------+
 | struct,                    |                    | dict [#1]_       |
 | union                      |                    |                  |
 +----------------------------+--------------------+------------------+
@@ -568,6 +492,10 @@ possibilities.
    combinations.  An example is a union of an ``int`` and a ``char*``,
    in which case the pointer value may or may not be a valid pointer.
 
+.. [#2] Other than signed/unsigned char[].
+   The conversion will fail if the length of C array is not known at compile time,
+   and when using a slice of a C array.
+
 
 Caveats when using a Python string in a C context
 -------------------------------------------------
@@ -632,26 +560,9 @@ You can also cast a C pointer back to a Python object reference
 with ``<object>``, or a more specific builtin or extension type
 (e.g. ``<MyExtType>ptr``). This will increase the reference count of
 the object by one, i.e. the cast returns an owned reference.
-Here is an example::
-
-    from cpython.ref cimport PyObject
-    from libc.stdint cimport uintptr_t
-
-    python_string = "foo"
-
-    cdef void* ptr = <void*>python_string
-    cdef uintptr_t adress_in_c = <uintptr_t>ptr
-    address_from_void = adress_in_c        # address_from_void is a python int
-
-    cdef PyObject* ptr2 = <PyObject*>python_string
-    cdef uintptr_t address_in_c2 = <uintptr_t>ptr2
-    address_from_PyObject = address_in_c2  # address_from_PyObject is a python int
-
-    assert address_from_void == address_from_PyObject == id(python_string)
-
-    print(<object>ptr)                     # Prints "foo"
-    print(<object>ptr2)                    # prints "foo"
+Here is an example:
 
+.. literalinclude:: ../../examples/userguide/language_basics/casting_python.pyx
 
 The precedence of ``<...>`` is such that ``<type>a.b.c`` is interpreted as ``<type>(a.b.c)``.
 
@@ -971,13 +882,7 @@ the source at that point as a literal. For this to work, the compile-time
 expression must evaluate to a Python value of type ``int``, ``long``,
 ``float``, ``bytes`` or ``unicode`` (``str`` in Py3).
 
-::
-
-    from __future__ import print_function
-
-    cdef int a1[ArraySize]
-    cdef int a2[OtherArraySize]
-    print("I like", FavouriteFood)
+.. literalinclude:: ../../examples/userguide/language_basics/compile_time.pyx
 
 Conditional Statements
 ----------------------

docs/src/userguide/memoryviews.rst

@@ -71,14 +71,9 @@ This also works conveniently as function arguments:
 The ``not None`` declaration for the argument automatically rejects
 None values as input, which would otherwise be allowed.  The reason why
 None is allowed by default is that it is conveniently used for return
-arguments::
+arguments:
 
-   def process_buffer(int[:,:] input not None,
-                      int[:,:] output = None):
-       if output is None:
-           output = ...  # e.g. numpy.empty_like(input)
-       # process 'input' into 'output'
-       return output
+.. literalinclude:: ../../examples/userguide/memoryviews/not_none.pyx
 
 Cython will reject incompatible buffers automatically, e.g. passing a
 three dimensional buffer into a function that requires a two
@@ -102,40 +97,24 @@ dimension::
    print(buf[-1,-2])
 
 The following function loops over each dimension of a 2D array and
-adds 1 to each item::
+adds 1 to each item:
 
-   def add_one(int[:,:] buf):
-       for x in xrange(buf.shape[0]):
-           for y in xrange(buf.shape[1]):
-               buf[x,y] += 1
+.. literalinclude:: ../../examples/userguide/memoryviews/add_one.pyx
 
 Indexing and slicing can be done with or without the GIL.  It basically works
 like NumPy.  If indices are specified for every dimension you will get an element
 of the base type (e.g. `int`).  Otherwise, you will get a new view.  An Ellipsis
-means you get consecutive slices for every unspecified dimension::
+means you get consecutive slices for every unspecified dimension:
 
-    cdef int[:, :, :] my_view = exporting_object
-
-    # These are all equivalent
-    my_view[10]
-    my_view[10, :, :]
-    my_view[10, ...]
+.. literalinclude:: ../../examples/userguide/memoryviews/slicing.pyx
 
 
 Copying
 -------
 
-Memory views can be copied in place::
-
-    cdef int[:, :, :] to_view, from_view
-    ...
+Memory views can be copied in place:
 
-    # copy the elements in from_view to to_view
-    to_view[...] = from_view
-    # or
-    to_view[:] = from_view
-    # or
-    to_view[:, :, :] = from_view
+.. literalinclude:: ../../examples/userguide/memoryviews/copy.pyx
 
 They can also be copied with the ``copy()`` and ``copy_fortran()`` methods; see
 :ref:`view_copy_c_fortran`.
@@ -146,10 +125,9 @@ Transposing
 -----------
 
 In most cases (see below), the memoryview can be transposed in the same way that
-NumPy slices can be transposed::
+NumPy slices can be transposed:
 
-    cdef int[:, ::1] c_contig = ...
-    cdef int[::1, :] f_contig = c_contig.T
+.. literalinclude:: ../../examples/userguide/memoryviews/transpose.pyx
 
 This gives a new, transposed, view on the data.
 
@@ -171,6 +149,9 @@ As for NumPy, new axes can be introduced by indexing an array with ``None`` ::
     # 2D array with shape (50, 1)
     myslice[:, None]
 
+    # 3D array with shape (1, 10, 1)
+    myslice[None, 10:-20:2, None]
+
 One may mix new axis indexing with all other forms of indexing and slicing.
 See also an example_.
 
@@ -178,13 +159,14 @@ Read-only views
 ---------------
 
 Since Cython 0.28, the memoryview item type can be declared as ``const`` to
-support read-only buffers as input::
+support read-only buffers as input:
 
-    cdef const double[:] myslice   # const item type => read-only view
+.. literalinclude:: ../../examples/userguide/memoryviews/np_flag_const.pyx
 
-    a = np.linspace(0, 10, num=50)
-    a.setflags(write=False)
-    myslice = a
+Using a non-const memoryview with a binary Python string produces a runtime error.
+You can solve this issue with a ``const`` memoryview:
+
+.. literalinclude:: ../../examples/userguide/memoryviews/view_string.pyx
 
 Note that this does not *require* the input buffer to be read-only::
 
@@ -436,31 +418,21 @@ The flags are as follows:
 * contiguous - contiguous and direct
 * indirect_contiguous - the list of pointers is contiguous
 
-and they can be used like this::
-
-    from cython cimport view
+and they can be used like this:
 
-    # direct access in both dimensions, strided in the first dimension, contiguous in the last
-    cdef int[:, ::view.contiguous] a
+.. literalinclude:: ../../examples/userguide/memoryviews/memory_layout.pyx
 
-    # contiguous list of pointers to contiguous lists of ints
-    cdef int[::view.indirect_contiguous, ::1] b
+Only the first, last or the dimension following an indirect dimension may be
+specified contiguous:
 
-    # direct or indirect in the first dimension, direct in the second dimension
-    # strided in both dimensions
-    cdef int[::view.generic, :] c
+.. literalinclude:: ../../examples/userguide/memoryviews/memory_layout_2.pyx
 
-Only the first, last or the dimension following an indirect dimension may be
-specified contiguous::
+::
 
     # INVALID
-    cdef int[::view.contiguous, ::view.indirect, :] a
-    cdef int[::1, ::view.indirect, :] b
+    cdef int[::view.contiguous, ::view.indirect, :] d
+    cdef int[::1, ::view.indirect, :] e
 
-    # VALID
-    cdef int[::view.indirect, ::1, :] a
-    cdef int[::view.indirect, :, ::1] b
-    cdef int[::view.indirect_contiguous, ::1, :]
 
 The difference between the `contiguous` flag and the `::1` specifier is that the
 former specifies contiguity for only one dimension, whereas the latter specifies
@@ -686,7 +658,5 @@ call functions in C files, see :ref:`using_c_libraries`.
 
 
 .. _GIL: http://docs.python.org/dev/glossary.html#term-global-interpreter-lock
-.. _new style buffers: https://docs.python.org/c-api/buffer.html
-.. _pep 3118: https://www.python.org/dev/peps/pep-3118/
 .. _NumPy: https://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html#memory-layout
-.. _example: http://www.scipy.org/Numpy_Example_List#newaxis
+.. _example: https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html

docs/src/userguide/numpy_tutorial.rst

@@ -147,7 +147,8 @@ Cython version -- Cython uses ".pyx" as its file suffix.
 .. literalinclude:: ../../examples/userguide/numpy_tutorial/convolve_py.py
     :linenos:
 
-This should be compiled to produce :file:`convolve_cy.so` (for Linux systems). We
+This should be compiled to produce :file:`convolve_cy.so` (for Linux systems,
+on Windows systems, this will be a ``.pyd`` file). We
 run a Python session to test both the Python version (imported from
 ``.py``-file) and the compiled Cython module.
 

docs/src/userguide/parallelism.rst

@@ -131,7 +131,7 @@ It currently supports OpenMP, but later on more backends might be supported.
 
        with nogil, parallel():
            local_buf = <int *> malloc(sizeof(int) * size)
-           if local_buf == NULL:
+           if local_buf is NULL:
                abort()
 
            # populate our local buffer in a sequential loop

docs/src/userguide/pypy.rst

 Porting Cython code to PyPy
 ===========================
 
-Since version 0.17, Cython has basic support for cpyext, the layer in
+Cython has basic support for cpyext, the layer in
 `PyPy <http://pypy.org/>`_ that emulates CPython's C-API.  This is
 achieved by making the generated C code adapt at C compile time, so
 the generated code will compile in both CPython and PyPy unchanged.

docs/src/userguide/pyrex_differences.rst

@@ -21,10 +21,14 @@ Python 3 Support
 
 Cython creates ``.c`` files that can be built and used with both
 Python 2.x and Python 3.x. In fact, compiling your module with
-Cython may very well be the easiest way to port code to Python 3.
-We are also working to make the compiler run in both Python 2.x and 3.x.
+Cython may very well be an easy way to port code to Python 3.
 
-Many Python 3 constructs are already supported by Cython.
+Cython also supports various syntax additions that came with
+Python 3.0 and later major Python releases.  If they do not conflict
+with existing Python 2.x syntax or semantics, they are usually just
+accepted by the compiler.  Everything else depends on the
+compiler directive ``language_level=3``
+(see :ref:`compiler directives<compiler-directives>`).
 
 List/Set/Dict Comprehensions
 ----------------------------
@@ -67,7 +71,6 @@ extra positional arguments, e.g.::
 takes exactly two positional parameters and has two required keyword parameters.
 
 
-
 Conditional expressions "x if b else y"
 =========================================
 
@@ -258,26 +261,13 @@ remain the same. There is a slight performance penalty in some cases when a
 cdef/cpdef function without any optional is overridden with one that does have
 default argument values.
 
-For example, one can have the ``.pxd`` file::
+For example, one can have the ``.pxd`` file:
 
-    cdef class A:
-        cdef foo(self)
-    cdef class B(A)
-        cdef foo(self, x=*)
-    cdef class C(B):
-        cpdef foo(self, x=*, int k=*)
+.. literalinclude:: ../../examples/userguide/language_basics/optional_subclassing.pxd
 
-with corresponding ``.pyx`` file::
+with corresponding ``.pyx`` file:
 
-    cdef class A:
-        cdef foo(self):
-            print "A"
-    cdef class B(A)
-        cdef foo(self, x=None)
-            print "B", x
-    cdef class C(B):
-        cpdef foo(self, x=True, int k=3)
-            print "C", x, k
+.. literalinclude:: ../../examples/userguide/language_basics/optional_subclassing.pyx
 
 .. note::
 

docs/src/userguide/sharing_declarations.rst

@@ -80,28 +80,13 @@ Here is an example. :file:`dishes.pxd` is a definition file which exports a
 C data type. :file:`restaurant.pyx` is an implementation file which imports and
 uses it.
 
-:file:`dishes.pxd`::
+:file:`dishes.pxd`:
 
-   cdef enum otherstuff:
-       sausage, eggs, lettuce
+.. literalinclude:: ../../examples/userguide/sharing_declarations/dishes.pxd
 
-   cdef struct spamdish:
-       int oz_of_spam
-       otherstuff filler
+:file:`restaurant.pyx`:
 
-:file:`restaurant.pyx`::
-
-    cimport dishes
-    from dishes cimport spamdish
-
-    cdef void prepare(spamdish *d):
-        d.oz_of_spam = 42
-        d.filler = dishes.sausage
-
-    def serve():
-        cdef spamdish d
-        prepare(&d)
-        print("%d oz spam, filler no. %d" % (d.oz_of_spam, d.filler))
+.. literalinclude:: ../../examples/userguide/sharing_declarations/restaurant.pyx
 
 It is important to understand that the :keyword:`cimport` statement can only
 be used to import C data types, C functions and variables, and extension
@@ -147,17 +132,13 @@ for an imaginary module, and :keyword:`cimport` that module. You can then
 refer to the C functions by qualifying them with the name of the module.
 Here's an example:
 
-:file:`c_lunch.pxd`::
+:file:`c_lunch.pxd`:
 
-    cdef extern from "lunch.h":
-        void eject_tomato(float)
+.. literalinclude:: ../../examples/userguide/sharing_declarations/c_lunch.pxd
 
-:file:`lunch.pyx`::
+:file:`lunch.pyx`:
 
-    cimport c_lunch
-
-    def eject_tomato(float speed):
-        c_lunch.eject_tomato(speed)
+.. literalinclude:: ../../examples/userguide/sharing_declarations/lunch.pyx
 
 You don't need any :file:`c_lunch.pyx` file, because the only things defined
 in :file:`c_lunch.pxd` are extern C entities. There won't be any actual
@@ -173,28 +154,17 @@ C functions defined at the top level of a module can be made available via
 :keyword:`cimport` by putting headers for them in the ``.pxd`` file, for
 example:
 
-:file:`volume.pxd`::
-
-    cdef float cube(float)
+:file:`volume.pxd`:
 
-:file:`volume.pyx`::
+.. literalinclude:: ../../examples/userguide/sharing_declarations/volume.pxd
 
-    cdef float cube(float x):
-        return x * x * x
+:file:`volume.pyx`:
 
-:file:`spammery.pyx`::
+.. literalinclude:: ../../examples/userguide/sharing_declarations/volume.pyx
 
-    from __future__ import print_function
+:file:`spammery.pyx`:
 
-    from volume cimport cube
-
-    def menu(description, size):
-        print(description, ":", cube(size),
-              "cubic metres of spam")
-
-    menu("Entree", 1)
-    menu("Main course", 3)
-    menu("Dessert", 2)
+.. literalinclude:: ../../examples/userguide/sharing_declarations/spammery.pyx
 
 .. note::
 
@@ -203,6 +173,7 @@ example:
     this object from Python, nor can you use it from Cython using a normal import
     statement; you have to use :keyword:`cimport`.
 
+.. _sharing_extension_types:
 
 Sharing Extension Types
 =======================
@@ -222,38 +193,23 @@ Python methods.
 Here is an example of a module which defines and exports an extension type,
 and another module which uses it:
 
-:file:`Shrubbing.pxd`::
-
-    cdef class Shrubbery:
-        cdef int width
-        cdef int length
-
-:file:`Shrubbing.pyx`::
+:file:`shrubbing.pxd`:
 
-    cdef class Shrubbery:
-        def __cinit__(self, int w, int l):
-            self.width = w
-            self.length = l
+.. literalinclude:: ../../examples/userguide/sharing_declarations/shrubbing.pxd
 
-    def standard_shrubbery():
-        return Shrubbery(3, 7)
+:file:`shrubbing.pyx`:
 
-:file:`Landscaping.pyx`::
+.. literalinclude:: ../../examples/userguide/sharing_declarations/shrubbing.pyx
 
-    cimport Shrubbing
-    import Shrubbing
+:file:`landscaping.pyx`:
 
-    cdef Shrubbing.Shrubbery sh
-    sh = Shrubbing.standard_shrubbery()
-    print("Shrubbery size is %d x %d" % (sh.width, sh.length))
+.. literalinclude:: ../../examples/userguide/sharing_declarations/landscaping.pyx
 
 One would then need to compile both of these modules, e.g. using
 
-:file:`setup.py`::
+:file:`setup.py`:
 
-    from distutils.core import setup
-    from Cython.Build import cythonize
-    setup(ext_modules = cythonize(["Landscaping.pyx", "Shrubbing.pyx"]))
+.. literalinclude:: ../../examples/userguide/sharing_declarations/setup.py
 
 Some things to note about this example:
 

docs/src/userguide/source_files_and_compilation.rst

@@ -75,8 +75,6 @@ them through :func:`cythonize`::
     )
 
 
-.. _pyximport:
-
 Pyximport
 ===========
 
@@ -107,51 +105,4 @@ on end user side as it hooks into their import system.  The best way
 to cater for end users is to provide pre-built binary packages in the
 `wheel <https://wheel.readthedocs.io/>`_ packaging format.
 
-Arguments
----------
+To have more information of :mod:`pyximport`, please refer to :ref:`pyximport`.
\ No newline at end of file
-
-The function ``pyximport.install()`` can take several arguments to
-influence the compilation of Cython or Python files.
-
-.. autofunction:: pyximport.install
-
-Dependency Handling
---------------------
-
-Since :mod:`pyximport` does not use `cythonize()` internally, it currently
-requires a different setup for dependencies.  It is possible to declare that
-your module depends on multiple files, (likely ``.h`` and ``.pxd`` files).
-If your Cython module is named ``foo`` and thus has the filename
-:file:`foo.pyx` then you should create another file in the same directory
-called :file:`foo.pyxdep`.  The :file:`modname.pyxdep` file can be a list of
-filenames or "globs" (like ``*.pxd`` or ``include/*.h``).  Each filename or
-glob must be on a separate line.  Pyximport will check the file date for each
-of those files before deciding whether to rebuild the module.  In order to
-keep track of the fact that the dependency has been handled, Pyximport updates
-the modification time of your ".pyx" source file.  Future versions may do
-something more sophisticated like informing distutils of the dependencies
-directly.
-
-Limitations
-------------
-
-Pyximport does not give you any control over how your Cython file is
-compiled.  Usually the defaults are fine.  You might run into problems if
-you wanted to write your program in half-C, half-Cython and build them
-into a single library.
-
-Pyximport does not hide the Distutils/GCC warnings and errors generated
-by the import process.  Arguably this will give you better feedback if
-something went wrong and why.  And if nothing went wrong it will give you
-the warm fuzzy feeling that pyximport really did rebuild your module as it
-was supposed to.
-
-Basic module reloading support is available with the option ``reload_support=True``.
-Note that this will generate a new module filename for each build and thus
-end up loading multiple shared libraries into memory over time.  CPython does
-not support reloading shared libraries as such.
-
-Pyximport puts both your ``.c`` file and the platform-specific binary into
-a separate build directory, usually ``$HOME/.pyxblx/``.  To copy it back
-into the package hierarchy (usually next to the source file) for manual
-reuse, you can pass the option ``inplace=True``.

docs/src/userguide/special_methods.rst

@@ -185,6 +185,8 @@ method called :meth:`__next__`, not next. The Python system will automatically
 supply a next method which calls your :meth:`__next__`. Do *NOT* explicitly
 give your type a :meth:`next` method, or bad things could happen.
 
+.. _special_methods_table:
+
 Special Method Table
 ---------------------
 
@@ -241,6 +243,8 @@ like :meth:`__eq__` or the single special method :meth:`__richcmp__`.
 Depending on the application, one way or the other may be better.
 
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
+| Name 	                | Parameters                            | Return type | 	Description                                    |
++=======================+=======================================+=============+========================================================+
 | __eq__                |self, y                                | object      | self == y                                              |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
 | __ne__                |self, y                                | object      | self != y  (falls back to ``__eq__`` if not available) |

docs/src/userguide/wrapping_CPlusPlus.rst

@@ -252,25 +252,12 @@ themselves::
 Nested class declarations
 --------------------------
 C++ allows nested class declaration. Class declarations can also be
-nested in Cython::
-
-    cdef extern from "<vector>" namespace "std":
-        cdef cppclass vector[T]:
-            cppclass iterator:
-                T operator*()
-                iterator operator++()
-                bint operator==(iterator)
-                bint operator!=(iterator)
-            vector()
-            void push_back(T&)
-            T& operator[](int)
-            T& at(int)
-            iterator begin()
-            iterator end()
-
-    cdef vector[int].iterator iter  #iter is declared as being of type vector<int>::iterator
-
-Note that the nested class is declared with a ``cppclass`` but without a ``cdef``.
+nested in Cython:
+
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/nested_class.pyx
+
+Note that the nested class is declared with a ``cppclass`` but without a ``cdef``,
+as it is already part of a ``cdef`` declaration section.
 
 C++ operators not compatible with Python syntax
 ------------------------------------------------
@@ -299,36 +286,9 @@ which can also be written ``&foo``.
 Templates
 ----------
 
-Cython uses a bracket syntax for templating. A simple example for wrapping C++ vector::
-
-    # import dereference and increment operators
-    from cython.operator cimport dereference as deref, preincrement as inc
-
-    cdef extern from "<vector>" namespace "std":
-        cdef cppclass vector[T]:
-            cppclass iterator:
-                T operator*()
-                iterator operator++()
-                bint operator==(iterator)
-                bint operator!=(iterator)
-            vector()
-            void push_back(T&)
-            T& operator[](int)
-            T& at(int)
-            iterator begin()
-            iterator end()
-
-    cdef vector[int] *v = new vector[int]()
-    cdef int i
-    for i in range(10):
-        v.push_back(i)
-
-    cdef vector[int].iterator it = v.begin()
-    while it != v.end():
-        print(deref(it))
-        inc(it)
-
-    del v
+Cython uses a bracket syntax for templating. A simple example for wrapping C++ vector:
+
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/templates.pyx
 
 Multiple template parameters can be defined as a list, such as ``[T, U, V]``
 or ``[int, bool, char]``.  Optional template parameters can be indicated
@@ -339,55 +299,33 @@ a typedef for its template parameters it is preferable to use that name here.
 
 
 Template functions are defined similarly to class templates, with
-the template parameter list following the function name::
-
-    cdef extern from "<algorithm>" namespace "std":
-        T max[T](T a, T b)
+the template parameter list following the function name:
 
-    print(max[long](3, 4))
-    print(max(1.5, 2.5))  # simple template argument deduction
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/function_template.pyx
 
 
 Standard library
 -----------------
 
 Most of the containers of the C++ Standard Library have been declared
-in pxd files located in ``/Cython/Includes/libcpp``.  These containers
-are: deque, list, map,  pair,  queue,  set,  stack,  vector.
+in pxd files located
+in `/Cython/Includes/libcpp <https://github.com/cython/cython/tree/master/Cython/Includes/libcpp>`_.
+These containers are: deque, list, map,  pair,  queue,  set,  stack,  vector.
 
-For example::
+For example:
 
-    from libcpp.vector cimport vector
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/vector_demo.pyx
 
-    cdef vector[int] vect
-    cdef int i, x
-    for i in range(10):
-        vect.push_back(i)
-    for i in range(10):
-        print(vect[i])
-    for x in vect:
-        print(x)
+The pxd files
+in `/Cython/Includes/libcpp <https://github.com/cython/cython/tree/master/Cython/Includes/libcpp>`_
+also work as good examples on how to declare C++ classes.
 
-The pxd files in ``/Cython/Includes/libcpp`` also work as good examples on
-how to declare C++ classes.
-
-Since Cython 0.17, the STL containers coerce from and to the
+The STL containers coerce from and to the
 corresponding Python builtin types.  The conversion is triggered
 either by an assignment to a typed variable (including typed function
-arguments) or by an explicit cast, e.g.::
-
-    from libcpp.string cimport string
-    from libcpp.vector cimport vector
-
-    cdef string s = py_bytes_object
-    print(s)
-    cpp_string = <string> py_unicode_object.encode('utf-8')
+arguments) or by an explicit cast, e.g.:
 
-    cdef vector[int] vect = xrange(1, 10, 2)
-    print(vect)              # [1, 3, 5, 7, 9]
-
-    cdef vector[string] cpp_strings = b'ab cd ef gh'.split()
-    print(cpp_strings[1])   # b'cd'
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/python_to_cpp.pyx
 
 The following coercions are available:
 
@@ -413,16 +351,21 @@ inside of containers, e.g. a C++ vector of maps of strings.
 Iteration over stl containers (or indeed any class with ``begin()`` and
 ``end()`` methods returning an object supporting incrementing, dereferencing,
 and comparison) is supported via the ``for .. in`` syntax (including in list
-comprehensions).  For example, one can write::
+comprehensions).  For example, one can write:
 
-    cdef vector[int] v = ...
-    for value in v:
-        f(value)
-    return [x*x for x in v if x % 2 == 0]
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/iterate.pyx
 
 If the loop target variable is unspecified, an assignment from type
 ``*container.begin()`` is used for :ref:`type inference <compiler-directives>`.
 
+.. note::
+
+    Slicing stl containers is supported,
+    you can do ``for x in my_vector[:5]: ...`` but unlike pointers slices,
+    it will create a temporary Python object and iterate over it. Thus
+    making the iteration very slow. You might want to avoid slicing
+    C++ containers for performance reasons.
+
 
 Simplified wrapping with default constructor
 --------------------------------------------
@@ -430,20 +373,9 @@ Simplified wrapping with default constructor
 If your extension type instantiates a wrapped C++ class using the default
 constructor (not passing any arguments), you may be able to simplify the
 lifecycle handling by tying it directly to the lifetime of the Python wrapper
-object.  Instead of a pointer attribute, you can declare an instance::
-
-    cdef class VectorStack:
-        cdef vector[int] v
-
-        def push(self, x):
-            self.v.push_back(x)
+object.  Instead of a pointer attribute, you can declare an instance:
 
-        def pop(self):
-            if self.v.empty():
-                raise IndexError()
-            x = self.v.back()
-            self.v.pop_back()
-            return x
+.. literalinclude:: ../../examples/userguide/wrapping_CPlusPlus/wrapper_vector.pyx
 
 Cython will automatically generate code that instantiates the C++ object
 instance when the Python object is created and deletes it when the Python
@@ -598,7 +530,8 @@ possible to declare them in the :file:`setup.py` file::
 Cython will generate and compile the :file:`rect.cpp` file (from
 :file:`rect.pyx`), then it will compile :file:`Rectangle.cpp`
 (implementation of the ``Rectangle`` class) and link both object files
-together into :file:`rect.so`, which you can then import in Python using
+together into :file:`rect.so` on Linux, or :file:`rect.pyd` on windows,
+which you can then import in Python using
 ``import rect`` (if you forget to link the :file:`Rectangle.o`, you will
 get missing symbols while importing the library in Python).
 

runtests.py

@@ -618,7 +618,7 @@ class TestBuilder(object):
                     test_class = CythonUnitTestCase
                 else:
                     test_class = CythonRunTestCase
-            elif mode in ['compile', 'error', 'test']:
+            elif mode in ['compile', 'error']:
                 test_class = CythonCompileTestCase
             else:
                 raise KeyError('Invalid test mode: ' + mode)

setup.py

@@ -85,20 +85,20 @@ def compile_cython_modules(profile=False, compile_more=False, cython_with_refnan
     compiled_modules = [
         "Cython.Plex.Scanners",
         "Cython.Plex.Actions",
-        "Cython.Compiler.Pythran",
-        "Cython.Compiler.Lexicon",
         "Cython.Compiler.Scanning",
-        "Cython.Compiler.Parsing",
         "Cython.Compiler.Visitor",
         "Cython.Compiler.FlowControl",
-        "Cython.Compiler.Code",
         "Cython.Runtime.refnanny",
         "Cython.Compiler.FusedNode",
         "Cython.Tempita._tempita",
-        "Cython.StringIOTree",
     ]
     if compile_more:
         compiled_modules.extend([
+            "Cython.StringIOTree",
+            "Cython.Compiler.Code",
+            "Cython.Compiler.Lexicon",
+            "Cython.Compiler.Parsing",
+            "Cython.Compiler.Pythran",
             "Cython.Build.Dependencies",
             "Cython.Compiler.ParseTreeTransforms",
             "Cython.Compiler.Nodes",

tests/build/cythonize_cython.srctree

+PYTHON -c "import cythonize_tests"
+PYTHON -c "import cython_tests"
+
+######## cythonize_tests.py ########
+
+from Cython.Build.Cythonize import main as cythonize
+
+for test_case in ["cython.pyx", "src/cython.pyx", "src2/cython.pyx"]:
+    try:
+        cythonize([test_case])
+    except ValueError:
+        pass
+    else:
+        assert False, "ValueError not raised - forbidding cythonize "+test_case+" doesn't work"
+
+try:
+    cythonize(["notcython.pys"])
+except ValueError:
+    assert False, "ValueError raised - forbidding cythonize notcython.pyx should work"
+else:
+    pass
+
+######## cython_tests.py ########
+
+
+from Cython.Compiler.Main import main as cython
+import sys
+
+for test_case in ["cython.pyx", "src/cython.pyx", "src2/cython.pyx"]:
+    sys.argv=["cython", test_case]  #cython.py will extract parameters from sys.argv
+    try:
+        cython(command_line=1)
+    except ValueError:
+        pass
+    else:
+        assert False, "ValueError not raised - forbidding cython "+test_case+" doesn't work"
+
+sys.argv=["cython", "notcython.pyx"]  #cython.py will extract parameters from sys.argv
+try:
+    cython(["notcython.pys"])
+except ValueError:
+    assert False, "ValueError raised - forbidding cythonize notcython.pyx should work"
+else:
+    pass
+
+######## cython.pyx ########
+######## src/__init__.py ########
+######## src/cython.pyx ########
+######## notcython.pyx ########
+######## src2/cython.pyx ########

tests/run/cpp_stl_forward_list.pyx

+# mode: run
+# tag: cpp, werror, cpp11
+
+from cython.operator cimport dereference as deref
+from cython.operator cimport preincrement as incr
+
+from libcpp.forward_list cimport forward_list
+from libcpp cimport bool as cbool
+
+
+def simple_iteration_test(L):
+    """
+    >>> iteration_test([1,2,4,8])
+    8
+    4
+    2
+    1
+    >>> iteration_test([8,4,2,1])
+    1
+    2
+    4
+    8
+    """
+    cdef forward_list[int] l
+    for a in L:
+        l.push_front(a)
+    for a in l:
+        print(a)
+
+def iteration_test(L):
+    """
+    >>> iteration_test([1,2,4,8])
+    8
+    4
+    2
+    1
+    >>> iteration_test([8,4,2,1])
+    1
+    2
+    4
+    8
+    """
+    l = new forward_list[int]()
+    try:
+        for a in L:
+            l.push_front(a)
+        it = l.begin()
+        while it != l.end():
+            a = deref(it)
+            incr(it)
+            print(a)
+    finally:
+        del l
+
+def test_value_type(x):
+    """
+    >>> test_value_type(2)
+    2.0
+    >>> test_value_type(2.5)
+    2.5
+    """
+    cdef forward_list[double].value_type val = x
+    return val
+
+def test_value_type_complex(x):
+    """
+    >>> test_value_type_complex(2)
+    (2+0j)
+    """
+    cdef forward_list[double complex].value_type val = x
+    return val
+
+
+#  Tests GitHub issue #1788.
+cdef cppclass MyForwardList[T](forward_list):
+    pass
+
+cdef cppclass Ints(MyForwardList[int]):
+    pass

tests/run/numpy_test.pyx

@@ -898,4 +898,33 @@ def test_copy_buffer(np.ndarray[double, ndim=1] a):
     return a
 
 
+@testcase
+def test_broadcast_comparison(np.ndarray[double, ndim=1] a):
+    """
+    >>> a = np.ones(10, dtype=np.double)
+    >>> a0, obj0, a1, obj1 = test_broadcast_comparison(a)
+    >>> np.all(a0 == (a == 0)) or a0
+    True
+    >>> np.all(a1 == (a == 1)) or a1
+    True
+    >>> np.all(obj0 == (a == 0)) or obj0
+    True
+    >>> np.all(obj1 == (a == 1)) or obj1
+    True
+
+    >>> a = np.zeros(10, dtype=np.double)
+    >>> a0, obj0, a1, obj1 = test_broadcast_comparison(a)
+    >>> np.all(a0 == (a == 0)) or a0
+    True
+    >>> np.all(a1 == (a == 1)) or a1
+    True
+    >>> np.all(obj0 == (a == 0)) or obj0
+    True
+    >>> np.all(obj1 == (a == 1)) or obj1
+    True
+    """
+    cdef object obj = a
+    return a == 0, obj == 0, a == 1, obj == 1
+
+
 include "numpy_common.pxi"

tests/run/posix_time.pyx

@@ -22,7 +22,7 @@ def test_itimer(sec, usec):
     t.it_value.tv_sec = 0
     t.it_value.tv_usec = 0
     ret = setitimer(ITIMER_REAL, &t, NULL)
-    return gtime.it_interval.tv_sec, gtime.it_interval.tv_usec
+    return int(gtime.it_interval.tv_sec), int(gtime.it_interval.tv_usec)
 
 def test_gettimeofday():
     """

tests/run/simpcall.pyx

-# mode: test
+# mode: run
 
 def f(x, y):
     x = y

tests/run/tryexcept.pyx

@@ -58,6 +58,36 @@ def single_except_expression(a, x):
         i = 3
     return i
 
+
+exceptions = (ValueError, TypeError)
+
+
+def single_except_global_tuple(x):
+    """
+    >>> single_except_global_tuple(None)
+    2
+    >>> single_except_global_tuple(ValueError('test'))
+    3
+    >>> single_except_global_tuple(TypeError('test'))
+    3
+    >>> class TypeErrorSubtype(TypeError): pass
+    >>> single_except_global_tuple(TypeErrorSubtype('test'))
+    3
+    >>> single_except_global_tuple(AttributeError('test'))
+    Traceback (most recent call last):
+    AttributeError: test
+    """
+    cdef int i
+    try:
+        i = 1
+        if x:
+            raise x
+        i = 2
+    except exceptions:
+        i = 3
+    return i
+
+
 def double_except_no_raise(a,b):
     """
     >>> double_except_no_raise(TypeError, ValueError)
@@ -179,6 +209,10 @@ def normal_and_bare_except_raise(x, a):
     2
     >>> normal_and_bare_except_raise(ValueError('test'), TypeError)
     3
+    >>> normal_and_bare_except_raise(TypeError('test'), (TypeError, ValueError))
+    2
+    >>> normal_and_bare_except_raise(ValueError('test'), (TypeError, ValueError))
+    2
     >>> normal_and_bare_except_raise(None, TypeError)
     1
     """