Description:

focus 0.1.3

Introduction============Focus is a command-line productivity tool for improved task workflows.Why Focus?----------For developers, Focus aims to help fight distractions while you work;less distractions means more focus. Currently, Focus targets Unix-likeoperating systems, such as Linux or Mac OSX.Features========Open Applications-----------------Launch applications needed for your task.Close Applications------------------Quit unnecessary applications when starting your task.Block Applications------------------Continuously quit unnecessary applications if they are launched during a task.Block Websites--------------Block distracting websites, such as Hacker News, Facebook, YouTube, andTwitter.Run Commands------------Execute arbitrary shell commands useful for your task.Play Sounds-----------Play a sound after your task timer runs out or whenever you end the task.You can also play a sound when starting tasks, in case you want to getyour groove on.Notifications-------------Show a popup system notification message when a task is started orhas ended, either by you completing the task or the timer running out.Update IM Status----------------Update the account status for your favorite instant messenger (IM) applicationswhile you work. Focus supports `Pidgin <http://www.pidgin.im/>`_,`Empathy <https://live.gnome.org/Empathy>`_, and`Skype <http://www.skype.com>`_ on Linux and `Adium <http://adium.im/>`_ and`Skype <http://www.skype.com>`_ on Mac OSX.Track Your Time---------------Keep tabs on how long you work on tasks per day. Focus will record your timeautomatically and present your time as a simple report.**If these features won't do it for you, Focus boasts a simple, yet powerfulplugin system. More on this later.**Installation============ sudopipinstallfocusorfromsource: sudo python setup.py installPython Libraries----------------The following Python libraries are required to run Focus; though ``pip``should handle taking care of installing them if not available.* psutil >= 0.4.1* argparse (Python <2.7)* dbus (Linux only)Optional External Dependencies------------------------------* Linux: `mpg123 <http://www.mpg123.de/>`_, `play <http://sox.sourceforge.net/>`_, or `aplay <http://www.alsaplayer.org/>`_ [WAV only] (to play sounds)* Mac OSX: `terminal-notifier <https://github.com/alloy/terminal-notifier>`_ or `growlnotify <http://growl.info/extras.php/#growlnotify>`_ (to show notifications)Usage=====Create Task----------- focusmaketaskname[−−skip−edit]or,clonefromexistingtask: focus make task_name other_task [--skip-edit]This command opens the task configuration file using the shell's default editor(EDITOR),unlessthe‘‘−−skip−edit‘‘flagisprovided.Aftertheeditorexits,theconfigurationfileisvalidatedandwillpromptforretryifvalidationfails.StartTask−−−−−−−−−− focus on task_nameThis starts the provided task, running any initial settings as indicated in thetask's configuration file.End Task-------- focusendThisendsthecurrenttask,runninganyendingsettingsasindicatedinthetask′sconfigurationfile.∗Note:thiscommandisonlyavailablewhenataskisactive.∗EditTask−−−−−−−−− focus edit task_name [--skip-edit]Like the ``make`` command, this command opens the task configuration file usingthe shell's default editor (EDITOR).Aftertheeditorexits,theconfigurationfileisvalidatedandwillpromptforretryifvalidationfails.ListTasks−−−−−−−−−− focus list [-v] [--verbose]This will scan for existing tasks with valid configuration files and printthe names of the tasks found. Specify the ``-v`` or ``--verbose`` flag to alsoprint setting information for each task's configuration file. Invalid tasksare marked in red, while the active task is marked in green.View Task--------- focusview[taskname]Thisprintsthesettinginformationfromthetask′sconfigurationfile.Ifnotasknameisprovided,theactivetaskwillbeshown.RenameTask−−−−−−−−−−− focus rename old_task_name new_task_nameThis commands gives the provided task a new name.Delete Task----------- focusdestroytaskname[−f][−−force]Thiscommandsremovestheprovidedtaskafterpromptingforconfirmation.Specifythe‘‘−f‘‘or‘‘−−force‘‘flagtoskipconfirmation.ShowRemainingTimeforActiveTask−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− focus left [-s] [--short]This commands prints the amount of time remaining, in minutes, for the activetask. Specify the ``-s`` or ``--short`` flag to print just the number ofminutes.*Note: this command is only available if the active task has defined theduration option.*Show Available Usage Statistics------------------------------- You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math modeHOME or ~). Under that lives a ``plugins`` subdirectory,where you can drop your .py python plugin files. If they are valid, the pluginswill automatically become available when running ``focus``. For commandplugins, running ``focus`` will print a help banner with the installedcommands, which will include your plugins.*Remember, if the plugin is available only for active tasks, the appropriatetask must be active to see your plugin show up.*Command Plugins---------------Command plugins define the commands that are available for the Focus binary(e.g. ``on``, ``make``, etc.). These can be available always, only for tasksthat define certain options, or only for active tasks.The ``command`` class attribute identifies the plugin as a command plugin andspecifies the actual command name to register with the plugin.*Note: The command name should be unique.*The plugin should define the ``execute()`` method for running the command. The``env`` argument represents the environment and the ``args`` argument is theresult of parsing the command-line arguments using the ``ArgumentParser``object.**Method Definition:** :: def execute(self, env, args): env.io.write('Verbose: {0}'.format(args.verbose))To simply print an error message, use the ``env.io.error()`` method. If youneed to also return a specific error code along with printing an error messageraise a ``FocusError`` exception from the ``focus.errors`` module: :: from focus.errors import FocusError def execute(self, env, args): # env.io.error('Oh noes!') # just prints and returns exit code 0 raise FocusError('message here', code=123)If the plugin needs to define any command-line arguments, it should define the``setup_parser()`` method. The ``parser`` argument is an instance of``argparse.ArgumentParser`` and should be updated as necessary to addarguments.**Method Definition:** :: def setup_parser(self, parser): parser.add_argument('-v', '--verbose', action='store_true')**Plugin Example:** :: from focus.plugin import Plugin class Foo(Plugin): """ Description of plugin, used when generating help message. """ name = "FooPlugin" # Name of plugin, must be unique version = "1.0" # Plugin version target_version = ">=0.1" # Target Focus version, (<, <=, ==, >=, >) command = "bar" # Command name def setup_parser(self, parser): parser.add_argument('-v', '--verbose', action='store_true') def execute(self, env, args): env.io.write('Verbose: {0}'.format(args.verbose)) #env.io.error('Oh noes!') #env.io.success('Woot') # resp = env.io.prompt('Are you distracted? (y/n)') # stdin_data = env.io.read()Task Event Plugins------------------Task event plugins are only available for active tasks. They can be registeredto run at the start of the task, during the task loop (every second), at theend of a task, or some combination therein. These plugins will be run within adaemon process when the task starts.The ``events`` class attribute identifies the plugin as a task event plugin andspecifies the events of the task that should be registered: ``task_start``,``task_run``, ``task_end``.The plugin should define the ``on_taskstart()``, ``on_taskrun()``, or``on_taskend()`` methods corresponding to the values provided for the``events`` attribute. The ``task`` argument represents the active task, whichincludes ``name``, ``duration`` (minutes), and a few methods such as``start()`` and ``stop()``.**Method Definition:** :: def on_taskstart(self, task): pass**Plugin Example:** :: from focus.plugin import Plugin class Foo(Plugin): """ Description of plugin. """ name = "FooPlugin" # Name of plugin, must be unique version = "1.0" # Plugin version target_version = ">=0.1" # Target Focus version, (<, <=, ==, >=, >) events = ['task_start', 'task_run', 'task_end'] def on_taskstart(self, task): pass def on_taskrun(self, task): pass def on_taskend(self, task): passPlugin Options--------------Two attributes exist to allow plugins to only be loaded for active tasks:1. **options** Set the ``options`` class attribute. This defines the options that, if provided in a task configuration file, will trigger the load of this plugin. Options are either non-block (e.g. ``duration``) or block (e.g. ``apps`` => { ``run``, ``close``, ``block`` }, ``sites`` => { ``block`` }, etc.). When this attribute is set, the plugin should define the ``parse_option()`` method in order to parse the values set in a task configuration file. See example below. *Note: these options should be unique.* **Plugin Snippet:** :: from focus.plugin import Plugin class Foo(Plugin): ... options = [ # duration (non-block option) { 'name': 'duration', 'allow_duplicates': False # disallow duplicate definitions }, # apps.run, apps.close (block options) { 'block': 'apps', 'options': [ { 'name': 'run', 'allow_duplicates': True # the default }, { 'name': 'close' } ] } ] **Task Configuration Example:** :: task { duration 30; apps { run firefox, chromium, /path/to/file, /path/to/other\ file; run "/path/to/file arg1 arg2", helloworld\ -a\ b; close adium; } } **Method Definition:** :: def parse_option(self, option, block_name, *values): # raise ValueError exception with a message to reject the provided # value. this will propagate up to the cli when loading a task Here, the ``option`` and ``block_name`` names for the currently parsed option are provided. ``block_name`` will be ``None`` when parsing non-block options. ``values`` holds one or more values associated with the provided option.2. **task_only** Set the ``task_only`` class attribute, so the plugin will be available for any task once started. **Plugin Snippet:** :: class Foo(Plugin): ... task_only = True ...Root Access-----------If a plugin needs root access, it should define the ``needs_root`` attribute.When set, this installs a ``run_root()`` method on the plugin class, whichaccepts an arbitrary command string and returns a boolean for success orfailure. Internally, Focus uses the ``sudo`` command to temporarily escalateprivileges.**Plugin Snippet:** :: from focus.plugin import Plugin class Foo(Plugin): ... command = 'foo' events = ['task_start'] needs_root = True def execute(self, env, args): self.run_root('whoami >> /tmp/whoami_focus.log') def on_taskstart(self, task): self.run_root('whoami >> /tmp/whoami_focus2.log')

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter