sigye 0.1.0__tar.gz

sigye-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.python-version
+.coverage

sigye-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.3
+Name: sigye
+Version: 0.1.0
+Summary: Add your description here
+Author-email: swilcox <steven@wilcoxzone.com>
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.7
+Requires-Dist: humanize>=4.11.0
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.4
+Description-Content-Type: text/markdown
+
+# sigye (시계)
+
+A simple, command-line time tracking program.
+
+## Overview
+
+sigye (시계 Korean for hour(s)/time) is a CLI program to help you track your time. With sigye, there are basic operations:
+* start (start tracking time towards a project)
+* stop (stop tracking time)
+* status (get the current status)
+* edit (edit a time entry record using the current default EDITOR)
+* list (list entries)
+  * can filter entries by time range ("today", "week", "month") or fixed start and end dates.
+  * can filter entries by project name(s) or a project starts with.
+  * can filter entries by tags name(s).
+
+The default storage of time entries is a YAML file (near future will be sqlite support). Using YAML makes manual editing of the entire file possible using any editor.
+
+## Installation
+
+### Via `uv`
+```shell
+uv tool install sigye
+```
+
+### Via `pipx`
+```shell
+pipx install sigye
+```
+
+## Usage
+
+### Start tracking
+```shell
+sigye start <project-name> "<optional comment>" --tag "optional_tag"
+```
+
+### Check status
+```shell
+sigye status
+```
+
+### Stop tracking
+```shell
+sigye stop
+```
+
+### List Entries
+#### List All Entries
+```shell
+sigye list
+```
+#### List Filtered Entries
+
+All entries from a named time frame (options: `today`, `week` and `month`):
+```shell
+sigye list TIMEFRAME
+```
+
+All entries for a certain project (or list of projects)
+```shell
+sigye list --project abc-1234 --project abc-1233
+```
+
+Entries that "start with" a project name (note: you can use `+` or `.` or `*`):
+```
+sigye list --project abc+
+```
+
+All entries with any tag matching a tag or multiple tags:
+```
+sigye list --tag mytag
+```
+
+### Edit Entries
+To edit an entry, use the full or partial ID (just has to be enough digits for it to be unique among your time entry file or data). By default, sigye shows the first 4 digits from an entry ID.
+```shell
+sigye edit ID
+```
+
+## Development
+
+### Install requirements
+
+This project uses `uv` for dependency management.
+
+### Running tests
+
+```shell
+uv run pytest
+```

sigye-0.1.0/README.md

@@ -0,0 +1,91 @@
+# sigye (시계)
+
+A simple, command-line time tracking program.
+
+## Overview
+
+sigye (시계 Korean for hour(s)/time) is a CLI program to help you track your time. With sigye, there are basic operations:
+* start (start tracking time towards a project)
+* stop (stop tracking time)
+* status (get the current status)
+* edit (edit a time entry record using the current default EDITOR)
+* list (list entries)
+  * can filter entries by time range ("today", "week", "month") or fixed start and end dates.
+  * can filter entries by project name(s) or a project starts with.
+  * can filter entries by tags name(s).
+
+The default storage of time entries is a YAML file (near future will be sqlite support). Using YAML makes manual editing of the entire file possible using any editor.
+
+## Installation
+
+### Via `uv`
+```shell
+uv tool install sigye
+```
+
+### Via `pipx`
+```shell
+pipx install sigye
+```
+
+## Usage
+
+### Start tracking
+```shell
+sigye start <project-name> "<optional comment>" --tag "optional_tag"
+```
+
+### Check status
+```shell
+sigye status
+```
+
+### Stop tracking
+```shell
+sigye stop
+```
+
+### List Entries
+#### List All Entries
+```shell
+sigye list
+```
+#### List Filtered Entries
+
+All entries from a named time frame (options: `today`, `week` and `month`):
+```shell
+sigye list TIMEFRAME
+```
+
+All entries for a certain project (or list of projects)
+```shell
+sigye list --project abc-1234 --project abc-1233
+```
+
+Entries that "start with" a project name (note: you can use `+` or `.` or `*`):
+```
+sigye list --project abc+
+```
+
+All entries with any tag matching a tag or multiple tags:
+```
+sigye list --tag mytag
+```
+
+### Edit Entries
+To edit an entry, use the full or partial ID (just has to be enough digits for it to be unique among your time entry file or data). By default, sigye shows the first 4 digits from an entry ID.
+```shell
+sigye edit ID
+```
+
+## Development
+
+### Install requirements
+
+This project uses `uv` for dependency management.
+
+### Running tests
+
+```shell
+uv run pytest
+```

sigye-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "sigye"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "swilcox", email = "steven@wilcoxzone.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.1.7",
+    "humanize>=4.11.0",
+    "pydantic>=2.9.2",
+    "pyyaml>=6.0.2",
+    "rich>=13.9.4",
+]
+
+[project.scripts]
+sigye = "sigye.cli:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "freezegun>=1.5.1",
+    "pytest-cov>=6.0.0",
+    "pytest>=8.3.3",
+]

sigye-0.1.0/src/sigye/cli.py

@@ -0,0 +1,171 @@
+from datetime import datetime, timedelta
+import functools
+import tempfile
+import os
+import subprocess
+import yaml
+
+import click
+
+from .models import EntryListFilter, TimeEntry
+from .output.text_output import list_output, single_entry_output
+from .services import TimeTrackingService
+from .repositories.time_entry_repo import TimeEntryRepository
+from .repositories.time_entry_repo_yaml import TimeEntryRepositoryYaml
+
+
+def _get_repo_from_filename(filename: str) -> TimeEntryRepository:
+    # TODO: add logic here to swap to sqlite or something else based on the filename
+    return TimeEntryRepositoryYaml(filename)
+
+
+def config_params(func):
+    @click.option("--filename", "-f", default="time_entries.yaml")
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def _get_editor_command():
+    return os.environ.get("EDITOR", "vim")
+
+
+def _format_entry_for_edit(entry: TimeEntry) -> str:
+    """Format a time entry as YAML for editing"""
+    # Convert to dict and format as YAML
+    entry_dict = entry.model_dump(mode="json")
+    return yaml.dump(entry_dict)
+
+
+def _parse_edited_entry(content: str) -> TimeEntry:
+    """Parse edited YAML content back into a TimeEntry"""
+    try:
+        data = yaml.safe_load(content)
+        return TimeEntry(**data)
+    except Exception as e:
+        raise click.ClickException(f"Invalid entry format: {str(e)}")
+
+
+@click.group()
+@click.version_option()
+@click.pass_context
+def cli(ctx): ...
+
+
+@cli.command()
+@click.argument("project", required=True, type=str)
+@click.option("--tag", multiple=True)
+@click.argument("comment", required=False, type=str, default="")
+@config_params
+def start(project, tag, comment, filename):
+    """start tracking work on a project"""
+    tts = TimeTrackingService(_get_repo_from_filename(filename))
+    time_entry = tts.start_tracking(project, comment=comment, tags=tag)
+    single_entry_output(time_entry)
+
+
+@cli.command()
+@config_params
+def stop(filename):
+    """stop tracking work on a project"""
+    tts = TimeTrackingService(_get_repo_from_filename(filename))
+    time_entry = tts.stop_tracking()
+    if time_entry:
+        single_entry_output(time_entry)
+    else:
+        print("No active time entry to stop.")
+
+
+@cli.command()
+@config_params
+def status(filename):
+    """displays currently tracked (if active)"""
+    tts = TimeTrackingService(_get_repo_from_filename(filename))
+    time_entry = tts.get_active_entry()
+    if time_entry:
+        single_entry_output(time_entry)
+    else:
+        print("No active time entry.")
+
+
+@cli.command()
+@click.argument("id", required=True, type=str)
+@config_params
+def edit(id, filename):
+    """edit a time entry using the system editor"""
+    tts = TimeTrackingService(_get_repo_from_filename(filename))
+
+    # Get the entry to edit
+    try:
+        if entries := tts.list_entries(EntryListFilter(id=id)):
+            if len(entries) > 1:
+                raise IndexError
+            entry = entries[0]
+        else:
+            raise KeyError
+    except KeyError:
+        raise click.ClickException(f"No entry found with id {id}")
+    except IndexError:
+        raise click.ClickException(f"Multiple records found starting with id {id}")
+
+    # Create temp file with entry content
+    with tempfile.NamedTemporaryFile(suffix=".yaml", mode="w+", delete=False) as tmp:
+        tmp.write(_format_entry_for_edit(entry))
+        tmp.flush()
+        tmp_path = tmp.name
+
+    try:
+        # Open editor
+        editor = _get_editor_command()
+        subprocess.run([editor, tmp_path], check=True)
+
+        # Read and parse edited content
+        with open(tmp_path, "r") as f:
+            edited_content = f.read()
+            updated_entry = _parse_edited_entry(edited_content)
+
+        # Save the updated entry
+        tts.update_entry(updated_entry)
+        single_entry_output(updated_entry)
+
+    finally:
+        # Clean up temp file
+        os.unlink(tmp_path)
+
+
+@cli.command()
+@click.argument(
+    "time_period",
+    required=False,
+    type=click.Choice(["today", "week", "month", ""]),
+    default="",
+)
+@click.option("--start_date")
+@click.option("--end_date")
+@click.option("--tag", multiple=True)
+@click.option("--project", multiple=True)
+@click.option("--format")
+@config_params
+def list(time_period, start_date, end_date, tag, project, format, filename):
+    """display list of time entries for a time period"""
+    tts = TimeTrackingService(_get_repo_from_filename(filename))
+
+    filter_params = {}
+    if time_period:
+        filter_params["time_period"] = time_period
+    if start_date:
+        filter_params["start_date"] = datetime.strptime(start_date, "%Y-%m-%d").date()
+    if end_date:
+        filter_params["end_date"] = datetime.strptime(end_date, "%Y-%m-%d").date()
+    if tag:
+        filter_params["tags"] = set(tag)
+    if project:
+        filter_params["projects"] = set(project)
+    if format:
+        filter_params["output_format"] = format
+
+    filter = EntryListFilter(**filter_params)
+    time_list = tts.list_entries(filter=filter)
+    list_output(time_list)

sigye-0.1.0/src/sigye/models.py

@@ -0,0 +1,87 @@
+from datetime import datetime, date, timedelta
+from uuid import uuid4
+from typing import Literal
+
+from pydantic import BaseModel, Field
+import humanize
+
+
+class TimeEntry(BaseModel):
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    start_time: datetime
+    end_time: datetime | None = None
+    project: str
+    tags: set[str] = Field(default_factory=set)
+    comment: str = ""
+
+    @property
+    def humanized_duration(self):
+        td = (
+            self.end_time - self.start_time
+            if self.end_time
+            else datetime.now().astimezone() - self.start_time
+        )
+        return humanize.precisedelta(
+            td,
+            suppress=("seconds", "milliseconds", "microseconds"),
+            minimum_unit="hours",
+            format="%0.1f",
+        )
+
+    @staticmethod
+    def _get_naive_time(ts: datetime) -> datetime | None:
+        """remove the tzinfo so we get the original hour"""
+        return ts.replace(tzinfo=None) if ts else None
+
+    @property
+    def naive_start_time(self):
+        return self._get_naive_time(self.start_time)
+
+    @property
+    def naive_end_time(self):
+        return self._get_naive_time(self.end_time)
+
+    def stop(self, end_time: datetime = None):
+        if self.end_time is None or (
+            self.end_time is not None and self.end_time < self.start_time
+        ):
+            self.end_time = end_time or datetime.now().astimezone()
+        else:
+            raise ValueError("already stopped")
+
+    @property
+    def duration(self):
+        return (
+            self.end_time - self.start_time
+            if self.end_time
+            else datetime.now().astimezone() - self.start_time
+        )
+
+
+class EntryListFilter(BaseModel):
+    id: str = ""
+    projects: set[str] = Field(default_factory=set)
+    start_date: date | None = None
+    end_date: date | None = None
+    tags: set[str] = Field(default_factory=set)
+    time_period: Literal["today", "week", "month"] | None = None
+    output_format: str | None = None
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        if self.time_period:
+            self._apply_time_period()
+
+    def _apply_time_period(self):
+        """Apply date filters based on time period"""
+        now = datetime.now()
+        if self.time_period == "today":
+            self.start_date = now.date()
+        elif self.time_period == "week":
+            self.start_date = now.date() - timedelta(
+                days=now.date().weekday()
+            )  # Monday
+        elif self.time_period == "month":
+            self.start_date = now.date() - timedelta(
+                days=(now.date().day - 1)
+            )  # 1st of current month

sigye-0.1.0/src/sigye/output/text_output.py

@@ -0,0 +1,60 @@
+from datetime import date
+from rich.console import Console
+from rich.table import Table
+from ..models import TimeEntry
+
+
+ABBR_ID_LENGTH = 4
+
+
+def single_entry_output(entry: TimeEntry):
+    table = Table(title="Time Entry")
+    table.add_column("field")
+    table.add_column("value")
+    table.add_row(
+        "ID",
+        f"[magenta]{entry.id[0:ABBR_ID_LENGTH]}[/magenta]{entry.id[ABBR_ID_LENGTH:]}",
+    )
+    table.add_row(
+        "start date/time", f"[cyan]{entry.naive_start_time:%Y-%m-%d %H:%M:%S}[/cyan]"
+    )
+    table.add_row(
+        "end time",
+        f"[magenta]{entry.naive_end_time:%H:%M:%S}[/magenta]"
+        if entry.end_time
+        else "-",
+    )
+    table.add_row("duration", f"[cyan]{entry.humanized_duration}[/cyan]")
+    table.add_row("project", f"[green]{entry.project}[/green]")
+    table.add_row("comments", f"[blue]{entry.comment}[/blue]")
+    table.add_row("tags", "[red]" + ", ".join(tag for tag in entry.tags) + "[/red]")
+    console = Console()
+    console.print(table)
+
+
+def list_output(entry_list: list[TimeEntry]):
+    table = Table(title="Time Entries")
+    table.add_column("id", justify="left", style="#707070")
+    table.add_column("start", justify="right", style="cyan")
+    table.add_column("end", justify="right", style="magenta")
+    table.add_column("delta", style="cyan")
+    table.add_column("project", justify="left", style="green")
+    table.add_column("comments", style="blue")
+    table.add_column("tags", style="red")
+    current_date = date(1970, 1, 1)
+    for entry in entry_list:
+        if entry.start_time.date() != current_date:
+            current_date = entry.start_time.date()
+            table.add_section()
+            table.add_row("", f"{current_date:%Y-%m-%d}", style="yellow")
+        table.add_row(
+            f"{entry.id[0:ABBR_ID_LENGTH]}",
+            f"{entry.naive_start_time:%H:%M:%S}",
+            f"{entry.naive_end_time:%H:%M:%S}" if entry.end_time else "-",
+            f"{entry.humanized_duration}",
+            entry.project,
+            entry.comment,
+            ", ".join(tag for tag in entry.tags),
+        )
+    console = Console()
+    console.print(table)

sigye-0.1.0/src/sigye/repositories/time_entry_repo.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+from ..models import TimeEntry, EntryListFilter
+
+
+class TimeEntryRepository(ABC):
+    @abstractmethod
+    def save(self, entry: TimeEntry) -> TimeEntry:
+        pass
+
+    @abstractmethod
+    def get_active_entry(self) -> TimeEntry | None:
+        pass
+
+    @abstractmethod
+    def get_by_project(self, project: str) -> list[TimeEntry]:
+        pass
+
+    @abstractmethod
+    def get_all(self) -> list[TimeEntry]:
+        pass
+
+    @abstractmethod
+    def filter(self, *, filter: EntryListFilter):
+        pass
+
+    @abstractmethod
+    def get_entry_by_id(self) -> TimeEntry:
+        pass

sigye-0.1.0/src/sigye/repositories/time_entry_repo_yaml.py

@@ -0,0 +1,99 @@
+import os
+import yaml
+from ..models import TimeEntry, EntryListFilter
+from .time_entry_repo import TimeEntryRepository
+
+
+class TimeEntryRepositoryYaml(TimeEntryRepository):
+    def __init__(self, filename: str = "timesheet.yaml"):
+        self.filename = filename
+        self._ensure_file_exists()
+
+    def _ensure_file_exists(self):
+        if not os.path.exists(self.filename):
+            self._save_data({"entries": []})
+
+    def _load_data(self) -> list[TimeEntry]:
+        with open(self.filename, "r") as f:
+            return yaml.load(f, yaml.FullLoader)
+
+    def _save_data(self, data: dict):
+        with open(self.filename, "w") as f:
+            yaml.dump(data, f)
+
+    def get_active_entry(self) -> TimeEntry | None:
+        data = self._load_data()
+        active = next((e for e in data["entries"] if not e.get("end_time")), None)
+        return TimeEntry(**active) if active else None
+
+    def get_all(self):
+        data = self._load_data()
+        return [TimeEntry(**entry) for entry in data["entries"]]
+
+    def get_by_project(self, project):
+        data = self._load_data()
+        return [
+            TimeEntry(**entry)
+            for entry in data["entries"]
+            if entry["project"] == project
+        ]
+
+    def get_entry_by_id(self, id: str):
+        data = self._load_data()
+        for entry in data["entries"]:
+            if entry["id"] == id:
+                return TimeEntry(**entry)
+        raise KeyError("record id not found")
+
+    @staticmethod
+    def _project_matching(filter_projects: set[str], project: str) -> bool:
+        for f_proj in filter_projects:
+            if (
+                f_proj[-1] in "*+." and project.startswith(f_proj[0:-1])
+            ) or f_proj == project:
+                return True
+        return False
+
+    def _check_against_filter(self, filter: EntryListFilter, entry: TimeEntry) -> bool:
+        conditions = [
+            # id filter
+            (not filter.id or entry.id.startswith(filter.id)),
+            # Project filters
+            (
+                not filter.projects
+                or self._project_matching(filter.projects, entry.project)
+            ),
+            # Date filters
+            (not filter.start_date or entry.start_time.date() >= filter.start_date),
+            (
+                not filter.end_date
+                or (entry.end_time and entry.end_time.date() <= filter.end_date)
+            ),
+            # Tag filter
+            (not filter.tags or any(tag in entry.tags for tag in filter.tags)),
+        ]
+        return all(conditions)
+
+    def filter(self, *, filter: EntryListFilter | None = None) -> list[TimeEntry]:
+        time_entries = self.get_all()
+        if filter is None:
+            return time_entries
+        return [
+            entry for entry in time_entries if self._check_against_filter(filter, entry)
+        ]
+
+    def save(self, entry: TimeEntry) -> None:
+        data = self._load_data()
+        entry_dict = entry.model_dump(mode="json")
+        found = False
+        entries = []
+        for e in data["entries"]:
+            if e["id"] == entry.id:
+                entries.append(entry_dict)
+                found = True
+            else:
+                entries.append(e)
+        if not found:
+            entries.append(entry_dict)
+        data["entries"] = entries
+        self._save_data(data)