The big V2 refactoring and API thread

[deanishe]

A significant refactoring of Alfred-Workflow is long overdue. The Workflow class has grown very large and the unittests are a horror show, largely due to the necessity of a workflow-like environment to run them in.

I'd love to hear your ideas on how the library should be refactored and how the API should be changed.

My thoughts so far:

Refactoring

• Move all the code that requires a workflow environment (info.plist or version files, Alfred environmental variables) to its own module(s).
• Split the different feature groups of Workflow into separate modules (data storage and cache functions, settings, filtering, text processing, serialisation etc.).
• Generalise the update API, so other backends (e.g. RSS, Packal) can be added easily.
• Add lots of mocking to unittests, especially to return canned HTTP responses and avoid hitting web APIs.

  API changes

• Change default max_age to 0 in Workflow.cached_data(), so cached data is always returned regardless of age by default.
• Move version from update_settings dict to a Workflow argument (as an alternative to version file).
• (Possibly) allow filter() to be called with an empty query, whereupon it will return all items. This would mirror the way the built-in Python filter() function works, and allow @smargh to not bother checking whether query is empty.

Paging @smargh @fniephaus @owenwater :grinning:

[shawnrice]

If you want the theme light/theme dark, then just steal the algorithms that I wrote for the bundler. All the color math is already there, and the research is done.

On Fri, Jan 30, 2015 at 9:24 PM, Dean Jackson notifications@github.com wrote:

I'm confused as fuck now. Who was it complained again? I'd got it into my head that it was you @owenwater, but I'm a bit drunk right now. Oh wait. Did one of us type @owenmin instead of @owenwater? Haha! Regarding coding, nothing that still needs implementing has a fixed API yet. As a result, I'm hesitant to ask someone to have a go at writing it for fear that it will need rewriting. I'm currently working on the cached/stored data API, but all I've done so far is cut-and-paste it into storage.py (I haven't actually run any of the code yet). The update system needs refactoring around hooks/plugins, but depends on the caching API. Keychain and magic args need moving out of Workflow, but they're mostly cut-and-paste jobs. I think what would help most at this point would be an "audit" of the code I've written/moved around so far, and some brainy thinking about what's wrong, what's missing and how the update, serializer and magic argument APIs should work.

• Have I done anything obviously bone-headed (code and tests)?
• Is there anything that could be refactored/generalised (code and tests)?
• Are there other hooks that could/should be added?
• Assuming hooks can be used to override built-in functions, which functions should be made overrideable? XML generation? Workflow.filter()?
• What should you be able to specify in workflow.ini apart from version and update settings? How should it be integrated with Workflow? Does it go in Workflow or env? (I'm thinking env, so plugins can access the configuration without having to instantiate Workflow, which is something I want to avoid.)
• What else could/should be added to env? For example, I've been thinking about theme_light/theme_dark, which would be a boolean calculated from the colour of the theme background, so users would know whether to use light or dark icons.

- How should be the update API work?

Reply to this email directly or view it on GitHub: https://github.com/deanishe/alfred-workflow/issues/55#issuecomment-72300349

[deanishe]

just steal the algorithms that I wrote for the bundler

Goes without saying, tbh.

[shawnrice]

I just wrote that in there in case someone else decided to tackle it and didn't know about the color work done in the bundler.

But, for ease, here is the consolidated code from the PHP bundler. The key calculation is the one that sets the luminance variable.

  function light_or_dark() {
    // Regex pattern to parse the Alfred background variable
    $pattern = "/rgba\(([0-9]{1,3}),([0-9]{1,3}),([0-9]{1,3}),([0-9.]{4,})\)/";
    // Do the regex, matching everything in the $matches variable
    preg_match_all( $pattern, $_ENV[ 'alfred_theme_background' ], $matches );
    // Pull the values into an $rgb array
    $rgb = array( 'r' => $matches[1][0], 'g' => $matches[2][0], 'b' => $matches[3][0] );

    // This calculates the luminance. Values are between 0 and 1.
    $luminance = ( 0.299 * $rgb[ 'r' ] + 0.587 * $rgb[ 'g' ] + 0.114 * $rgb[ 'b' ] ) / 255;

    if ( 0.5 < $luminance ) {
        return 'light';
    }
    return 'dark';
  }

[fniephaus]

I use this:

def is_dark(wf):
      return min([int(x) for x in wf.alfred_env['theme_background'][5:-6].split(',')]) < 128

[deanishe]

How has that worked out for you @fniephaus? @shawnrice says the luminance is the critical calculation, but that bit's missing from yours. Does it matter?

I have no idea myself.

Also, frohes Neues :fireworks:

[fniephaus]

I haven't really given it that much thought, so Shawn's algorithm is probably more accurate. Nonetheless, it does what it should be doing except maybe for weird colors that I haven't tested...

[shawnrice]

The luminance calculates the "brightness" of the image. The human eye sees green light really well and blue light terribly. So, the coefficients weight that appropriately.

Granted, any difference is probably going to be an edge case.

[fniephaus]

Just for the record, here's a Python equivalent of @shawnrice's algorithm:

def is_dark():
    rgb = [int(x) for x in WF.alfred_env['theme_background'][5:-6].split(',')]
    return (0.299 * rgb[0] + 0.587 * rgb[1] + 0.114 * rgb[2] ) / 255 < 0.5

[idpaterson]

@deanishe have you had any involvement in testing Alfred 3.0? It looks like there are a lot of interesting changes coming though the details will be shared in follow-up blog posts over the next few weeks. It is not clear yet to what extent the changes to workflows would affect workflow libraries like alfred-workflow.

[deanishe]

@idpaterson I know nothing about Alfred 3 beyond a few educated guesses based on what Andrew has expressed interest in on the forums. Everything in that blog post is news to me.

[shawnrice]

From my discussions with Andrew, most Alfred 2 workflows should still be compatible with Alfred 3. There will definitely be improvements, but I'm not sure either how much the libraries will need to change or what new stuff should be added in so as to take advantage of newer features.

[idpaterson]

That is reassuring. From the screenshot it looks like primarily changes within the info.plist but I'm looking forward to learning more as it is unveiled on the blog over the coming weeks.

[deanishe]

Closing this thread. V2 Is coming, and I’m going to start a more up-to-date issue.