Metadata-Version: 2.1
Name: lektor-limit-dependencies
Version: 1.0.0
Summary: Lektor plugin to limit dependencies created by queries
Author-email: Jeff Dairiki <dairiki@dairiki.org>
License: Copyright © 2020 Geoffrey T. Dairiki
        
        Permission is hereby granted, free of charge, to any person obtaining
        a copy of this software and associated documentation files (the
        "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to
        the following conditions:
        
        The above copyright notice and this permission notice shall be
        included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
        LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
        OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/dairiki/lektor-limit-dependencies
Keywords: Lektor plugin
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Environment :: Web Environment
Classifier: Framework :: Lektor
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Text Processing
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# Lektor Limit Dependencies

[![PyPI version](https://img.shields.io/pypi/v/lektor-limit-dependencies.svg)](https://pypi.org/project/lektor-limit-dependencies/)
[![PyPI Supported Python Versions](https://img.shields.io/pypi/pyversions/lektor-limit-dependencies.svg)](https://pypi.python.org/pypi/lektor-limit-dependencies/)
[![GitHub license](https://img.shields.io/github/license/dairiki/lektor-limit-dependencies)](https://github.com/dairiki/lektor-limit-dependencies/blob/master/LICENSE)
[![GitHub Actions (Tests)](https://github.com/dairiki/lektor-limit-dependencies/workflows/Tests/badge.svg)](https://github.com/dairiki/lektor-limit-dependencies)


This is an experimental [Lektor][] plugin which aims to provide tools (or,
at least, a tool) to help keep Lektor’s dependency tracking under
control.

[lektor]: <https://www.getlektor.com/>


## Introduction

### Motivating Example

Suppose that you would like to list the three most recent blog posts
in the sidebar of your Lektor-based site.  This can be done by adding
something like to your site base template:

```html+jinja
<h3>Recent Posts</h3>
<ul>
  {% for post in site.query('/blog').order_by('-pub_date').limit(3) %}
    <li><a href="{{ post|url }}">{{ post.title }}</a></li>
  {% endfor %}
</ul>
```

This is not without drawbacks, however.  To sort the post query by
date, Lektor iterates through ***all*** of the blog’s posts, then sorts
them.  In so doing, it records all of the blog posts as dependencies
*of every page on which this most-recent-post query is used*.  If this
is in the sidebar of every page on your site, *now every page on your
site will be rebuilt whenever any blog post at all* (not just one of
the three most recent posts) *is edited*.

Technically, it is true that all pages now depend on all posts.  You
might well edit the `pub_date` of one of your older posts, such that
it should now appear in the most-recent listing.  However, it is not
true that all pages need to be rebuilt for *any* edit of any post.
Unfortunately, Lektor’s dependency tracking system is not elaborate
enough to be able to express details about *how* pages are
dependent on other pages; it only records that they *are*
dependent, so Lektor has no option but to rebuild everything.

### A Solution?

This plugin introduces a Jinja filter, `limit_dependencies`.  It
expects, as input, a Lektor [query][] instance.  It iterates through the
input query, and returns a new query instance which will yield the
same results.  While it is doing its iteration, it — essentially —
monkey-patches Lektor’s dependency tracking machinery to prevent it
from recording any dependencies.

At the end, `limit_dependencies` records one dependency on a [virtual
source object][virtual] which depends only on the sequence of the identities
of the records in the query result.  (Lektor provides a means by which
virtual source objects can report checksums.  The
dependency tracking mechanism records those checksums, and will
trigger a rebuild should the checksum change.  `Limit_dependencies`
generates a virtual source object whose checksum depends on the
sequence of identities in the query result.)

In the above example, this is exactly what we want.  We only want to
trigger a rebuild if the order or composition of the most-recent three
posts changes.  (Or if any of their titles change.  Note that this
gets covered, too, since when the resulting query is iterated over in
the `{% for %}` loop, dependencies will be recorded on the three
most-recent posts.)

Thus, the example above, if replaced by:

```html+jinja
<h3>Recent Posts</h3>
<ul>
  {% for post in site.query('/blog').order_by('-pub_date').limit(3)|limit_dependencies %}
    <li><a href="{{ post|url }}">{{ post.title }}</a></li>
  {% endfor %}
</ul>
```

will work in a much more efficient and sane manner.  Pages will be
rebuilt only if there are changes in the order, composition or content
of the three most recent posts.


[virtual]: <https://www.getlektor.com/docs/api/db/obj/#virtual-source-objects>
    "Lektor documentation on Virtual Source Objects"

[query]: <https://www.getlektor.com/docs/api/db/query/>
    "Lektor documentation on the Query class"

## Installation

Add lektor-limit-dependencies to your project from command line:

```
lektor plugins add lektor-limit-dependencies
```

See [the Lektor plugin documentation][plugins] for more information.

[plugins]: <https://www.getlektor.com/docs/plugins/>

## Author

Jeff Dairiki <dairiki@dairiki.org>

## Changelog

### Release 1.0.0 (2023-01-31)

No code changes from 1.0.0b1.

Test under python 3.11.

### Release 1.0.0b1 (2021-03-29)

Drop support for python<3.7 and lektor<3.3.

### Release 0.1 (2021-02-05)

No code changes.

Update development status classifier to "stable".

Test under python 3.9.  Stop testing under 3.5.

### Release 0.1a1 (2020-05-19)

Initial release.
