Files
Django_TasksApp/main/home_assistant/task_sync.py
T
2026-10-23 14:30:58 +02:00

358 lines
19 KiB
Python

"""Optional synchronization for simple, top-level TasksNest planner tasks."""
import hashlib
import json
from datetime import date
from django.db import transaction
from django.db.models import Q
from django.utils import timezone
from planner.models import Task
from .client import ConnectionError, add_item, decrypt_token, get_items, update_item
from .models import HomeAssistantConnection, HomeAssistantItemMap
from .sync import _record_run, _schedule_after_failure, _schedule_after_success
FEATURE_CREATE = 1
FEATURE_UPDATE = 4
FEATURE_DUE_DATE = 16
FEATURE_DESCRIPTION = 64
def _due_date(value):
if not value:
return ''
try:
return date.fromisoformat(value[:10]).isoformat()
except (TypeError, ValueError):
raise ConnectionError('Home Assistant returned an invalid task due date.') from None
def _local_state(task):
return {
'name': task.title,
'status': 'completed' if task.is_completed else 'needs_action',
'description': task.description,
'due': task.scheduled_for.isoformat(),
}
def _remote_state(item):
return {
'name': item['name'],
'status': item['status'],
'description': item.get('description', ''),
'due': _due_date(item.get('due')),
}
def _hash(state):
raw = json.dumps(state, ensure_ascii=False, sort_keys=True, separators=(',', ':'))
return hashlib.sha256(raw.encode()).hexdigest()
def _snapshot(connection):
if not connection.task_entity_id:
raise ConnectionError('Choose a Home Assistant task list first.')
token = decrypt_token(connection.encrypted_token)
remote = get_items(connection.base_url, token, connection.task_entity_id)
tasks = list(Task.objects.filter(owner=connection.user))
eligible = {str(task.pk): task for task in tasks
if task.parent_task_id is None and task.is_active and not task.is_recurring}
maps = list(HomeAssistantItemMap.objects.filter(connection=connection,
entity_id=connection.task_entity_id).select_related('task'))
return token, tasks, eligible, remote, maps
def build_task_plan(connection, tasks, eligible, remote, maps):
operations, issues, recoveries = [], [], []
features = next((int(e.get('features') or 0) for e in connection.entities
if e.get('id') == connection.task_entity_id), 0)
can_create = bool(features & FEATURE_CREATE)
can_update = bool(features & FEATURE_UPDATE)
can_due = bool(features & FEATURE_DUE_DATE)
can_description = bool(features & FEATURE_DESCRIPTION)
mapped_local = {str(link.task_id) for link in maps if link.task_id}
mapped_remote = {link.ha_uid for link in maps if link.ha_uid}
for task in tasks:
if task.parent_task_id is not None:
issues.append(f'“{task.title}” is a subtask and is not synced as a separate item.')
elif not task.is_active:
issues.append(f'“{task.title}” is inactive and is not synced.')
elif task.is_recurring:
issues.append(f'“{task.title}” recurs; recurring tasks are not synced as single list items.')
for link in sorted(maps, key=lambda row: row.pk):
task = eligible.get(str(link.task_id)) if link.task_id else None
ha = remote.get(link.ha_uid) if link.ha_uid else None
if link.pending_create:
if not task:
issues.append('An unfinished Home Assistant task addition lost its TasksNest task; review it manually.')
continue
candidates = [row for uid, row in remote.items()
if uid not in mapped_remote and row['name'].casefold() == task.title.casefold()]
if len(candidates) == 1:
operations.append({'kind': 'task_reconcile', 'local_id': str(task.pk),
'uid': candidates[0]['uid'], 'label': task.title})
else:
issues.append(f'Addition of “{task.title}” is uncertain; review Home Assistant before retrying.')
if not candidates:
recoveries.append({'mapping_id': link.pk, 'label': task.title})
continue
if not task or not ha:
issues.append(f'Mapped task {link.ha_uid or "unknown"} is missing on one side; no deletion will occur.')
continue
local_state, remote_state = _local_state(task), _remote_state(ha)
local_hash, remote_hash = _hash(local_state), _hash(remote_state)
if local_hash == remote_hash:
if link.last_local_hash != local_hash or link.last_remote_hash != remote_hash:
operations.append({'kind': 'task_baseline', 'local_id': str(task.pk),
'uid': link.ha_uid, 'label': task.title})
continue
local_changed, remote_changed = local_hash != link.last_local_hash, remote_hash != link.last_remote_hash
if connection.direction == 'from_ha':
winner = 'ha'
elif connection.direction == 'to_ha':
winner = 'tasksnest'
elif local_changed and remote_changed:
winner = connection.conflict_winner
elif remote_changed:
winner = 'ha'
elif local_changed:
winner = 'tasksnest'
else:
issues.append(f'“{task.title}” has inconsistent sync history; no change was made.')
continue
if winner == 'ha' and connection.direction != 'to_ha':
if not remote_state['due'] and local_state['due']:
issues.append(f'“{task.title}” has no Home Assistant due date; TasksNest requires a scheduled date, so it was left unchanged.')
elif remote_state['due'] and not can_due and remote_state['due'] != local_state['due']:
issues.append(f'“{task.title}” has a due date this Home Assistant list cannot edit; review it manually.')
elif remote_state['description'] and not can_description and remote_state['description'] != local_state['description']:
issues.append(f'“{task.title}” has a description this Home Assistant list cannot edit; review it manually.')
else:
operations.append({'kind': 'task_pull', 'local_id': str(task.pk), 'uid': link.ha_uid,
'label': ha['name']})
elif winner == 'tasksnest' and connection.direction != 'from_ha':
unsupported = ((local_state['due'] != remote_state['due'] and not can_due)
or (local_state['description'] != remote_state['description'] and not can_description))
if not can_update:
issues.append(f'“{task.title}” cannot be updated: this Home Assistant list is read-only.')
elif unsupported:
issues.append(f'“{task.title}” has fields this Home Assistant list cannot update; no fields were changed.')
else:
operations.append({'kind': 'task_push', 'local_id': str(task.pk), 'uid': link.ha_uid,
'label': task.title})
unmatched = [task for key, task in eligible.items() if key not in mapped_local]
unmatched_remote = [row for uid, row in remote.items() if uid not in mapped_remote]
local_names = {task.title.casefold() for task in eligible.values()}
remote_names = {row['name'].casefold() for row in remote.values()}
collisions = ({task.title.casefold() for task in unmatched} & remote_names) | (
{row['name'].casefold() for row in unmatched_remote} & local_names)
for title in sorted(collisions):
issues.append(f'“{title}” exists on both lists without a UID mapping; review duplicates before syncing it.')
if connection.direction in {'both', 'to_ha'}:
for task in sorted(unmatched, key=lambda row: str(row.pk)):
state = _local_state(task)
if len(task.title) > 180:
issues.append(f'“{task.title[:80]}…” is longer than Home Assistant supports and was not exported.')
continue
unsupported = (not can_create or (task.is_completed and not can_update)
or (state['due'] and not can_due)
or (state['description'] and not can_description))
if task.title.casefold() in collisions:
continue
if unsupported:
issues.append(f'“{task.title}” needs create, update, due-date, and description support on the selected list.')
else:
operations.append({'kind': 'task_export', 'local_id': str(task.pk), 'label': task.title})
if connection.direction in {'both', 'from_ha'}:
for uid, item in sorted(remote.items()):
if uid in mapped_remote or item['name'].casefold() in collisions:
continue
state = _remote_state(item)
if not state['due']:
issues.append(f'“{item["name"]}” has no due date; TasksNest requires a scheduled date, so it was not imported.')
continue
if (state['due'] and not can_due) or (state['description'] and not can_description):
issues.append(f'“{item["name"]}” has fields this list cannot preserve in TasksNest; it was not imported.')
continue
operations.append({'kind': 'task_import', 'uid': uid, 'label': item['name']})
snapshot = {
'connection': connection.pk, 'entity': connection.task_entity_id,
'direction': connection.direction, 'winner': connection.conflict_winner, 'features': features,
'local': sorted((key, _hash(_local_state(task))) for key, task in eligible.items()),
'remote': sorted((uid, _hash(_remote_state(item))) for uid, item in remote.items()),
'maps': sorted((row.pk, str(row.task_id), row.ha_uid, row.last_local_hash,
row.last_remote_hash, row.pending_create) for row in maps),
}
digest = hashlib.sha256(json.dumps(snapshot, sort_keys=True).encode()).hexdigest()
return {'operations': operations, 'issues': issues, 'pending_recoveries': recoveries,
'digest': digest, 'limited': len(operations) > 20}
def preview_tasks(connection):
_, tasks, eligible, remote, maps = _snapshot(connection)
return build_task_plan(connection, tasks, eligible, remote, maps)
def _task_map(connection, task, uid='', *, pending=False, local_hash='', remote_hash=''):
return HomeAssistantItemMap.objects.create(connection=connection, entity_id=connection.task_entity_id,
task=task, ha_uid=uid, pending_create=pending, last_local_hash=local_hash,
last_remote_hash=remote_hash)
def _apply_task(connection, token, action, eligible, remote, features):
kind, uid = action['kind'], action.get('uid', '')
task = eligible.get(action.get('local_id'))
ha = remote.get(uid)
link = HomeAssistantItemMap.objects.filter(connection=connection,
entity_id=connection.task_entity_id, task=task).first() if task else None
if kind == 'task_import':
if not ha:
raise ConnectionError('The Home Assistant list changed. Preview again.')
state = _remote_state(ha)
with transaction.atomic():
task = Task.objects.create(owner=connection.user, title=state['name'],
description=state['description'], scheduled_for=date.fromisoformat(state['due']) if state['due'] else timezone.localdate(),
is_completed=state['status'] == 'completed')
_task_map(connection, task, uid, local_hash=_hash(state), remote_hash=_hash(state))
return
if not task:
raise ConnectionError('A TasksNest task changed. Preview again.')
state = _local_state(task)
if kind == 'task_export':
link = _task_map(connection, task, pending=True)
add_item(connection.base_url, token, connection.task_entity_id, task.title,
due_date=state['due'] if features & FEATURE_DUE_DATE else None,
description=state['description'] if features & FEATURE_DESCRIPTION else None)
latest = get_items(connection.base_url, token, connection.task_entity_id)
candidates = [row for candidate_uid, row in latest.items()
if candidate_uid not in remote and row['name'] == task.title]
if len(candidates) != 1:
raise ConnectionError(f'Added “{task.title}”, but its new UID could not be identified. Review the list before retrying.')
item = candidates[0]
uid = item['uid']
link.ha_uid, link.pending_create = uid, False
link.last_local_hash = link.last_remote_hash = _hash(_remote_state(item))
link.save()
if state['status'] == 'completed':
update_item(connection.base_url, token, connection.task_entity_id, uid, status='completed')
item = get_items(connection.base_url, token, connection.task_entity_id).get(uid)
if not item or item['status'] != 'completed':
raise ConnectionError(f'“{task.title}” was added but its completed state was not confirmed.')
remote_state = _remote_state(item)
link.last_local_hash = _hash(state)
link.last_remote_hash = _hash(remote_state)
link.save(update_fields=['last_local_hash', 'last_remote_hash', 'updated_at'])
return
if not link or not ha:
raise ConnectionError('A mapped task changed. Preview again.')
if kind == 'task_reconcile':
item = remote.get(uid)
if not item:
raise ConnectionError('The Home Assistant list changed. Preview again.')
remote_state = _remote_state(item)
link.ha_uid, link.pending_create = uid, False
link.last_local_hash = link.last_remote_hash = _hash(remote_state)
link.save()
elif kind == 'task_baseline':
task.refresh_from_db()
local_state, remote_state = _local_state(task), _remote_state(ha)
link.last_local_hash, link.last_remote_hash = _hash(local_state), _hash(remote_state)
link.save(update_fields=['last_local_hash', 'last_remote_hash', 'updated_at'])
elif kind == 'task_pull':
remote_state = _remote_state(ha)
if not remote_state['due']:
raise ConnectionError('Home Assistant removed a due date TasksNest requires. Review the task before syncing again.')
task.title = remote_state['name']
task.is_completed = remote_state['status'] == 'completed'
task.description = remote_state['description']
fields = ['title', 'is_completed', 'description', 'updated_at']
if remote_state['due']:
task.scheduled_for = date.fromisoformat(remote_state['due'])
fields.append('scheduled_for')
task.save(update_fields=fields)
link.last_local_hash = link.last_remote_hash = _hash(remote_state)
link.save(update_fields=['last_local_hash', 'last_remote_hash', 'updated_at'])
elif kind == 'task_push':
remote_state = _remote_state(ha)
update_item(connection.base_url, token, connection.task_entity_id, uid,
name=state['name'] if state['name'] != remote_state['name'] else None,
status=state['status'] if state['status'] != remote_state['status'] else None,
due_date=state['due'] if state['due'] != remote_state['due'] else None,
description=state['description'] if state['description'] != remote_state['description'] else None)
item = get_items(connection.base_url, token, connection.task_entity_id).get(uid)
if not item or _hash(_remote_state(item)) != _hash(state):
raise ConnectionError(f'Home Assistant did not confirm the update to “{task.title}”.')
link.last_local_hash = link.last_remote_hash = _hash(state)
link.save(update_fields=['last_local_hash', 'last_remote_hash', 'updated_at'])
def confirm_task_sync(connection, expected_digest, *, automatic=False):
from datetime import timedelta
from django.db import transaction
now = timezone.now()
claimed = HomeAssistantConnection.objects.filter(pk=connection.pk).filter(
Q(sync_lock_until__isnull=True) | Q(sync_lock_until__lt=now)).update(
sync_lock_until=now + timedelta(minutes=3))
if not claimed:
raise ConnectionError('A sync is already running. Try again shortly.')
try:
connection.refresh_from_db()
token, tasks, eligible, remote, maps = _snapshot(connection)
plan = build_task_plan(connection, tasks, eligible, remote, maps)
if plan['digest'] != expected_digest:
raise ConnectionError('The lists changed after the preview. Review a fresh preview before syncing.')
connection.task_initial_sync_confirmed = True
connection.save(update_fields=['task_initial_sync_confirmed', 'updated_at'])
done = 0
features = next((int(e.get('features') or 0) for e in connection.entities
if e.get('id') == connection.task_entity_id), 0)
for action in plan['operations'][:20]:
_apply_task(connection, token, action, eligible, remote, features)
done += 1
token, tasks, eligible, remote, maps = _snapshot(connection)
_schedule_after_success(connection, timezone.now())
connection.save(update_fields=['last_synced_at', 'last_sync_error', 'next_sync_at',
'consecutive_sync_failures', 'updated_at'])
_record_run(connection, succeeded=True, automatic=automatic, changes=done,
summary=f'Task sync applied {done} change(s); {len(plan["issues"])} item(s) need review.')
return done, plan
except ConnectionError as exc:
_schedule_after_failure(connection, exc, automatic)
raise
finally:
HomeAssistantConnection.objects.filter(pk=connection.pk).update(sync_lock_until=None)
def reset_task_pending(connection, expected_digest, mapping_id):
from datetime import timedelta
now = timezone.now()
claimed = HomeAssistantConnection.objects.filter(pk=connection.pk).filter(
Q(sync_lock_until__isnull=True) | Q(sync_lock_until__lt=now)).update(
sync_lock_until=now + timedelta(minutes=3))
if not claimed:
raise ConnectionError('A sync is already running. Try again shortly.')
try:
connection.refresh_from_db()
_, tasks, eligible, remote, maps = _snapshot(connection)
plan = build_task_plan(connection, tasks, eligible, remote, maps)
if plan['digest'] != expected_digest:
raise ConnectionError('The lists changed after the preview. Review a fresh preview.')
mapping = HomeAssistantItemMap.objects.filter(pk=mapping_id, connection=connection,
entity_id=connection.task_entity_id, pending_create=True).select_related('task').first()
if not mapping or not mapping.task_id:
raise ConnectionError('This pending task addition can no longer be reset.')
if any(row['name'].casefold() == mapping.task.title.casefold() for row in remote.values()):
raise ConnectionError('A matching item is now visible in Home Assistant. Preview again to reconcile it.')
title = mapping.task.title
mapping.delete()
_record_run(connection, succeeded=True, automatic=False,
summary=f'Reset uncertain task addition for “{title}”.')
finally:
HomeAssistantConnection.objects.filter(pk=connection.pk).update(sync_lock_until=None)