Unraveling Python File Types: .py, .ipynb, .pyc, .pyi, .pyd

Python has a vast ecosystem and several types of file extensions. Some of these are directly related to writing and executing Python code, while others play supporting roles or serve different purposes entirely.

In this article, I will introduce five common Python file extensions: .py, .ipynb, .pyi, .pyc, and .pyd.

Python Scripts: .py Files

The .py file extension is probably the most recognizable to anyone who has worked with Python. It is the standard extension for Python script files. .py files are plain text files that contain Python code, which can be executed by a Python interpreter.

For instance, when you write and save a script as hello_world.py, you are creating a .py file. It can be run directly from the command line using the Python interpreter like so: python hello_world.py.

print("Hello, World!")

Interactive Notebooks: .ipynb Files

The .ipynb file extension stands for IPython Notebook, which is the legacy term for what we now call Jupyter Notebooks. Jupyter Notebooks are an open-source web application that allows creation and sharing of documents containing live code, equations, visualizations, and narrative text.

.ipynb files can contain multiple elements like code blocks, text, images, and equations, making them ideal for data analysis, scientific computing, and education. The “iPython” part of the name reflects the fact that Jupyter Notebooks began as part of the IPython project, a command shell for interactive computing in multiple programming languages.

Below is an extremely simplified example of how it might look:

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello, World!\n"
     ]
    }
   ],
   "source": [
    "print('Hello, World!')"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 2
}

Stub Files: .pyi Files

The .pyi extension denotes Python Interface files or stub files. Introduced in Python 3.5, these files hold type information that can’t be expressed directly in Python code.

When a Python interpreter or tool encounters a .pyi file, it uses the type annotations contained therein to check the types of the elements in the corresponding .py file. Stub files are not meant for execution; instead, they are used by static type checking tools like Mypy, PyCharm, or Pyright to improve code quality and detect potential errors earlier in the development process.

A Python Interface file (.pyi) could look like this:

# content of hello.pyi
from typing import Any
def print(a: Any) -> None: ...

Bytecode Files: .pyc Files

The .pyc extension refers to Python bytecode files. When a .py file is executed, the Python interpreter compiles the file into a format known as bytecode to speed up the start-up time of the script in future runs. This compiled version is stored with a .pyc extension.

In Python3, these .pyc files are stored in a subfolder named __pycache__. While these files aren't meant to be directly executed or manipulated by developers, they play an important role in improving the performance of Python programs.

Python Dynamic Modules: .pyd Files

Finally, the .pyd file extension is equivalent to a .dll (Dynamic Link Library) file on Windows. These files are created when a Python module is compiled in C or C++. A .pyd file can be imported into a Python script like a regular .py file, but the actual code execution occurs in the compiled language, which can offer performance benefits.

For example, many core Python libraries, like NumPy or SciPy, use .pyd files to perform computationally intensive tasks more efficiently than could be achieved with Python alone.

#include <Python.h>

static PyObject* say_hello(PyObject* self, PyObject* args)
{
    const char* name;

    if (!PyArg_ParseTuple(args, "s", &name))
        return NULL;

    printf("Hello %s!\n", name);

    Py_RETURN_NONE;
}

static PyMethodDef HelloMethods[] = {
    {"say_hello", say_hello, METH_VARARGS, "Greet somebody."},
    {NULL, NULL, 0, NULL}
};

static struct PyModuleDef hellomodule = {
    PyModuleDef_HEAD_INIT, "hello", NULL, -1, HelloMethods
};

PyMODINIT_FUNC
PyInit_hello(void)
{
    return PyModule_Create(&hellomodule);
}

This C code defines a Python module hello with a single function say_hello, which takes a string argument and prints a greeting. After compiling this C code into a .pyd file, you could use it in Python like this:

import hello
hello.say_hello("World")

Conclusion

Understanding Python’s file extensions can help you navigate the language’s ecosystem more effectively and take full advantage of its diverse capabilities. From scripting and interactive notebooks to type annotations, performance optimizations, and integration with C/C++, the Python language offers a range of file types to support various programming needs.

While you might not work directly with .pyc, .pyi, or .pyd files on a daily basis, understanding what they are and how they contribute to Python’s flexibility and power can broaden your perspective and enrich your Python programming skills.