03-cython-types.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Cython language\n",
    "\n",
    "* The Cython language is a superset of the Python language -- nearly any Python code is valid Cython code, with very few edge cases.\n",
    "\n",
    "* Cython is a [_creole programming language_](https://en.wikipedia.org/wiki/Creole_language) -- a stable (programming) language developed from a mixture of different languages.  In this case, the component languages are Python, C, and C++, with a few cython-specific constructs.\n",
    "\n",
    "* It is designed to make it easy to write compiled CPython extension modules, and to fluidly mix in C and C++ constructs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Brief tour of Cython types\n",
    "\n",
    "* Regular python variables are dynamically typed, and work just fine in Cython.\n",
    "* Dynamically typed variables are simply Cython `object` types.\n",
    "* Cython introduces the `cdef` keyword to declare a C-level construct.\n",
    "* Cython supports the rest of the C type system--almost all beginning with `cdef` or a variant.  We won't be covering all of these."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%load_ext Cython"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "# untyped objects are simply Python declarations like we know and love...\n",
    "o = 1\n",
    "print(o)\n",
    "\n",
    "# and can be reassigned to a different type...\n",
    "o = 'a'\n",
    "\n",
    "# This print() function happens at extension module import time.\n",
    "print(o)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Integral types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "# The panoply of C integer types and their modifiers...\n",
    "# We typically get away with using just ints and longs...\n",
    "# https://en.wikipedia.org/wiki/C_data_types\n",
    "cdef:\n",
    "    int i = 0\n",
    "    unsigned long j = 1\n",
    "    signed short k = -3\n",
    "    long long ll = 1LL\n",
    "    bint flag = True\n",
    "\n",
    "print(i, j, k, ll, flag)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cython enforces static typing (either compile time or runtime, depending)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "cdef int i = 0\n",
    "\n",
    "# ...\n",
    "\n",
    "i = 'qwerty'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Floating point types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "# doubles are preferred for compatibility with Python `float` types\n",
    "# https://docs.python.org/3/c-api/float.html\n",
    "\n",
    "cdef:\n",
    "    float a = 1.0\n",
    "    double b = -1.0\n",
    "    long double c = 1e100\n",
    "print(a, b, c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Complex types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "# `double complex` is preferred for compatibility with Python's `complex` type:\n",
    "# https://docs.python.org/3/c-api/complex.html\n",
    "\n",
    "cdef:\n",
    "    float complex fc = 1+1j\n",
    "    double complex dc = 1+1j\n",
    "    long double complex ldc = 1+1j\n",
    "\n",
    "print(fc, dc, ldc)\n",
    "print(fc.real, dc.imag, ldc.conjugate())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## String types\n",
    "\n",
    "* Note that string types in Python are complicated by Py2 / Py3 differences.\n",
    "* This tutorial is entirely in Python 3, so we do not have to go into the minutiae here.\n",
    "* See [the fine manual](http://cython.readthedocs.io/en/latest/src/tutorial/strings.html#python-string-types-in-cython-code) or [other documentation](http://shop.oreilly.com/product/0636920033431.do) for more details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Statically declaring Python string types in Cython"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "cdef str s = \"asdf\"\n",
    "cdef bytes b = b\"jkl;\"\n",
    "print(s, b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Cython allows static declaration of Python types!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### C \"string\"s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "bb = b\"asdf\"\n",
    "cdef char *buf = bb\n",
    "print(bb, buf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Pop quiz:\n",
    "\n",
    "* What can we infer from the (runtime) warning generated here?\n",
    "    ```\n",
    "    warning: [...] Obtaining 'char *' from externally modifiable global Python value\n",
    "    ```\n",
    "* When working with C-level strings, what must we keep in mind to maintain Python guarantees?\n",
    "\n",
    "**Strong recommendation**: Work with `str` and `bytes` objects only; avoid `char *` buffers unless you're interfacing with external C code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "# Why is this very, very bad?\n",
    "a = b'a'\n",
    "b = b'b'\n",
    "cdef char *c = a + b\n",
    "\n",
    "# ...and how can we address it?\n",
    "\n",
    "# Again, it's best to avoid using char *'s unless absolutely necessary -- keep your\n",
    "# Strings Python-level strings, and all will be copacetic."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other statically-declarable Python types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "import datetime\n",
    "cimport cpython.datetime # We'll cover the `cimport` keyword later\n",
    "\n",
    "import array\n",
    "cimport cpython.array\n",
    "\n",
    "cdef:\n",
    "    list lst = [1]\n",
    "    dict dd = {'a': 'b'}\n",
    "    set ss = set([1])\n",
    "    frozenset fs = frozenset([1])\n",
    "    cpython.datetime.datetime dt = datetime.datetime.now()\n",
    "    cpython.array.array aa = array.array('i', [1, 2, 3])\n",
    "    \n",
    "print(lst, dd, ss, fs, dt, aa)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Nota Bene:\n",
    "\n",
    "* Everything on the LHS of the declaration is a C-level, statically typed entity.\n",
    "* Everything on the RHS of the declaration is a Python object of the corresponding type.\n",
    "* Cython enforces the static type at compile time -- a `list` variable can only ever be assigned to a `list` (or subclass)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Declaring and manipulating pointers\n",
    "\n",
    "**NOTE** Only do this if you have to -- fortunately we rarely have to drop to using or manipulating pointers in Cython unless we're interfacing with a C library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%cython\n",
    "\n",
    "cdef:\n",
    "    int *a = NULL\n",
    "    int b = 42\n",
    "\n",
    "# Point `a` at `b`\n",
    "a = &b\n",
    "\n",
    "# Dereference `a` -- Note the use of `a[0]` -- we don't use `*a` to dereference!\n",
    "print(a[0], b)\n",
    "\n",
    "# Modify b via a:\n",
    "a[0] = 137\n",
    "\n",
    "# Confirm that both refer to same value:\n",
    "print(a[0], b)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}