Django proporciona unas pocas clases que te ayudan a gestionar datos paginados - es decir, datos divididos en varias páginas, con enlaces de «Anterior/Siguiente». Estas clases viven en :source:`django/core/paginator.py.
Para ejemplos, consulta la guía de temas de paginación: Paginación.
Un paginador actúa como una secuencia de Page cuando se utiliza len() o al iterarlo directamente.
Un objeto que admita paginación con un método count() o __len__(). Para la paginación consistente, los conjuntos de consultas deben estar ordenados, por ejemplo, mediante una cláusula order_by() o con un ordenamiento predeterminado ordering en el modelo.
Los problemas de rendimiento al paginar grandes conjuntos de datos QuerySets
Si estás utilizando un conjunto de datos QuerySet con un número muy grande de elementos, solicitar números de página elevados puede ser lento en algunas bases de datos, porque la consulta resultante LIMIT/OFFSET necesita contar los registros de OFFSET que tarda más a medida que el número de página aumenta.
Requerido. El número máximo de elementos a incluir en una página, sin contabilizar huérfanos (consulte la argumento opcional orphans a continuación).
Opcional. Utiliza este cuando no quieras tener una última página con muy pocos elementos. Si la última página normalmente tendría un número de elementos menor o igual a orphans, entonces esos elementos se agregarán a la página anterior (que se convierte en la última) en lugar de dejar los elementos en una página por sí mismos. Por ejemplo, con 23 elementos, per_page=10 y orphans=3, habrá dos páginas; la primera página con 10 elementos y la segunda (y última) página con 13 elementos. orphans tiene un valor predeterminado de cero, lo que significa que las páginas nunca se combinan y la última página puede tener un solo elemento.
Opcional. Si False y object_list está vacío, entonces se levantará una excepción EmptyPage.
El argumento error_messages te permite sobrescribir los mensajes de error predeterminados que el paginador lanzará. Pasa un diccionario con claves que coincidan con los mensajes de error que quieras sobrescribir. Las claves disponibles para los mensajes de error son: invalid_page, min_page y no_results.
Por ejemplo, aquí está el mensaje de error predeterminado:
>>> from django.core.paginator import Paginator
>>> paginator = Paginator([1, 2, 3], 2)
>>> paginator.page(5)
Traceback (most recent call last):
...
EmptyPage: That page contains no results
Y aquí está un mensaje de error personalizado:
>>> paginator = Paginator(
... [1, 2, 3],
... 2,
... error_messages={"no_results": "Page does not exist"},
... )
>>> paginator.page(5)
Traceback (most recent call last):
...
EmptyPage: Page does not exist
Devuelve un objeto Page con el índice 1-basado dado, mientras también maneja números de página fuera del rango e inválidos.
Si la página no es un número, devuelve la primera página. Si el número de página es negativo o mayor que el número de páginas, devuelve la última página.
Lanza una excepción EmptyPage solo si especificas Paginator(..., allow_empty_first_page=False) y el object_list está vacío.
Returns a Página object con el índice dado de 1 en base. Levanta PáginaNoEntera si el number no puede ser convertido a un entero llamando a int(). Levanta PáginaVacia si el número de página dado no existe.
Returns a lista de números de páginas en base 1 similar a Paginator.page_range, pero puede agregar un punto suspensivo a uno o ambos lados del número de página actual cuando Paginator.num_pages es grande.
El número de páginas que incluir en cada lado del número de página actual se determina por el argumento on_each_side que tiene como valor predeterminado 3.
El número de páginas que incluir al principio y al final del rango de páginas se determina por el argumento on_ends que tiene como valor predeterminado 2.
Por ejemplo, con los valores predeterminados para on_each_side y on_ends, si la página actual es 10 y hay 50 páginas, el rango de páginas será [1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]. Esto dará como resultado que las páginas 7, 8 y 9 estén a la izquierda de y las páginas 11, 12 y 13 estén a la derecha de la página actual, así como las páginas 1 y 2 al principio y las páginas 49 y 50 al final.
Levanta PáginaInválida si el número de página dado no existe.
Una cadena translatable utilizada como sustituto para los números de página omitidos en el rango de páginas devuelto por get_elided_page_range(). El valor predeterminado es '…'.
El número total de objetos, a través de todas las páginas.
Nota
Cuando se determina el número de objetos contenidos en object_list, Paginator intentará primero llamar a object_list.count(). Si object_list no tiene un método count(), entonces Paginator caerá hacia atrás a usar len(object_list). Esto permite que los objetos, como QuerySet, utilicen un método count() más eficiente cuando esté disponible.
Page¶Normalmente no construirás objetos Page a mano – los obtendrás al iterar sobre Paginator, o utilizando Paginator.page().
Una página actúa como una secuencia de Page.object_list cuando se utiliza len() o se itera directamente.
Devuelve el número de página siguiente. Levanta InvalidPage si no existe la página siguiente.
Devuelve el número de página anterior. Levanta InvalidPage si no existe la página anterior.
Devuelve el índice 1-basado del primer objeto en la página, relativo a todos los objetos en la lista del paginador. Por ejemplo, cuando se paga una lista de 5 objetos con 2 objetos por página, el método start_index() de la segunda página devolvería 3.
Returns el índice 1-basado del último objeto en la página, relativo a todos los objetos en la lista del paginador. Por ejemplo, cuando se paga una lista de 5 objetos con 2 objetos por página, el segundo end_index() devolvería 4.
La lista de objetos en esta página.
El número de página 1-basado para esta página.
El objeto paginador asociado.
Una clase base para excepciones lanzadas cuando se le pasa un número de página inválido a un paginador.
La Paginator.page() método lanza una excepción si la página solicitada es inválida (es decir, no es un entero) o contiene objetos. Generalmente, basta con atrapar la excepción InvalidPage, pero si deseas más precisión, puedes atrapar cualquiera de las siguientes excepciones:
Lanzado cuando page() se le da un valor válido pero no existen objetos en esa página.
Ambas excepciones son subclases de InvalidPage, por lo que puedes manejarlas ambas con except InvalidPage.
may 31, 2026