Fix semantics of Record equality

[dairiki]

These are bits extracted from the stale draft PR #1007.

It changes/fixes the equality semantics for Records and VirtualSourceObjects so that they compare equal only if all of the following match:

• __class__
• path (which includes page_num in the case of Pages)
• alt
• pad

Previously only __class__ and _path were compared, thus records with differing page_num, alt, or pad were comparing as equal.

In general, a record is obtained by calling pad.get(path, alt, page_num) and a "different" record obtains if any of pad, path, alt, or page_num is changed.

Other Changes

All SourceObjects should now implement iter_source_filenames

In general, the data comprising a SourceObject can come from multiple source files.
This happens for Pages when alts are in use. It happens for attachments even when alts are not being used: an Attachment depends on both the attachment file and its corresponding metadata .lr file.

I suspect that we should deprecate the SourceObject.source_filename property altogether. The primary use of source_filename or iter_source_filenames is for dependency tracking — in that case, we always want to track all (potential) source files. In cases where a source object has multiple source files, 'm not sure the concept of a "primary" source file makes sense.

New class: DBSourceObject

This PR introduces a DBSourceObject class. It is a subclass of SourceObject and serves as a superclass of all the object types that can be returned from Pad.get.
(The fixed equality comparison is implemented for DBSourceObject.)

The new class hierarchy (for classes in the Lektor source which derive from SourceObject) is

classDiagram
    SourceObject <|-- DBSourceObject
   DBSourceObject <|-- Record
   Record <|-- Page
   Record <|-- Attachment
   Attachment <|-- Image
   Attachment <|-- Video
   DBSourceObject <|-- VirtualSourceObject
   VirtualSourceObject <|-- Siblings
    SourceObject <|-- Asset
    Asset <|-- Directory
    Asset <|-- File

Issue(s) Resolved

Fixes #1101

Related Issues / Links

Description of Changes

• Wrote at least one-line docstrings (for any new functions)
• Added unit test(s) covering the changes (if testable)

[relikd]

Can you elaborate more on the reason why the Pad has to be the same for equality? I am not sure but for me it just does not feel right. Path, page_num, and alt are properties that describe a specific page / end-point. Whereas Pad is the data structure that generates the page. I think I understand the reason behind the thinking (in a build process you want to know if you have seen the same object before), but I could imagine scenarios where you want to compare accross multiple builders to know if you are targeting the same page.

[dairiki]

Can you elaborate more on the reason why the Pad has to be the same for equality? I am not sure but for me it just does not feel right. Path, page_num, and alt are properties that describe a specific page / end-point. Whereas Pad is the data structure that generates the page. I think I understand the reason behind the thinking (in a build process you want to know if you have seen the same object before), but I could imagine scenarios where you want to compare accross multiple builders to know if you are targeting the same page.

Here's my thinking:

Equality is a question of identity. Records from different pads are not the same and can not be used interchangeably. Pad is a attribute of Record, after all. If record1.pad != record2.pad, it would be confusing if len({record1, record2}) == 1.
(That is not to say that there might not be use cases where one wants to check only that the path and alt match — but in those cases, one should make the check explicit. E.g. if (r1.path, r1.alt) == (r2.path, r2.alt): ....)

I could sort of see fudging this, if there were a common use-case that if facilitated — but even if one relaxes things so that record-equality doesn't depend on the pad, it should certainly depend on the db. Records from different databases are clearly not the same.
So relaxing the requirements that the pad be the same to instead require that pad.db be the same doesn't really save any complexity.

Adjusting the semantics of equality to mean that two objects are "the same for some but not all purposes" seems likely to produce surprises. Especially in this case where we define a __hash__ (which makes a claim to Python that the records are immutable.)

(If one does want to work across multiple pads, a useful abstraction would probably be to implement a replace(record, pad) function that returns a (possibly) new record bound to pad rather than whatever other pad it originally came from. Then one could check if replace(record2, pad=record1.pad) == record1: ....)