yatesjr / toggl-cmder Goto Github PK

This project started as a way for me to easily start and stop timers right from the command line. It sports a regex to help find items without needing to spell them perfectly.

License: Apache License 2.0

Python 100.00%

python toggl cli rest-client

toggl-cmder's Introduction

togglcmder

This script allows a user to control Toggl via the REST API.

Features

Complete control over Toggl projects, tags, and timers.
Easily stop and resume timers.
- togglcmder timers stop: will stop the current timer.
- togglcmder timers resume: will resume the most recently stopped timer.
Ability to download and view details on workspaces, projects, timers, and tags.
Support for Python regex in all search fields, so that you don't need to know the exact name of an item to find it or restart it (or even delete it).
- togglcmder timers --workspace '.*' list: list all timers in all workspaces.
- togglcmder timers list --description '^Python\s.*$': match any timer with Python in the description.
Update projects, tags, and timers with various details.
- Add a new tag to an old timer.
- Remove tags from old timers.
- Change the color designation of a project.

Installation

From the directory where you cloned this repository:

python3 -m venv $(pwd)/venv

source $(pwd)/venv/bin/activate

pip install -r requirements.txt

From PyPI via pip:

pip install togglcmder

Usage Requirements

You must log in to the Toggl site and retrieve the API key to access the API using this script.

Login to the Toggl site.
Go to https://toggl.com/app/profile and find the API key at the bottom of the page.
Run the following command to initialize the configuration:
1. togglcmder --api-key <YOUR_API_KEY>
Sync remote changes to the local database:
1. togglcmder --sync workspaces
You may test the connection by simply running togglcmder workspaces.
1. It should at least your personal workspace.

Usage

The script will attempt to download data from the Toggl servers and store the data in a local cache file. For Linux users this will be in ~/.config/togglcmder/cache.db. This file is a SQLITE database. For Windows users it will be in %APPDATA%/togglcmder. This tool has not been tested on Windows. You may pass --help to most sub commands to get more information on them.

Main Options

Usage: togglcmder [OPTIONS] COMMAND [ARGS]...

Options:
  --api-key TEXT                  Your API key for the Toggl API
  --reset-api-key                 Resets the Toggl API key and downloads it to
                                  the local device.
  --default-workspace TEXT        Specify a default workspace to use when
                                  otherwise not specified.
  --default-project TEXT          Specify a default project to use when
                                  otherwise not specified.
  --default-tags TEXT             Specify some default tags to always include
                                  for timers started on this machine.
  --default-time-entry-start-days INTEGER
                                  Specify some default start time to refresh
                                  time entries.
  --default-time-entry-stop-days INTEGER
                                  Specify some default stop time to refresh
                                  time entries.
  -v, --verbosity
  --version
  --sync                          Download from remote Toggl servers before
                                  attempting item lookups.  [default: False]
  --show-config                   Simply prints the current configuration.
  --help                          Show this message and exit.

Commands:
  projects    Add, update, delete, and list projects.
  tags        Add, update, delete, and list tags.
  timers      Add, update, delete, start, stop, and list timers.
  workspaces  List the currently available workspaces.

Project Options

Usage: togglcmder projects [OPTIONS] COMMAND [ARGS]...

  Add, update, delete, and list projects.

Options:
  --workspace TEXT
  --help            Show this message and exit.

Commands:
  add
  delete
  list
  update

Tag Options

Usage: togglcmder tags [OPTIONS] COMMAND [ARGS]...

  Add, update, delete, and list tags.

Options:
  --workspace TEXT
  --help            Show this message and exit.

Commands:
  add
  delete
  list
  update

Timer Options

Usage: togglcmder timers [OPTIONS] COMMAND [ARGS]...

  Add, update, delete, start, stop, and list timers.

Options:
  --workspace TEXT
  --project TEXT
  --download-start VALIDATED_TIME
                                  This can be now[-/+[dhms]] or an iso
                                  formatted time string.
  --download-stop VALIDATED_TIME  This can be now[-/+[dhms]] or an iso
                                  formatted time string.
  --help                          Show this message and exit.

Commands:
  add      Add a completed time entry.
  current  Get the current running timer, if one exists.
  delete
  list
  resume   Resume the most recent timer.
  start    Start a new running timer.
  stop     Stop the current running timer, if one exists.
  update   Update an existing time entry with new details.

######NOTE

You can get more information on sub-commands by running help, for instance: togglcmder timers update --help

Usage Examples

First Run

Required for usage.

togglcmder --api-key b81d43def5cd60acea1e44ad319a7979

Automatically Reset the API Key

This will automatically download and store a new API key for you.

togglcmder --reset-api-key

Setting Up a Default Workspace

togglcmder --default-workspace Personal

Setting Up a Default Project

togglcmder --default-project CoolProject

Listing All Projects in the Default Workspace

togglcmder projects list

Listing All Projects in a Specific Workspace

togglcmder projects --workspace 'Work' list

Adding a New Project to the Default Workspace

togglcmder projects add --name 'Cool Project'

Adding a New Tag to the Default Workspace

togglcmder tags add --name 'cool_new_tag'

Starting a New Timer with the Default Workspace and Project

togglcmder timers start --description "I'm doing some work.." --tags "cool_new_tag,cool_old_tag"

Display the Current Timer

togglcmder timers current

Stopping the Current Timer

togglcmder timers stop

Adding a Timer that has already Completed with Default Project and Workspace

togglcmder timers add --description 'I already did this work.' --start-time "2020-03-10 01:00:00" --stop-time "2020-03-10 02:00:00" --tags "tag_one,tag_two"

Troubleshooting

If there are any issues you have come across, please open a new issue or email me.

Limitations

This does not support Toggl Pro; I have no plans to implement this support. Feel free to open a pull request if you feel like adding that kind of support!

toggl-cmder's People

Contributors

Stargazers

Watchers

toggl-cmder's Issues

When listing items (such as tags or time entries), you should be able to filter on workspace and projects.

Is your feature request related to a problem? Please describe.
When printing the list of tags, all tags are printed. This can be hard to filter visually.

Describe the solution you'd like
An extra option can be passed when listing items to filter on workspace or projects.

Using --current to get details on latest timer no longer works.

Describe the bug
When you use python toggl-cmder --current it should return the latest running timer.

To Reproduce
Steps to reproduce the behavior:

Start a timer via the website.
Run python toggl-cmder --current..
An exception is thrown:

--- Logging error ---
Traceback (most recent call last):
  File "/usr/lib/python3.7/logging/__init__.py", line 1025, in emit
    msg = self.format(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 869, in format
    return fmt.format(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 608, in format
    record.message = record.getMessage()
  File "/usr/lib/python3.7/logging/__init__.py", line 367, in getMessage
    msg = str(self.msg)
  File "toggl-cmder/toggl/time_entry.py", line 111, in __str__
    self.__project.name,
AttributeError: 'NoneType' object has no attribute 'name'
Call stack:
  File "/usr/lib/python3.7/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.7/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "toggl-cmder/__main__.py", line 107, in <module>
    logger.info(time_entry)
Message: <toggl.time_entry.TimeEntry object at 0x7f21672d4350>
Arguments: ()
--- Logging error ---
Traceback (most recent call last):
  File "/usr/lib/python3.7/logging/__init__.py", line 1025, in emit
    msg = self.format(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 869, in format
    return fmt.format(record)
  File "/usr/lib/python3.7/logging/__init__.py", line 608, in format
    record.message = record.getMessage()
  File "/usr/lib/python3.7/logging/__init__.py", line 367, in getMessage
    msg = str(self.msg)
  File "toggl-cmder/toggl/time_entry.py", line 111, in __str__
    self.__project.name,
AttributeError: 'NoneType' object has no attribute 'name'
Call stack:
  File "/usr/lib/python3.7/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.7/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "toggl-cmder/__main__.py", line 107, in <module>
    logger.info(time_entry)
Message: <toggl.time_entry.TimeEntry object at 0x7f21672d4350>
Arguments: ()

Expected behavior
Details about the current timer should be shown.

Application (please complete the following information):

Python Version == 3.7.4
Toggl-Cmder Version == 1.0.0

Documentation needs to be updated to reflect all the latest changes.

Describe the bug
No bug; documentation needs to be updated/improved to include all possible arguments.

Toggl-Cmder Version: latest

Tags passed to start-timer don't make it to the started timer.

Describe the bug
When starting a new timer, if you pass tags, they don't make it to the timer as viewed on the Toggl web interface.

To Reproduce
Steps to reproduce the behavior:

Run python toggl-cmder start-timer --description TimerDescription --workspace TimerWorkspace --project TimerProject --tags "tagOne,tagTwo"..
Timer starts, but tags aren't present when viewing the current running timer via the tool or the web interface Toggl provides.

Expected behavior
Tags should be transmitted along with the start timer request.

Application (please complete the following information):

Python Version==3.7.4
Toggl-Cmder Version==1.1.0

Allow 'resume' option to take arguments specifying pattern matching description.

Is your feature request related to a problem? Please describe.
Right now, resume only works with the latest timer. If you're working on many different things, it would be helpful to have resume support taking an argument to resume a specific timer.

Describe the solution you'd like
Resume option should take something like:
--description "timer description"

The script, when using --list-<item>, always assumes there is at least 1 item.

Describe the bug
When a new user calls --list-tags or any of the others, if there are no entries available, an exception is thrown.

To Reproduce
Steps to reproduce the behavior:

Run python toggl-cmder --list-tags as a new user with no tags.
An exception is thrown.

Application (please complete the following information):

Python Version == 3.7.4
Toggl-Cmder Version == 1.0.0

When listing projects or time entries, the workspace should be listed as name rather than ID.

Currently the list functionality does not print the name of the workspace when listing a project. It would be helpful to get the actual name in the workspace that a project belongs to.

json isn't being parsed properly

Describe the bug
There are multiple classes attempting to parse JSON when there should be one that creates different objects depending on the JSON data. JSON is parsed from the inside out and objects are updated in-place, so we don't need to handle the recursive parsing ourselves.

Should be able to resume a a recent running timer that has been stopped.

Is your feature request related to a problem? Please describe.
Currently, there is no way to resume a recently stopped timer. You can only create new timers.

Describe the solution you'd like
Simply being able to resume timers.

Duration in logs should show time unit being used.

Is your feature request related to a problem? Please describe.
Right now a number of unknown units is shown when running --current or --list-time-entries. It would increase clarity if the unit of time was shown. This is seconds.

Describe the solution you'd like
Show the unit of time, but also change the unit depending on the amount of seconds... seconds -> minutes -> hours.

Toggl recently rebranded; the API urls need to be updated.

Describe the bug
The old API URL is: https://www.toggl.com/api
The new API URL is: https://api.track.toggl.com/api

NOTE: the tool still works as-is, but it's to be expected that Toggl will deprecate the old API URL eventually.

Additional context
API docs: https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md

Enable user data caching.

I'd like to be able to save, or cache, the data downloaded from Toggl. I'm not sure how useful this will be or how to determine when the cache needs to be updated, but it should be helpful for debugging or just exploring the data (and importing into other sinks).

The data should be cached as JSON (which is what the Toggl API returns). The script reads the data and converts the JSON into Python objects, so reading cached data into the script would be handled the same way.

Need to be able to modify already existing items.

Is your feature request related to a problem? Please describe.
To modify items, you currently need to go to the Toggl website and make the changes there.

Describe the solution you'd like
The script needs support for modifying existing items.

Enable publishing of the script to PyPI.

Is your feature request related to a problem? Please describe.
It would be good if this was available via pip.

Describe the solution you'd like
Follow this guide to publish the script: https://realpython.com/pypi-publish-python-package/

The command add-project fails because it expects a project argument.

Describe the bug
The command add-project fails; the code expects the project argument instead of the name argument.

To Reproduce
Steps to reproduce the behavior:

Run python toggl-cmder add-project --name ProjectName --workspace ProjectWorkspace..
Exception:

Traceback (most recent call last):
  File "/usr/lib/python3.7/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.7/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "toggl-cmder/__main__.py", line 168, in <module>
    args.project,
AttributeError: 'Namespace' object has no attribute 'project'

Expected behavior
Should be able to add a new project.

Application (please complete the following information):

Python Version==3.7.4
Toggl-Cmder==1.1.0

Need to be able to delete items from the CLI.

It would be useful to be able to delete items from a workspace (such as removing unnecessary tags or time entries).

Failure to start a new timer when no workspace or project is provided.

Describe the bug
When omitting the workspace/project, the timer fails to start and the script throws an exception.

To Reproduce

Attempt to start a new timer without providing the workspace or project.

python toggl-cmder start-timer --description test
Traceback (most recent call last):
  File "toggl-cmder/__main__.py", line 143, in <module>
    args.project)
  File "toggl-cmder/toggl/user.py", line 94, in find_time_entry
    raise ValueError("no time entries exist in user data")
ValueError: no time entries exist in user data

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3.7/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.7/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "toggl-cmder/__main__.py", line 147, in <module>
    workspace = user_data.find_workspace(args.workspace)
  File "toggl-cmder/toggl/user.py", line 131, in find_workspace
    self.__workspaces), None)
  File "toggl-cmder/toggl/user.py", line 130, in <lambda>
    re.IGNORECASE),
  File "/usr/lib/python3.7/re.py", line 183, in search
    return _compile(pattern, flags).search(string)
  File "/usr/lib/python3.7/re.py", line 285, in _compile
    raise TypeError("first argument must be string or compiled pattern")
TypeError: first argument must be string or compiled pattern

Expected behavior
The API does not require workspace and project to be there when starting a new timer; this should be allowed.

Application (please complete the following information):

Python Version: 3.7.4
Toggl-Cmder Version: 1.0.0

Argument start-timer no longer works as the start URL is invalid

Describe the bug
After a while of not using Toggl, attempting to start a new timer fails.

To Reproduce
Steps to reproduce the behavior:

Run python toggl-cmder start-timer --description 'working on GH-2' --project toggl-cmder --tags prog:python,skill:programming,type:tools --workspace personal..
An exception is thrown because the endpoint is invalid.

Expected behavior
I expected to be able to start a new timer.

Application (please complete the following information):

Python Version == 3.7.4
Toggl-Cmder Version == 1.0.0

When the default workspace is invalid, adding a new tag results in a message that says 'a workspace must be provided'.

Describe the bug
The functionality to add a new tag depends on an existing workspace. If the default workspace is invalid, then adding a new tag (or possibly others), results in a message that says 'a workspace must be provided'. It would be more help to have a more descriptive error message, something like 'the current default workspace is invalid, provide an alternative'.

To Reproduce
Steps to reproduce the behavior (this assumes togglcmder is installed):

Run togglcmder --default-workspace someinvalidworkspace to set an invalid workspace.
Run togglcmder tags add --name newtag
The error message produced:

Expected behavior
Need a clear error message so that users can resolve the issue with less confusion.

Application (please complete the following information):

Python Version: 3.8.5
Toggl-Cmder Version: 2.0.5

yatesjr / toggl-cmder Goto Github PK

toggl-cmder's Introduction

togglcmder

Features

Installation

Usage Requirements

Usage

Main Options

Project Options

Tag Options

Timer Options

Usage Examples

First Run

Automatically Reset the API Key

Setting Up a Default Workspace

Setting Up a Default Project

Listing All Projects in the Default Workspace

Listing All Projects in a Specific Workspace

Adding a New Project to the Default Workspace

Adding a New Tag to the Default Workspace

Starting a New Timer with the Default Workspace and Project

Display the Current Timer

Stopping the Current Timer

Adding a Timer that has already Completed with Default Project and Workspace

Troubleshooting

Limitations

toggl-cmder's People

Contributors

Stargazers

Watchers

toggl-cmder's Issues

Recommend Projects

Recommend Topics

Recommend Org