Skip to content

entries

entries #

Keyed props — how one is built from a container, and how a component reads it back.

  1. Build. entries_of — the walk behind every of constructor — runs function over a container with pmap (a Map by key, an Array by index) as a progress step named for the component, keeping the results that are there, and records which entry each kept result came from as Entries. An entry whose function fails is left out like an absent one; the walk raises only when every entry fails.
  2. Read. items_of is the one way a component enumerates a keyed prop, whether it was given plainly or built by of: (position, key, item) triples, absent items left out but still counted in the position, so a prop read alongside it lines up; the key is None for a plain list. item_hrefs says where each item links — its entry's page under of, nowhere otherwise — and caption captions it by key.

Entries dataclass #

The container entry each item of a keyed prop came from, in the prop's order.

Entries(target.sessions, (noon, dusk))
Source code in capturegraph-lib/capturegraph/ui/entries.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@dataclass(frozen=True)
class Entries:
    """The container entry each item of a keyed prop came from, in the prop's order.

    ```python
    Entries(target.sessions, (noon, dusk))
    ```
    """

    container: Map | Array
    keys: tuple[object, ...]

    def hrefs(self, render: Render) -> list[str | None]:
        """The relative link to each entry's page, ``None`` where the container has no position."""
        return [render.entry_href(self.container, key) for key in self.keys]

hrefs(render) #

The relative link to each entry's page, None where the container has no position.

Source code in capturegraph-lib/capturegraph/ui/entries.py 
59
60
61
def hrefs(self, render: Render) -> list[str | None]:
    """The relative link to each entry's page, ``None`` where the container has no position."""
    return [render.entry_href(self.container, key) for key in self.keys]

caption(key) #

key as a caption: an instant or a date in ISO form, anything else as text.

Source code in capturegraph-lib/capturegraph/ui/entries.py 
139
140
141
def caption(key: object) -> str:
    """``key`` as a caption: an instant or a date in ISO form, anything else as text."""
    return key.isoformat() if isinstance(key, date) else str(key)

entries_of(container, function, label) #

entries_of(
    container: Map[K, E],
    function: Callable[[E], R | None],
    label: str,
) -> tuple[Map[K, R], Entries]

entries_of(
    container: Array[E],
    function: Callable[[E], R | None],
    label: str,
) -> tuple[list[R], Entries]

function over container, keyed as the container is, with the entries kept.

thumbnails, entries = entries_of(journal.sessions, lambda s: thumbnail(s.photo), "Gallery")
assert entries.keys == (noon, dusk)

Parameters:

Name Type Description Default
container Map[K, E] | Array[E]

The Map or Array to walk.

 required
function Callable[[E], R | None]

The per-element operation.

 required
label str

What the walk's progress step shows, the component's name.

 required
Source code in capturegraph-lib/capturegraph/ui/entries.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def entries_of[K, E, R](
    container: Map[K, E] | Array[E],
    function: Callable[[E], R | None],
    label: str,
) -> tuple[Map[K, R] | list[R], Entries]:
    """``function`` over ``container``, keyed as the container is, with the entries kept.

    ```python
    thumbnails, entries = entries_of(journal.sessions, lambda s: thumbnail(s.photo), "Gallery")
    assert entries.keys == (noon, dusk)
    ```

    Args:
        container: The ``Map`` or ``Array`` to walk.
        function: The per-element operation.
        label: What the walk's progress step shows, the component's name.
    """
    if isinstance(container, Array):
        kept = [
            (index, cast(R, result))
            for index, result in enumerate(container.pmap(function, label))
            if present(result)
        ]
        return [result for _, result in kept], Entries(container, tuple(index for index, _ in kept))
    results = {
        key: cast(R, result)
        for key, result in container.pmap(function, label).to_dict().items()
        if present(result)
    }
    return Map(results), Entries(container, tuple(results))

item_hrefs(render, entries, count) #

Where each of count items links: its entry's page under of, else nowhere.

Source code in capturegraph-lib/capturegraph/ui/entries.py 
128
129
130
131
132
133
134
135
136
def item_hrefs(
    render: Render,
    entries: Entries | None,
    count: int,
) -> list[str | None]:
    """Where each of ``count`` items links: its entry's page under ``of``, else nowhere."""
    if entries is None:
        return [None] * count
    return entries.hrefs(render)

items_of(prop) #

The (position, key, item) triples of a keyed prop, absent items left out.

The position is where the item sits in the prop as given, absent items counted, so a prop read alongside it — a component's labels — still lines up. A list has no keys, so its key is None.

assert items_of([a, b]) == [(0, None, a), (1, None, b)]
assert items_of(target.sessions.photo) == [(0, noon, noon_photo)]  # dusk has no photo
Source code in capturegraph-lib/capturegraph/ui/entries.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def items_of[V](
    prop: Map | Array | list[V] | tuple[V, ...],
) -> list[tuple[int, object | None, V]]:
    """The ``(position, key, item)`` triples of a keyed prop, absent items left out.

    The position is where the item sits in the prop as given, absent items
    counted, so a prop read alongside it — a component's ``labels`` — still
    lines up. A list has no keys, so its key is ``None``.

    ```python
    assert items_of([a, b]) == [(0, None, a), (1, None, b)]
    assert items_of(target.sessions.photo) == [(0, noon, noon_photo)]  # dusk has no photo
    ```
    """
    pairs: Iterable[tuple[object | None, V]] = (
        prop.to_dict().items() if isinstance(prop, Map) else ((None, item) for item in prop)
    )
    return [(position, key, item) for position, (key, item) in enumerate(pairs) if present(item)]

present(value) #

Whether value is a value at all, rather than None or a Missing.

assert present(session.photo)
assert not present(cg.Missing)
Source code in capturegraph-lib/capturegraph/ui/entries.py 
36
37
38
39
40
41
42
43
44
def present[V](value: V | None) -> TypeIs[V]:
    """Whether ``value`` is a value at all, rather than ``None`` or a ``Missing``.

    ```python
    assert present(session.photo)
    assert not present(cg.Missing)
    ```
    """
    return not is_missing(value)