taskli-cli 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
taskli/migrations.py ADDED
@@ -0,0 +1,165 @@
1
+ """Versioned migrations for on-disk list and config files."""
2
+
3
+ import copy
4
+ from collections.abc import Callable
5
+ from typing import Any
6
+
7
+ # the historical label strings below ("done", "todo", "high", ...) are a
8
+ # frozen contract: each migration step captures a past on-disk shape, so
9
+ # the literals are hard-coded here rather than imported from
10
+ # models/attributes.py -- a later enum-label rename must not retroactively
11
+ # change what an old migration means.
12
+
13
+ CURRENT_LIST_VERSION = 1
14
+ CURRENT_CONFIG_VERSION = 1
15
+
16
+
17
+ def file_version(raw: dict[str, Any]) -> int:
18
+ """Return the schema version recorded in a parsed file dict.
19
+
20
+ Parameters
21
+ ----------
22
+ raw : dict[str, Any]
23
+ The parsed JSON contents of a list or config file.
24
+
25
+ Returns
26
+ -------
27
+ int
28
+ The recorded ``version``, or 0 when the key is absent, ``null``,
29
+ or not an integer.
30
+ """
31
+
32
+ version = raw.get("version")
33
+ if isinstance(version, bool) or not isinstance(version, int):
34
+ return 0
35
+
36
+ return version
37
+
38
+
39
+ def _list_base_to_v1(raw: dict[str, Any]) -> dict[str, Any]:
40
+ """Bring a pre-versioned list dict up to the current v1 item shape.
41
+
42
+ v1 was introduced in #101 and redefined by #92 (recursive subtasks)
43
+ before any real data reached it, so this single step also stringifies
44
+ each ``id`` into a dotted path and defaults ``children`` -- there is no
45
+ v2. The historical label strings below stay frozen regardless.
46
+ """
47
+
48
+ for item in raw.get("items", []):
49
+ if "done" in item and "status" not in item:
50
+ item["status"] = "done" if item.pop("done") else "todo"
51
+ if item.get("modified_at") is None and "created_at" in item:
52
+ item["modified_at"] = item["created_at"]
53
+ for key in ("priority", "status"):
54
+ value = item.get(key)
55
+ if isinstance(value, dict):
56
+ item[key] = value.get("label")
57
+ if "id" in item:
58
+ item["id"] = str(item["id"])
59
+ # base/v0 files are flat, so no recursion into children here.
60
+ item.setdefault("children", [])
61
+
62
+ return raw
63
+
64
+
65
+ def _config_base_to_v1(raw: dict[str, Any]) -> dict[str, Any]:
66
+ """Bring a pre-versioned config dict up to the v1 field shape."""
67
+
68
+ value = raw.get("default_priority")
69
+ if isinstance(value, dict):
70
+ raw["default_priority"] = value.get("label")
71
+
72
+ return raw
73
+
74
+
75
+ # index i migrates a file at version i to version i + 1.
76
+ _LIST_MIGRATIONS: list[Callable[[dict[str, Any]], dict[str, Any]]] = [
77
+ _list_base_to_v1
78
+ ]
79
+ _CONFIG_MIGRATIONS: list[Callable[[dict[str, Any]], dict[str, Any]]] = [
80
+ _config_base_to_v1
81
+ ]
82
+
83
+
84
+ def migrate_list(raw: dict[str, Any]) -> dict[str, Any]:
85
+ """Return a copy of a list dict migrated to the current schema.
86
+
87
+ Parameters
88
+ ----------
89
+ raw : dict[str, Any]
90
+ The parsed JSON contents of a list file.
91
+
92
+ Returns
93
+ -------
94
+ dict[str, Any]
95
+ A new dict with every pending migration applied and ``version``
96
+ stamped to ``CURRENT_LIST_VERSION``. An input already at or above
97
+ the current version is returned unchanged.
98
+ """
99
+
100
+ working = copy.deepcopy(raw)
101
+ for migration in _LIST_MIGRATIONS[file_version(working) :]:
102
+ working = migration(working)
103
+ if file_version(working) < CURRENT_LIST_VERSION:
104
+ working["version"] = CURRENT_LIST_VERSION
105
+
106
+ return working
107
+
108
+
109
+ def migrate_config(raw: dict[str, Any]) -> dict[str, Any]:
110
+ """Return a copy of a config dict migrated to the current schema.
111
+
112
+ Parameters
113
+ ----------
114
+ raw : dict[str, Any]
115
+ The parsed JSON contents of a config file.
116
+
117
+ Returns
118
+ -------
119
+ dict[str, Any]
120
+ A new dict with every pending migration applied and ``version``
121
+ stamped to ``CURRENT_CONFIG_VERSION``. An input already at or above
122
+ the current version is returned unchanged.
123
+ """
124
+
125
+ working = copy.deepcopy(raw)
126
+ for migration in _CONFIG_MIGRATIONS[file_version(working) :]:
127
+ working = migration(working)
128
+ if file_version(working) < CURRENT_CONFIG_VERSION:
129
+ working["version"] = CURRENT_CONFIG_VERSION
130
+
131
+ return working
132
+
133
+
134
+ def list_needs_migration(raw: dict[str, Any]) -> bool:
135
+ """Return whether a parsed list dict is on an older schema.
136
+
137
+ Parameters
138
+ ----------
139
+ raw : dict[str, Any]
140
+ The parsed JSON contents of a list file.
141
+
142
+ Returns
143
+ -------
144
+ bool
145
+ True when the file's version is below ``CURRENT_LIST_VERSION``.
146
+ """
147
+
148
+ return file_version(raw) < CURRENT_LIST_VERSION
149
+
150
+
151
+ def config_needs_migration(raw: dict[str, Any]) -> bool:
152
+ """Return whether a parsed config dict is on an older schema.
153
+
154
+ Parameters
155
+ ----------
156
+ raw : dict[str, Any]
157
+ The parsed JSON contents of a config file.
158
+
159
+ Returns
160
+ -------
161
+ bool
162
+ True when the file's version is below ``CURRENT_CONFIG_VERSION``.
163
+ """
164
+
165
+ return file_version(raw) < CURRENT_CONFIG_VERSION
@@ -0,0 +1 @@
1
+ """Pydantic data models, enums, and pure value objects."""
@@ -0,0 +1,140 @@
1
+ """Task & task list attributes."""
2
+
3
+ from collections.abc import Iterable
4
+ from dataclasses import dataclass
5
+ from enum import Enum, StrEnum
6
+ from typing import assert_never
7
+
8
+ __all__ = ["Color", "Operator", "Priority", "Status"]
9
+
10
+
11
+ class Color(StrEnum):
12
+ WHITE = "#F8FAFC"
13
+ RED = "#FF4D6D"
14
+ CORAL = "#FF6B6B"
15
+ ORANGE = "#FF8A3D"
16
+ YELLOW = "#FFD60A"
17
+ LIME = "#A3E635"
18
+ GREEN = "#22C55E"
19
+ TEAL = "#14D8B4"
20
+ CYAN = "#00D9FF"
21
+ SKY = "#38BDF8"
22
+ BLUE = "#3B82F6"
23
+ INDIGO = "#6366F1"
24
+ VIOLET = "#8B5CF6"
25
+ PURPLE = "#A855F7"
26
+ MAGENTA = "#D946EF"
27
+ PINK = "#FF4FCB"
28
+
29
+ @classmethod
30
+ def _missing_(cls, value: object) -> "Color | None":
31
+ if isinstance(value, str) and value.upper() in cls.__members__:
32
+ return cls[value.upper()]
33
+
34
+ return None
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class PriorityContainer:
39
+ label: str
40
+ index: int
41
+ color: str
42
+
43
+
44
+ class Priority(PriorityContainer, Enum):
45
+ LOW = ("low", 1, "green")
46
+ MEDIUM = ("medium", 2, "yellow")
47
+ HIGH = ("high", 3, "red")
48
+
49
+ @classmethod
50
+ def _missing_(cls, value: object) -> "Priority | None":
51
+ if isinstance(value, str) and value.upper() in cls.__members__:
52
+ return cls[value.upper()]
53
+
54
+ return None
55
+
56
+
57
+ @dataclass(frozen=True)
58
+ class StatusContainer:
59
+ label: str
60
+ marker: str
61
+ color: str
62
+
63
+
64
+ class Status(StatusContainer, Enum):
65
+ TODO = ("todo", "☐", Color.WHITE.value)
66
+ IN_PROGRESS = ("in_progress", "■", Color.CYAN.value)
67
+ DONE = ("done", "■", Color.WHITE.value)
68
+
69
+ @property
70
+ def marker_style(self) -> str:
71
+ """Rich style for this status's marker glyph.
72
+
73
+ Returns
74
+ -------
75
+ str
76
+ ``"dim"`` for a done item, else the status's marker color.
77
+ """
78
+
79
+ return "dim" if self is Status.DONE else self.color
80
+
81
+ @classmethod
82
+ def _missing_(cls, value: object) -> "Status | None":
83
+ if isinstance(value, str) and value.upper() in cls.__members__:
84
+ return cls[value.upper()]
85
+
86
+ return None
87
+
88
+
89
+ class Operator(Enum):
90
+ EQ = "eq"
91
+ CONTAINS = "contains"
92
+ LT = "lt"
93
+ GTE = "gte"
94
+
95
+ def compare(self, value: object, operand: object) -> bool:
96
+ """Test ``value`` against ``operand`` under this operator.
97
+
98
+ Parameters
99
+ ----------
100
+ value : object
101
+ The item attribute value to test.
102
+ operand : object
103
+ The value the criterion holds to test against.
104
+
105
+ Returns
106
+ -------
107
+ bool
108
+ Whether ``value`` satisfies ``operand`` under this operator.
109
+ """
110
+
111
+ if self is Operator.EQ:
112
+ return value == operand
113
+
114
+ if self is Operator.CONTAINS:
115
+ # case-insensitive containment: substring for a plain string,
116
+ # exact membership for any other iterable (reproduces the old
117
+ # ``needle in (t.lower() for t in item.tags)`` on tags).
118
+ needle = str(operand).lower()
119
+ if isinstance(value, str):
120
+ return needle in value.lower()
121
+ if isinstance(value, Iterable):
122
+ return needle in (str(v).lower() for v in value)
123
+
124
+ return False
125
+
126
+ if self is Operator.LT:
127
+ if value is None or operand is None:
128
+ return False
129
+
130
+ # object carries no ordering, so operand compatibility rests
131
+ # on the caller pairing the criterion, not on a check here.
132
+ return bool(value < operand) # type: ignore[operator]
133
+
134
+ if self is Operator.GTE:
135
+ if value is None or operand is None:
136
+ return False
137
+
138
+ return bool(value >= operand) # type: ignore[operator]
139
+
140
+ assert_never(self)
@@ -0,0 +1,111 @@
1
+ """List, tag, task, & priority models."""
2
+
3
+ from typing import Literal
4
+
5
+ from pydantic import (
6
+ BaseModel,
7
+ ConfigDict,
8
+ Field,
9
+ ValidationError,
10
+ field_serializer,
11
+ field_validator,
12
+ )
13
+
14
+ from ..exceptions import (
15
+ InvalidConfigValueError,
16
+ InvalidModifierValueError,
17
+ UnknownConfigKeyError,
18
+ )
19
+ from .attributes import Color, Priority
20
+ from .dates import parse_agenda_window
21
+ from .registry import sortable
22
+
23
+ __all__ = ["Config", "SortBy", "Delimters"]
24
+
25
+
26
+ # kept as a name for the models package export and call sites; the set
27
+ # of valid values now lives in the attribute registry.
28
+ type SortBy = str
29
+ type Delimters = Literal[".", "/", "-", "|"]
30
+
31
+
32
+ class Config(BaseModel):
33
+ model_config = ConfigDict(validate_assignment=True)
34
+
35
+ auto_prune: bool = False
36
+ silent_prune: bool = False
37
+ show_reminders: bool = True
38
+ inherit_sublist_color: bool = True
39
+ sublist_delimiter: Delimters = "."
40
+ default_list: str = Field(default="inbox", min_length=1)
41
+ default_sort: SortBy = "created_at"
42
+ default_priority: Priority = Priority.MEDIUM
43
+ default_color: Color | None = Color.WHITE
44
+ agenda_window: str = "week"
45
+ agenda_include_overdue: bool = True
46
+
47
+ @field_serializer("default_priority")
48
+ def _serialize_priority(self, value: Priority) -> str:
49
+ return value.label
50
+
51
+ @field_validator("default_sort")
52
+ @classmethod
53
+ def _validate_default_sort(cls, value: str) -> str:
54
+ if value not in sortable():
55
+ raise ValueError(
56
+ f"'{value}' is not a valid value for 'default_sort'."
57
+ )
58
+
59
+ return value
60
+
61
+ @field_validator("agenda_window")
62
+ @classmethod
63
+ def _validate_agenda_window(cls, value: str) -> str:
64
+ try:
65
+ return parse_agenda_window(value)
66
+ except InvalidModifierValueError as e:
67
+ raise ValueError(str(e)) from e
68
+
69
+ def _has_key(self, key: str) -> None:
70
+ if hasattr(self, key):
71
+ return
72
+
73
+ raise UnknownConfigKeyError(f"'{key}' is not a config key.")
74
+
75
+ def get_value(self, key: str) -> object:
76
+ """Return the current value of a config key.
77
+
78
+ Parameters
79
+ ----------
80
+ key : str
81
+ The config key.
82
+
83
+ Returns
84
+ -------
85
+ object
86
+ The key's current value.
87
+ """
88
+
89
+ self._has_key(key)
90
+ return getattr(self, key)
91
+
92
+ def set_value(self, key: str, raw_value: str) -> None:
93
+ """Parse a CLI string and set a config key.
94
+
95
+ Parameters
96
+ ----------
97
+ key : str
98
+ The config key.
99
+ raw_value : str
100
+ The raw CLI value to parse and assign.
101
+ """
102
+
103
+ self._has_key(key)
104
+ try:
105
+ setattr(self, key, raw_value)
106
+ except ValidationError as e:
107
+ raise InvalidConfigValueError(
108
+ f"'{raw_value}' is not a valid value for '{key}'."
109
+ ) from e
110
+
111
+ return None
taskli/models/dates.py ADDED
@@ -0,0 +1,141 @@
1
+ """Due-date modifier value parsing."""
2
+
3
+ import re
4
+ from datetime import date, datetime, timedelta
5
+
6
+ from ..exceptions import InvalidModifierValueError
7
+
8
+ __all__ = ["parse_agenda_window", "parse_due_date", "today"]
9
+
10
+ # both the full and 3-letter forms, keyed to date.weekday() (mon=0).
11
+ WEEKDAY_INDEX = {
12
+ "monday": 0,
13
+ "mon": 0,
14
+ "tuesday": 1,
15
+ "tue": 1,
16
+ "wednesday": 2,
17
+ "wed": 2,
18
+ "thursday": 3,
19
+ "thu": 3,
20
+ "friday": 4,
21
+ "fri": 4,
22
+ "saturday": 5,
23
+ "sat": 5,
24
+ "sunday": 6,
25
+ "sun": 6,
26
+ }
27
+
28
+ # discrete keyword tokens for --due, used by the shell completer.
29
+ DUE_DATE_KEYWORDS = ("today", "tomorrow", "next-week")
30
+
31
+
32
+ def today() -> date:
33
+ """Return the current calendar day.
34
+
35
+ A thin seam over ``datetime.now`` so tests can pin "now".
36
+
37
+ Returns
38
+ -------
39
+ date
40
+ The local date at the moment of the call.
41
+ """
42
+
43
+ return datetime.now().date()
44
+
45
+
46
+ def midnight(value: date) -> datetime:
47
+ """Return ``value`` as a datetime at that calendar day's midnight.
48
+
49
+ Parameters
50
+ ----------
51
+ value : date
52
+ The calendar day to normalize (a ``datetime`` is also accepted;
53
+ its time component is dropped).
54
+
55
+ Returns
56
+ -------
57
+ datetime
58
+ ``value`` with hour, minute, second, and microsecond zeroed.
59
+ """
60
+
61
+ return datetime(value.year, value.month, value.day)
62
+
63
+
64
+ def parse_due_date(raw: str) -> datetime:
65
+ """Parse a due-date modifier value to a midnight datetime.
66
+
67
+ Parameters
68
+ ----------
69
+ raw : str
70
+ The user-supplied value, e.g. ``"tomorrow"``, ``"3 days"``, or
71
+ ``"04-15-2026"``.
72
+
73
+ Returns
74
+ -------
75
+ datetime
76
+ The resolved calendar day at midnight (no time component).
77
+ """
78
+
79
+ text = raw.strip()
80
+ keyword = text.casefold()
81
+
82
+ if keyword == "today":
83
+ return midnight(today())
84
+ if keyword == "tomorrow":
85
+ return midnight(today() + timedelta(days=1))
86
+ if keyword == "next-week":
87
+ return midnight(today() + timedelta(days=7))
88
+
89
+ if keyword in WEEKDAY_INDEX:
90
+ current = today()
91
+ delta = (WEEKDAY_INDEX[keyword] - current.weekday()) % 7
92
+ # a named weekday that is today resolves to the following week.
93
+ if delta == 0:
94
+ delta = 7
95
+
96
+ return midnight(current + timedelta(days=delta))
97
+
98
+ relative = re.match(r"^(\d+)\s+(days?|weeks?)$", keyword)
99
+ if relative is not None:
100
+ count = int(relative.group(1))
101
+ if count > 0:
102
+ span = 7 if relative.group(2).startswith("week") else 1
103
+ return midnight(today() + timedelta(days=count * span))
104
+
105
+ try:
106
+ explicit = datetime.strptime(text, "%m-%d-%Y")
107
+ except ValueError as error:
108
+ raise InvalidModifierValueError(
109
+ "due date must be one of: today, tomorrow, next-week, "
110
+ "N days, N weeks, a weekday name (e.g. monday), or "
111
+ "MM-DD-YYYY"
112
+ ) from error
113
+
114
+ return midnight(explicit)
115
+
116
+
117
+ def parse_agenda_window(raw: str) -> str:
118
+ """Validate and normalize an agenda window token.
119
+
120
+ Parameters
121
+ ----------
122
+ raw : str
123
+ The user-supplied value, e.g. ``"today"``, ``"week"``,
124
+ ``"overdue"``, or a positive integer of days as a string.
125
+
126
+ Returns
127
+ -------
128
+ str
129
+ The normalized token: ``"today"``, ``"week"``, ``"overdue"``,
130
+ or the digit string unchanged.
131
+ """
132
+
133
+ keyword = raw.strip().casefold()
134
+ if keyword in {"today", "week", "overdue"}:
135
+ return keyword
136
+ if keyword.isdigit() and int(keyword) > 0:
137
+ return keyword
138
+
139
+ raise InvalidModifierValueError(
140
+ "agenda window must be one of: today, week, overdue, or N (days)."
141
+ )
taskli/models/paths.py ADDED
@@ -0,0 +1,21 @@
1
+ """Dotted item-path helpers."""
2
+
3
+ __all__ = ["path_key"]
4
+
5
+
6
+ def path_key(path: str) -> tuple[int, ...]:
7
+ """Return the positional sort key for a dotted item path.
8
+
9
+ Parameters
10
+ ----------
11
+ path : str
12
+ A dotted positional path such as ``"1"`` or ``"1.10"``.
13
+
14
+ Returns
15
+ -------
16
+ tuple of int
17
+ One integer per path segment, so ``"1.10"`` yields ``(1, 10)``
18
+ and orders after ``"1.2"`` -> ``(1, 2)``.
19
+ """
20
+
21
+ return tuple(int(segment) for segment in path.split("."))