feat(modtools): Backend foundation for bulk version editing (Part 1/3)

[dcschreiber]

Part 1 of 3: Backend Foundation

Related PRs:

• Part 2: UI Refactoring → feat(modtools): UI refactoring and shared component library (Part 2/3) #2985
• Part 3: BulkVersionEditor Feature → feat(modtools): BulkVersionEditor feature (Part 3/3) #2986

Merge order: PR1 → PR2 → PR3 (all target master, merge in sequence)

!! Don't Merge into Master Until After MDL and Post MDL !!

---

Summary

This PR adds the backend foundation:

• PyMongo 4.x compatibility fixes (update() → update_many())
• Activity feed logging for version metadata changes (new rev_type: edit version_metadata)
• New API endpoints for bulk version operations
• Enhanced Index API error handling
• Minor fixes for export and link helpers

---

New API Endpoints (sefaria/views.py)

Three new endpoints were added to support bulk version editing:

/api/version-indices (GET)

• Returns a list of indices that have versions matching a specific versionTitle
• Used by BulkVersionEditor to show which indices a version appears in
• Example: ?versionTitle=Tanach with Nikkud&language=he → {indices: ["Genesis", "Exodus", ...], metadata: {...}}
• Includes metadata with categories for each index (uses cached library.get_index() for efficiency)

/api/version-bulk-edit (POST)

• Bulk updates Version metadata across multiple indices
• Request: {versionTitle, language, indices: [...], updates: {...}}
• Response: {status: "ok"|"partial"|"error", successes: [...], failures: [{index, error}, ...]}
• Security: Whitelisted fields (VERSION_BULK_EDIT_ALLOWED_FIELDS) prevent arbitrary attribute injection
• Partial success handling: Processes all indices even if some fail, returning detailed success/failure arrays
• Field clearing: null values are treated as "delete this field" - backend uses delattr to remove from MongoDB
• History logging: Uses tracker.update_version_metadata() to log changes to activity feed

/api/check-index-dependencies/<title> (GET) - Disabled in frontend

• Checks dependencies before index title changes
• Used by NodeTitleEditor (currently disabled)
• Returns: dependent indices, version count, link count, has_dependencies flag

---

Activity Feed / History Logging

Added audit logging for version metadata changes. Previously, metadata edits (license, status, priority, etc.) were not tracked anywhere in the system.

New rev_type: edit version_metadata

Changes are now logged to the MongoDB history collection and displayed on the /activity page.

Implementation:

File	Addition
sefaria/model/history.py	log_version_metadata(user, old_dict, new_dict, **kwargs) - Creates history entry with old/new values, title, version, language
sefaria/model/__init__.py	Added log_version_metadata to exports
sefaria/tracker.py	update_version_metadata(user, version, updates, **kwargs) - Centralized function: captures old state → applies updates → saves → logs to history

Endpoints updated to use tracker:

• version_bulk_edit_api (sefaria/views.py) - The new bulk editor
• flag_text_api (reader/views.py) - Flag text feature
• lock_text_api (reader/views.py) - Lock/unlock text feature

Activity Feed Display:

• templates/elements/activity_feed.html - Added template block for version_metadata events
• templates/activity.html - Added "Version Metadata" filter option to dropdown
• sefaria/history.py - Added version_metadata case to filter_type_to_query()

---

Enhanced reader/views.py

Index API Error Handling:
Enhanced the index_post function with categorized error responses:

• Supports both old format ({update: {...}}) and new format (direct index data)
• Dependency pre-checks when renaming indices
• Categorized errors: dependency_error, validation_error, title_validation_error, general_error
• Backward-compatible: Works with both request formats
• Enhanced error display: Changed from semicolon-separated strings to bullet-list format with newlines

Version Metadata Logging:
Updated flag_text_api and lock_text_api to use tracker.update_version_metadata() for history logging.

---

PyMongo 4.x Migration

Updated deprecated MongoDB operations:

• sefaria/model/history.py:210: update() → update_many()
• sefaria/helper/text.py:322: update() → update_many()
• Both maintain identical functionality with updated API

---

Minor Improvements

• sefaria/export.py: Fixed missing user_id parameter in import_versions_from_file()
• sefaria/helper/link.py: Added bytes decoding for CSV uploads (handles both bytes and str)

---

Files Changed

Backend (Python):

• sefaria/views.py - New API endpoints, uses tracker for history logging
• reader/views.py - Enhanced Index API error handling, flag_text_api and lock_text_api now use tracker
• sefaria/urls_shared.py - URL routing for new endpoints
• sefaria/tracker.py - New update_version_metadata() function
• sefaria/model/history.py - PyMongo 4.x migration, new log_version_metadata() function
• sefaria/model/__init__.py - Added log_version_metadata export
• sefaria/history.py - Added version_metadata filter type
• sefaria/helper/text.py - PyMongo 4.x migration
• sefaria/helper/link.py - CSV bytes handling
• sefaria/export.py - user_id parameter fix

Templates:

• templates/elements/activity_feed.html - Added version_metadata display block
• templates/activity.html - Added "Version Metadata" filter option

---

🤖 Generated with Claude Code

---

Next PR

➡️ Part 2 is a draft: #2985 - Remove from draft status when this PR is merged.

[stevekaplan123]

Does this PR do anything on its own? If someone were to use modtools or existing functionality if this were merged into master, would everything work the same? Otherwise, it's a problem because it will mean we have introduced a new bug(s). What we might want to do is to create a fourth branch that each of these merges into and then at the end we merge it all into master.

[dcschreiber]

@stevekaplan123 no other than the improvements we did there, there should be no change to master. So no degradation, but I still made these mergers a chain so we can:

1. Approve one, then two, then three - then merge three into two, two into one, one into master.

[Copilot]

Pull request overview

This PR establishes the backend foundation for bulk version editing capabilities. It introduces PyMongo 4.x compatibility updates, a new activity feed logging system for version metadata changes, and REST API endpoints to support bulk editing operations across multiple text indices.

Changes:

• New API endpoints for querying and bulk-editing version metadata across multiple indices
• Activity feed integration for tracking version metadata changes with new "edit version_metadata" revision type
• PyMongo 4.x migration replacing deprecated update() with update_many()

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
sefaria/views.py	Adds version_indices_api and version_bulk_edit_api endpoints with field whitelisting and partial success handling
sefaria/urls_shared.py	URL routing for new API endpoints
sefaria/tracker.py	New update_version_metadata() function centralizing metadata updates and history logging
sefaria/model/history.py	Adds version_metadata logging support and PyMongo 4.x migration
sefaria/history.py	Adds version_metadata filter type for activity queries
reader/views.py	Refactors flag_text_api and lock_text_api to use tracker.update_version_metadata()
sefaria/helper/text.py	PyMongo 4.x migration in split_text_section()
sefaria/helper/link.py	Bytes/string handling for CSV uploads
sefaria/export.py	Adds user_id parameter to import_versions_from_file()
templates/elements/activity_feed.html	Template block for displaying version_metadata events
templates/activity.html	Filter dropdown option for Version Metadata

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The flag_text_api's update_version function doesn't check if the Version was found before using it. If Version().load() returns None (version doesn't exist), vobj will be None and building the updates dict will still proceed, then calling tracker.update_version_metadata will cause an AttributeError.

Add a check after line 2503:

if not vobj:
    return jsonResponse({"error": "Version not found"})

[stevekaplan123]

Ditto

[dcschreiber]

Fixed, see the other comment

[Copilot]

The lock_text_api doesn't check if the Version was found before calling tracker.update_version_metadata. If Version().load() returns None (version doesn't exist), calling tracker.update_version_metadata(request.user.id, vobj, updates) on line 2481 will cause an AttributeError when trying to access vobj.contents() in the tracker function.

Add a check after line 2474:

if not vobj:
    return jsonResponse({"error": "Version not found"})

[stevekaplan123]

@dcschreiber Do we have validation anywhere that the user must add existing versions? I suspect we already have this validation somewhere in one of the PRs, so that CoPilot's comment here is irrelevant but I just wnat to confirm.

[dcschreiber]

[Claude] No, this validation didn't exist anywhere - Added if not vobj checks to both.

[stevekaplan123]

I agreed with some of CoPilot's comments and left comments of my own.