Package: next-action
Next-actionDetermine the next action to work on from a list of actions in a todo.txt file.Don't know whatTodo.txtis? Seehttps://github.com/todotxt/todo.txtfor theTodo.txtspecification.Next-actionis not a tool for editing todo.txt files, seehttp://todotxt.orgfor available options.Table of contentsDemoInstallationNext-actionTab completion forNext-actionUsageLimiting the tasks from which next actions are selectedShowing more than one next actionTask dependenciesOutput optionsConfiguringNext-actionOption detailsRecent changesDevelopingNext-actionInstalling the development environment and dependenciesRunning unit testsRunning feature testsRunning quality checksGenerating documentationSource code structure and dependenciesDemoInstallationNext-actionNext-actionrequires Python 3.6 or newer.pip install --upgrade next-actionTab completion forNext-actionTo install tab completion forNext-actionin the Bash shell, follow these steps:Downloadextra/.next-action-completion.bashand save it in your home folder.Next, add this line to your~/.bash_profilefile:source~/.next-action-completion.bashThen, open a new terminal.Typingnext-action [TAB]should give you the possible command line options. Hitting tab after an option that takes
arguments, shows the possible arguments.Usage$next-action--helpUsage: next-action [-h] [-V] [-c [<config.cfg>] | -w] [-f <todo.txt> ...] [-b] [-g [<group>]] [-l] [-r <ref>][-s [<style>]] [-a | -n <number>] [-d [<due date>] | -o] [-p [<priority>]] [-u] [--] [<context|project>...]Show the next action in your todo.txt. The next action is selected from the tasks in the todo.txt file basedon task properties such as priority, due date, and creation date. Limit the tasks from which the next actionis selected by specifying contexts the tasks must have and/or projects the tasks must belong to.Optional arguments:-h, --help            show this help message and exit-V, --version         show program's version number and exitConfiguration options:-c [<config.cfg>], --config-file [<config.cfg>]filename of configuration file to read (default: ~/.next-action.cfg); omit filenameto not read any configuration file-w, --write-config-filegenerate a sample configuration file and exitInput options:-f <todo.txt>, --file <todo.txt>filename of todo.txt file to read; can be '-' to read from standard input; argumentcan be repeated to read tasks from multiple todo.txt files (default: ~/todo.txt)Output options:-b, --blocked         show the tasks blocked by the next action, if any (default: False)-g [<group>], --groupby [<group>]group the next actions; available groups: context, duedate, priority, project,source (default: None)-l, --line-number     reference next actions with the line number in their todo.txt file (default: False)-r {always,never,multiple}, --reference {always,never,multiple}reference next actions with the name of their todo.txt file (default: when readingmultiple todo.txt files)-s [<style>], --style [<style>]colorize the output; available styles: abap, algol, algol_nu, arduino, autumn,borland, bw, colorful, default, emacs, friendly, fruity, igor, lovelace, manni,monokai, murphy, native, paraiso-dark, paraiso-light, pastie, perldoc, rainbow_dash,rrt, sas, solarized-dark, solarized-light, stata, stata-dark, stata-light, tango,trac, vim, vs, xcode (default: None)-u, --open-urls       open the urls in the next actions, if any (default: False)Show multiple next actions:-a, --all             show all next actions-n <number>, --number <number>number of next actions to show (default: 1)Limit the tasks from which the next actions are selected:-d [<due date>], --due [<due date>]show only next actions with a due date; if a date is given, show only next actionsdue on or before that date-o, --overdue         show only overdue next actions-p [<priority>], --priority [<priority>]minimum priority (A-Z) of next actions to show (default: None)@<context> ...        contexts the next action must have+<project> ...        projects the next action must be part of; if repeated the next action must be partof at least one of the projects-@<context> ...       contexts the next action must not have-+<project> ...       projects the next action must not be part ofUse -- to separate options with optional arguments from contexts and projects, in order to handle caseswhere a context or project is mistaken for an argument to an option.Assuming your todo.txt file is in your home folder, runningNext-actionwithout arguments will show the next action
you should do. For example, given thistodo.txt, calling mom would be the next
action:$next-action(A)Call mom @phoneThe next action is determined using priority. Due date is considered after priority, with tasks due earlier getting
precedence over tasks due later. Creation date is considered after due date, with older tasks getting precedence over
newer tasks. Finally, tasks that belong to more projects get precedence over tasks that belong to fewer projects.Several types of tasks can not be a next action:completed tasks (x This is a completed task),tasks with a creation date in the future (9999-01-01 Start preparing for five-digit years),tasks with a future threshold date (Start preparing for emigration to Mars t:3000-01-01),blocked tasks (seetask dependenciesbelow), andhidden tasks (This is a hidden task h:1).Limiting the tasks from which next actions are selectedBy contexts and/or projectsYou can limit the tasks from whichNext-actionpicks the next action by passing contexts and/or projects:$next-action@work(C)Finish proposal for important client @work$next-action+DogHouse(G)Buy wood for new +DogHouse @store$next-action+DogHouse@homeGet rid of old +DogHouse @homeWhen you supply multiple contexts and/or projects, the next action belongs to all of the contexts and at least one of
the projects:$next-action+DogHouse+PaintHouse@store@weekend(B)Buy paint to +PaintHouse @store @weekendIt is also possible to exclude contexts, which means the next action will not have the specified contexts:$next-action+PaintHouse-@storeBorrow ladder from the neighbors +PaintHouse @homeAnd of course, in a similar vein, projects can be excluded:$next-action-+PaintHouse@store(G)Buy wood for new +DogHouse @storeIf no tasks match the combination of tasks and projects, it's time to get some coffee:$next-action+DogHouse@weekendNothing to do! 😴If there's nothing to do because you use contexts or projects that aren't present in the todo.txt file,Next-actionwill warn you:$next-action+PaintGarage@freetimeNothing to do! (warning: unknown context: freetime; unknown project: PaintGarage)By due dateTo limit the the tasks from which the next action is selected to actions with a due date, use the--dueoption:$next-action@home--due(K)Pay October invoice @home due:2020-10-28Add a due date to select a next action from tasks due on or before that date:$next-action@home--due"2020-10-01"(L)Pay September invoice @home due:2020-09-28To make sure you have no overdue actions, or work on overdue actions first, limit the tasks from which the next action
is selected to overdue actions:$next-action--overdueBuy flowers due:2018-02-14By priorityTo make sure you work on important tasks rather than urgent tasks, you can make sure the tasks from which the
next action is selected have at least a minimum priority:$next-action@work--priorityC(C)Finish proposal for important client @workShowing more than one next actionTo show more than one next action, supply the number you think you can handle:$next-action--number3(A)Call mom @phone(B)Buy paint to +PaintHouse @store @weekend(C)Finish proposal for important client @workOr show all next actions, e.g. for a specific context:$next-action--all@store(B)Buy paint to +PaintHouse @store @weekend(G)Buy wood for new +DogHouse @storeBuy groceries @store +DinnerParty before:mealNote again that completed tasks, tasks with a future creation or threshold date, and blocked tasks are never the next
action.Task dependenciesNext-actiontakes task dependencies into account when determining the next actions. For example, that cooking a meal
depends on buying groceries and that doing the dishes comes after cooking the meal can be specified as follows:$grep+DinnerPartydocs/todo.txtBuy groceries @store +DinnerParty before:mealCook meal @home +DinnerParty id:meal due:2018-07-01Take out the garbage @home +DinnerParty due:2018-07-02Do the dishes @home +DinnerParty after:mealThis means that buying groceries blocks cooking the meal; cooking, and thus doing the dishes as well, can't be done
until buying the groceries has been completed:$next-action--all+DinnerPartyBuy groceries @store +DinnerParty before:mealTake out the garbage @home +DinnerParty due:2018-07-02Note how buying the groceries comes before taking out the garbage even though buying the groceries has no due date and
taking out the garbage does. As buying groceries has to be done before cooking the meal and cooking the meal does have
a due date, buying groceries takes on the same due date as cooking the meal. Priority is taken into account in a
similar way.To show which tasks are blocked by the next action, use the--blockedoption:$next-action--blocked--all+DinnerPartyBuy groceries @store +DinnerParty before:mealblocks:- Cook meal @home +DinnerParty id:meal due:2018-07-01blocks:- Do the dishes @home +DinnerParty after:mealTake out the garbage @home +DinnerParty due:2018-07-02If you always want to see the tasks that are blocked by the next action, you can configure this in the configuration
file. See the section below on how to configureNext-action.Additional notes:The ids can be any string without whitespace.Instead ofbeforeyou can also usep(for "parent") because some other tools that work withTodo.txtfiles
use that.A task can block multiple other tasks by repeating the before key,
e.g.Buy groceries before:cooking and before:sending_invites.A task can be blocked by multiple other tasks by repeating the after key,
e.g.Eat meal after:cooking and after:setting_the_table.If a task blocks one or more tasks, the blocking task takes on the priority and due date of the tasks it is blocking:the blocking task is considered to have a priority that is the maximum of its own priority and the priorities of
the tasks it is blocking, andthe blocking task is considered to have a due date that is the minimum of its own due date and the due dates of
the tasks it is blocking.Output optionsBy default,Next-actionreferences the todo.txt file from which actions were read if you read tasks from multiple
todo.txt files. The--referenceoption controls this:$next-action--referencealways(A)Call mom @phone [docs/todo.txt]Use--reference neverto not show the source files, even when tasks are read from multiple todo.txt files. To
permanently change this, configure thereferenceoption in the configuration file. See the section below on how to
configureNext-action.To makeNext-actionreference the line number that tasks have in their source todo.txt files, use the--line-numberoption:$next-action--line-number(A)Call mom @phone [1]It's also possible to haveNext-actionshow both the source file and the line number:$next-action--line-number--referencealways(A)Call mom @phone [docs/todo.txt:1]See the section below on how to configureNext-actionto always show the source file and/or line number.The next actions can be colorized using the--styleargument. Runnext-action --helpto see the list of possible
styles.When you've decided on a style you prefer, it makes sense to configure the style in the configuration file. See the
section below on how to configureNext-action.Not passing an argument to--stylecancels the style that is configured in the configuration file, if any.When showing multiple next actions, these can be grouped by passing the--groupbyoption:$next-action--number5--groupbycontextphone:- (A) Call mom @phonestore:- (B) Buy paint to +PaintHouse @store @weekend- (G) Buy wood for new +DogHouse @storeweekend:- (B) Buy paint to +PaintHouse @store @weekendwork:- (C) Finish proposal for important client @workhome:- (K) Pay October invoice @home due:2020-10-28Next-actionsorts the groups according to the most important next action in the group. Actions may be repeated
if they belong to multiple groups, as is the case with theBuy painttask above.If you always want to group next actions, you can configure this in the configuration file. See the section
below on how to configureNext-action.To open URLs in the description of the next actions, use the--open-urlscommand line option.ConfiguringNext-actionIn addition to specifying options on the command-line, you can also configure options in a configuration file. The
configuration file format isYAML. The options currently supported are which todo.txt files must be
read, how many next actions should be shown, output styling, and context and/or project filters.Writing the configuration fileTo get started, you can tellNext-actionto generate a configuration file with the default options:$next-action--write-config-file#ConfigurationfileforNext-action.Editthesettingsbelowasyoulike.file: ~/todo.txtnumber: 1reference: multiplestyle: defaultTo make this the configuration thatNext-actionreads by default, redirect the output to~/.next-action.cfglike
this:next-action --write-config-file > ~/.next-action.cfg.Any additional options specified on the command line are used to generate the configuration file:$next-action--write-config-file--blocked--groupbycontext--number3--file~/tasks.txt--stylefruity--priorityZ-@waiting#ConfigurationfileforNext-action.Editthesettingsbelowasyoulike.blocked: truefile: ~/tasks.txtfilters:- -@waitinggroupby: contextnumber: 3priority: Zreference: multiplestyle: fruityReading the configuration fileBy default,Next-actiontries to read a file called.next-action.cfgin your home
folder.If you want to use a configuration file that is not in the default location (~/.next-action.cfg), you'll need to
explicitly specify its location:$next-action--config-filedocs/.next-action.cfg(A)Call mom @phoneTo skip reading the default configuration file, and also not read an alternative configuration file, use the--config-fileoption without arguments.Configuring a default todo.txtA default todo.txt file to use can be specified like this in the configuration file:file:~/Dropbox/todo.txtMultiple todo.txt files can be listed, if needed:file:-personal-todo.txt-work-todo.txt-big-project/tasks.txtConfiguring the number of next actions to showThe number of next actions to show can be specified like this:number:3Or you can haveNext-actionshow all next actions:all:TrueConfiguring the tasks from which next actions are selectedLimiting by contexts and/or projectsYou can limit the tasks from which the next action is selected by specifying contexts and/or projects to filter on,
just like you would do on the command line:filters:-+FutureProject @work -@waitingThis would makeNext-actionby default select next actions from tasks with a@workcontext and without the@waitingcontext and not belonging to the+FutureProject.An alternative syntax is:filters:--+FutureProject-'@work'--@waitingNote that filters starting with@need to be in quotes. This is aYAML restriction.Limiting by priorityThe minimum priority of next actions to show can be specified as well:priority:ZThis could be useful if you, for example, keep a backlog of ideas without priority in your todo.txt file and
prioritize only the tasks that are actionable.Specifying a value on the command line overrides the priority in the configuration file, e.g.next-action --priority C. To override the priority set in the configuration but not set another minimum priority,
use the priority option without argument:next-action --priority.Configuring the outputWhether the next actions should have a reference to the todo.txt file from which they were read can be configured using
thereferencekeyword:reference:alwaysPossible values arealways,never, ormultiple. The latter means that the filename is only added when you read
tasks from multiple todo.txt files. The default value ismultiple.Whether the next actions should have a reference to their line number in the todo.txt file from which they were read
can be configured using theline_numberkeyword:line_number:trueThe output style can be configured using thestylekeyword:style:colorfulRunnext-action --helpto see the list of possible styles.To always see the tasks blocked by the next action, put this in your configuration file:blocked:trueNext actions can be configured to be grouped as follows:groupby:priorityPossible grouping options are bycontext,duedate,priority,project, andsource. Specifying a value on
the command line overrides the grouping in the configuration file, e.g.next-action --groupby project.
To cancel the grouping set in the configuration file all together, use the groupby option without argument:next-action --groupby.To always open URLs, use theopen_urlsoption:open_urls:trueOption detailsPrecedenceOptions in the configuration file override the default options. Command-line options in turn override options in the
configuration file.If you have a configuration file with default options that you occasionally want to ignore, you can skip reading the
configuration file entirely with the--no-config-fileoption.Optional arguments followed by positional argumentsWhen you use an option that takes an optional argument, but have it followed by a positional argument,Next-actionwill interpret the positional argument as the argument to the option and complain, e.g.:$next-action--due@homeUsage: next-action [-h] [-V] [-c [<config.cfg>] | -w] [-f <todo.txt> ...] [-b] [-g [<group>]] [-l] [-r <ref>][-s [<style>]] [-a | -n <number>] [-d [<due date>] | -o] [-p [<priority>]] [-u] [--] [<context|project>...]next-action: error: argument -d/--due: invalid date: @homeThere's two ways to helpNext-actionfigure out what you mean. Either reverse the order of the arguments:$next-action@home--due(K)Pay October invoice @home due:2020-10-28Or use--to separate the option from the positional argument(s):$next-action--due--@home(K)Pay October invoice @home due:2020-10-28Recent changesSee thechange log.DevelopingNext-actionInstalling the development environment and dependenciesWe use Docker as development environment. To build the Docker image with all the development dependencies make sure
you have Git and Docker installed. Then, follow these steps:Clone the repository:git clone https://github.com/fniessink/next-action.git.Enter the folder:cd next-action.Build the Docker image:docker build . -t next-action-dev.Thedocker-compose.ymlcontains services for each of the development tools. These are described below.Running unit testsTo run the unit tests and check their code coverage:$docker-compose--no-ansiupunittestRecreating next-action_unittest_1 ...Recreating next-action_unittest_1 ... doneAttaching to next-action_unittest_1unittest_1                | ----------------------------------------------------------------------unittest_1                | Ran 271 tests in 6.171sunittest_1                |unittest_1                | OKunittest_1                | Name    Stmts   Miss Branch BrPart  Coverunittest_1                | -----------------------------------------unittest_1                | -----------------------------------------unittest_1                | TOTAL    1625      0    248      0   100%unittest_1                |unittest_1                | 31 files skipped due to complete coverage.next-action_unittest_1 exited with code 0The HTML coverage report is written tobuild/unittest-coverage/.Running feature testsTo run the feature tests and measure their code coverage:$docker-compose--no-ansiupbehaveRecreating next-action_behave_1 ...Recreating next-action_behave_1 ... doneAttaching to next-action_behave_1behave_1                  | 17 features passed, 0 failed, 0 skippedbehave_1                  | 123 scenarios passed, 0 failed, 0 skippedbehave_1                  | 411 steps passed, 0 failed, 0 skipped, 0 undefinedbehave_1                  | Took 4m15.737sbehave_1                  | Name    Stmts   Miss Branch BrPart  Coverbehave_1                  | -----------------------------------------behave_1                  | -----------------------------------------behave_1                  | TOTAL     509      0    228      0   100%behave_1                  |behave_1                  | 13 files skipped due to complete coverage.next-action_behave_1 exited with code 0The HTML coverage report is written tobuild/feature-coverage/.Running quality checksThe tools Mypy, Pylint, Pycodestyle, Pydocstyle, Bandit, Pyroma, and Vulture are used to check for quality issues in
the Python code. Shellcheck is used evaluate the Bash code. Gherkin feature files are checked with Gherkin-lint.
The Markdown files are evaluated with Markdownlint. The Dockerfile is checked with Hadolint. The docker-compose.yml is
checked with Docker-compose.To run the quality checks:$docker-compose--no-ansiupqualityRecreating next-action_quality_1 ...Recreating next-action_quality_1 ... doneAttaching to next-action_quality_1quality_1                 | Generated HTML report (via XSLT): /Users/fniessink/workspace/next-action/build/mypy/index.htmlquality_1                 | Success: no issues found in 13 source filesquality_1                 |quality_1                 | ------------------------------------quality_1                 | Your code has been rated at 10.00/10quality_1                 |quality_1                 | ------------------------------quality_1                 | Checking .quality_1                 | Found next-actionquality_1                 | ------------------------------quality_1                 | Final rating: 10/10quality_1                 | Your cheese is so fresh most people think it's a cream: Mascarponequality_1                 | ------------------------------next-action_quality_1 exited with code 0Generating documentationThisREADME.mdfile is generated withdocker-compose up docs.The dependency graph below is created with Pydeps and the package and class diagrams below are created with
Pyreverse (part of Pylint).Source code structure and dependenciesThe dependency graph shows the relationships between the packages and modules in the code base and the third-party
packages used. When the user imvokesNext-actionfrom the command-line, thenext_action()method in thenext_actionpackage is run. Thenext_action()method uses thenext_action.argumentspackage to parse the
command-line arguments and the configuration file. TheTodo.txtfile is read into a domain model using thenext_action.todotxtpackage. Thenext_action.pick_actionmodule contains the logic to select the next action.
Finally, the output is formatted using thenext_action.outputpackage.The package diagram created by Pyreverse looks quite similar.The class diagram created by Pyreverse shows the classes used. The biggest one is theNextActionArgumentParserclass,
responsible for parsing the command-line arguments. The other two relevant classes are theTaskclass for holding
information about an individual task and theTasksclass that contains a collection of tasks.