ENH: add search term for retrieving Entries that are nested under an ancestor

[shilorigins]

Description

Add support for ancestor SearchTerm to FilestoreBackend.search
Add FilestoreBackend._gather_progeny utility method

Closes #102

Motivation and Context

With an Entry in one Nestable, it is impossible to retrieve the corresponding Entry in another Nestable using the existing SearchTerms. The attributes of the known Entry do not reliably correspond to attributes of the desired Entry, other than the .pv_name or .title, so it is necessary to be able to limit searches to Entrys that are nested under a known Nestable.

A concrete use case is comparing snapshots. For each PV in the first snapshot, the corresponding PV must be found in the second snapshot using only the PV string. This becomes possible using the new search term.

The current implementation uses a utility method to gather all Entrys nested under an ancestor Entry. This enables caching the result using functools.cache, which lets us avoid:

1. Traversing the ancestor's DAG for each entry we check
2. Iterating over the search terms in advance in order to gather all progeny before checking the search conditions

Calling cache directly rather than as a decorator limits the caching to each FilestoreBackend.search call, so changes to the data between searches are reflected properly. I believe each cache should be garbage collected after each search, but I haven't been able to verify this yet.

How Has This Been Tested?

A unit test in tests/test_backend and an integration test in tests/test_client.

Where Has This Been Documented?

Pre-merge checklist

• Code works interactively
• Code follows the style guide
• Code contains descriptive docstrings, including context and API
• New/changed functions and methods are covered in the test suite where possible
• Test suite passes locally
• Test suite passes on GitHub Actions
• Ran docs/pre-release-notes.sh and created a pre-release documentation page
• Pre-release docs include context, functional descriptions, and contributors as appropriate

[tangkong]

Looks good to me 👍 I left suggestions for a slightly expanded test and a more permissive type hint, but I think the core of this is hard to disagree with. I imagine this gets refactored a bit with the Visitor concept