Categories — Category System

The categories package provides task categorization with customizable templates and configuration.

CategoryManager

class jot.categories.manager.CategoryManager(project_dir=None)

Bases: object

Manages categories within a project directory and globally

MAX_CATEGORIES = 12

GLOBAL_CATEGORIES_DIR = PosixPath('/home/runner/.jot-categories')

__init__(project_dir=None)

Initialize category manager for a project directory

discover_categories()

Find all category files in .jot-categories/ directory. Returns list of category names (without .json suffix).

count_categories()

Count existing categories in the project

can_create_category(category_name)

Check if a new category can be created. Returns (can_create: bool, message: str)

get_warning_message(category_name)

Get warning message if approaching category limit. Returns None if no warning needed.

discover_global_categories()

Find all global category files in ~/.jot-categories/ Returns list of category names (without .json suffix). Excludes special files like ids, archive, etc.

category_exists_locally(category_name)

Check if category exists locally in project

category_exists_globally(category_name)

Check if category exists globally

resolve_category_location(category_name)

Determine if category is local, global, or new. Returns: ‘local’, ‘global’, or ‘new’

get_category_file_path(category_name, is_global=False)

Get the full path for a category file.

Parameters:

• category_name – Name of the category

• is_global – If True, return global path; if False, return local path

Returns:

Path object for the category file

CategoryConfig

class jot.categories.config.CategoryConfig(project_dir=None)

Bases: object

Manages category colors and configuration

COLORS = {'blue': '\x1b[94m', 'cyan': '\x1b[96m', 'green': '\x1b[92m', 'lime': '\x1b[38;5;154m', 'magenta': '\x1b[95m', 'orange': '\x1b[38;5;208m', 'pink': '\x1b[38;5;213m', 'purple': '\x1b[38;5;141m', 'red': '\x1b[91m', 'teal': '\x1b[38;5;44m', 'white': '\x1b[97m', 'yellow': '\x1b[93m'}

DEFAULT_COLORS = {'backlog': 'cyan', 'bills': 'orange', 'bugs': 'red', 'default': 'white', 'docs': 'blue', 'features': 'green', 'health': 'lime', 'ideas': 'purple', 'personal': 'pink', 'testing': 'yellow', 'work': 'teal'}

__init__(project_dir=None)

Initialize category config

get_color(category_name, for_global=False)

Get ANSI color code for a category

set_color(category_name, color_name)

Set color for a category

get_all_colors()

Get all configured colors

reset_colors()

Reset all colors to defaults

list_available_colors()

List all available color names

get_tts_config()

Get TTS configuration settings

set_tts_config(**kwargs)

Set TTS configuration settings

CategoryTemplates

class jot.categories.templates.CategoryTemplates(project_dir=None)

Bases: object

Manages category templates for quick project setup

TEMPLATES = {'academic': {'categories': ['reading', 'research', 'writing', 'teaching'], 'description': 'Academic and research project categories', 'name': 'Academic/Research', 'sample_tasks': {'reading': ['Literature review', 'Paper analysis'], 'research': ['Experiment design', 'Data collection'], 'teaching': ['Prepare lecture', 'Grade assignments'], 'writing': ['Draft paper', 'Revise manuscript']}}, 'business': {'categories': ['leads', 'clients', 'invoicing', 'marketing'], 'description': 'Business and client work categories', 'name': 'Business Management', 'sample_tasks': {'clients': ['Client meetings', 'Project deliverables'], 'invoicing': ['Send invoices', 'Track payments'], 'leads': ['Follow up prospects', 'Update CRM'], 'marketing': ['Social media posts', 'Email campaign']}}, 'creative': {'categories': ['ideas', 'drafts', 'editing', 'publishing'], 'description': 'Creative and content creation categories', 'name': 'Creative Project', 'sample_tasks': {'drafts': ['Write first draft'], 'editing': ['Review and revise'], 'ideas': ['Brainstorm topics', 'Research inspiration'], 'publishing': ['Format and publish']}}, 'personal': {'categories': ['work', 'home', 'bills', 'health'], 'description': 'Personal life management categories', 'name': 'Personal Tasks', 'sample_tasks': {'bills': ['Pay rent', 'Review budget'], 'health': ['Exercise', 'Doctor appointment'], 'home': ['Grocery shopping', 'Clean house'], 'work': ['Check email', 'Weekly planning']}}, 'software-dev': {'categories': ['features', 'bugs', 'testing', 'docs'], 'description': 'Standard software project categories', 'name': 'Software Development', 'sample_tasks': {'bugs': ['Triage bug reports'], 'docs': ['Update README', 'Write API docs'], 'features': ['Plan next sprint', 'Review backlog'], 'testing': ['Run test suite', 'Update test coverage']}}}

__init__(project_dir=None)

Initialize templates manager

list_templates()

List all available templates

apply_template(template_name, with_samples=False)

Apply a template to create categories

get_template_info(template_name)

Get detailed information about a template