Metadata-Version: 2.1
Name: pyramid_listing
Version: 0.2.2
Summary: Pyramid List Pagination contains helpers for pagination of result lists.
Home-page: https://github.com/holgi/pyramid_listing
License: Beerware
Keywords: pyramid list pagination resource
Author: Holger Frey
Author-email: mail@holgerfrey.de
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: Freely Distributable
Classifier: Framework :: Pyramid
Requires-Dist: SQLAlchemy
Requires-Dist: black ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: flake8-comprehensions ; extra == "dev"
Requires-Dist: isort ; extra == "dev"
Requires-Dist: keyring ; extra == "dev"
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: Sphinx ; extra == "dev"
Requires-Dist: pytest >=4.0.0 ; extra == "test"
Requires-Dist: pytest-cov ; extra == "test"
Requires-Dist: pytest-mock ; extra == "test"
Requires-Dist: tox ; extra == "test"
Provides-Extra: dev
Provides-Extra: test

===============
Pyramid Listing
===============

Pyramid Listing contains pyramid resources and helpers for pagination
of result lists.

A lot of pyramid_ applications that use a (SQL) database need to list the result
of queries. This result list might get quite long and are split into several
pages. This package is offering some help in this.


Quickstart
----------

Lets assume, that you'd like to start a cheese shop and define a simple
database model in the pyramid application::

    from .meta import Base

    class Cheese(Base):
        id = Column(Integer, primary_key=True)
        name = Column(Text, nullable=False)

To get a result list including pagination, just create a sub-class from
``pyramid_listing.SQLAlchemyListing`` and define a ``get_base_query``
method::

    from pyramid_listing import SQLAlchemyListing

    class CheeseList(SQLAlchemyListing):

        def get_base_query(self, request)
            return request.dbsession.query(Cheese)

In a view you could then use this class to autmagically get paged results::

    @view_config(route_name='cheeses')
    def cheese_list_view(request):
        listing = CheeseList(request)
        return {'cheeses': listing.items(), 'pagination': listing.pages}

With this URLs you could access different result pages:

    shows page 3:

    https://example.com/cheeses?p=3

    shows page 1 with 42 items per page:

    https://example.com/cheeses?p=1&n=42


Features
--------

* automatically calculate pagination information like first, next or last page
  from `pyradmid.request.GET` parameters
* loading configuration defaults from .ini files
* easily implement ordering and filtering of results
* helper method for creating `pyradmid.request.GET` parameters for different
  pages
* base class for listings as location aware pyramid resources


Example Project
---------------

To see this in action install the sample project from
https://github.com/holgi/pyramid_listing_example
and take a look at it

.. _pyramid: https://trypyramid.com

