193

In Python, what does "i" represent in .pyi extension?

In PEP-484, it mentions .pyi is "a stub file" but no mnemonic help on the extension. So does the "i" mean "Include"? "Implementation"? "Interface"?

Sabito stands with Ukraine
  • 4,271
  • 8
  • 34
  • 56
ChrisFreeman
  • 5,831
  • 4
  • 20
  • 32

4 Answers4

163

I think the i in .pyi stands for "Interface"

Definition for Interface in Java:

An interface in the Java programming language is an abstract type that is used to specify a behaviour that classes must implement

  • From Python typeshed github repository:

Each Python module is represented by a .pyi "stub". This is a normal Python file (i.e., it can be interpreted by Python 3), except all the methods are empty.

  • In 'Mypy' repository, they explicitly mention "stub" files as public interfaces:

A stubs file only contains a description of the public interface of the module without any implementations.

Because "Interfaces" do not exist in Python (see this SO question between Abstract class and Interface) I think the designers intended to dedicate a special extension for it.

pyi implements "stub" file (definition from Martin Fowler)

Stubs: provide canned answers to calls made during the test, usually not responding at all to anything outside what's programmed in for the test.

But people are more familiar with Interfaces than "stub" files, therefore it was easier to choose .pyi rather than .pys to avoid unnecessary confusion.

Wild Pottok
  • 318
  • 3
  • 8
Kruupös
  • 5,097
  • 3
  • 27
  • 43
  • 1
    Do the methods have to be empty? or can the be some reference implementation? – Robert McPythons Sep 30 '20 at 11:21
  • 1
    ‘I think the i in .pyi stands for "Interface". Definition for Interface in Java’ — why bring up a completely unrelated language that uses the term differently? – user3840170 Mar 25 '22 at 07:04
  • 3
    You're bringing up completely unrelated terms. Java interface is Java's way to multiple inheritance. Stub is simplified but working implementation used to speed up automated tests (eg in-memory database). – iirekm Apr 23 '22 at 13:45
49

The i in .pyi stands for ‘interface’.

The .pyi extension was first mentioned in this GitHub issue thread where JukkaL says:

I'd probably prefer an extension with just a single dot. It also needs to be something that is not in use (it should not be used by cython, etc.). .pys seems to be used in Windows (or was). Maybe .pyi, where i stands for an interface definition?

Pyprohly
  • 1,128
  • 1
  • 11
  • 10
  • 8
    Excellent reference! This supports the notion `.pyi` was first born from within the mypy project then more broadly adapted after discussions with in this thread https://github.com/python/typing/issues/22 – ChrisFreeman Mar 09 '21 at 17:54
40

Apparently PyCharm creates .pyi file for its own purposes:

The *.pyi files are used by PyCharm and other development tools to provide more information, such as PEP 484 type hints, than it is able to glean from introspection of extension types and methods. They are not intended to be imported, executed or used for any other purpose other than providing info to the tools. If you don't use use a tool that makes use of .pyi files then you can safely ignore this file.

See: https://www.python.org/dev/peps/pep-0484/ https://www.jetbrains.com/help/pycharm/2016.1/type-hinting-in-pycharm.html

This comment was found in: python27/Lib/site-packages/wx/core.pyi

Ollie
  • 1,641
  • 1
  • 13
  • 31
Ribo
  • 3,363
  • 1
  • 29
  • 35
  • 6
    Great info. Does it give a definitive answer to what the “i” in “pyi” stands for? – ChrisFreeman Mar 09 '19 at 02:19
  • I didn't see one. How about 'introspection'? (I was just trying to understand what the file was) – Ribo Mar 13 '19 at 15:30
  • @ChrisFreeman it says actually in 2nd ref (by PyCharm) literally next "PyCharm supports Python stub files with the .pyi extension. These files allow you to specify the type hints using Python 3 syntax for both Python 2 and 3. The stub files are created as usual , but you must specify the extension .pyi explicitly." – silpol Dec 23 '20 at 08:47
1

Another way to explain the contents of a module that Wing can't figure out is with a pyi Python Interface file. This file is merely a Python skeleton with the proper structure, call signature, and return values to correspond to the functions, attributes, classes, and methods specified in a module.

CinnamonCubing
  • 353
  • 2
  • 9