Python index Method

Last modified April 8, 2025

This comprehensive guide explores Python’s index method, the special method used for integer conversion in indexing operations. We’ll cover basic usage, sequence protocols, custom number types, and practical examples.

Basic Definitions

The index method is a special method that returns an integer representation of an object. It’s used when an object needs to be converted to an integer for indexing operations.

Key characteristics: it must return an integer, is called by operator.index(), and is used in slicing and indexing operations. It provides lossless integer conversion unlike int.

Basic index Implementation

Here’s a simple implementation showing how index enables objects to be used as indices in sequences like lists or tuples.

basic_index.py

class MyIndex: def init(self, value): self.value = value

def __index__(self):
    return self.value

idx = MyIndex(3) my_list = [10, 20, 30, 40, 50] print(my_list[idx]) # Output: 40

This example shows how an object with index can be used directly as a list index. The method returns the stored integer value when needed for indexing.

The index method is called implicitly when the object is used in an indexing context, converting it to a suitable integer index.

Using index with Slicing

index is also used in slice operations, allowing custom objects to be used as slice indices.

slicing.py

class SliceIndex: def init(self, value): self.value = value

def __index__(self):
    return self.value

start = SliceIndex(1) stop = SliceIndex(4) my_list = [0, 10, 20, 30, 40, 50] print(my_list[start:stop]) # Output: [10, 20, 30]

This demonstrates how objects with index can be used in slice notation. Both start and stop positions are converted to integers automatically.

The slice operation calls index on both slice bounds before performing the slice, enabling custom index types in slicing.

Difference Between index and int

While similar, index and int serve different purposes. index is specifically for lossless integer conversion.

index_vs_int.py

class Number: def init(self, value): self.value = value

def __index__(self):
    print("__index__ called")
    return self.value

def __int__(self):
    print("__int__ called")
    return self.value + 0.5  # Not a pure integer

num = Number(5) print(operator.index(num)) # Uses index print(int(num)) # Uses int

This shows the different behavior between the two methods. index must return an exact integer, while int can perform conversions.

index is preferred in indexing contexts as it guarantees proper integer values, while int is for general number conversion.

Custom Number Types with index

index allows custom number types to integrate with Python’s indexing system, making them behave like built-in integers in sequences.

custom_number.py

class BinaryNumber: def init(self, binary_str): self.binary = binary_str

def __index__(self):
    return int(self.binary, 2)

binary = BinaryNumber(‘1101’) # 13 in decimal my_list = [i*10 for i in range(20)] print(my_list[binary]) # Output: 130 print(operator.index(binary)) # Output: 13

This binary number class converts its value to an integer when used as an index. The index method handles the binary-to-decimal conversion.

This pattern is useful for custom numeric types that need to work with Python’s sequence protocols while maintaining their own internal representation.

Using index with NumPy Arrays

NumPy arrays and other scientific Python libraries use index for array indexing, allowing custom index types to work with these libraries.

numpy_index.py

import numpy as np

class ArrayIndex: def init(self, value): self.value = value

def __index__(self):
    return self.value * 2  # Custom index transformation

arr = np.arange(0, 100, 10) # [0, 10, 20, …, 90] idx = ArrayIndex(3) print(arr[idx]) # Output: 60 (uses value 6 as index)

This example shows how a custom index type can be used with NumPy arrays. The index method transforms the index value before array access.

NumPy calls index when processing array indices, enabling custom index transformations while maintaining array access performance.

Best Practices

• Return integers only: index must return an integer

• Keep it lossless: Conversion should preserve all information

• Prefer over int for indexing: Use index in sequence contexts

• Implement for custom sequences: If your class needs integer conversion

• Consider performance: index should be fast for indexing

Source References

• Python index Documentation

• operator.index() Documentation

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.