{"id":17148747,"url":"https://github.com/trustmaster/gkeeptodo","last_synced_at":"2025-03-24T11:41:00.594Z","repository":{"id":140830799,"uuid":"310899133","full_name":"trustmaster/gkeeptodo","owner":"trustmaster","description":"Statistics and planner tool for Google Keep task lists","archived":false,"fork":false,"pushed_at":"2021-01-06T18:12:28.000Z","size":187,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-29T16:44:06.683Z","etag":null,"topics":["google-keep"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trustmaster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-07T17:40:47.000Z","updated_at":"2021-01-06T18:12:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"e19bed76-dde4-4dd8-afaf-ee7c79abd65b","html_url":"https://github.com/trustmaster/gkeeptodo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustmaster%2Fgkeeptodo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustmaster%2Fgkeeptodo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustmaster%2Fgkeeptodo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustmaster%2Fgkeeptodo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trustmaster","download_url":"https://codeload.github.com/trustmaster/gkeeptodo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245265844,"owners_count":20587407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-keep"],"created_at":"2024-10-14T21:29:43.524Z","updated_at":"2025-03-24T11:41:00.570Z","avatar_url":"https://github.com/trustmaster.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Google Keep TODO\n\nStatistics exporter and task planner for Google Keep task lists.\n\n![Example user flow](./example_flow.png)\n\nCommands:\n\n- `stats` - export statistics for task lists as CSV\n- `plan` - schedule regular task lists from template\n\nFeatures:\n\n- Calculate overall completion rate for task lists by keyword\n- Aggregate task list completion daily/weekly/monthly/yearly\n- Export time series data and aggregates as CSV\n- Configurable date formats\n\nSupported metrics:\n\n- Number of checked items\n- Number of unchecked items\n- Total items\n- Completion rate\n\n## Installation\n\nThis script requires Python 3.9+, https://github.com/kiwiz/gkeepapi, and a couple more libraries to run. Install the pre-requisite libraries via Pip3:\n\n```\npip3 install -r requirements.txt\n```\n\nOptional: make the script executable:\n\n```\nchmod +x gkeeptodo.py\n```\n\n### Preventing \"Authentication failed\" on some systems\n\nOn some systems the authentication fails even with valid credentials. This may happen because of two reasons: either Google issues a CAPTCHA for your IP address, or SSL certificate validation fails.\n\nTo fix the CAPTCHA problem, try using the [Unlock CAPTCHA link](https://accounts.google.com/DisplayUnlockCaptcha) before retrying login.\n\nTo try fixing the SSL problem, revert to an older version of the following library:\n\n```\npip3 install requests==2.23.0\n```\n\n## Usage\n\nThis tool is configured via a config file, to avoid reentering parameters on every call. Copy the example config file:\n\n```\ncp gkeeptodo.example.ini gkeeptodo.ini\n```\n\nAnd edit it to come up with your own setup.\n\nThen you can simply call the script in one of the available ways:\n\n```\npython3 gkeeptodo.py\n# or\n./gkeeptodo.py\n```\n\nFor available command line options see the help page:\n\n```\n./gkeeptodo.py -h\n```\n\n### Authentication\n\ngkeeptodo can use the operating system key ring to save the access token securely. First time you need to authenticate with your password by running the `login` command:\n\n```\n./gkeeptodo.py login\n```\n\nIf it authenticates successfully and your operating system supports key ring, access token is saved and from the next time onwards you can use it without `login` and password prompt won't be necessary:\n\n```\n./gkeeptodo.py\n```\n\n### Collecting statistics\n\nDefault command is `stats` which collects statistics, given the metrics configured in the config file. Calling\n\n```\n./gkeeptodo.py stats\n```\n\nis equivalent to just\n\n```\n./gkeeptodo.py\n```\n\nTo filter the data by date range use the `--from-date` (`-f`) and `--to-date` (`-t`) options, e.g.:\n\n```\n./gkeeptodo.py stats -f 2020-01-01 -t 2020-12-31\n```\n\nThe range boundaries are inclusive. If any of these two options is omitted, the boundary stays open and includes all data available.\n\n### Output\n\nBy default, CSV export is written to files in the current folder. Each metric is written in a separate file called `{Metric}_{mode}_{timestamp}.csv`.\n\nYou can disable CSV export by adding `--dry` option:\n\n```\n./gkeeptodo.py --dry\n```\n\nUse the `--verbose` or `-v` option to enable verbose printing of the results in the console, e.g.:\n\n```\n./gkeeptodo.py -v\n./gkeeptodo.py -v --dry\n```\n\n### Planning repetitive task lists\n\nWith\n\n```\n./gkeeptodo.py plan -f \u003cfrom-date\u003e -t \u003cto-date\u003e\n```\n\nyou can create repetitive task lists in your Google Keep account from template. An example template is described in [gkeeptodo.example.ini](./gkeeptodo.example.ini). More information on how to configure templates in the [Configuration section](#Templates).\n\nFor instance, if you have a `daily` template configured in the `gkeeptodo.ini` file, you can generate a task list per each day from 1st of January 2021 to 9th of January 2021 with the following command:\n\n```\n./gkeeptodo.py plan -f 2021-01-01 -t 2021-01-09\n```\n\n## Configuration\n\nThis section describes configuration options available in `gkeeptodo.ini` file. See also [gkeeptodo.example.ini](./gkeeptodo.example.ini).\n\n### User\n\nThe user section is an easy way to save your Google account, so you don't have to enter it manually every time you use the command.\n\n```ini\n[user]\nemail=user.email@example.com\n```\n\n### Formats\n\nThe formats section sets up date formats that you use in the titles for your task lists. It helps the program parse your TODO titles like `Cooking 2020-12-30` and understand that the task category is `Cooking` and the date is `30th of December, 2020`. Or vice versa, when generating TODOs from templates, it helps to put the correct dates in the generated task list titles.\n\n The script uses directives described in [Python's strptime function docs](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior). The default ones use ISO-like formats:\n\n```ini\n[formats]\nyearly=%Y      # example: 2020\nmonthly=%Y-%m  # example: 2020-12\nweekly=%Y-W%W  # example: 2020-W52\ndaily=%Y-%m-%d # example: 2020-12-24\n```\n\nFor example, `%Y` will be replaced with an actual year and become `2021`. Or vice versa, when scanning your TODOs, given `%Y` in the date pattern, it expects a year number to be in that position.\n\nHere is another example using US date format:\n\n```ini\n[formats]\nyearly=%Y      # example: 2020\nmonthly=%B %Y  # example: December 2020\nweekly=%Y-W%W  # example: 2020-W52\ndaily=%m/%d/%Y # example: 12/24/2020\n```\n\n### Metrics\n\nMetrics configure statistics collected per category. Each `metric` entry corresponds to one category. There can be multiple metrics in the configuration, and each metric may collect data and output statistics in multiple modes. Example:\n\n```ini\n[metric: Work]\nkeyword=Work\nmodes=total, weekly, monthly\n```\n\nIn this example we create a metic called `Work` which measures progress on task lists in \"Work\" category.\n\nThe `keyword` is used as a category prefix. The script will search all your Google Keep task lists that start with that keyword and are followed by corresponding date formats (see Formats section above). For example, it will match entries like `Work 2020-12-01` and `Work 2020-12-02` and put them in category `Work` as 2 data points for different days.\n\nThe `modes` is a comma separated list of interval types which you want to collect statistics for. For example, if you want statistics aggregated by month, you should add `monthly` mode to the list. In the above example we ar interested in overall statistics, as well as data aggregated by week and month.\n\nAll supported modes are:\n\n- `total` - overall statistics for all time\n- `yearly` - statistics aggregated by year\n- `monthly` - statistics aggregated by month\n- `daily` - statistics for every day\n\n### Templates\n\nTemplates are used to [plan repetitive task lists](#Planning-repetitive-task-lists). Each `template` entry configures a task list. You can add more than one template in configuration.\n\nExample:\n\n```ini\n[template: Wellness]\ntitle=Wellness {date} # {date} is replaced with actual formatted date\nitems=Meditate, Walk outside, Workout\nmode=daily\nlabels=personal # optional, comma separated\ncolor=green # optional\n```\n\nThe name of this template is `Wellness`. And as the `title` goes, each title will start with prefix `Wellness` followed by a date, e.g. `2020-12-24`.\n\nThe `mode` setting configures the frequency interval, which is used to generate a sequence of task lists with this template. Valid modes are: `daily`, `weekly`, `monthly`, `yearly`. For example, in `weekly` mode given a range from `2021-01-01` to `2021-01-30` the tool will generate 5 task lists: `2020-W53`, `2021-W01`, `2021-W02`, `2021-W03`, `2021-W04`, each of them prefixed with the keyword according to `title` format (which is \"Wellness\" in the example above).\n\nThe `items` option contains comma separated tasks for the task list.\n\nThe `labels` are comma separated labels. You should already have these labels configured in your Google Keep account, non-existent labels are ignored. This setting is optional.\n\nThe `color` option assigns a color to the note in Google Keep. Supported values: `blue`, `brown`, `dark-blue`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `white`, `yellow`. This setting is optional.\n\n## Credits\n\nThis tool uses the unofficial Google Keep API https://github.com/kiwiz/gkeepapi by [kiwiz](https://github.com/kiwiz). Google Keep is of course a registered trademark of Google and neither the API nor this script are affiliated with Google.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustmaster%2Fgkeeptodo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrustmaster%2Fgkeeptodo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustmaster%2Fgkeeptodo/lists"}