This is a casual guide to setting up Cython for your Python! The info on how to do this is quite scattered, thus I think this collection of steps would be useful to others to get them started.
First things first, assuming you have a Python implementation, you will need to install Cython. Depending on your operating system, distro, system config, etc. you will have a name to call it by. For a standard installation on Windows its python or py. For a lot of Linux distros it is python3, while on others it is just python. Figure that out, I'm sure you can handle it. For the sake of this demonstration, we will be using python for the example; replace with yours.
Open up your terminal (for Windows folks, that is cmd / command prompt):
python -m pip install cython
If you are using pypy3 without pip, you must do this instead:
pypy -m ensurepip
pypy -m pip install --upgrade pip
pypy -m pip install cython
Enter that in and it will install. Easy right? Well, unfortunately we also need a C compiler. That will be covered in the following sections. It covers Windows and Linux.
Before any of this, make sure your Python is in Windows Enviroment Variables PATH (the standard install has an option). This includes PyPy, ASnake will not be able to detect it if isn't in PATH.
Prepare for the mess that is C compilers on Windows.
Is the most common way to install a C compiler on Windows for Python.
The above picture is from this link:
https://wiki.python.org/moin/WindowsCompilers
Which leads to:
https://visualstudio.microsoft.com/downloads
It is a bit bulky at 7.8GB, and it installs Visual Studio which we may not want. If you do, you will probably want the community edition.
This is the package you'll want to select if you go this route.
A very slightly less bloaty alternative is to scroll down to All Downloads and select Build Tools for Visual Studio 2022.
Selecting:
The download at 7.14GB, which is a minor win. It will not include Visual Studio.
If anyone knows a more minimal component setup, please tell me on Discord to save some people some download time and drive space.
Either of those ways should work without further setup.
There are many with slow connection, data limits, and not much storage space. This option is for the desperate, or those who simply hate Visual Studio. This option is only 940MB! That is just the final disk space; the download size should be lower since it downloads compressed files. Note that with this compiler you will have to abandon your main Python install and use MinGW's. Since it is a seperate Python installation, you will have to reinstall libraries.
Here is some whining about me trying to figure out this snake-hole. My apologies.
The Cython Documentation reccomends to read how to install MinGW at mingw.org, but that site has been down for quite some time. Instead it is reccomended to use minGW-w64, the 64 bit version. OK, it has a Sourceforge download. Buuut... The installer breaks!
And the direct download seems to just be source files. Which we would need a C compiler for. Which is... What we are trying to get in the first place! Terrible.
Someone else has done the work of compiling it here and here, but their included Python builds do not include zlib, which is required for pip. I had some trouble compiling a Python build with it too. Ugh. Please contact me if you can get a good Windows Python compile with MinGW-w64.
cygwin doesn't come with MinGW by default. It is potentially viable but I dislike it's installation.
So we are left with one option: MSYS2. It is as close to running a Linux enviroment you can get without actually having Linux. So basically it is just a bunch of Linux tools ported to be used on Windows. You can hopefully find the installer somewhere at this link. Just click next on all the installation options.
Once installed, you open up app and you will be greeted by a command line interface. Paste in these commands to get you set up with the minimal requirements:
pacman -S gcc python
python -m ensurepip
python -m pip install autopep8 cython sly
You can skip autopep8 and sly if you are not going to use ASnake.
If you need access to your Windows drives and files, you can cd to them easily. It is just the drive letter name, just make sure it starts with /
cd /c/
cd Users/HiMyNameIsBob/Documents
There you go, I went through a lot of suffering to find a more minimal setup for Cython on Windows. You're welcome.
You're kidding right? Some distros do not even need setup for this! If they do, it is so much simpler than Windows, it is crazy. How do people survive on there?
Python is already included via the command python3. If for whatever reason you do not have pip, you can install it via:
sudo apt-get install python3-pip
And if build-tools are not already included, simply do:
sudo apt install build-essential
Thats it!
sudo pacman -S base-devel
Pfft.
The setup will be similar for other Linux distros. It really is that easy.
After that wonderous journey, I'm sure you're pumped for ASnake having a compile target for Cython.
No? Oh c'mon, please stay! Alright fine, if you don't like ASnake I'm glad I assisted you. For those who want to automate Cython a bit, read on!
ASnake has gradual typing; type labeling of variables can be done at your own pace or not at all. It's optimizer can sometimes figure out types and label them for you. In Cython most of the gain are from static typing. Note that when using Cython with ASnake, it will be very strict about the types you defined, converting it from gradual typing to static typing. You can still have untyped variables.
# ASNAKE:
int number 12
# CYTHON:
cdef int number = 12
So in ASnake you are not required to type the cdef, it will convert automatically. You can also type function arguments.
thing does str
return x*y
from str x = 'hi' , int y = 2
Which Cython can also utilize. On top of that, there are some little tricks the ASnake compiler has up it's sleeve:
# ASNAKE:
import random
bool negative is random.randint(0,1)
int number is random.randint(0,100)
if negative
number is -number
print number
Might produce a .pyx file like:
# CYTHON:
from libc.time cimport time as Ctime
from libc.stdlib cimport rand, RAND_MAX, srand
from libc.stdio cimport printf
cdef extern from "stdbool.h":
ctypedef bint bool
srand(Ctime(NULL))
rand()
cdef bool negative = int(rand() / (RAND_MAX + 1.0) * 2)
cdef int number = int(rand() / (RAND_MAX + 1.0) * 101)
if negative:
number = -number
printf("%d\n", number)
That is a lot of work done for you! Writing this by hand is certianly doable, but more annoying. It cannot always be this good at conversion; converting to full C is hard task. ASnake can be used as a tool to jumpstart the process, while still maintaining the regular Python script. Even better, you can write scripts without planning for Cython in mind. When you need more performance you can just activate ASnake's Cython compile mode.
So, how do you activate Cython via ASnake? It is just a compile flag. Assume that we have a file called test.asnake with the code "Hello world!".
All we have to do is: python ASnake.py -cy -c -r test.asnake
┬─[ahri@Ahri:~/D/C/ASnake]─[11:37:41 AM]─[G:master]
╰─>$ python ASnake.py -cy -c -r test.asnake
# build time: 0.0003
# C compile time: 0.7222026269882917
Compiling test.pyx because it changed.
[1/1] Cythonizing test.pyx
running build_ext
building 'test' extension
gcc -pthread -Wno-unused-result -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -march=x86-64 -mtune=generic -O3 -pipe -fno-plt -fexceptions -Wp,-D_FORTIFY_SOURCE=2 -Wformat -Werror=format-security -fstack-clash-protection -fcf-protection -flto -ffat-lto-objects -march=x86-64 -mtune=generic -O3 -pipe -fno-plt -fexceptions -Wp,-D_FORTIFY_SOURCE=2 -Wformat -Werror=format-security -fstack-clash-protection -fcf-protection -flto -march=x86-64 -mtune=generic -O3 -pipe -fno-plt -fexceptions -Wp,-D_FORTIFY_SOURCE=2 -Wformat -Werror=format-security -fstack-clash-protection -fcf-protection -flto -fPIC -I. -I/usr/include/python3.10 -c test.c -o build/temp.linux-x86_64-3.10/test.o
gcc -pthread -shared -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -flto -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now -flto build/temp.linux-x86_64-3.10/test.o -L/usr/lib -o build/lib.linux-x86_64-3.10/test.cpython-310-x86_64-linux-gnu.so
copying build/lib.linux-x86_64-3.10/test.cpython-310-x86_64-linux-gnu.so ->
import test
____________
~ Cython Eval
Hello world!
____________
exec time: 0.01396291796118021
test.asnake compiled to test.pyx and test.cpython-310-x86_64-linux-gnu.so
Easy! The -cy flag stands for --cython, which sets the compile target to Cython. -c stands for --compile, which compiles the .pyx generated. Then -r is --run, which runs the script right after compilation. If you just want the .pyx file, remove the -c flag and pipe the text to a file. If you want to compile Cython in a more manual way, the Cython documentation explains here.
So that is how to install and setup Cython, and how to use it with ASnake. Hope this helps some of you out there!