Utils — Utilities¶

The utils package provides shared helper functions for text processing, date handling, and validation.

Text Utilities¶

Text manipulation and search utilities for jot

jot.utils.text_utils.extract_urls(text)[source]¶

Extract URLs from text

Parameters:: text – String to search for URLs
Returns:: List of URLs found in text

jot.utils.text_utils.fuzzy_match(query, text)[source]¶

Fuzzy match query against text.

Tries matching from every occurrence of the first query character and returns the highest-scoring result, avoiding the greedy trap where an early character locks in a suboptimal match.

Returns:

is_match: bool indicating if all query chars found in text in order
score: int score (higher is better match)
match_positions: list of indices in text where query chars matched

Return type:

(is_match, score, match_positions) where

Date Utilities¶

Date and time utility functions for jot

jot.utils.date_utils.get_today_day_name()[source]¶

Get the current day of the week

Returns:: Full day name like “Monday”
Return type:: str

jot.utils.date_utils.sort_tasks_by_day(tasks)[source]¶

Sort tasks by day of week (Sunday-Saturday)

Parameters:: tasks – List of task dictionaries
Returns:: tasks with days (Sun-Sat order) + tasks without days
Return type:: Sorted list

jot.utils.date_utils.filter_today_tasks(tasks, today)[source]¶

Filter tasks to only show those assigned to today

Parameters:

tasks – List of task dictionaries
today – String name of today’s day (e.g., “Monday”)

Returns:

List of tasks assigned to today

jot.utils.date_utils.extract_time_tag(text)[source]¶

Extract military time tag (HHMM) from task text.

Finds a standalone 4-digit pattern where HH is 00-23 and MM is 00-59.

Parameters:: text – Task text potentially containing a time tag
Returns:: (hour, minute, cleaned_text) if found, (None, None, text) otherwise

jot.utils.date_utils.round_to_15_minutes(dt)[source]¶

Round datetime to nearest 15 minutes

Parameters:: dt – datetime object
Returns:: datetime rounded to nearest 15 minutes

Validation¶

Validation utilities for jot

jot.utils.validation.validate_safe_name(name, name_type='name')[source]¶

Validate category/project names for path traversal attacks.

Security: Prevents directory traversal attacks by rejecting: - Path separators (/, ) - Parent directory references (..) - Absolute paths - Non-alphanumeric characters (except dash and underscore)

Parameters:

name – Name to validate (category, project, etc.)
name_type – Type of name for error messages (default: “name”)

Returns:

Validated name (unchanged if valid)

Return type:

str

Raises:

ValueError – If name contains dangerous characters or patterns

Examples

>>> validate_safe_name("my-project")
'my-project'
>>> validate_safe_name("../etc/passwd")
ValueError: Invalid name: ../etc/passwd (no path separators allowed)