| Name | sigye JSON |
| Version |
0.9.0
JSON |
| download |
| home_page | None |
| Summary | (시계) A simple command-line program for tracking time. |
| upload_time | 2024-12-15 15:27:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT License |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sigye (시계)
A simple, command-line time tracking program.
## Overview
sigye (시계 Korean for clock) 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` value or `nano` if you don't have `EDITOR` set in your shell)
* 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
### Default Storage of Entries
By default, entries are stored in a YAML file at: `$HOME/.sigye/time_entries.yml`
To override this value, you can add `--filename <date_filename>` on every command to override adhoc.
To override this value for an environment, you can set the environment variable `SIGYE_DATA_FILENAME` to whatever value you'd like and that will become the default.
Or better yet, set the `data_filename` in the config.yaml file.
> [!IMPORTANT]
> Make sure the directory exists before overriding.
### Start tracking
```shell
sigye start <project-name> "<optional comment>" --tag "optional_tag" --start_time "HH:MM"
```
The start command begins tracking time for a project. You can:
- Add an optional comment in quotes to describe what you're working on
- Add one or more tags using the --tag option
- Specify a custom start time using --start_time (or -s) in 24-hour format (HH:MM or HH:MM:SS) or AM/PM format
- Only one time entry can be tracked at a time
- Starting a new entry automatically stops the currently running one
### Stop tracking
```shell
sigye stop ["optional comment"] --stop_time "HH:MM"
```
The stop command ends time tracking for the current entry. You can:
- Add an optional comment in quotes to describe what was completed
- Specify a custom stop time using --stop_time (or -s) in 24-hour format (HH:MM or HH:MM:SS) or AM/PM format
- Use stop without a comment to simply end tracking
- If no stop time is specified, the current time is used
### Check status
```shell
sigye status
```
### List Entries
#### List All Entries
```shell
sigye list
```
#### List Filtered Entries
All entries from a named time frame (options: `today`, `yesterday`, `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
```
#### List Entries in a Different format
The output format can be set/overridden with the `--output_format` or `-o` option.
Valid options are:
* `rich` -- colorized text with ascii/unicode characters for nicer display. This is the default output if the `sigye` command is not being redirected somewhere besides `stdout`.
* `text` -- an extremely plain output mostly used for testing.
* `json` -- output in JSON format. This is the default if no option is provided and `stdout` is redirected.
* `yaml` -- output in YAML format, suitable for exporting entries to a new file.
Example:
```
sigye -o yaml list --project abc.
```
The above would list all entries that have a project that starts with "abc" in yaml format.
### 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
```
## Configuration
sigye can be configured using a YAML configuration file located at `~/.sigye/config.yaml`. Here's an example configuration file with available options:
```yaml
# Override the default locale (en_US)
# locale: ko_KR
# data_filename: /full/path/to/a/file.yaml
# Auto-tagging rules
# Each rule consists of:
# - pattern: regular expression pattern to match against project name
# - match_type: how to match the pattern (regex)
# - tags: list of tags to apply when pattern matches
auto_tag_rules:
- pattern: "^abc" # Matches projects starting with "abc"
match_type: "regex"
tags: ["learning"]
- pattern: "^PROJ-\\d+" # Matches PROJ- followed by numbers
match_type: "regex"
tags: ["work", "billable"]
- pattern: ".*-urgent$" # Projects ending with "-urgent"
match_type: "regex"
tags: ["urgent", "high-priority"]
- pattern: "(feature|bugfix)/" # Projects containing feature/ or bugfix/
match_type: "regex"
tags: ["development"]
```
The auto-tagging rules automatically apply tags to your time entries based on the project name. This helps maintain consistent tagging across similar projects without having to manually specify tags each time.
### Localization Support (experimental Korean output)
To get *output* in Korean:
`export SIGYE_LOCALE=ko_KR`
The `sigye list` and `sigye status` commands will now output some information in Korean.
> [!NOTE]
> This work is ongoing and subject to change.
## Development
### Install requirements
This project uses `uv` for dependency management.
### Running tests
```shell
uv run pytest
```
## Future Changes
* Configuration file support
* YAML (mostly complete now)
* TOML
* Language Localization (in-progress)
* SQLite storage
* TOML storage
Raw data
{
"_id": null,
"home_page": null,
"name": "sigye",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "swilcox <steven@wilcox.be>",
"download_url": "https://files.pythonhosted.org/packages/a5/96/dce809eddd2e8c999f87f1a2ed03d94b6c1e1de8683d509de1960dc6196a/sigye-0.9.0.tar.gz",
"platform": null,
"description": "# sigye (\uc2dc\uacc4)\n\nA simple, command-line time tracking program.\n\n## Overview\n\nsigye (\uc2dc\uacc4 Korean for clock) is a CLI program to help you track your time. With sigye, there are basic operations:\n* start (start tracking time towards a project)\n* stop (stop tracking time)\n* status (get the current status)\n* edit (edit a time entry record using the current default `EDITOR` value or `nano` if you don't have `EDITOR` set in your shell)\n* list (list entries)\n * can filter entries by time range (\"today\", \"week\", \"month\") or fixed start and end dates.\n * can filter entries by project name(s) or a project starts with.\n * can filter entries by tags name(s).\n\nThe 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.\n\n## Installation\n\n### Via `uv`\n```shell\nuv tool install sigye\n```\n\n### Via `pipx`\n```shell\npipx install sigye\n```\n\n## Usage\n\n### Default Storage of Entries\nBy default, entries are stored in a YAML file at: `$HOME/.sigye/time_entries.yml`\n\nTo override this value, you can add `--filename <date_filename>` on every command to override adhoc.\n\nTo override this value for an environment, you can set the environment variable `SIGYE_DATA_FILENAME` to whatever value you'd like and that will become the default.\n\nOr better yet, set the `data_filename` in the config.yaml file.\n\n> [!IMPORTANT] \n> Make sure the directory exists before overriding.\n\n### Start tracking\n```shell\nsigye start <project-name> \"<optional comment>\" --tag \"optional_tag\" --start_time \"HH:MM\"\n```\n\nThe start command begins tracking time for a project. You can:\n- Add an optional comment in quotes to describe what you're working on\n- Add one or more tags using the --tag option\n- Specify a custom start time using --start_time (or -s) in 24-hour format (HH:MM or HH:MM:SS) or AM/PM format\n- Only one time entry can be tracked at a time\n- Starting a new entry automatically stops the currently running one\n\n### Stop tracking\n```shell\nsigye stop [\"optional comment\"] --stop_time \"HH:MM\"\n```\n\nThe stop command ends time tracking for the current entry. You can:\n- Add an optional comment in quotes to describe what was completed\n- Specify a custom stop time using --stop_time (or -s) in 24-hour format (HH:MM or HH:MM:SS) or AM/PM format\n- Use stop without a comment to simply end tracking\n- If no stop time is specified, the current time is used\n\n### Check status\n```shell\nsigye status\n```\n\n### List Entries\n#### List All Entries\n```shell\nsigye list\n```\n#### List Filtered Entries\n\nAll entries from a named time frame (options: `today`, `yesterday`, `week` and `month`):\n```shell\nsigye list TIMEFRAME\n```\n\nAll entries for a certain project (or list of projects)\n```shell\nsigye list --project abc-1234 --project abc-1233\n```\n\nEntries that \"start with\" a project name (note: you can use `+` or `.` or `*`):\n```\nsigye list --project abc+\n```\n\nAll entries with any tag matching a tag or multiple tags:\n```\nsigye list --tag mytag\n```\n\n#### List Entries in a Different format\n\nThe output format can be set/overridden with the `--output_format` or `-o` option.\n\nValid options are:\n* `rich` -- colorized text with ascii/unicode characters for nicer display. This is the default output if the `sigye` command is not being redirected somewhere besides `stdout`.\n* `text` -- an extremely plain output mostly used for testing.\n* `json` -- output in JSON format. This is the default if no option is provided and `stdout` is redirected.\n* `yaml` -- output in YAML format, suitable for exporting entries to a new file.\n\nExample:\n\n```\nsigye -o yaml list --project abc.\n```\n\nThe above would list all entries that have a project that starts with \"abc\" in yaml format.\n\n### Edit Entries\nTo 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.\n```shell\nsigye edit ID\n```\n\n## Configuration\n\nsigye can be configured using a YAML configuration file located at `~/.sigye/config.yaml`. Here's an example configuration file with available options:\n\n```yaml\n# Override the default locale (en_US)\n# locale: ko_KR\n# data_filename: /full/path/to/a/file.yaml\n# Auto-tagging rules\n# Each rule consists of:\n# - pattern: regular expression pattern to match against project name\n# - match_type: how to match the pattern (regex)\n# - tags: list of tags to apply when pattern matches\nauto_tag_rules:\n - pattern: \"^abc\" # Matches projects starting with \"abc\"\n match_type: \"regex\"\n tags: [\"learning\"]\n \n - pattern: \"^PROJ-\\\\d+\" # Matches PROJ- followed by numbers\n match_type: \"regex\"\n tags: [\"work\", \"billable\"]\n \n - pattern: \".*-urgent$\" # Projects ending with \"-urgent\"\n match_type: \"regex\"\n tags: [\"urgent\", \"high-priority\"]\n \n - pattern: \"(feature|bugfix)/\" # Projects containing feature/ or bugfix/\n match_type: \"regex\"\n tags: [\"development\"]\n```\n\nThe auto-tagging rules automatically apply tags to your time entries based on the project name. This helps maintain consistent tagging across similar projects without having to manually specify tags each time.\n\n### Localization Support (experimental Korean output)\nTo get *output* in Korean:\n`export SIGYE_LOCALE=ko_KR`\n\nThe `sigye list` and `sigye status` commands will now output some information in Korean.\n\n> [!NOTE]\n> This work is ongoing and subject to change.\n\n## Development\n\n### Install requirements\n\nThis project uses `uv` for dependency management.\n\n### Running tests\n\n```shell\nuv run pytest\n```\n\n## Future Changes\n\n* Configuration file support\n * YAML (mostly complete now)\n * TOML\n* Language Localization (in-progress)\n* SQLite storage\n* TOML storage\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "(\uc2dc\uacc4) A simple command-line program for tracking time.",
"version": "0.9.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd31d41573b3236be781ba59e351092c4923c7a04f78d27ee40f4884ec05d195",
"md5": "08ab792f9f6f6c26bfca9d06728b958c",
"sha256": "40215d19fa8a40068ea91017ee4f5b05c4c9aa25ffe6726d60f492d6cd3a79ef"
},
"downloads": -1,
"filename": "sigye-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08ab792f9f6f6c26bfca9d06728b958c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 31560,
"upload_time": "2024-12-15T15:27:38",
"upload_time_iso_8601": "2024-12-15T15:27:38.510312Z",
"url": "https://files.pythonhosted.org/packages/fd/31/d41573b3236be781ba59e351092c4923c7a04f78d27ee40f4884ec05d195/sigye-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a596dce809eddd2e8c999f87f1a2ed03d94b6c1e1de8683d509de1960dc6196a",
"md5": "2d5ee0d82dfc5aa60aa0e3a54ca96c44",
"sha256": "d2393b51ced95f89a4ac1d1c324f63562d4c10cf33ebf97c404cac0fdc2d7600"
},
"downloads": -1,
"filename": "sigye-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "2d5ee0d82dfc5aa60aa0e3a54ca96c44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 35735,
"upload_time": "2024-12-15T15:27:40",
"upload_time_iso_8601": "2024-12-15T15:27:40.350696Z",
"url": "https://files.pythonhosted.org/packages/a5/96/dce809eddd2e8c999f87f1a2ed03d94b6c1e1de8683d509de1960dc6196a/sigye-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 15:27:40",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sigye"
}
