Clear inherited CI debt in the Python libs

main was red on file length, the noqa ban, codespell, test naming and
dart coverage; this change touches every one of those jobs.

- sickdays: set_enabled is keyword-only; the panel test splits in two
  with shared probes; the sync wire format moves to DOCS-sync.md.
- earned_time: _focus types the project as a Protocol, no noqa; the
  gate-maturity section moves to DOCS-maturity.md; codespell knows the
  `checkin` event name.
- focus_project: real fixes for every noqa (local-day clocks, typed
  fakes, logged broad catches, split helpers). The public API that
  focus-guard calls keeps its signatures; their PLR0913 exemption
  lives in pyproject with the reason, not in noqa.
- crdt-sync: pylint gets nacl/argon2, docstrings, and allows the
  public E2eLayout.of; _blobs moves to _e2e_blobs.py.
- crdt_sync_dart: Argon2Params and the header errors move to
  e2e_params.dart (re-exported); tests split and reach 100% lines.
- sql_drills: test helpers get a leading underscore, as in earned_time.

Todo: fda71ed1
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-11-16 08:55:10 +01:00
parent f21bfa7a5b
commit c29d0989dd
74 changed files with 1000 additions and 610 deletions

View File

@ -113,6 +113,9 @@ repos:
# dies on Python 3.15 (code objects lost co_lnotab), 2026-11-16.
- --jobs=1
additional_dependencies:
# Kept in step with pyproject.toml, so pylint resolves the e2e imports.
- argon2-cffi==25.1.0
- pynacl==1.6.2
- pytest
- requests

View File

@ -0,0 +1,32 @@
# Copyright (c) 2026 Krzysztof Rudnicki
"""Read every text blob under an old (plaintext) prefix, for the e2e copy."""
from __future__ import annotations
from typing import TYPE_CHECKING
from crdt_sync._sync import default_revs_path
if TYPE_CHECKING:
from crdt_sync._remote import RemoteStore
def blobs(store: RemoteStore, root: str) -> dict[str, str]:
"""Every text blob under ``root`` (flat leaves and ``<dir>/<file>``)."""
skip = {default_revs_path(root), f"{root}/e2e", f"{root}/revs"}
out: dict[str, str] = {}
for name in store.list_directory(root):
full = f"{root}/{name}"
if full in skip:
continue
children = store.list_directory(full)
if not children:
text = store.get_file_text(full)
if text is not None:
out[name] = text
continue
for child in children:
text = store.get_file_text(f"{full}/{child}")
if text is not None:
out[f"{name}/{child}"] = text
return out

View File

@ -12,8 +12,9 @@ from __future__ import annotations
import hmac
from typing import TYPE_CHECKING
from crdt_sync._e2e_blobs import blobs as _blobs
from crdt_sync._e2e_key import derive_key, read_header
from crdt_sync._e2e_store import E2eLayout, E2eLockedError, EncryptingStore, _blobs
from crdt_sync._e2e_store import E2eLayout, E2eLockedError, EncryptingStore
from crdt_sync._log import merge_logs
from crdt_sync._store import dump_log, load_log

View File

@ -97,6 +97,7 @@ class _Header:
@classmethod
def parse(cls, text: str) -> _Header:
"""Read a header from its JSON text; ``E2eHeaderError`` if it is not one."""
try:
data = json.loads(text)
except ValueError as exc:
@ -119,6 +120,7 @@ class _Header:
raise E2eHeaderError(msg) from exc
def encode(self) -> str:
"""The header as the JSON text ``parse`` reads back."""
return json.dumps(
{
"v": _HEADER_VERSION,

View File

@ -12,6 +12,7 @@ from dataclasses import dataclass
import logging
from typing import TYPE_CHECKING
from crdt_sync._e2e_blobs import blobs as _blobs
from crdt_sync._e2e_cache import (
read_cached_key,
read_copy_memo,
@ -126,27 +127,6 @@ class EncryptingStore:
return self._inner.can_access_remote()
def _blobs(store: RemoteStore, root: str) -> dict[str, str]:
"""Every text blob under ``root`` (flat leaves and ``<dir>/<file>``)."""
skip = {default_revs_path(root), f"{root}/e2e", f"{root}/revs"}
out: dict[str, str] = {}
for name in store.list_directory(root):
full = f"{root}/{name}"
if full in skip:
continue
children = store.list_directory(full)
if not children:
text = store.get_file_text(full)
if text is not None:
out[name] = text
continue
for child in children:
text = store.get_file_text(f"{full}/{child}")
if text is not None:
out[f"{name}/{child}"] = text
return out
def copy_to_encrypted(
store: RemoteStore, key: E2eKey, old_prefix: str, layout: E2eLayout
) -> int:

View File

@ -20,7 +20,8 @@ from crdt_sync import (
reset_e2e_copy_memo,
unlock_e2e,
)
from crdt_sync._e2e_store import _blobs, _fingerprint
from crdt_sync._e2e_blobs import blobs as _blobs
from crdt_sync._e2e_store import _fingerprint
from crdt_sync.tests.conftest import FakeStore, FakeStoreWithoutBulkRead
if TYPE_CHECKING:

View File

@ -108,8 +108,9 @@ ignore-patterns = [".*\\.pyi$"]
[tool.pylint.basic]
# snake_case, plus the ``do_<METHOD>`` names http.server dispatches on: the
# stdlib looks handlers up as ``"do_" + command``, so ``do_GET`` is the only
# spelling that works and cannot be renamed to satisfy the style.
method-rgx = "([^\\W\\dA-Z][^\\WA-Z]{2,}|_[^\\WA-Z]*|__[^\\W\\dA-Z][^\\WA-Z]+__|do_[A-Z]+)$"
# spelling that works and cannot be renamed to satisfy the style. ``of`` is
# ``E2eLayout.of``, public API that daily-limits and diet-guard call by name.
method-rgx = "([^\\W\\dA-Z][^\\WA-Z]{2,}|_[^\\WA-Z]*|__[^\\W\\dA-Z][^\\WA-Z]+__|do_[A-Z]+|of)$"
[tool.pylint.messages_control]
enable = "all"

View File

@ -4,44 +4,15 @@ import 'dart:math';
import 'package:cryptography/cryptography.dart';
import 'e2e_cipher.dart';
import 'e2e_params.dart';
import 'encrypting_store.dart';
import 'remote_store.dart';
export 'e2e_params.dart';
const _saltLength = 16;
const _headerVersion = 1;
/// Argon2id cost, stored in the header so it can be raised later.
class Argon2Params {
const Argon2Params({
required this.memoryKiB,
required this.iterations,
required this.parallelism,
});
/// OWASP's floor (19 MiB, t=2); higher stalls the Flutter-web desktop build.
static const recommended = Argon2Params(
memoryKiB: 19456,
iterations: 2,
parallelism: 1,
);
final int memoryKiB;
final int iterations;
final int parallelism;
}
class E2eHeaderError extends FormatException {
E2eHeaderError(super.message);
@override
String toString() => 'E2eHeaderError: $message';
}
class E2eWrongPassphraseError implements Exception {
@override
String toString() => 'E2eWrongPassphraseError: wrong sync passphrase';
}
/// The clear header's path: a sibling of the device dirs, like `revs`.
String defaultE2ePath(String pathPrefix) {
final cut = pathPrefix.lastIndexOf('/');

View File

@ -0,0 +1,34 @@
/// The e2e header's Argon2id cost and the errors unlocking it can raise.
library;
/// Argon2id cost, stored in the header so it can be raised later.
class Argon2Params {
const Argon2Params({
required this.memoryKiB,
required this.iterations,
required this.parallelism,
});
/// OWASP's floor (19 MiB, t=2); higher stalls the Flutter-web desktop build.
static const recommended = Argon2Params(
memoryKiB: 19456,
iterations: 2,
parallelism: 1,
);
final int memoryKiB;
final int iterations;
final int parallelism;
}
class E2eHeaderError extends FormatException {
E2eHeaderError(super.message);
@override
String toString() => 'E2eHeaderError: $message';
}
class E2eWrongPassphraseError implements Exception {
@override
String toString() => 'E2eWrongPassphraseError: wrong sync passphrase';
}

View File

@ -145,6 +145,25 @@ void main() {
throwsA(isA<E2eDecryptError>()),
);
});
test('unknown envelope version asks for an app update', () async {
expect(
() => openLogText('{"v":99,"r":{}}', _cipher(), path: _path),
throwsA(
isA<E2eDecryptError>().having(
(e) => e.toString(),
'message',
contains('format 99'),
),
),
);
});
test('mis-shaped record', () async {
expect(
() =>
openLogText('{"v":1,"r":{"n1":{"p":"x"}}}', _cipher(), path: _path),
throwsA(isA<E2eDecryptError>()),
);
});
});
test('text that is not a log is sealed whole and opens back', () async {

View File

@ -0,0 +1,55 @@
/// Migration over flat `<node>.json` leaves and non-log source blobs.
library;
import 'package:crdt_sync/crdt_sync.dart';
import 'package:test/test.dart';
import 'e2e_fakes.dart';
const _old = 'app/notes';
void main() {
final layout = E2eLayout.of(_old);
Future<E2eKey> key(RemoteStore remote) => unlockE2e(
store: remote,
pathPrefix: layout.prefix,
passphrase: 'pw',
params: cheapArgon,
e2ePath: layout.e2ePath,
);
test('a flat leaf is read one by one when the backend has no bulk', () async {
final inner = MemoryRemote({
'$_old/node.json': encodeLog(logOf({'a': 'milk'})),
});
final remote = PlainRemote(inner);
final report = await copyToEncrypted(
store: remote,
key: await key(remote),
fromPrefix: _old,
layout: layout,
);
expect(report.copied, 1);
final blob = inner.files['${layout.prefix}/node.json']!;
expect(blob, isNot(contains('milk')));
});
test('a source blob that is not a JSON object is skipped', () async {
final remote = MemoryRemote({
'$_old/list/log.json': '[1,2]',
'$_old/shape/log.json': '{"a":5}',
});
final report = await copyToEncrypted(
store: remote,
key: await key(remote),
fromPrefix: _old,
layout: layout,
);
expect(report.copied, 0);
expect(
report.skipped,
unorderedEquals(['list/log.json', 'shape/log.json']),
);
});
}

View File

@ -95,4 +95,18 @@ void main() {
final map = await state.store.getStringMap('app/notes-e2e');
expect(map['k1'], log);
});
test('a cache that reports a bad header locks as badHeader', () async {
final state = await openEncryptedStore(
store: MemoryRemote(),
oldPrefix: _old,
readPassphrase: () async => 'pw',
params: cheapArgon,
keyCache: E2eKeyCache(
read: () async => throw E2eHeaderError('bad header'),
write: (_) async {},
),
);
expect((state as E2eLocked).reason, E2eLockReason.badHeader);
});
}

View File

@ -13,6 +13,9 @@ Future<E2eState> _open(MemoryRemote r, String? pass) => openEncryptedStore(
);
void main() {
// The copy memo is process-wide; a prior open would skip the copy.
setUp(resetE2eCopyMemo);
test('no passphrase is locked', () async {
for (final p in [null, '']) {
final s = await _open(MemoryRemote(), p);

View File

@ -0,0 +1,53 @@
/// EncryptingStore.getStringMap on a data dir that also holds non-log
/// entries and unreadable ones.
library;
import 'package:crdt_sync/crdt_sync.dart';
import 'package:test/test.dart';
import 'e2e_fakes.dart';
const _old = 'settings-sync';
void main() {
final layout = E2eLayout.of(_old);
Future<E2eKey> key(RemoteStore remote) => unlockE2e(
store: remote,
pathPrefix: layout.prefix,
passphrase: 'pw',
params: cheapArgon,
e2ePath: layout.e2ePath,
);
EncryptingStore open(
MemoryRemote remote,
E2eKey k, {
bool acceptPlaintext = true,
}) => EncryptingStore(
remote,
k,
pathPrefix: layout.prefix,
revsPath: layout.revsPath,
e2ePath: layout.e2ePath,
acceptPlaintext: acceptPlaintext,
);
test('the header inside the prefix passes through undecrypted', () async {
final remote = MemoryRemote();
final store = open(remote, await key(remote));
final log = encodeLog(logOf({'a': 'secret'}));
await store.putFileText('${layout.prefix}/node.json', log, message: 'm');
final map = await store.getStringMap(layout.prefix);
expect(map['e2e'], remote.files[layout.e2ePath]);
expect(map['node.json'], log);
});
test('an unreadable entry is dropped from the bulk read', () async {
final remote = MemoryRemote();
final store = open(remote, await key(remote), acceptPlaintext: false);
remote.files['${layout.prefix}/old.json'] = encodeLog(logOf({'a': 'x'}));
final map = await store.getStringMap(layout.prefix);
expect(map.containsKey('old.json'), isFalse);
});
}

View File

@ -0,0 +1,72 @@
/// EncryptingStore forwards what it does not seal to the inner store.
library;
import 'package:crdt_sync/crdt_sync.dart';
import 'package:glados/glados.dart' show Random;
import 'package:test/test.dart';
import 'e2e_fakes.dart';
const _prefix = 'todo-sync/notes';
const _revs = 'todo-sync/revs';
Future<E2eKey> _key(MemoryRemote remote, [String passphrase = 'pw']) =>
unlockE2e(
store: remote,
pathPrefix: _prefix,
passphrase: passphrase,
params: cheapArgon,
random: Random(1),
);
void main() {
test('paths outside the prefix pass through untouched', () async {
final remote = MemoryRemote();
final store = EncryptingStore(
remote,
await _key(remote),
pathPrefix: _prefix,
);
await store.putFileText('other/x', '{"a":1}', message: 'm');
expect(remote.files['other/x'], '{"a":1}');
expect(await store.getFileText('other/x'), '{"a":1}');
expect(await store.getFileText('$_prefix/none/log.json'), isNull);
});
group('delegation', () {
test('bulk reads forward when the inner store has them', () async {
final remote = MemoryRemote({'$_revs/a': 'r'});
final store = EncryptingStore(
remote,
await _key(remote),
pathPrefix: _prefix,
);
expect(await store.getStringMap(_revs), {'a': 'r'});
});
test('bulk reads degrade to "fetch everything" without them', () async {
final remote = MemoryRemote({'$_revs/a': 'r'});
final store = EncryptingStore(
PlainRemote(remote),
await _key(remote),
pathPrefix: _prefix,
);
expect(await store.getStringMap(_revs), isEmpty);
});
test('list, delete, access and close reach the inner store', () async {
final remote = MemoryRemote({'$_prefix/a/log.json': '{}'});
final store = EncryptingStore(
remote,
await _key(remote),
pathPrefix: _prefix,
);
expect(await store.listDirectory(_prefix), ['a']);
await store.deleteFile('$_prefix/a/log.json', message: 'm');
expect(remote.files.containsKey('$_prefix/a/log.json'), isFalse);
expect(await store.canAccessRemote(), isTrue);
store.close();
expect(remote.closed, isTrue);
});
});
}

View File

@ -150,19 +150,6 @@ void main() {
expect(remote.files['wake-alarm/e2e'], contains('argon2id'));
});
test('paths outside the prefix pass through untouched', () async {
final remote = MemoryRemote();
final store = EncryptingStore(
remote,
await _key(remote),
pathPrefix: _prefix,
);
await store.putFileText('other/x', '{"a":1}', message: 'm');
expect(remote.files['other/x'], '{"a":1}');
expect(await store.getFileText('other/x'), '{"a":1}');
expect(await store.getFileText('$_prefix/none/log.json'), isNull);
});
test('a flat <prefix>/<node>.json layout (todo) is sealed too', () async {
final remote = MemoryRemote();
final store = EncryptingStore(
@ -205,43 +192,6 @@ void main() {
expect(await _tick(store, 'phone', {}), isEmpty);
});
group('delegation', () {
test('bulk reads forward when the inner store has them', () async {
final remote = MemoryRemote({'$_revs/a': 'r'});
final store = EncryptingStore(
remote,
await _key(remote),
pathPrefix: _prefix,
);
expect(await store.getStringMap(_revs), {'a': 'r'});
});
test('bulk reads degrade to "fetch everything" without them', () async {
final remote = MemoryRemote({'$_revs/a': 'r'});
final store = EncryptingStore(
PlainRemote(remote),
await _key(remote),
pathPrefix: _prefix,
);
expect(await store.getStringMap(_revs), isEmpty);
});
test('list, delete, access and close reach the inner store', () async {
final remote = MemoryRemote({'$_prefix/a/log.json': '{}'});
final store = EncryptingStore(
remote,
await _key(remote),
pathPrefix: _prefix,
);
expect(await store.listDirectory(_prefix), ['a']);
await store.deleteFile('$_prefix/a/log.json', message: 'm');
expect(remote.files.containsKey('$_prefix/a/log.json'), isFalse);
expect(await store.canAccessRemote(), isTrue);
store.close();
expect(remote.closed, isTrue);
});
});
// Differential: the same sync rounds over a plain and an encrypting relay
// must converge to the same logs.
Glados(

View File

@ -145,3 +145,5 @@ repos:
- id: codespell
args:
- --skip=*.json,*.lock,.git,__pycache__,.venv
# `checkin` is a timer event name on the wire, not a typo.
- --ignore-words-list=checkin

View File

@ -0,0 +1,34 @@
# earned_time: gate maturity (0.6.0)
How far to trust a gate is computed from its ledger, never listed by name:
`maturity(earner, ledger, key_file, today) -> Maturity` (`_maturity.py`).
- **Real credit:** HMAC-verified `credit` row, accepted by the earner's
`match`, not manual (`detail.source` `manual`/`manual_grant`, `entry_id`
`manual:`/`manual_grant:`), and `amount > 0` when the row has one -- a
gate's own re-evaluation grant (`detail.grant_of`, book-guard `bonus:`
rows) may pay 0. A matcher cannot loosen this (`anki_match` alone accepts a
`manual_grant` row).
- **Levels:** `new` = no real credit, or no `Earner.confirmed_on` (set by
kuhy); `mature` = at least `MATURE_MIN_CREDIT_DAYS` (14) distinct credit
days and the first at least `MATURE_MIN_AGE_DAYS` (21) old; else `maturing`.
An unreadable ledger or key is `checked=False`, `new`, reason recorded.
- **Penalty start:** `penalty_start(earner, first_credit)` =
max(`penalty_from`, day after the first real credit, day after
`confirmed_on`). No first credit (never paid out, or could not check) is
not penalised -- unless `confirmed_on` is set: then fail closed,
max(`penalty_from`, day after `confirmed_on`), so deleting or locking a
ledger cannot lift a penalty. Pass `first_credits={name: Maturity.first_credit}`, computed
over `earners_for(day)` (until 0.9.0 two earners shared the name `automation`), to `resolve`
/ `base_for` to apply it; omitted, a penalty starts at `penalty_from`, as
in 0.5.0. It can only delay a penalty, never add one.
- **Ladder floor (0.6.1):** the same start gates the shutdown floor. A rung
comes off the floor only for a pure bonus (no `penalty_from`: workout,
LeetCode) or an earner whose penalty has started, so a gate that never paid
out cannot lower it either (10-10, tutor never credited: 19:50, not 19:00).
An unwired consumer (no `first_credits`) cuts the tutor from `penalty_from`:
19:00 / 3 h.
- **CLI:** `python -m earned_time maturity [--json] [--day YYYY-MM-DD]`
prints one row per ledger-backed earner of every registry. It and
`leisure_from()` alone resolve real paths (`~/<Earner.ledger>`,
`/etc/workout-locker/hmac.key`), and it only reads.

View File

@ -124,38 +124,8 @@ it, and ignore answers for an earner of another day's registry.
## Gate maturity (0.6.0)
How far to trust a gate is computed from its ledger, never listed by name:
`maturity(earner, ledger, key_file, today) -> Maturity` (`_maturity.py`).
- **Real credit:** HMAC-verified `credit` row, accepted by the earner's
`match`, not manual (`detail.source` `manual`/`manual_grant`, `entry_id`
`manual:`/`manual_grant:`), and `amount > 0` when the row has one -- a
gate's own re-evaluation grant (`detail.grant_of`, book-guard `bonus:`
rows) may pay 0. A matcher cannot loosen this (`anki_match` alone accepts a
`manual_grant` row).
- **Levels:** `new` = no real credit, or no `Earner.confirmed_on` (set by
kuhy); `mature` = at least `MATURE_MIN_CREDIT_DAYS` (14) distinct credit
days and the first at least `MATURE_MIN_AGE_DAYS` (21) old; else `maturing`.
An unreadable ledger or key is `checked=False`, `new`, reason recorded.
- **Penalty start:** `penalty_start(earner, first_credit)` =
max(`penalty_from`, day after the first real credit, day after
`confirmed_on`). No first credit (never paid out, or could not check) is
not penalised -- unless `confirmed_on` is set: then fail closed,
max(`penalty_from`, day after `confirmed_on`), so deleting or locking a
ledger cannot lift a penalty. Pass `first_credits={name: Maturity.first_credit}`, computed
over `earners_for(day)` (until 0.9.0 two earners shared the name `automation`), to `resolve`
/ `base_for` to apply it; omitted, a penalty starts at `penalty_from`, as
in 0.5.0. It can only delay a penalty, never add one.
- **Ladder floor (0.6.1):** the same start gates the shutdown floor. A rung
comes off the floor only for a pure bonus (no `penalty_from`: workout,
LeetCode) or an earner whose penalty has started, so a gate that never paid
out cannot lower it either (10-10, tutor never credited: 19:50, not 19:00).
An unwired consumer (no `first_credits`) cuts the tutor from `penalty_from`:
19:00 / 3 h.
- **CLI:** `python -m earned_time maturity [--json] [--day YYYY-MM-DD]`
prints one row per ledger-backed earner of every registry. It and
`leisure_from()` alone resolve real paths (`~/<Earner.ledger>`,
`/etc/workout-locker/hmac.key`), and it only reads.
How far to trust a gate, computed from its ledger by `maturity()`, is in
[DOCS-maturity.md](DOCS-maturity.md).
## API

View File

@ -7,12 +7,15 @@ from dataclasses import dataclass
from datetime import date, timedelta
import importlib
import logging
from typing import Any, Final
from typing import TYPE_CHECKING, Final, Protocol
from earned_time._ladder import shutdown_units_minutes
from earned_time._match import focus_match
from earned_time._policy import Earner
if TYPE_CHECKING:
from collections.abc import Iterable
__all__ = [
"FOCUS_LEDGER",
"FOCUS_WATCH",
@ -27,6 +30,16 @@ _logger: Final = logging.getLogger(__name__)
_warned: set[str] = set()
class _Project(Protocol):
"""What this module reads off a ``focus_project.Project``."""
start: date
daily_minutes: int
#: The gate names the project stands in for.
replaces: Iterable[str]
@dataclass(frozen=True)
class FocusEarner(Earner):
"""Counted; ``gaming_minutes``/``shutdown_minutes`` pay a FULL day.
@ -45,31 +58,34 @@ class FocusEarner(Earner):
def shutdown_for(
self,
units: int,
day: date | None = None, # noqa: ARG002
day: date | None = None,
) -> int:
"""Shutdown minutes of ``units`` focused minutes, floored."""
del day # the base signature takes it; focus pay is the same every day
return self.capped(units) * self.shutdown_minutes // (self.max_units or 1)
def _active(day: date) -> Any: # noqa: ANN401
def _active(day: date) -> _Project | None:
"""The active project on ``day``; ``None`` for none or on any failure."""
try:
return importlib.import_module("focus_project").active(day)
except Exception as exc: # noqa: BLE001 # pylint: disable=broad-exception-caught
except Exception as exc: # pylint: disable=broad-exception-caught
message = f"focus_project unusable ({type(exc).__name__}: {exc})"
if message not in _warned:
_warned.add(message)
_logger.warning("%s; behaving as if no project is active", message)
_logger.warning(
"%s; behaving as if no project is active", message, exc_info=True
)
return None
def daily_on(project: Any, day: date) -> int: # noqa: ANN401
def daily_on(project: _Project, day: date) -> int:
"""``day``'s target: ``project.daily_on(day)`` (a later edit never re-prices it)."""
pick = getattr(project, "daily_on", None)
return int(pick(day) if pick is not None else project.daily_minutes)
def focus_earner(project: Any, dropped: tuple[Earner, ...], day: date) -> Earner: # noqa: ANN401
def focus_earner(project: _Project, dropped: tuple[Earner, ...], day: date) -> Earner:
"""The ``focus`` earner paying what ``dropped`` paid, over ``project``.
Gaming: the cut is every dropped gate's full pay; a full day pays that plus

View File

@ -33,6 +33,8 @@ repos:
- id: debug-statements
- id: name-tests-test
args: [--pytest-test-first]
# Shared test helpers (rows, fixtures) are _private modules, not tests.
exclude: ^focus_project/focus_project/tests/_[a-z_]+\.py$
- id: check-ast
- id: mixed-line-ending
args: [--fix=lf]
@ -147,3 +149,5 @@ repos:
- id: codespell
args:
- --skip=*.json,*.lock,.git,__pycache__,.venv
# `checkin` is a timer event name on the wire, not a typo.
- --ignore-words-list=checkin

View File

@ -93,7 +93,7 @@ def _validate(project: Project) -> None:
raise ValueError(msg)
def create_project( # noqa: PLR0913
def create_project( # pylint: disable=too-many-arguments,too-many-locals
project_id: str,
*,
name: str,
@ -161,20 +161,18 @@ def end_project(project_id: str, day: date) -> Project:
"""
with _store.locked():
existing = _store.read_all()
for i, project in enumerate(existing):
if project.id != project_id:
continue
if project.ended_on is not None:
msg = f"project {project_id!r} already ended on {project.ended_on}"
raise ValueError(msg)
if day < project.start:
msg = f"cannot end {project_id!r} before its start {project.start}"
raise ValueError(msg)
if day < _clock.today():
msg = f"cannot end {project_id!r} in the past ({day})"
raise ValueError(msg)
ended = replace(project, ended_on=min(day, project.end))
existing[i] = ended
_store.write_all(existing)
return ended
raise KeyError(project_id)
i = _store.index_of(existing, project_id)
project = existing[i]
if project.ended_on is not None:
msg = f"project {project_id!r} already ended on {project.ended_on}"
raise ValueError(msg)
if day < project.start:
msg = f"cannot end {project_id!r} before its start {project.start}"
raise ValueError(msg)
if day < _clock.today():
msg = f"cannot end {project_id!r} in the past ({day})"
raise ValueError(msg)
ended = replace(project, ended_on=min(day, project.end))
existing[i] = ended
_store.write_all(existing)
return ended

View File

@ -3,8 +3,12 @@
from __future__ import annotations
from datetime import date
from datetime import UTC, datetime
import time
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from datetime import date
def now() -> float:
@ -14,4 +18,4 @@ def now() -> float:
def today() -> date:
"""The local calendar date right now."""
return date.fromtimestamp(now()) # noqa: DTZ012 (local day by contract)
return datetime.fromtimestamp(now(), tz=UTC).astimezone().date()

View File

@ -5,12 +5,15 @@ from __future__ import annotations
from dataclasses import dataclass
from datetime import date, datetime
from typing import Any
from typing import TYPE_CHECKING, Any
from focus_project._errors import RegistryError
from focus_project._kind import FOCUS, INTERVIEW, interview_minutes
from focus_project._trips import Trip
if TYPE_CHECKING:
from collections.abc import Mapping
GATES = frozenset({"leetcode", "reading", "tutor"})
_ALIASES = {"book": "reading"}
@ -53,7 +56,7 @@ class Limits:
return row
@classmethod
def from_dict(cls, row: Any) -> Limits: # noqa: ANN401
def from_dict(cls, row: Mapping[str, Any]) -> Limits:
"""Parse a history row (errors surface as RegistryError upstream)."""
gates = row.get("replaces")
return cls(
@ -65,7 +68,7 @@ class Limits:
@dataclass(frozen=True)
class Project:
class Project: # pylint: disable=too-many-instance-attributes
"""One time-boxed focus project; at most one is active per day."""
id: str
@ -154,7 +157,7 @@ class Project:
return row
@classmethod
def from_dict(cls, row: Any) -> Project: # noqa: ANN401
def from_dict(cls, row: Mapping[str, Any]) -> Project:
"""Parse a registry row, or raise :class:`RegistryError`."""
try:
ended = row.get("ended_on")

View File

@ -144,7 +144,7 @@ def _clean(
return True # tap, slot_confirm
def record_evidence( # noqa: PLR0913
def record_evidence( # pylint: disable=too-many-arguments
project_id: str,
milestone: str,
kind: str,

View File

@ -28,6 +28,15 @@ def locked() -> Iterator[None]:
yield
def _project_rows(text: str) -> list[object]:
"""The ``projects`` list of a registry file; ValueError/KeyError/TypeError."""
rows = json.loads(text)["projects"]
if not isinstance(rows, list):
msg = "'projects' is not a list"
raise TypeError(msg)
return rows
def read_all() -> list[Project]:
"""Every project; a missing file is empty, a bad one raises."""
try:
@ -35,16 +44,21 @@ def read_all() -> list[Project]:
except FileNotFoundError:
return []
try:
rows = json.loads(text)["projects"]
if not isinstance(rows, list):
msg = "'projects' is not a list"
raise TypeError(msg) # noqa: TRY301
rows = _project_rows(text)
except (ValueError, KeyError, TypeError) as exc:
msg = f"unreadable {projects_path()}: {exc}"
raise RegistryError(msg) from exc
return [Project.from_dict(row) for row in rows]
def index_of(projects: list[Project], project_id: str) -> int:
"""Position of the first project with ``project_id``; KeyError if none."""
for i, project in enumerate(projects):
if project.id == project_id:
return i
raise KeyError(project_id)
def write_all(projects: list[Project]) -> None:
"""Replace the file atomically: temp file in the same dir, fsync, rename."""
target = projects_path()
@ -55,7 +69,7 @@ def write_all(projects: list[Project]) -> None:
handle.write(payload + "\n")
handle.flush()
os.fsync(handle.fileno())
os.replace(tmp, target) # noqa: PTH105
Path(tmp).replace(target)
except BaseException:
Path(tmp).unlink(missing_ok=True)
raise

View File

@ -4,7 +4,7 @@
from __future__ import annotations
from dataclasses import dataclass, replace
from datetime import date, timedelta
from datetime import UTC, date, datetime, timedelta
from typing import Any
from focus_project import _store
@ -113,7 +113,7 @@ def apply_update(
project_id: str,
*,
today: date | None = None,
**changes: Any, # noqa: ANN401
**changes: object,
) -> Update:
"""Edit ``project_id``; ValueError on bad input, overlap or a past edit.
@ -130,32 +130,29 @@ def apply_update(
if unknown:
msg = f"cannot change {unknown}"
raise ValueError(msg)
today = today or date.today() # noqa: DTZ011
today = today or datetime.now(tz=UTC).astimezone().date()
with _store.locked():
existing = _store.read_all()
for i, project in enumerate(existing):
if project.id != project_id:
continue
done = _apply(project, changes, today)
edited = done.project
_validate(edited)
for other in existing:
if other.id != project_id and (
edited.start <= other.last_day and other.start <= edited.last_day
):
msg = f"project overlaps {other.id!r}"
raise ValueError(msg)
existing[i] = edited
_store.write_all(existing)
return done
raise KeyError(project_id)
i = _store.index_of(existing, project_id)
done = _apply(existing[i], changes, today)
edited = done.project
_validate(edited)
for other in existing:
if other.id != project_id and (
edited.start <= other.last_day and other.start <= edited.last_day
):
msg = f"project overlaps {other.id!r}"
raise ValueError(msg)
existing[i] = edited
_store.write_all(existing)
return done
def update_project(
project_id: str,
*,
today: date | None = None,
**changes: Any, # noqa: ANN401
**changes: object,
) -> Project:
""":func:`apply_update` returning just the project."""
return apply_update(project_id, today=today, **changes).project

View File

@ -3,7 +3,7 @@
from __future__ import annotations
from datetime import date
from datetime import UTC, datetime
import fcntl
import json
import os
@ -20,7 +20,7 @@ DEVICES = frozenset({"pc", "phone"})
MAX_SKEW_S = 120.0
def record_activity( # noqa: PLR0913, PLR0917
def record_activity( # pylint: disable=too-many-arguments,too-many-positional-arguments
source: str,
kind: str,
ts: float | None = None,
@ -48,7 +48,7 @@ def record_activity( # noqa: PLR0913, PLR0917
msg = f"ts is {when - now:.0f} s ahead of the clock (max {MAX_SKEW_S:.0f} s)"
raise ValueError(msg)
if project is None:
found = _api.active(date.fromtimestamp(when)) # noqa: DTZ012
found = _api.active(datetime.fromtimestamp(when, tz=UTC).astimezone().date())
project = found.id if found else None
line = json.dumps(
{

View File

@ -18,7 +18,7 @@ import logging
from focus_project import _milestones, _mutate, _store, evidence
from focus_project._model import Project
_LOG = logging.getLogger(__name__)
_logger = logging.getLogger(__name__)
CheckSource = Callable[[Project, datetime], bool | None]
DAY_MS = 24 * 3600 * 1000
# A phone check starts 24 h before the milestone is due.
@ -48,10 +48,12 @@ def phone_source(project: Project, now: datetime) -> bool | None:
"""
report = evidence.last(evidence.read(project.id), "phone", "phone_check")
if report is None:
_LOG.warning("phone check: no tutor report for %s", project.id)
_logger.warning("phone check: no tutor report for %s", project.id)
return None
if not 0 <= evidence.to_ms(now) - report.ms <= DAY_MS:
_LOG.warning("phone check: tutor report for %s is stale or ahead", project.id)
_logger.warning(
"phone check: tutor report for %s is stale or ahead", project.id
)
return None
return _report_ok(report.value, report.ms)
@ -70,8 +72,9 @@ def register_source(name: str, source: CheckSource) -> None:
def _run(project: Project, now: datetime) -> bool | None:
try:
return SOURCES["phone"](project, now)
except Exception as exc: # noqa: BLE001 (pluggable code: any failure = unknown)
_LOG.warning("phone check source failed: %s", exc)
# Pluggable code: any failure means unknown, never a crash.
except Exception as exc: # pylint: disable=broad-exception-caught
_logger.warning("phone check source failed: %s", exc, exc_info=True)
return None

View File

@ -17,7 +17,7 @@ carry row pays it from the day's start, own-work rows pay the rest.
from __future__ import annotations
from datetime import date, timedelta
from datetime import UTC, date, datetime, timedelta
import logging
import sys
@ -64,7 +64,7 @@ def harvest_day(day: date, now: float) -> int:
def harvest(now: float | None = None) -> int:
"""Harvest the backfill window; 0 on success, 1 if any path failed."""
moment = _clock.now() if now is None else now
today = date.fromtimestamp(moment) # noqa: DTZ012 (local day)
today = datetime.fromtimestamp(moment, tz=UTC).astimezone().date()
try:
days = project_days(today)
except (RegistryError, OSError) as exc:

View File

@ -19,7 +19,7 @@ import os
from pathlib import Path
import tempfile
import time
from typing import TYPE_CHECKING, Any, Final
from typing import TYPE_CHECKING, Any, Final, TypeIs
import earned_time
@ -93,6 +93,27 @@ def _write_rows(path: Path, rows: list[Any]) -> None:
Path(handle.name).replace(path)
def _whole_minutes(value: object) -> TypeIs[int]:
"""Whether ``value`` is a positive int minute count (bools excluded)."""
return isinstance(value, int) and not isinstance(value, bool) and value >= 1
def _pays_for(
row: dict[str, Any],
detail: dict[str, Any],
project_id: str,
day: date,
*,
carry: bool | None,
) -> bool:
"""Whether a credit row is for ``project_id`` on ``day`` in class ``carry``."""
return (
row.get("day") == day.isoformat()
and detail.get("project") == project_id
and (carry is None or bool(detail.get("carry")) == carry)
)
def paid_minutes(
rows: list[Any],
key: bytes,
@ -116,12 +137,8 @@ def paid_minutes(
continue
minutes = detail.get("minutes")
if (
row.get("day") != day.isoformat()
or detail.get("project") != project_id
or not isinstance(minutes, int)
or isinstance(minutes, bool)
or minutes < 1
or (carry is not None and bool(detail.get("carry")) != carry)
not _whole_minutes(minutes)
or not _pays_for(row, detail, project_id, day, carry=carry)
or not earned_time.verified(row, key)
):
continue
@ -130,7 +147,7 @@ def paid_minutes(
return sum(by_id.values())
def build_row( # noqa: PLR0913
def build_row( # pylint: disable=too-many-arguments
project_id: str,
day: date,
total: int,
@ -207,7 +224,7 @@ def credit_to(
key,
now=now or time.time(),
carry=carry,
first_carry=paid == 0,
first_carry=not paid,
)
if any(
isinstance(r, dict) and r.get("entry_id") == row["entry_id"] for r in rows

View File

@ -16,14 +16,17 @@ local day up to "now"; carry and the cap play no part. Shown, never paid.
from __future__ import annotations
from datetime import date # noqa: TC003
import logging
from typing import TYPE_CHECKING
from focus_project import _api, _clock, carry, sources
from focus_project._errors import RegistryError
from focus_project._own import union_seconds
from focus_project.sources import activity
if TYPE_CHECKING:
from datetime import date
_LOG = logging.getLogger(__name__)

View File

@ -79,7 +79,7 @@ def _open_site(url: str) -> bool:
return False
try:
# Not a `with`: the browser must outlive this process.
subprocess.Popen(
subprocess.Popen( # pylint: disable=consider-using-with
[opener, url],
stdin=subprocess.DEVNULL,
stdout=subprocess.DEVNULL,

View File

@ -30,7 +30,7 @@ Interval = tuple[float, float]
# Each heartbeat vouches for the five minutes before it.
HEARTBEAT_WINDOW_S = 300.0
ADAPTERS = ("activity", "leetcode", "browser")
_LOG = logging.getLogger(__name__)
_logger = logging.getLogger(__name__)
def heartbeat_interval(ts: float) -> Interval:
@ -61,19 +61,25 @@ def collect_by_source(day: date, project: Project) -> dict[str, list[Interval]]:
found: dict[str, list[Interval]] = {}
for name in ADAPTERS:
module_name = f"{__name__}.{name}"
# A broken adapter must add 0, never stop the others.
try:
module = importlib.import_module(module_name)
except Exception as exc: # noqa: BLE001 (a broken adapter must add 0)
if isinstance(exc, ModuleNotFoundError) and exc.name == module_name:
_LOG.info("source %s: not installed (inactive)", name)
except ModuleNotFoundError as exc:
if exc.name == module_name:
_logger.info("source %s: not installed (inactive)", name)
continue
_LOG.exception("source %s: import failed, contributes 0", name)
_logger.exception("source %s: import failed, contributes 0", name)
found[name] = []
continue
except Exception: # pylint: disable=broad-exception-caught
_logger.exception("source %s: import failed, contributes 0", name)
found[name] = []
continue
# Fail closed: this source adds 0.
try:
found[name] = clip(list(module.intervals(day, project)), bounds)
except Exception: # noqa: BLE001 (fail closed: this source adds 0)
_LOG.exception("source %s: failed, contributes 0", name)
except Exception: # pylint: disable=broad-exception-caught
_logger.exception("source %s: failed, contributes 0", name)
found[name] = []
return found

View File

@ -43,7 +43,7 @@ MAX_GAP_S = 600.0
BACKING_FROM: Final = date(2026, 11, 8)
BACKING_SOURCES: Final = frozenset({"tutor", "sql_drills", "leetcode"})
BRIDGE_S: Final = 1200.0
_LOG = logging.getLogger(__name__)
_logger = logging.getLogger(__name__)
def read_events(project_id: str) -> list[dict[str, Any]]:
@ -67,7 +67,7 @@ def read_events(project_id: str) -> list[dict[str, Any]]:
if ok:
events.append(row)
elif line.strip():
_LOG.debug("activity line skipped: %.80s", line)
_logger.debug("activity line skipped: %.80s", line)
events.sort(key=lambda e: e["ts"])
return events
@ -127,8 +127,9 @@ def backing_times(events: list[dict[str, Any]], project: Project) -> list[float]
# working (heartbeat backing only) where that is not installed.
leetcode = importlib.import_module("focus_project.sources.leetcode")
times += leetcode.submission_times(project)
except Exception: # noqa: BLE001 (lose the submissions, keep the beats)
_LOG.exception("leetcode backing unavailable, heartbeats only")
# Lose the submissions, keep the beats.
except Exception: # pylint: disable=broad-exception-caught
_logger.exception("leetcode backing unavailable, heartbeats only")
return sorted(times)

View File

@ -25,7 +25,7 @@ import json
import logging
import os
from pathlib import Path
from typing import TYPE_CHECKING, Any
from typing import TYPE_CHECKING, Any, cast
from urllib.parse import urlencode
from urllib.request import Request, urlopen
@ -78,10 +78,10 @@ def _config() -> Config | None:
return Config(url.rstrip("/"), values.get("KT_TOKEN", "")) if url else None
def _get_json(cfg: Config, path: str, params: dict[str, str] | None = None) -> Any: # noqa: ANN401
def _get_json(cfg: Config, path: str, params: dict[str, str] | None = None) -> object:
"""One authenticated GET returning parsed JSON."""
url = cfg.url + path + (f"?{urlencode(params)}" if params else "")
request = Request(url) # noqa: S310 (operator-configured http URL)
request = Request(url)
if cfg.token:
request.add_header("Authorization", f"Bearer {cfg.token}")
with _urlopen(request, timeout=TIMEOUT_S) as response:
@ -158,17 +158,14 @@ def intervals(day: date, project: Project) -> list[Interval]:
if cfg is None:
_LOG.info("browser source: no kuhytrack config (inactive)")
return []
lo, hi = day_bounds(day)
stamp = "%Y-%m-%dT%H:%M:%S.000Z"
params = {
"start": datetime.fromtimestamp(lo - LOOKBACK_S, UTC).strftime(stamp),
"end": datetime.fromtimestamp(hi, UTC).strftime(stamp),
}
params = _window(day)
def events(bucket: dict[str, Any]) -> list[dict[str, Any]]:
return list(_get_json(cfg, f"/api/0/buckets/{bucket['id']}/events", params))
path = f"/api/0/buckets/{bucket['id']}/events"
return list(cast("list[dict[str, Any]]", _get_json(cfg, path, params)))
buckets = list(_get_json(cfg, "/api/0/buckets").values())
found = cast("dict[str, dict[str, Any]]", _get_json(cfg, "/api/0/buckets"))
buckets = list(found.values())
present: dict[str, list[Interval]] = {}
for bucket in buckets:
if bucket["type"] == "afkstatus":
@ -179,6 +176,23 @@ def intervals(day: date, project: Project) -> list[Interval]:
if bucket["type"] == "currentwindow":
hits = [e for e in events(bucket) if _matches(e["data"], full, stems)]
on_site.setdefault(bucket["hostname"], []).extend(_spans(hits))
return _present_on_site(on_site, present)
def _window(day: date) -> dict[str, str]:
"""The tracker query range: ``day`` plus :data:`LOOKBACK_S` before it."""
lo, hi = day_bounds(day)
stamp = "%Y-%m-%dT%H:%M:%S.000Z"
return {
"start": datetime.fromtimestamp(lo - LOOKBACK_S, UTC).strftime(stamp),
"end": datetime.fromtimestamp(hi, UTC).strftime(stamp),
}
def _present_on_site(
on_site: dict[str, list[Interval]], present: dict[str, list[Interval]]
) -> list[Interval]:
"""Each host's site time trimmed to its presence (no AFK bucket: present)."""
out: list[Interval] = []
for host, spans in on_site.items():
merged = _merge(spans)

View File

@ -49,8 +49,10 @@ def _submitted_at(row: object, key: bytes) -> float | None:
):
return None
detail = row.get("detail")
if not isinstance(detail, dict):
return None
try:
return float(detail["submitted_at"]) # type: ignore[index]
return float(detail["submitted_at"])
except KeyError, TypeError, ValueError:
return None
@ -67,6 +69,7 @@ def submission_times(project: Project) -> list[float]:
return [ts for ts in stamps if ts is not None]
def intervals(day: date, project: Project) -> list[Interval]: # noqa: ARG001
def intervals(day: date, project: Project) -> list[Interval]:
"""One heartbeat per accepted submission (the registry clips to the day)."""
del day # the adapter signature takes the day; the registry does the clipping
return [heartbeat_interval(ts) for ts in submission_times(project)]

View File

@ -5,7 +5,7 @@ from __future__ import annotations
from datetime import date, datetime, time, timedelta
import json
from typing import TYPE_CHECKING
from typing import TYPE_CHECKING, Any
import focus_project as fp
from focus_project._paths import activity_path
@ -27,7 +27,7 @@ def at(day: int, hour: int = 0, minute: int = 0) -> datetime:
def make(pid: str = "iv", /, **kw: object) -> fp.Project:
"""Create an interview project D1 = Nov 10, T = Nov 27."""
args: dict[str, object] = {
args: dict[str, Any] = {
"name": "Interview",
"start": START,
"end": TEST_DAY,
@ -39,7 +39,7 @@ def make(pid: str = "iv", /, **kw: object) -> fp.Project:
"invite_url": "https://app.codility.com/c/run/abc",
}
args.update(kw)
return fp.create_project(pid, **args) # type: ignore[arg-type]
return fp.create_project(pid, **args)
def shot(tmp_path: Path, name: str = "rules.png") -> Path:

View File

@ -3,12 +3,12 @@
from __future__ import annotations
from datetime import date, datetime
from datetime import UTC, date, datetime
import importlib
import json
from pathlib import Path # noqa: TC003
import threading
import time
from typing import TYPE_CHECKING, Any
import pytest
@ -16,6 +16,9 @@ import focus_project as fp
from focus_project import _clock
from focus_project._paths import data_dir
if TYPE_CHECKING:
from pathlib import Path
D1 = date(2026, 11, 2)
@ -64,7 +67,7 @@ def test_record_activity_defaults_now_and_project(
data: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(_clock, "now", time.time) # the real clock, once
today = date.today() # noqa: DTZ011
today = datetime.now(tz=UTC).astimezone().date()
fp.create_project(
"now",
name="n",
@ -96,9 +99,9 @@ def test_record_activity_no_project_when_none_active(data: Path) -> None:
{"source": "timer", "kind": "start", "dev": "tv"},
],
)
def test_record_activity_validation(kw: dict[str, str], data: Path) -> None:
def test_record_activity_validation(kw: dict[str, Any], data: Path) -> None:
with pytest.raises(ValueError, match="unknown"):
fp.record_activity(**kw) # type: ignore[arg-type]
fp.record_activity(**kw)
assert not (data / "activity.jsonl").exists()
@ -186,4 +189,4 @@ def test_a_timestamp_far_ahead_is_rejected(
def test_the_real_clock_seam_reads_wall_time() -> None:
importlib.reload(_clock) # undo the autouse pin on the module attribute
assert abs(_clock.now() - time.time()) < 5
assert _clock.today() == date.today() # noqa: DTZ011
assert _clock.today() == datetime.now(tz=UTC).astimezone().date()

View File

@ -5,7 +5,7 @@ from __future__ import annotations
from datetime import date, datetime, timedelta
import json
from typing import TYPE_CHECKING
from typing import TYPE_CHECKING, Any
from unittest import mock
import pytest
@ -24,14 +24,14 @@ D4 = date(2026, 11, 5)
def _make(
pid: str = "hr", start: date = D1, end: date = D4, **kw: object
) -> fp.Project:
args: dict[str, object] = {
args: dict[str, Any] = {
"name": "HackerRank prep",
"replaces": ["leetcode", "reading", "tutor"],
"daily_minutes": 120,
"unlock_minutes": 30,
}
args.update(kw)
return fp.create_project(pid, start=start, end=end, **args) # type: ignore[arg-type]
return fp.create_project(pid, start=start, end=end, **args)
def test_empty_registry() -> None:
@ -57,8 +57,10 @@ def test_create_roundtrip_and_file_shape(data: Path) -> None:
def test_active_boundaries() -> None:
_make()
assert fp.active(D1 - timedelta(days=1)) is None
assert fp.active(D1).id == "hr" # type: ignore[union-attr]
assert fp.active(D4).id == "hr" # type: ignore[union-attr]
for day in (D1, D4):
found = fp.active(day)
assert found is not None
assert found.id == "hr"
assert fp.active(D4 + timedelta(days=1)) is None
@ -141,9 +143,9 @@ def test_end_project_errors() -> None:
({"name": " "}, "name"),
],
)
def test_create_validation(kw: dict[str, object], match: str) -> None:
def test_create_validation(kw: dict[str, Any], match: str) -> None:
with pytest.raises(ValueError, match=match):
_make(**kw) # type: ignore[arg-type]
_make(**kw)
assert fp.list_projects() == []
@ -185,7 +187,7 @@ def test_failed_write_keeps_old_file(data: Path) -> None:
_make()
before = (data / "projects.json").read_text()
with (
mock.patch("focus_project._store.os.replace", side_effect=OSError("boom")),
mock.patch("focus_project._store.Path.replace", side_effect=OSError("boom")),
pytest.raises(OSError, match="boom"),
):
_make("two", start=D4 + timedelta(days=3), end=D4 + timedelta(days=4))

View File

@ -5,8 +5,7 @@ from __future__ import annotations
from datetime import date, timedelta
import json
from pathlib import Path # noqa: TC003
from typing import Any
from typing import TYPE_CHECKING, Any
import earned_time
import pytest
@ -15,6 +14,9 @@ import focus_project as fp
from focus_project import carry, harvest, ledger, minutes
from focus_project.tests.test_minutes import D1, at, events, project
if TYPE_CHECKING:
from pathlib import Path
KEY = b"k" * 32
D2 = D1 + timedelta(days=1)
D3 = D2 + timedelta(days=1)

View File

@ -4,13 +4,13 @@
from __future__ import annotations
import json
from typing import TYPE_CHECKING
from typing import TYPE_CHECKING, Any
import pytest
import focus_project as fp
from focus_project import _paths, checks, evidence
from focus_project.tests.helpers import SAT1, at, make
from focus_project.tests._helpers import SAT1, at, make
if TYPE_CHECKING:
from collections.abc import Callable
@ -57,9 +57,9 @@ def test_phone_source_passes_on_a_fresh_good_report() -> None:
"bad",
[{"plan": False}, {"due": 0}, {"seen": at(11, 7)}],
)
def test_phone_source_fails_on_any_bad_part(bad: dict[str, object]) -> None:
def test_phone_source_fails_on_any_bad_part(bad: dict[str, Any]) -> None:
make()
_report(at(13, 8), **bad) # type: ignore[arg-type]
_report(at(13, 8), **bad)
assert _phone(at(13, 9)) is False

View File

@ -10,7 +10,7 @@ import pytest
import focus_project as fp
from focus_project import _paths, evidence
from focus_project.tests.helpers import at, make, shot
from focus_project.tests._helpers import at, make, shot
if TYPE_CHECKING:
from pathlib import Path
@ -50,28 +50,35 @@ def test_same_name_files_do_not_overwrite(tmp_path: Path) -> None:
assert one.value != two.value
_KINDS = "takes evidence kinds"
_SCORE = "a score must be a finite, non-negative number"
_PHONE = "phone_check needs"
@pytest.mark.parametrize(
("milestone", "kind", "value"),
("milestone", "kind", "value", "match"),
[
("rules", "tap", True), # wrong kind for the milestone
("rules", "check", True), # internal kind
("trip_ask:2026-11-14", "answer", True), # use answer_weekend
("nope", "tap", True), # not a milestone of the project
("mock", "score", "high"),
("mock", "score", True),
("mock", "score", float("nan")),
("mock", "score", -1),
("slot", "slot", "tomorrow"),
("slot", "slot", "2026-11-26T10:00:00+02:00"), # aware
("slot", "slot_confirm", False),
("phone", "phone_check", {"plan": True}),
("phone", "phone_check", {"plan": "yes", "due": 1, "seen_ms": 1}),
("phone", "phone_check", "ok"),
("rules", "tap", True, _KINDS), # wrong kind for the milestone
("rules", "check", True, _KINDS), # internal kind
("trip_ask:2026-11-14", "answer", True, _KINDS), # use answer_weekend
("nope", "tap", True, "is not a milestone of"), # not of the project
("mock", "score", "high", _SCORE),
("mock", "score", True, _SCORE),
("mock", "score", float("nan"), _SCORE),
("mock", "score", -1, _SCORE),
("slot", "slot", "tomorrow", "Invalid isoformat string"),
("slot", "slot", "2026-11-26T10:00:00+02:00", "naive local"), # aware
("slot", "slot_confirm", False, "slot_confirm is a tap"),
("phone", "phone_check", {"plan": True}, "due must be a non-negative"),
("phone", "phone_check", {"plan": "yes", "due": 1, "seen_ms": 1}, _PHONE),
("phone", "phone_check", "ok", _PHONE),
],
)
def test_bad_evidence_refused(milestone: str, kind: str, value: object) -> None:
def test_bad_evidence_refused(
milestone: str, kind: str, value: object, match: str
) -> None:
make()
with pytest.raises(ValueError): # noqa: PT011
with pytest.raises(ValueError, match=match):
fp.record_evidence("iv", milestone, kind, value, now=at(12, 9))

View File

@ -4,7 +4,7 @@
from __future__ import annotations
from datetime import date, timedelta
from pathlib import Path # noqa: TC003
from typing import TYPE_CHECKING
import pytest
@ -13,6 +13,9 @@ from focus_project import harvest, ledger
from focus_project.tests.test_ledger_harvest import KEY, rows
from focus_project.tests.test_minutes import D1, at, events
if TYPE_CHECKING:
from pathlib import Path
@pytest.fixture(autouse=True)
def _key(tmp_path: Path) -> None:

View File

@ -12,7 +12,7 @@ import pytest
import focus_project as fp
from focus_project import _interview, _milestones
from focus_project._errors import RegistryError
from focus_project.tests.helpers import SAT1, START, TEST_AT, TEST_DAY, at, make
from focus_project.tests._helpers import SAT1, START, TEST_AT, TEST_DAY, at, make
if TYPE_CHECKING:
from pathlib import Path
@ -80,25 +80,30 @@ def test_interview_roundtrip_and_file_shape(data: Path) -> None:
assert row["invite_url"].startswith("https://")
_URL = "invite_url must be an http"
_TRIP = "must start by the test day"
_WEEKEND = "is not a weekend inside the project"
@pytest.mark.parametrize(
"bad",
("bad", "match"),
[
{"test_at": None},
{"test_at": at(26, 10)}, # end != test day
{"test_at": at(9, 10), "end": date(2026, 11, 9)},
{"invite_url": "ftp://x.example/t"},
{"invite_url": "javascript:alert(1)"},
{"invite_url": "https://a b.example"},
{"kind": "bogus"},
{"trips": [fp.Trip(date(2026, 11, 28), date(2026, 11, 29))]},
{"trips": [fp.Trip(date(2026, 11, 20), date(2026, 11, 19))]},
{"weekend_answers": {date(2026, 11, 15): True}}, # a Sunday
{"weekend_answers": {date(2026, 11, 28): True}}, # after T
{"daily_minutes": 29},
({"test_at": None}, "needs test_at"),
({"test_at": at(26, 10)}, "end must be the test day"), # end != test day
({"test_at": at(9, 10), "end": date(2026, 11, 9)}, "end is before start"),
({"invite_url": "ftp://x.example/t"}, _URL),
({"invite_url": "javascript:alert(1)"}, _URL),
({"invite_url": "https://a b.example"}, _URL),
({"kind": "bogus"}, "kind must be one of"),
({"trips": [fp.Trip(date(2026, 11, 28), date(2026, 11, 29))]}, _TRIP),
({"trips": [fp.Trip(date(2026, 11, 20), date(2026, 11, 19))]}, _TRIP),
({"weekend_answers": {date(2026, 11, 15): True}}, _WEEKEND), # a Sunday
({"weekend_answers": {date(2026, 11, 28): True}}, _WEEKEND), # after T
({"daily_minutes": 29}, "daily_minutes must be at least 30"),
],
)
def test_interview_validation(bad: dict[str, object]) -> None:
with pytest.raises(ValueError): # noqa: PT011
def test_interview_validation(bad: dict[str, object], match: str) -> None:
with pytest.raises(ValueError, match=match):
make(**bad)

View File

@ -6,8 +6,7 @@ from __future__ import annotations
from datetime import date, timedelta
import json
import logging
from pathlib import Path # noqa: TC003
from typing import Any
from typing import TYPE_CHECKING, Any
import earned_time
import pytest
@ -16,6 +15,9 @@ import focus_project as fp
from focus_project import harvest, ledger, minutes
from focus_project.tests.test_minutes import D1, at, events, project
if TYPE_CHECKING:
from pathlib import Path
KEY = b"k" * 32

View File

@ -8,7 +8,7 @@ from typing import TYPE_CHECKING
import focus_project as fp
from focus_project import evidence
from focus_project.tests.helpers import SAT1, SAT2, at, make, session, shot, states
from focus_project.tests._helpers import SAT1, SAT2, at, make, session, shot, states
if TYPE_CHECKING:
from pathlib import Path

View File

@ -4,7 +4,7 @@
from __future__ import annotations
import focus_project as fp
from focus_project.tests.helpers import at, make, session, states
from focus_project.tests._helpers import at, make, session, states
def test_mock_needs_a_score_after_a_long_session() -> None:

View File

@ -9,7 +9,7 @@ import stat
import subprocess
import sys
import time
from typing import TYPE_CHECKING
from typing import TYPE_CHECKING, Any
import pytest
@ -43,6 +43,7 @@ def stubs(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> dict[str, Path]:
def _project(**fields: object) -> None:
extra: dict[str, Any] = dict(fields)
fp.create_project(
"hr",
name="HackerRank prep",
@ -52,7 +53,7 @@ def _project(**fields: object) -> None:
daily_minutes=120,
unlock_minutes=30,
site_patterns=["leetcode.com", "hackerrank.com"],
**fields, # type: ignore[arg-type]
**extra,
)

View File

@ -9,7 +9,7 @@ import pytest
import focus_project as fp
from focus_project import evidence
from focus_project.tests.helpers import SAT1, at, make, states
from focus_project.tests._helpers import SAT1, at, make, states
def _ms(day: int, hour: int) -> int:
@ -69,7 +69,7 @@ def test_trip_may_not_shrink_or_start_later(start: date, end: date) -> None:
)
def test_bad_trip_ranges(start: date, end: date) -> None:
make()
with pytest.raises(ValueError): # noqa: PT011
with pytest.raises(ValueError, match="must start by the test day"):
fp.add_trip("iv", start, end, now=at(10, 9))

View File

@ -53,7 +53,7 @@ def _fake_tracker(
def fake(
_cfg: browser.Config, path: str, params: dict[str, str] | None = None
) -> Any: # noqa: ANN401
) -> object:
calls.append((path, params))
if path == "/api/0/buckets":
return {b["id"]: b for b in buckets}

View File

@ -10,6 +10,7 @@ from focus_project.sources import browser
if TYPE_CHECKING:
from pathlib import Path
from urllib.request import Request
import pytest
@ -42,7 +43,7 @@ def test_config_without_url_is_none(
def test_get_json_sends_bearer_and_query(monkeypatch: pytest.MonkeyPatch) -> None:
seen: dict[str, Any] = {}
def fake_open(req: Any, timeout: float) -> io.BytesIO: # noqa: ANN401
def fake_open(req: Request, timeout: float) -> io.BytesIO:
seen["url"] = req.full_url
seen["auth"] = req.get_header("Authorization")
seen["timeout"] = timeout
@ -62,7 +63,7 @@ def test_get_json_without_token_sends_no_header(
) -> None:
seen: dict[str, Any] = {}
def fake_open(req: Any, timeout: float) -> io.BytesIO: # noqa: ANN401
def fake_open(req: Request, timeout: float) -> io.BytesIO:
seen["auth"] = req.get_header("Authorization")
return io.BytesIO(b"[]")

View File

@ -35,7 +35,7 @@ def _fake(
fn: Callable[[date, Project], list[sources.Interval]],
) -> None:
module = types.ModuleType(f"focus_project.sources.{name}")
module.intervals = fn # type: ignore[attr-defined]
vars(module)["intervals"] = fn
monkeypatch.setitem(sys.modules, f"focus_project.sources.{name}", module)
@ -106,3 +106,17 @@ def test_broken_adapter_import_contributes_zero(
assert all(spans == [] for spans in result.values())
assert set(result) == set(sources.ADAPTERS)
assert "import failed" in caplog.text
def test_adapter_missing_a_dependency_contributes_zero(
monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
def missing_dep(name: str) -> None:
msg = "No module named 'some_dep'"
raise ModuleNotFoundError(msg, name="some_dep")
monkeypatch.setattr("focus_project.sources.importlib.import_module", missing_dep)
with caplog.at_level(logging.ERROR):
result = sources.collect_by_source(DAY, PROJECT)
assert result == {key: [] for key in sources.ADAPTERS}
assert "import failed" in caplog.text

View File

@ -8,7 +8,7 @@ from typing import TYPE_CHECKING
import focus_project as fp
from focus_project import _clock, evidence
from focus_project.tests.helpers import at, make
from focus_project.tests._helpers import at, make
if TYPE_CHECKING:
from pathlib import Path

View File

@ -3,7 +3,7 @@
from __future__ import annotations
from datetime import date, timedelta
from datetime import UTC, date, datetime, timedelta
import json
from typing import TYPE_CHECKING
@ -57,7 +57,7 @@ def test_update_nothing_is_a_noop() -> None:
def test_update_defaults_today_to_real_today() -> None:
now = date.today() # noqa: DTZ011
now = datetime.now(tz=UTC).astimezone().date()
_make("now", start=now, end=now + DAY)
assert fp.update_project("now", name="X").name == "X"

View File

@ -36,6 +36,16 @@ unfixable = []
[tool.ruff.lint.per-file-ignores]
"**/tests/**/*.py" = ["ARG", "D", "PLC0415", "PLR2004", "S101", "SLF001"]
"**/test_*.py" = ["ARG", "D", "PLC0415", "PLR2004", "S101", "SLF001"]
# Public API that focus-guard (and its e2e scripts) call by keyword: these
# signatures mirror Project's fields, so cutting arguments means a breaking
# release across the consumers. The matching pylint disables sit on each def.
"focus_project/_api.py" = ["PLR0913"]
"focus_project/_mutate.py" = ["PLR0913"]
"focus_project/activity.py" = ["PLR0913", "PLR0917"]
"focus_project/ledger.py" = ["PLR0913"]
# The browser source's base URL is operator config (an http:// localhost
# extension bridge), never user input, so urllib's scheme check is moot.
"focus_project/sources/browser.py" = ["S310"]
[tool.ruff.lint.pydocstyle]
convention = "google"

View File

@ -33,6 +33,7 @@ repos:
- id: debug-statements
- id: name-tests-test
args: [--pytest-test-first]
exclude: ^sickdays/sickdays/tests/_[a-z_]+\.py$
- id: check-ast
- id: mixed-line-ending
args: [--fix=lf]

91
sickdays/DOCS-sync.md Normal file
View File

@ -0,0 +1,91 @@
# sickdays: sync and the wire format (for the phone)
Firebase RTDB only, shared credential `~/.config/crdt-sync/` (crdt-sync's
`firebase_client_for("sickdays")`). One directory per device; each device
writes only its own node:
| RTDB node | value |
|---|---|
| `sickdays-sync/devices/<uuid>/sick_days~2Ejson` | a JSON **string** holding the log (below) |
| `sickdays-sync/revs/<uuid>` | hex SHA-256 of that exact string |
The logical path is `sickdays-sync/devices/<uuid>/sick_days.json`. crdt-sync
escapes the `.` in keys as `~2E`. Write the log first, then the rev; a peer
skips any device whose rev it has already merged. The `<uuid>` is a
persisted per-install uuid4, never `pc`/`phone`.
The log is a JSON object keyed by ISO date. Each value is a crdt-sync record:
```json
{
"2026-10-20": {
"id": "2026-10-20",
"fields": {
"state": ["sick", "2026-10-16T08:12:03.517Z-0000-<uuid>"],
"actor": ["<uuid>", "2026-10-16T08:12:03.517Z-0000-<uuid>"],
"keep": [["leetcode", "workout"], "2026-10-16T08:12:03.517Z-0000-<uuid>"]
},
"deleted": false,
"deleted_hlc": null
}
}
```
- `id` equals the key: `YYYY-MM-DD`, local date.
- `state` is `"sick"` or `"cleared"`. Anything else, or a missing record,
means a normal day. `actor` is the uuid of the device that last wrote it.
- Each field is `[value, hlc]`, and every field of one write carries the
**same** HLC. The HLC string is
`YYYY-MM-DDTHH:MM:SS.mmmZ-<counter, 4 hex>-<node uuid>` (UTC wall time). It
orders as the tuple `(wall_ms, counter, node_id)`. A new tick is
`max(now_ms, last_own.wall_ms)`, with the counter bumped when the wall time
did not move.
- **Merge = per-field last-writer-wins**: for each date, keep the field with
the greater HLC. So the latest add *or remove* of a date wins on every
device, and a date can be added and removed any number of times.
- **Remove = write `state: "cleared"`. Never write `deleted: true`.**
crdt-sync OR-merges tombstones, so a deleted date could never be marked
sick again. A tombstoned record reads as "not sick".
#### `keep` (0.2.0)
`keep` is `[<list of locker-id strings>, <hlc>]`. The list is **sorted**
(plain string order) and **de-duplicated**, always: the rev is a SHA-256 of
the exact JSON string, so two devices holding the same set must write the
same bytes. Ids: `workout`, `leetcode`, `book`, `diet`, `alarm`.
Writing:
- **add** (mark sick) writes `state: "sick"`, `actor` and `keep` (default
`[]`), all three with the **same** HLC tick, always. So a stale `keep` from
another device cannot survive a clear and a re-add.
- **remove** writes `state: "cleared"`, `actor` and `keep: []`, same tick.
- **change kept lockers** on an existing sick day **does not touch `state`**:
copy the record, stamp only `keep` and `actor` with one fresh tick, and
leave `state` (and its HLC) as it was. Re-stamping `state` would make a
keep edit re-assert "sick" over a concurrent clear. Only today or later,
only on a day that is currently sick.
- Every new tick is issued after both this device's last tick and the
greatest HLC already on that day's record, so an edit never comes out
older than the `state` it was made against.
Reading (a locker *stands down* iff the day is sick and the locker is not in
the keep set), checked in this order:
1. Day not sick (no record, tombstone, state not `"sick"`, unreadable pool)
-> nothing stands down; `keep` is not looked at.
2. No `keep` field (every 0.1.0 record) -> keep nothing: every locker stands
down.
3. `keep`'s HLC is **older** than `state`'s HLC -> stale (an old 0.1.0
client re-added the day) -> keep nothing. Equal HLCs are not stale.
4. `keep`'s value is not a list, or holds a non-string element -> malformed
-> fail closed: **every** locker is kept (nothing stands down), and a
warning is logged. (A stale malformed value is just stale: rule 3 wins.)
5. Otherwise the kept set is the list, with unknown string ids **ignored**
(forward compatibility), not an error.
Don't hand-roll this on Dart: use `crdt_sync_dart` (`syncLog`, `logToJson`
/ `logFromJson`), exactly as wake-alarm's `free_day_sync.dart` does for
`freedays-sync`. Only the prefix (`sickdays-sync/devices`), the filename
(`sick_days.json`) and the `"sick"` state value differ. There is no
`consumed` or `reason` field. The phone must follow the `keep` rules in [README.md](README.md).

View File

@ -156,95 +156,9 @@ Days are local calendar dates (`_day.today()`), the same as freedays.
## Sync and the wire format (for the phone)
Firebase RTDB only, shared credential `~/.config/crdt-sync/` (crdt-sync's
`firebase_client_for("sickdays")`). One directory per device; each device
writes only its own node:
| RTDB node | value |
|---|---|
| `sickdays-sync/devices/<uuid>/sick_days~2Ejson` | a JSON **string** holding the log (below) |
| `sickdays-sync/revs/<uuid>` | hex SHA-256 of that exact string |
The logical path is `sickdays-sync/devices/<uuid>/sick_days.json`. crdt-sync
escapes the `.` in keys as `~2E`. Write the log first, then the rev; a peer
skips any device whose rev it has already merged. The `<uuid>` is a
persisted per-install uuid4, never `pc`/`phone`.
The log is a JSON object keyed by ISO date. Each value is a crdt-sync record:
```json
{
"2026-10-20": {
"id": "2026-10-20",
"fields": {
"state": ["sick", "2026-10-16T08:12:03.517Z-0000-<uuid>"],
"actor": ["<uuid>", "2026-10-16T08:12:03.517Z-0000-<uuid>"],
"keep": [["leetcode", "workout"], "2026-10-16T08:12:03.517Z-0000-<uuid>"]
},
"deleted": false,
"deleted_hlc": null
}
}
```
- `id` equals the key: `YYYY-MM-DD`, local date.
- `state` is `"sick"` or `"cleared"`. Anything else, or a missing record,
means a normal day. `actor` is the uuid of the device that last wrote it.
- Each field is `[value, hlc]`, and every field of one write carries the
**same** HLC. The HLC string is
`YYYY-MM-DDTHH:MM:SS.mmmZ-<counter, 4 hex>-<node uuid>` (UTC wall time). It
orders as the tuple `(wall_ms, counter, node_id)`. A new tick is
`max(now_ms, last_own.wall_ms)`, with the counter bumped when the wall time
did not move.
- **Merge = per-field last-writer-wins**: for each date, keep the field with
the greater HLC. So the latest add *or remove* of a date wins on every
device, and a date can be added and removed any number of times.
- **Remove = write `state: "cleared"`. Never write `deleted: true`.**
crdt-sync OR-merges tombstones, so a deleted date could never be marked
sick again. A tombstoned record reads as "not sick".
#### `keep` (0.2.0)
`keep` is `[<list of locker-id strings>, <hlc>]`. The list is **sorted**
(plain string order) and **de-duplicated**, always: the rev is a SHA-256 of
the exact JSON string, so two devices holding the same set must write the
same bytes. Ids: `workout`, `leetcode`, `book`, `diet`, `alarm`.
Writing:
- **add** (mark sick) writes `state: "sick"`, `actor` and `keep` (default
`[]`), all three with the **same** HLC tick, always. So a stale `keep` from
another device cannot survive a clear and a re-add.
- **remove** writes `state: "cleared"`, `actor` and `keep: []`, same tick.
- **change kept lockers** on an existing sick day **does not touch `state`**:
copy the record, stamp only `keep` and `actor` with one fresh tick, and
leave `state` (and its HLC) as it was. Re-stamping `state` would make a
keep edit re-assert "sick" over a concurrent clear. Only today or later,
only on a day that is currently sick.
- Every new tick is issued after both this device's last tick and the
greatest HLC already on that day's record, so an edit never comes out
older than the `state` it was made against.
Reading (a locker *stands down* iff the day is sick and the locker is not in
the keep set), checked in this order:
1. Day not sick (no record, tombstone, state not `"sick"`, unreadable pool)
-> nothing stands down; `keep` is not looked at.
2. No `keep` field (every 0.1.0 record) -> keep nothing: every locker stands
down.
3. `keep`'s HLC is **older** than `state`'s HLC -> stale (an old 0.1.0
client re-added the day) -> keep nothing. Equal HLCs are not stale.
4. `keep`'s value is not a list, or holds a non-string element -> malformed
-> fail closed: **every** locker is kept (nothing stands down), and a
warning is logged. (A stale malformed value is just stale: rule 3 wins.)
5. Otherwise the kept set is the list, with unknown string ids **ignored**
(forward compatibility), not an error.
Don't hand-roll this on Dart: use `crdt_sync_dart` (`syncLog`, `logToJson`
/ `logFromJson`), exactly as wake-alarm's `free_day_sync.dart` does for
`freedays-sync`. Only the prefix (`sickdays-sync/devices`), the filename
(`sick_days.json`) and the `"sick"` state value differ. There is no
`consumed` or `reason` field. The phone must follow the `keep` rules above.
Firebase RTDB through crdt-sync, one directory per device. The paths,
record layout and merge rules the phone must match are in
[DOCS-sync.md](DOCS-sync.md).
## Install

View File

@ -96,8 +96,8 @@ class MonthCalendar(tk.Frame):
def _draw_header(self) -> None:
back = IconButton(self._header, "prev", lambda: self.step(-1), name="prev")
forward = IconButton(self._header, "next", lambda: self.step(1), name="next")
back.set_enabled(self.month > self._first)
forward.set_enabled(self.month < self._last)
back.set_enabled(enabled=self.month > self._first)
forward.set_enabled(enabled=self.month < self._last)
back.pack(side="left")
forward.pack(side="right")
ui.label(self._header, _dates.month_title(self.month), "subtitle").pack(

View File

@ -66,7 +66,7 @@ class IconButton(tk.Canvas):
self.bind("<Button-1>", lambda _event: self.invoke())
self._paint()
def set_enabled(self, enabled: bool) -> None: # noqa: FBT001
def set_enabled(self, *, enabled: bool) -> None:
"""Grey the icon out and ignore clicks while disabled."""
self.configure(
state="normal" if enabled else "disabled",
@ -104,7 +104,7 @@ class Toggle(tk.Canvas):
self.bind("<Button-1>", lambda _event: self.invoke())
self.paint()
def set_enabled(self, enabled: bool) -> None: # noqa: FBT001
def set_enabled(self, *, enabled: bool) -> None:
"""Fade the switch and ignore clicks while disabled."""
self.configure(
state="normal" if enabled else "disabled",

View File

@ -166,7 +166,7 @@ class KeepPanel(tk.Frame):
switch = Toggle(self, self._vars[locker], name=f"keep-{locker}")
switch.grid(row=row, column=1, sticky="e", padx=(tok.LG, 0), pady=tok.XS)
if not editable:
switch.set_enabled(False)
switch.set_enabled(enabled=False)
def _draw_actions(
self, *, writable: bool, on_cancel: Callable[[], None] | None

View File

@ -0,0 +1,49 @@
# Copyright (c) 2026 Krzysztof Rudnicki
"""Shared probes for the KeepPanel tests: find its widgets by name."""
from __future__ import annotations
from datetime import timedelta
from typing import TYPE_CHECKING
from sickdays._day import today
from sickdays.gui._controls import IconButton, IconSlot, Toggle
if TYPE_CHECKING:
from sickdays.gui import KeepPanel
#: A day far enough ahead to stay editable for the whole run.
FUTURE = today() + timedelta(days=3)
def find_button(panel: KeepPanel, name: str) -> IconButton:
"""The action button called ``name``."""
widget = panel.nametowidget(f"actions.{name}")
assert isinstance(widget, IconButton)
return widget
def find_toggle(panel: KeepPanel, locker: str) -> Toggle:
"""The keep switch for ``locker``."""
widget = panel.nametowidget(f"keep-{locker}")
assert isinstance(widget, Toggle)
return widget
def status_icon(panel: KeepPanel) -> str | None:
"""The status slot's icon, or None when it is blank."""
slot = panel.nametowidget("status")
assert isinstance(slot, IconSlot)
return slot.icon
def action_names(panel: KeepPanel) -> set[str]:
"""The names of the action buttons shown now."""
actions = panel.nametowidget("actions")
return {child.winfo_name() for child in actions.winfo_children()}
def join_sync(panel: KeepPanel) -> None:
"""Wait for the panel's background sync to finish."""
assert panel.sync_thread is not None
panel.sync_thread.join(timeout=5)

View File

@ -87,3 +87,16 @@ def tk_root() -> Iterator[tk.Tk]:
root.withdraw()
yield root
root.destroy()
@pytest.fixture
def synced(monkeypatch: pytest.MonkeyPatch) -> list[Paths | None]:
"""Record every background sync the panel starts."""
calls: list[Paths | None] = []
def record(*, paths: Paths | None = None) -> bool:
calls.append(paths)
return True
monkeypatch.setattr("sickdays.gui._panel.sync_quietly", record)
return calls

View File

@ -45,12 +45,12 @@ def test_every_locker_has_an_icon() -> None:
def test_a_click_invokes_the_button_unless_disabled(shown: tk.Tk) -> None:
calls: list[int] = []
button = IconButton(shown, "check", lambda: calls.append(1), name="ok")
button.set_enabled(False)
button.set_enabled(enabled=False)
assert str(button.cget("cursor")) == "arrow"
_click(button)
button.invoke()
assert calls == []
button.set_enabled(True)
button.set_enabled(enabled=True)
_click(button)
assert calls == [1]
@ -61,10 +61,10 @@ def test_a_click_flips_the_switch_unless_disabled(shown: tk.Tk) -> None:
_click(switch)
assert switch.is_on()
assert on.get()
switch.set_enabled(False)
switch.set_enabled(enabled=False)
_click(switch)
switch.invoke()
assert switch.is_on()
switch.set_enabled(True)
switch.set_enabled(enabled=True)
switch.invoke()
assert not switch.is_on()

View File

@ -3,85 +3,43 @@
from __future__ import annotations
from datetime import timedelta
import logging
import threading
from typing import TYPE_CHECKING
import pytest
from sickdays._api import add_sick_day, is_sick_day, load
from sickdays._day import to_iso, today
from sickdays._errors import ConflictCheckUnavailableError
from sickdays._api import add_sick_day, is_sick_day
from sickdays._day import to_iso
from sickdays._keep_api import kept_lockers
from sickdays._paths import Paths
from sickdays._store import write_pool
from sickdays.gui import KeepPanel
from sickdays.gui._controls import IconButton, IconSlot, Toggle
from sickdays.gui._controls import IconSlot
from sickdays.tests._panel_probe import (
FUTURE,
action_names,
find_button,
find_toggle,
join_sync,
status_icon,
)
if TYPE_CHECKING:
from pathlib import Path
import tkinter as tk
from sickdays._model import SickDay
FUTURE = today() + timedelta(days=3)
@pytest.fixture
def synced(monkeypatch: pytest.MonkeyPatch) -> list[Paths | None]:
"""Record every background sync the panel starts."""
calls: list[Paths | None] = []
def record(*, paths: Paths | None = None) -> bool:
calls.append(paths)
return True
monkeypatch.setattr("sickdays.gui._panel.sync_quietly", record)
return calls
def _button(panel: KeepPanel, name: str) -> IconButton:
widget = panel.nametowidget(f"actions.{name}")
assert isinstance(widget, IconButton)
return widget
def _toggle(panel: KeepPanel, locker: str) -> Toggle:
widget = panel.nametowidget(f"keep-{locker}")
assert isinstance(widget, Toggle)
return widget
def _status(panel: KeepPanel) -> str | None:
slot = panel.nametowidget("status")
assert isinstance(slot, IconSlot)
return slot.icon
def _actions(panel: KeepPanel) -> set[str]:
actions = panel.nametowidget("actions")
return {child.winfo_name() for child in actions.winfo_children()}
def _join(panel: KeepPanel) -> None:
assert panel.sync_thread is not None
panel.sync_thread.join(timeout=5)
from sickdays._paths import Paths
def test_mark_sick_keeping_leetcode(tk_root: tk.Tk, synced: list[Paths | None]) -> None:
saved: list[SickDay | None] = []
panel = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
assert panel.kept() == frozenset()
assert _actions(panel) == {"mark"}
toggle = _toggle(panel, "leetcode")
assert action_names(panel) == {"mark"}
toggle = find_toggle(panel, "leetcode")
assert not toggle.is_on()
toggle.invoke()
assert toggle.is_on()
assert _button(panel, "mark").icon == "check"
assert _status(panel) is None
_button(panel, "mark").invoke()
_join(panel)
assert find_button(panel, "mark").icon == "check"
assert status_icon(panel) is None
find_button(panel, "mark").invoke()
join_sync(panel)
assert is_sick_day(FUTURE)
assert kept_lockers(FUTURE) == frozenset({"leetcode"})
assert len(saved) == 1
@ -95,12 +53,12 @@ def test_an_existing_sick_day_opens_with_its_switches(tk_root: tk.Tk) -> None:
add_sick_day(FUTURE, keep=["workout"])
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _entry: None)
assert panel.kept() == frozenset({"workout"})
assert _actions(panel) == {"save", "clear"}
assert action_names(panel) == {"save", "clear"}
assert panel.nametowidget("head.title").cget("text") == to_iso(FUTURE)
state = panel.nametowidget("head.state")
assert isinstance(state, IconSlot)
assert state.icon == "sick"
assert _button(panel, "clear").icon == "trash"
assert find_button(panel, "clear").icon == "trash"
icon = panel.nametowidget("icon-workout")
assert isinstance(icon, IconSlot)
assert icon.icon == "workout"
@ -110,10 +68,10 @@ def test_save_replaces_the_kept_set(tk_root: tk.Tk, synced: list[Paths | None])
add_sick_day(FUTURE, keep=["workout"])
saved: list[SickDay | None] = []
panel = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
_toggle(panel, "workout").invoke()
_toggle(panel, "diet").invoke()
_button(panel, "save").invoke()
_join(panel)
find_toggle(panel, "workout").invoke()
find_toggle(panel, "diet").invoke()
find_button(panel, "save").invoke()
join_sync(panel)
assert kept_lockers(FUTURE) == frozenset({"diet"})
assert saved[0] is not None
assert saved[0].keep == frozenset({"diet"})
@ -127,7 +85,7 @@ def test_an_unchanged_save_writes_nothing(
before = (state_dir / "audit.jsonl").read_text(encoding="utf-8")
saved: list[SickDay | None] = []
panel = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
_button(panel, "save").invoke()
find_button(panel, "save").invoke()
assert saved == [None]
assert panel.sync_thread is None
assert synced == []
@ -138,131 +96,9 @@ def test_clear_makes_the_day_normal(tk_root: tk.Tk, synced: list[Paths | None])
add_sick_day(FUTURE, keep=["alarm"])
saved: list[SickDay | None] = []
panel = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
_button(panel, "clear").invoke()
_join(panel)
find_button(panel, "clear").invoke()
join_sync(panel)
assert not is_sick_day(FUTURE)
assert saved[0] is not None
assert not saved[0].is_sick
assert len(synced) == 1
def test_a_past_day_is_shown_but_not_editable(tk_root: tk.Tk) -> None:
panel = KeepPanel(tk_root, today() - timedelta(days=1), on_saved=lambda _e: None)
assert panel.reason == "past"
assert _status(panel) == "padlock"
assert _actions(panel) == set()
diet = _toggle(panel, "diet")
assert str(diet.cget("state")) == "disabled"
diet.invoke()
assert not diet.is_on()
def test_a_free_day_is_refused_with_the_phones_message(
tk_root: tk.Tk, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(
"sickdays.gui._dates.free_day_predicate", lambda: lambda _d: True
)
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _e: None)
assert panel.reason == "free"
assert _status(panel) == "no_entry"
state = panel.nametowidget("head.state")
assert isinstance(state, IconSlot)
assert state.icon == "normal"
assert _actions(panel) == set()
def test_an_uncheckable_free_pool_refuses(
tk_root: tk.Tk, monkeypatch: pytest.MonkeyPatch
) -> None:
def unavailable() -> None:
msg = "cannot check the free-day pool"
raise ConflictCheckUnavailableError(msg)
monkeypatch.setattr("sickdays.gui._dates.free_day_predicate", unavailable)
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _e: None)
assert panel.reason == "unavailable"
assert _status(panel) == "warning"
assert _actions(panel) == set()
def test_a_refused_write_is_shown_not_raised(
tk_root: tk.Tk, synced: list[Paths | None], caplog: pytest.LogCaptureFixture
) -> None:
saved: list[SickDay | None] = []
panel = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
add_sick_day(FUTURE) # marked elsewhere while the panel was open
with caplog.at_level(logging.WARNING):
_button(panel, "mark").invoke()
assert panel.reason == "refused"
assert _status(panel) == "warning"
assert "already a sick day" in caplog.text
assert saved == []
assert synced == []
def test_cancel_calls_back(tk_root: tk.Tk) -> None:
cancelled: list[bool] = []
panel = KeepPanel(
tk_root,
FUTURE,
on_saved=lambda _e: None,
on_cancel=lambda: cancelled.append(True),
)
cancel = _button(panel, "cancel")
assert cancel.icon == "cross"
cancel.invoke()
assert cancelled == [True]
def test_explicit_paths_are_used_for_every_read_write_and_sync(
tk_root: tk.Tk, synced: list[Paths | None], tmp_path: Path
) -> None:
other = Paths.under(tmp_path / "other")
add_sick_day(FUTURE, keep=["book"], paths=other)
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _e: None, paths=other)
assert panel.kept() == frozenset({"book"})
_button(panel, "clear").invoke()
_join(panel)
assert not is_sick_day(FUTURE, log_path=other.log)
assert synced == [other]
assert not (tmp_path / "state" / "sick_days.json").exists()
def test_a_write_during_a_sync_is_refused_not_lost(
tk_root: tk.Tk, monkeypatch: pytest.MonkeyPatch
) -> None:
"""sync() reads the pool, waits on the network, then writes its merged
copy back: a write landing in that window would be silently overwritten.
"""
loaded = threading.Event()
release = threading.Event()
calls: list[int] = []
def slow_sync(*, paths: Paths | None = None) -> bool:
calls.append(1)
if len(calls) > 1 or paths is None:
return False
snapshot = load(paths.log)
loaded.set()
release.wait(timeout=5)
write_pool(paths.log, snapshot)
return True
monkeypatch.setattr("sickdays.gui._panel.sync_quietly", slow_sync)
saved: list[SickDay | None] = []
first = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
_button(first, "mark").invoke()
assert loaded.wait(timeout=5)
later = FUTURE + timedelta(days=1)
second = KeepPanel(tk_root, later, on_saved=saved.append)
_button(second, "mark").invoke()
release.set()
_join(first)
if second.sync_thread is not None:
second.sync_thread.join(timeout=5)
for entry in saved:
assert entry is not None
assert is_sick_day(entry.day), f"{entry.day} was written, then lost"
assert second.reason == "busy"
assert _status(second) == "hourglass"

View File

@ -0,0 +1,155 @@
# Copyright (c) 2026 Krzysztof Rudnicki
"""KeepPanel refusals: past days, free days, failed writes, cancel and paths."""
from __future__ import annotations
from datetime import timedelta
import logging
import threading
from typing import TYPE_CHECKING
from sickdays._api import add_sick_day, is_sick_day, load
from sickdays._day import today
from sickdays._errors import ConflictCheckUnavailableError
from sickdays._paths import Paths
from sickdays._store import write_pool
from sickdays.gui import KeepPanel
from sickdays.gui._controls import IconSlot
from sickdays.tests._panel_probe import (
FUTURE,
action_names,
find_button,
find_toggle,
join_sync,
status_icon,
)
if TYPE_CHECKING:
from pathlib import Path
import tkinter as tk
import pytest
from sickdays._model import SickDay
def test_a_past_day_is_shown_but_not_editable(tk_root: tk.Tk) -> None:
panel = KeepPanel(tk_root, today() - timedelta(days=1), on_saved=lambda _e: None)
assert panel.reason == "past"
assert status_icon(panel) == "padlock"
assert action_names(panel) == set()
diet = find_toggle(panel, "diet")
assert str(diet.cget("state")) == "disabled"
diet.invoke()
assert not diet.is_on()
def test_a_free_day_is_refused_with_the_phones_message(
tk_root: tk.Tk, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setattr(
"sickdays.gui._dates.free_day_predicate", lambda: lambda _d: True
)
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _e: None)
assert panel.reason == "free"
assert status_icon(panel) == "no_entry"
state = panel.nametowidget("head.state")
assert isinstance(state, IconSlot)
assert state.icon == "normal"
assert action_names(panel) == set()
def test_an_uncheckable_free_pool_refuses(
tk_root: tk.Tk, monkeypatch: pytest.MonkeyPatch
) -> None:
def unavailable() -> None:
msg = "cannot check the free-day pool"
raise ConflictCheckUnavailableError(msg)
monkeypatch.setattr("sickdays.gui._dates.free_day_predicate", unavailable)
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _e: None)
assert panel.reason == "unavailable"
assert status_icon(panel) == "warning"
assert action_names(panel) == set()
def test_a_refused_write_is_shown_not_raised(
tk_root: tk.Tk, synced: list[Paths | None], caplog: pytest.LogCaptureFixture
) -> None:
saved: list[SickDay | None] = []
panel = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
add_sick_day(FUTURE) # marked elsewhere while the panel was open
with caplog.at_level(logging.WARNING):
find_button(panel, "mark").invoke()
assert panel.reason == "refused"
assert status_icon(panel) == "warning"
assert "already a sick day" in caplog.text
assert saved == []
assert synced == []
def test_cancel_calls_back(tk_root: tk.Tk) -> None:
cancelled: list[bool] = []
panel = KeepPanel(
tk_root,
FUTURE,
on_saved=lambda _e: None,
on_cancel=lambda: cancelled.append(True),
)
cancel = find_button(panel, "cancel")
assert cancel.icon == "cross"
cancel.invoke()
assert cancelled == [True]
def test_explicit_paths_are_used_for_every_read_write_and_sync(
tk_root: tk.Tk, synced: list[Paths | None], tmp_path: Path
) -> None:
other = Paths.under(tmp_path / "other")
add_sick_day(FUTURE, keep=["book"], paths=other)
panel = KeepPanel(tk_root, FUTURE, on_saved=lambda _e: None, paths=other)
assert panel.kept() == frozenset({"book"})
find_button(panel, "clear").invoke()
join_sync(panel)
assert not is_sick_day(FUTURE, log_path=other.log)
assert synced == [other]
assert not (tmp_path / "state" / "sick_days.json").exists()
def test_a_write_during_a_sync_is_refused_not_lost(
tk_root: tk.Tk, monkeypatch: pytest.MonkeyPatch
) -> None:
"""sync() reads the pool, waits on the network, then writes its merged
copy back: a write landing in that window would be silently overwritten.
"""
loaded = threading.Event()
release = threading.Event()
calls: list[int] = []
def slow_sync(*, paths: Paths | None = None) -> bool:
calls.append(1)
if len(calls) > 1 or paths is None:
return False
snapshot = load(paths.log)
loaded.set()
release.wait(timeout=5)
write_pool(paths.log, snapshot)
return True
monkeypatch.setattr("sickdays.gui._panel.sync_quietly", slow_sync)
saved: list[SickDay | None] = []
first = KeepPanel(tk_root, FUTURE, on_saved=saved.append)
find_button(first, "mark").invoke()
assert loaded.wait(timeout=5)
later = FUTURE + timedelta(days=1)
second = KeepPanel(tk_root, later, on_saved=saved.append)
find_button(second, "mark").invoke()
release.set()
join_sync(first)
if second.sync_thread is not None:
second.sync_thread.join(timeout=5)
for entry in saved:
assert entry is not None
assert is_sick_day(entry.day), f"{entry.day} was written, then lost"
assert second.reason == "busy"
assert status_icon(second) == "hourglass"

View File

@ -33,6 +33,7 @@ repos:
- id: debug-statements
- id: name-tests-test
args: [--pytest-test-first]
exclude: ^sql_drills/sql_drills/tests/_[a-z_]+\.py$
- id: check-ast
- id: mixed-line-ending
args: [--fix=lf]

View File

@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
from sql_drills import _dialect
from sql_drills._sandbox import Executed
from sql_drills.tests import synthetic
from sql_drills.tests import _synthetic as synthetic
if TYPE_CHECKING:
from collections.abc import Callable, Iterator

View File

@ -3,7 +3,7 @@
from __future__ import annotations
from sql_drills import _lc_problem as lp
from sql_drills.tests.synthetic import ORDERS, PIVOT
from sql_drills.tests._synthetic import ORDERS, PIVOT
def test_pivot_example() -> None:

View File

@ -6,8 +6,8 @@ from typing import TYPE_CHECKING
import sql_drills as sd
from sql_drills._sandbox import Executed
from sql_drills.tests.stubs import GOOD_ROWS, MONTHS, done, install
from sql_drills.tests.synthetic import ORDERS, PIVOT
from sql_drills.tests._stubs import GOOD_ROWS, MONTHS, done, install
from sql_drills.tests._synthetic import ORDERS, PIVOT
if TYPE_CHECKING:
import pytest

View File

@ -7,8 +7,8 @@ from typing import TYPE_CHECKING, cast
import pytest
import sql_drills as sd
from sql_drills.tests.stubs import GOOD_ROWS, MONTHS, done, install
from sql_drills.tests.synthetic import PIVOT
from sql_drills.tests._stubs import GOOD_ROWS, MONTHS, done, install
from sql_drills.tests._synthetic import PIVOT
if TYPE_CHECKING:
from sql_drills._dialect import Dialect

View File

@ -12,7 +12,7 @@ import pytest
import sql_drills as sd
from sql_drills import _engine, _pg_engine, _pg_sandbox
from sql_drills.tests.synthetic import ORDERS, ORDERS_SQL, PIVOT, PIVOT_SQL
from sql_drills.tests._synthetic import ORDERS, ORDERS_SQL, PIVOT, PIVOT_SQL
if TYPE_CHECKING:
from collections.abc import Callable