Skip to content

History API

The history module manages browsing session history.

Overview

Astronomo maintains an in-memory history of visited pages during a session. Each history entry stores:

  • The page URL
  • The page content
  • Scroll position
  • Selected link index
  • Response metadata

History is not persisted between sessions.

API Reference

history

History management for browsing navigation.

This module provides history tracking for the Gemini browser, enabling back/forward navigation with cached content to avoid re-fetching pages.

HistoryEntry dataclass 

HistoryEntry(
    url: str,
    content: list[GemtextLine],
    scroll_position: float = 0,
    link_index: int = 0,
    timestamp: datetime = datetime.now(),
    status: int = 20,
    meta: str = "",
    mime_type: str = "text/gemini",
)

Represents a single entry in the browsing history.

Attributes:

Name Type Description
url str

The URL of the page
content list[GemtextLine]

Parsed Gemtext content as list of GemtextLine objects
scroll_position float

Vertical scroll position in the viewer
link_index int

Currently selected link index
timestamp datetime

When the page was visited
status int

Gemini response status code
meta str

Response metadata string
mime_type str

Content MIME type

HistoryManager 

HistoryManager(max_size: int = 100)

Manages browsing history with back/forward navigation.

Implements standard browser history behavior: - Each navigation creates a new entry - Navigating back/forward moves through the history stack - New navigation from a non-head position clears forward history - Maximum size enforced with LRU eviction (oldest entries removed first)

Parameters:

Name Type Description Default
max_size int

Maximum number of history entries to keep (default: 100)

 100

Initialize history manager with specified maximum size.

Source code in src/astronomo/history.py 
53
54
55
56
def __init__(self, max_size: int = 100):
    """Initialize history manager with specified maximum size."""
    self._history: deque[HistoryEntry] = deque(maxlen=max_size)
    self._current_index: int = -1  # -1 means no history

__len__ 

__len__() -> int

Return the number of entries in history.

Source code in src/astronomo/history.py 
131
132
133
def __len__(self) -> int:
    """Return the number of entries in history."""
    return len(self._history)

can_go_back 

can_go_back() -> bool

Check if back navigation is possible.

Returns:

Type Description
bool

True if there are entries before the current position
Source code in src/astronomo/history.py 
78
79
80
81
82
83
84
def can_go_back(self) -> bool:
    """Check if back navigation is possible.

    Returns:
        True if there are entries before the current position
    """
    return self._current_index > 0

can_go_forward 

can_go_forward() -> bool

Check if forward navigation is possible.

Returns:

Type Description
bool

True if there are entries after the current position
Source code in src/astronomo/history.py 
86
87
88
89
90
91
92
def can_go_forward(self) -> bool:
    """Check if forward navigation is possible.

    Returns:
        True if there are entries after the current position
    """
    return self._current_index >= 0 and self._current_index < len(self._history) - 1

clear 

clear() -> None

Clear all history.

Source code in src/astronomo/history.py 
126
127
128
129
def clear(self) -> None:
    """Clear all history."""
    self._history.clear()
    self._current_index = -1

current 

current() -> Optional[HistoryEntry]

Get current history entry.

Returns:

Type Description
Optional[HistoryEntry]

The current HistoryEntry, or None if history is empty
Source code in src/astronomo/history.py 
116
117
118
119
120
121
122
123
124
def current(self) -> Optional[HistoryEntry]:
    """Get current history entry.

    Returns:
        The current HistoryEntry, or None if history is empty
    """
    if self._current_index >= 0 and self._current_index < len(self._history):
        return self._history[self._current_index]
    return None

get_all_entries 

get_all_entries() -> list[HistoryEntry]

Return all history entries as a list.

Returns:

Type Description
list[HistoryEntry]

List of all HistoryEntry objects, oldest first
Source code in src/astronomo/history.py 
135
136
137
138
139
140
141
def get_all_entries(self) -> list[HistoryEntry]:
    """Return all history entries as a list.

    Returns:
        List of all HistoryEntry objects, oldest first
    """
    return list(self._history)

go_back 

go_back() -> Optional[HistoryEntry]

Navigate back and return the entry.

Returns:

Type Description
Optional[HistoryEntry]

The previous HistoryEntry, or None if already at the start
Source code in src/astronomo/history.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
def go_back(self) -> Optional[HistoryEntry]:
    """Navigate back and return the entry.

    Returns:
        The previous HistoryEntry, or None if already at the start
    """
    if not self.can_go_back():
        return None
    self._current_index -= 1
    return self._history[self._current_index]

go_forward 

go_forward() -> Optional[HistoryEntry]

Navigate forward and return the entry.

Returns:

Type Description
Optional[HistoryEntry]

The next HistoryEntry, or None if already at the end
Source code in src/astronomo/history.py 
105
106
107
108
109
110
111
112
113
114
def go_forward(self) -> Optional[HistoryEntry]:
    """Navigate forward and return the entry.

    Returns:
        The next HistoryEntry, or None if already at the end
    """
    if not self.can_go_forward():
        return None
    self._current_index += 1
    return self._history[self._current_index]

push 

push(entry: HistoryEntry) -> None

Add new entry to history, clearing forward history if not at head.

When adding a new entry while not at the head of history (i.e., after navigating back), all forward history entries are removed. This matches standard browser behavior.

Parameters:

Name Type Description Default
entry HistoryEntry

The HistoryEntry to add

 required
Source code in src/astronomo/history.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def push(self, entry: HistoryEntry) -> None:
    """Add new entry to history, clearing forward history if not at head.

    When adding a new entry while not at the head of history (i.e., after
    navigating back), all forward history entries are removed. This matches
    standard browser behavior.

    Args:
        entry: The HistoryEntry to add
    """
    # If we're not at the head of history, remove everything after current position
    if self._current_index >= 0 and self._current_index < len(self._history) - 1:
        # Clear forward history
        while len(self._history) > self._current_index + 1:
            self._history.pop()

    # Add new entry
    self._history.append(entry)
    self._current_index = len(self._history) - 1

Example Usage

from astronomo.history import HistoryManager, HistoryEntry

# Create a history manager with max 100 entries
history = HistoryManager(max_size=100)

# Add an entry
entry = HistoryEntry(
    url="gemini://example.com/",
    content="# Example Page",
    scroll_position=0,
    link_index=0,
)
history.push(entry)

# Navigate back
if history.can_go_back():
    previous = history.go_back()

# Navigate forward
if history.can_go_forward():
    next_entry = history.go_forward()