All jobs

Add Pagination to an aiohttp App

Yes. An agent pages a list view in your aiohttp app with a page query parameter, a bounded SQLAlchemy query, previous and next links and tests, then opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent starts from the view that lists everything. In the polls demo under demos/polls of aio-libs/aiohttp-demos, aiohttpdemo_polls/views.py has an index view that opens a session from request.app[db_key], runs select(db.Question) with no order and no limit, and hands questions.all() to templates/index.html, which loops over the list and prints one link per question. db.py defines Question with id, question_text and pub_date on SQLAlchemy's DeclarativeBase, and pg_context builds an async_sessionmaker over an asyncpg engine from the postgres block of config/polls.yaml. routes.py registers / without a name, while poll, results and vote are named, so the index template has nothing to build a link to itself from. requirements-dev.txt pins aiohttp==3.13.5, aiohttp-jinja2==1.6, asyncpg==0.32.0 and SQLalchemy==2.0.54, and pytest.ini sets asyncio_mode = auto and filterwarnings = error, so any deprecation warning the change provokes fails the suite.

The query changes first. The agent adds a page_size key to utils.py's TRAFARET and to both config/polls.yaml and config/polls_test.yaml, because settings.get_config validates the file against that schema and refuses unknown or missing keys. index reads page from request.query, turns a missing value into the first page, and raises web.HTTPBadRequest for anything that is not a positive integer; middlewares.py has no override for 400, so the plain text answer goes out as is. The select gains order_by(db.Question.pub_date.desc(), db.Question.id.desc()), since offset paging over an unordered table can repeat or skip rows between pages, plus offset and limit from the page number. A second statement, select(func.count()).select_from(db.Question), gives the total, from which the view computes the last page; a page past it raises web.HTTPNotFound, which the existing error middleware renders with 404.html.

The template gets what it needs to navigate. The agent names the index route (app.router.add_get("/", index, name="index")) so aiohttp_jinja2's url() helper can build url('index'), and index.html appends ?page= for a previous link when the page is above one and a next link when it is below the last, with a page x of y line between them. The No polls are available. branch stays for an empty table. Nothing else in the demo reads the question list, so detail.html and results.html are untouched.

Tests follow tests/test_integration.py, which needs a running Postgres: conftest.py creates the database with init_db.setup_db and the tables_and_data fixture inserts one question and three choices through init_db.sample_data. The agent adds a fixture that inserts more questions than one page holds, using the same async_sessionmaker pattern, and tests that the first page lists exactly page_size of them in date order, that the second page lists the rest with a previous link and no next link, that ?page=0 and ?page=abc answer 400, and that a page past the end answers 404 with the demo's 404 template. It runs make flake in demos/polls and pytest demos/polls as the root Makefile does, against a Postgres it starts in its sandbox the way the root .github/workflows/ci.yml test job does with its postgres service.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add pagination to the question list of this aiohttp app. Read aiohttpdemo_polls/views.py, routes.py, db.py, settings.py, utils.py, templates/index.html, config/polls.yaml, config/polls_test.yaml, init_db.py, tests/conftest.py, tests/test_integration.py, requirements-dev.txt and pytest.ini first. Add a page_size key to the config schema and both YAML files. In the index view read page from the query string, reject non-positive or non-integer values with 400, order the select by pub_date and id descending, apply offset and limit, count the total with a second select, and answer 404 past the last page. Name the index route and add previous and next links to index.html with url('index'). Write pytest tests for the first page, the last page, a bad page value and a page past the end, inserting enough questions through the existing async session pattern. Run flake8 and pytest against a local Postgres, then open a pull request that quotes the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes aiohttpdemo_polls/views.py (the ordered, bounded query and the two error cases), routes.py (the named index route), utils.py (the page_size key in the trafaret), config/polls.yaml, config/polls_test.yaml, templates/index.html and tests/test_integration.py, and adds the fixture that fills more than one page. Its description quotes the pytest output and the lines make flake printed, and shows the first and second page as curl output from the sandbox so a reviewer can see the links without starting Postgres.

A reviewer checks three things: that the order key is stable (two questions published on the same day are separated by id), that the count query and the page query run in the same session so a question inserted between them cannot push the last page off by one in a way the template does not handle, and that page_size has a sensible value in polls.yaml for the real app rather than the small one the tests use.

The vote flow, the per-question pages and the static route are untouched. A request to / with no query string renders the same first page as before, now with a next link when there is more.

Run it on every new list view

A list view that works on a demo table turns into a slow page once the table grows, so the useful moment is when a new one lands. An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize runs read-only with a prompt that looks for a select(...) in a view that neither limits nor orders its result, and comments on the pull request naming the view and the template. The event the trigger adds after the prompt names the pull request; nothing is filled into the prompt itself.

When the comment is right, a handler on your own server sends this body to POST /o/{org}/sessions with the view's name added to the end of the prompt and the pull request's branch in resources as https://github.com/your-org/your-app/tree/<branch>, with a request_id that is a UUID v5 of the pull request's head SHA so a repeated delivery returns the run it already started. The key that starts it gets run.completed at its webhook_url with the new pull request's URL.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The tests here need a Postgres with a database the suite creates and drops, which is why conftest.py calls setup_db and teardown_db with an admin connection. On a laptop that means a container or a local server and a matching polls_test.yaml; in the sandbox the agent starts one, runs the suite against it, and the exact commands and their output stay in the run's record beside the pull request.

The same change is due in every list view that was written against a small table, in this app and in the next one. One run per repository reads that app's own session and template conventions and opens one pull request each, so a team with several aiohttp services gets the same ordering and error behaviour in all of them without one person doing the rounds.

Frequently asked questions

Why offset paging rather than a cursor?

The list is small, server-rendered and navigated with previous and next links, which is what offset paging is for. A keyset cursor on (pub_date, id) is the right change if the table grows large or the list becomes an API; the ordered query the agent writes is the same one a cursor would need, so the move later is small.

Why does it change the config schema?

The demo validates its YAML with a trafaret in utils.py and get_config refuses keys the schema does not list. Putting page_size there means the test config can use a small page while the real one uses a larger value, and a missing key fails at startup rather than at the first request.

What happens past the last page?

The view raises web.HTTPNotFound, and the error middleware in middlewares.py already renders 404.html for that status. A bad value such as ?page=0 is a 400 with a plain text body, since nothing in the app renders that status.

Will the tests run in GitHub Actions?

Yes. The repository's ci.yml already starts a postgres service with the password init_db.py expects and runs the polls suite through the root Makefile, so the new tests run there with no workflow change.

Does it touch the vote or results pages?

No. Only the index view, its route name and its template change. The per-question views keep using db.get_question, and vote still redirects to the named results route.

More aiohttp jobs

The same job on other stacks

Keep reading