Python Scripting - Documentation

Drive the Heyweek CLI from Python with the subprocess module to automate your workflow.

Using subprocess

Wrap hw in a helper that runs a command and checks its exit code:

<span class="token comment">#!/usr/bin/env python3</span>
<span class="token keyword">import</span> subprocess
<span class="token keyword">import</span> json

<span class="token keyword">def</span> <span class="token function">run_hw</span><span class="token punctuation">(</span>args<span class="token punctuation">)</span><span class="token punctuation">:</span>
    <span class="token triple-quoted-string string">"""Run an hw command and return its stdout."""</span>
    result <span class="token operator">=</span> subprocess<span class="token punctuation">.</span>run<span class="token punctuation">(</span>
        <span class="token punctuation">[</span><span class="token string">"hw"</span><span class="token punctuation">]</span> <span class="token operator">+</span> args<span class="token punctuation">,</span>
        capture_output<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
        text<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
    <span class="token punctuation">)</span>
    <span class="token keyword">if</span> result<span class="token punctuation">.</span>returncode <span class="token operator">!=</span> <span class="token number">0</span><span class="token punctuation">:</span>
        <span class="token keyword">raise</span> RuntimeError<span class="token punctuation">(</span><span class="token string-interpolation"><span class="token string">f"Command failed: </span><span class="token interpolation"><span class="token punctuation">{</span>result<span class="token punctuation">.</span>stderr<span class="token punctuation">.</span>strip<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span><span class="token string">"</span></span><span class="token punctuation">)</span>
    <span class="token keyword">return</span> result<span class="token punctuation">.</span>stdout

<span class="token comment"># Start a timer</span>
run_hw<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string">"timer"</span><span class="token punctuation">,</span> <span class="token string">"start"</span><span class="token punctuation">,</span> <span class="token string">"-d"</span><span class="token punctuation">,</span> <span class="token string">"Continue work"</span><span class="token punctuation">]</span><span class="token punctuation">)</span>

<span class="token comment"># Check status (human-readable output)</span>
<span class="token keyword">print</span><span class="token punctuation">(</span>run_hw<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string">"timer"</span><span class="token punctuation">,</span> <span class="token string">"status"</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">)</span>

Parsing JSON output

hw project list can emit JSON, which json.loads turns into Python objects:

<span class="token comment">#!/usr/bin/env python3</span>
<span class="token keyword">import</span> subprocess
<span class="token keyword">import</span> json

<span class="token keyword">def</span> <span class="token function">list_projects</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
    <span class="token triple-quoted-string string">"""Return the workspace projects as a list of dicts."""</span>
    result <span class="token operator">=</span> subprocess<span class="token punctuation">.</span>run<span class="token punctuation">(</span>
        <span class="token punctuation">[</span><span class="token string">"hw"</span><span class="token punctuation">,</span> <span class="token string">"project"</span><span class="token punctuation">,</span> <span class="token string">"list"</span><span class="token punctuation">,</span> <span class="token string">"--json"</span><span class="token punctuation">,</span> <span class="token string">"id,name"</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
        capture_output<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
        text<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
        check<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
    <span class="token punctuation">)</span>
    <span class="token keyword">return</span> json<span class="token punctuation">.</span>loads<span class="token punctuation">(</span>result<span class="token punctuation">.</span>stdout<span class="token punctuation">)</span>

<span class="token keyword">def</span> <span class="token function">find_project_id</span><span class="token punctuation">(</span>name<span class="token punctuation">)</span><span class="token punctuation">:</span>
    <span class="token triple-quoted-string string">"""Find a project ID by name."""</span>
    <span class="token keyword">for</span> project <span class="token keyword">in</span> list_projects<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
        <span class="token keyword">if</span> project<span class="token punctuation">[</span><span class="token string">"name"</span><span class="token punctuation">]</span> <span class="token operator">==</span> name<span class="token punctuation">:</span>
            <span class="token keyword">return</span> project<span class="token punctuation">[</span><span class="token string">"id"</span><span class="token punctuation">]</span>
    <span class="token keyword">return</span> <span class="token boolean">None</span>

project_id <span class="token operator">=</span> find_project_id<span class="token punctuation">(</span><span class="token string">"Website"</span><span class="token punctuation">)</span>
<span class="token keyword">if</span> project_id<span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span><span class="token string-interpolation"><span class="token string">f"Found project </span><span class="token interpolation"><span class="token punctuation">{</span>project_id<span class="token punctuation">}</span></span><span class="token string">"</span></span><span class="token punctuation">)</span>
<span class="token keyword">else</span><span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span><span class="token string">"Project not found"</span><span class="token punctuation">)</span>

Logging time for each project

Iterate over the projects and create a log entry for each:

<span class="token comment">#!/usr/bin/env python3</span>
<span class="token keyword">import</span> subprocess
<span class="token keyword">import</span> json

projects <span class="token operator">=</span> json<span class="token punctuation">.</span>loads<span class="token punctuation">(</span>
    subprocess<span class="token punctuation">.</span>run<span class="token punctuation">(</span>
        <span class="token punctuation">[</span><span class="token string">"hw"</span><span class="token punctuation">,</span> <span class="token string">"project"</span><span class="token punctuation">,</span> <span class="token string">"list"</span><span class="token punctuation">,</span> <span class="token string">"--json"</span><span class="token punctuation">,</span> <span class="token string">"id,name"</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
        capture_output<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span> text<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span> check<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
    <span class="token punctuation">)</span><span class="token punctuation">.</span>stdout
<span class="token punctuation">)</span>

<span class="token keyword">for</span> project <span class="token keyword">in</span> projects<span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span><span class="token string-interpolation"><span class="token string">f"Logging time for </span><span class="token interpolation"><span class="token punctuation">{</span>project<span class="token punctuation">[</span><span class="token string">'name'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span><span class="token string">"</span></span><span class="token punctuation">)</span>
    subprocess<span class="token punctuation">.</span>run<span class="token punctuation">(</span>
        <span class="token punctuation">[</span>
            <span class="token string">"hw"</span><span class="token punctuation">,</span> <span class="token string">"log"</span><span class="token punctuation">,</span> <span class="token string">"create"</span><span class="token punctuation">,</span>
            <span class="token string">"-d"</span><span class="token punctuation">,</span> <span class="token string">"Daily standup"</span><span class="token punctuation">,</span>
            <span class="token string">"-p"</span><span class="token punctuation">,</span> project<span class="token punctuation">[</span><span class="token string">"id"</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
            <span class="token string">"-s"</span><span class="token punctuation">,</span> <span class="token string">"09:00"</span><span class="token punctuation">,</span>
            <span class="token string">"-e"</span><span class="token punctuation">,</span> <span class="token string">"09:15"</span><span class="token punctuation">,</span>
        <span class="token punctuation">]</span><span class="token punctuation">,</span>
        check<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">,</span>
    <span class="token punctuation">)</span>

← Back to CLI scripting.