An Aha Moment

That changed when I spotted a new Command Line Integration (CLI) in the release notes for Dropzone. Suddenly it clicked...

What if I could print directly to the Drop Bar in Dropzone?

macOS Print Plugins

On macOS, Automator Print Plugins let you do more with the PDF button in the Print dialog. Instead of just saving a file, you can set up quick actions like automatically naming, moving, or filing PDFs—right when you print. It’s a handy way to speed up routine tasks.

Setting Up a Print Plugin

Upon launching Automator, choose the "Print Plugin" workflow.

Since we will be using the Dropzone CLI via the dz command, you'll only need the Run Shell Script action for this workflow.

Code Explanation

The shell code is pretty simple, but here is a breakdown of the steps.

# 1. Set the directory (`base_dir`) for saving the PDF file.
base_dir="$HOME/Downloads/"
# 2. Move the PDF to the `base_dir`.
mv "$1" "$base_dir"
# 3. Set the final path of the PDF file.
file_path="$base_dir/$(basename "$1")"
# 4. Send the PDF file to Dropzone Drop Bar via the `dz add` command.
/usr/local/bin/dz add "$file_path"

A Few Notes

1. So, how do you get your new Automator Print Plugin to show up in the Print dialog’s PDF menu? When you save the workflow in Automator as a Print Plugin, it will appear automatically in the PDF dropdown the next time you open the Print dialog. For reference, all of your custom items from that menu are stored in your user’s Library folder at ~/Library/PDF Services/.

2. Full path to dz – Automator doesn’t always use your shell’s PATH, so call /usr/local/bin/dz explicitly.

3. By default, macOS prints PDFs to a temp directory. If you don’t need to move the file, you can send it straight to Dropzone with:

/usr/local/bin/dz add "$1"

Extra Credit

You can trigger Dropzone actions too 🙌!

/usr/local/bin/dz run "File Receipt" dragged "$1"

Final Thoughts

With this setup, I no longer clutter my Desktop or Downloads with stray PDFs and everything goes right into Dropzone, ready to be filed where it belongs.

🤖 Happy PDF filing!

I hope to go deeper into this subject in a later post, but for now I'll show you how I write the users last used settings out to a JSON "like" file on their hard disk.

What is JSON "like"?

Adobe ExtendScript doesn't include a JSON library, so to easily read and write JSON I'll be using the Adobe Bridge Messaging API. This API provides two key functions.

• toSource() to serialize/encode JavaScript objects and arrays
• eval() to reconstitute/decode JavaScript objects and arrays

The reason I say JSON "like" is because the toSource() function doesn't encode valid JSON, it serializes objects or arrays into a special string. There are a few funky aspects of this serialized string that make it invalid JSON, but since I'll be reconstituting it using the eval() function, it works perfect for my purposes.

// valid json
{
    "a": 1,
    "b": 2
}

// invalid `toSource()` serialized JSON string
({"a": 1, "b": 2})

Going forward, I'll just use the term JSON.

Script Setup

First, I'll setup some option variables that will be used to create the dialog window, and I'll also set defaults to be used on the first run (or when a preferences file isn't found).

var locations = ["Location 1", "Location 2", "Location 3"];
var products = ["Product 1", "Product 2", "Product 3"];
var defaults = { location: "Location 1", product: "Product 3" };

Next, I'll check to see if a preferences file already exists. To do this, I make a new File object pointing at the user’s default document folder path provided by ExtendScript's Folder object class properties Folder.myDocuments.

var prefsFile = new File(Folder.myDocuments + "/prefs.json");
var prefsData = prefsFile.exists ? readJSONData(prefsFile) : defaults;

Using a Conditional (ternary) operator I'll set prefsData to the data read from prefsFile (if it exists) using the readJSONData() function below, or to the defaults I set above.

Reading JSON Files With ExtendScript

Reading the JSON data from the preferences file is pretty straight forward. First, I try opening the file and reading its data to the variable json. If all is successful, I'll reconstitute/decode that data back into a JavaScript object (using the eval() function mentioned above) and return it for use in the dialog window.

function readJSONData(file) {
  var obj, json;
  try {
    file.encoding = "UTF-8";
    file.open("r");
    json = file.read();
    file.close();
  } catch (e) {
    alert("Error loading " + file + " file!");
  }
  obj = eval(json);
  return obj;
}

Presenting The Dialog

I won't go into too much detail in this post on the dialog creation code, but basically I create a simple dialog full of radio buttons determined by the locations and products arrays from above.

Now, the reason for all of this work is that while creating the radio buttons (or most any UI element), I can check to see if a particular element (radio button) is set in the prefsData object (be it either loaded from a file or the defaults), and if so, preselect if for the user. As you can see, this can be a huge timesaver if a dialog has lots of options or if the user needs the ability to save multiple presets for different uses.

// show the settings dialog
var settings = settingsWin(prefsData);
// parse the dialog settings
if (settings) {
  alert(
    "User Settings Saved!\nSelected Location: " +
      settings.location +
      "\nSelected Product: " +
      settings.product
  );
}

// get selected radio button from array
function captureRBSelection(rbs) {
  for (var i = 0; i < rbs.length; i++) {
    if (rbs[i].value) return rbs[i].text;
  }
  return null;
}

// setup the dialog window
function settingsWin(prefsData) {
  var win = new Window("dialog");
  win.text = "Save Preferences From Dialog Example";

  // create a radio button for each location
  win.add("statictext", undefined, "Select Your Location");
  var gLocation = win.add("group");
  var locationRBs = [];
  var rb;
  for (var i = 0; i < locations.length; i++) {
    rb = gLocation.add("radiobutton", undefined, locations[i]);
    if (prefsData["location"] == locations[i]) rb.value = true;
    locationRBs.push(rb);
  }

  // create a radio button for each product
  win.add("statictext", undefined, "Select Your Product Type");
  var gProducts = win.add("group");
  var productRBs = [];
  var rb;
  for (var i = 0; i < products.length; i++) {
    rb = gProducts.add("radiobutton", undefined, products[i]);
    if (prefsData["product"] == products[i]) rb.value = true;
    productRBs.push(rb);
  }

  // setup window buttons
  var gWindowButtons = win.add("group", undefined);
  var btOK = gWindowButtons.add("button", undefined, "OK");
  var btCancel = gWindowButtons.add("button", undefined, "Cancel");

  // if "ok" button clicked then return inputs
  if (win.show() == 1) {
    // check to see which location and product was selected
    var selectedSettings = {
      location: captureRBSelection(locationRBs),
      product: captureRBSelection(productRBs),
    };
    return selectedSettings;
  } else {
    return;
  }
}

The main thing to understand from the code above are the final few lines. If the user clicks the "OK" button if (win.show() == 1), I gather their dialog selections (radio buttons in this case) and construct an object from them that I can return for use in the rest of the script.

Writing JSON Files With ExtendScript

Now that I have the user selected settings from the dialog stored as an object, I can write that data to the preferences file.

if (settings) {
  writeJSONData(settings, prefsFile);
}

Writing the JSON data to a file is not that dissimilar from reading it. First, I serialize the JSON data using the toSource() function mentioned above. Then, I try writing the data to disk using the write() function provided by the file object.

function writeJSONData(obj, file) {
  var data = obj.toSource();
  try {
    file.encoding = "UTF-8";
    file.open("w");
    file.write(data);
    file.close();
  } catch (e) {
    alert("Error writing file " + file + "!");
  }
}

alert(
  "User Settings Saved!\nSelected Location: " +
    settings.location +
    "\nSelected Product: " +
    settings.product
);

Final Thoughts

This setup is just the base for more advanced functionality like I implemented in my Screen Print Separation Marks script shown below. I hope to do a more in-depth post on this in the future.

View the full script on Github. ✌️

>>> for step in steps:
...    print(f"processing {step} of {len(steps)}...")
...    long_running_process()
processing step 1 of 300 steps
processing step 2 of 300 steps
...
processing step 300 of 300 steps

But that mucks up my terminal and causes a lot of scrolling.

So, below are three ways I've found to do this, from simple to over engineered... They all write to stdout using the \r carriage return so that they keep updating the same line and keep my terminal clean.

Quick and Simple

My first attempt at this utilized a basic generator that yields defined "ticks" which simulate a spinning line.

import sys

def spinner(msg="working..."):
    i = 0
    ticks = ["-", "\\", "|", "/"]
    while True:
        tick = ticks[i % len(ticks)]
        yield sys.stdout.write(f"\r{tick} {msg}")
        i += 1

And I would setup and invoke the generator like below.

jobs = ["sample job", "another job"]
for job in jobs:
    s = spinner(f"processing {job}...")
    try:
        for i in long_running_iteration:
            next(s)
    finally:
        s.close()

This works, but I see two problems. First, the second job overwrites the first job, and once a job is done, the spinner just ends at the last yielded "tick" which isn't a good look.

Exiting The Generator

To fix both issues, I'm going to catch the GeneratorExit exception, then place a "✔" before the completed job and jump down a line so that any following output doesn't overwrite the previous output.

import sys

def spinner(msg="working..."):
    i = 0
    ticks = ["-", "\\", "|", "/"]
    try:
        while True:
            tick = ticks[i % len(ticks)]
            yield sys.stdout.write(f"\r{tick} {msg}")
            i += 1
    except GeneratorExit:
        sys.stdout.write("\r✔\n")
    finally:
        sys.stdout.flush()

Catching Errors

But what happens when there is an exception?

$ python spinner_simple.py
✔ processing sample job...
✔ processing another job...
✔ processing job with an exception...
Traceback (most recent call last):
  File "/Users/jbd/Dropbox/DEV/projects/progress-spinner/spinner_simple.py", line 31, in <module>
    raise ValueError("test exception")
ValueError: test exception

As you can see, even though there was an exception while processing the third job, my spinner still put a "✔" and that's not right.

To fix this, I need to now catch any Exception that is not a GeneratorExit. This allows me to put an "𝘅" at the start of the line for the job that errored and still provide the exception information.

def spinner(msg="working..."):
    ...
    except Exception:
        sys.stdout.write("\r𝘅\n")
        raise
    except GeneratorExit:
        sys.stdout.write("\r✔\n")
    ...

That looks much better!

Checkout the full Simple Spinner script on Github.

Context Manager

Building on the simple example, I can easily create a context manager that generates a progress spinner while being used.

First, I can pull the generator out as a separate function...

def spinner_indicator(msg):
    ticks = ["-", "\\", "|", "/"]
    i = 0
    while True:
        tick = ticks[i % len(ticks)]
        yield sys.stdout.write(f"\r{tick} {msg}")
        i += 1

Then, I can and handle all of the setup, exception catching, and tear down inside of the context manager and only call the generator when I need it.

@contextmanager
def spinner(msg="working..."):
    error = False
    try:
        yield spinner_indicator(msg)
    except Exception:
        error = True
        raise
    except GeneratorExit:
        sys.stdout.write("\r✔\n")
    finally:
        if error:
            sys.stdout.write("\r𝘅\n")
        else:
            sys.stdout.write("\r✔\n")
        sys.stdout.flush()

This version allows me to do something like below.

jobs = ["sample job", "another job", "job with an exception"]
for job in jobs:
    with spinner(f"processing {job}...") as s:
        for i in long_running_iteration:
            next(s)

Not necessarily any better than the simple option, just a different solution.

Checkout the full Spinner Context Manager script on Github.

Over The Top

Now, to get extra fancy, I'm going combine what I did above into a Python Class. The Spinner class will allow me to choose different spinners and also allow me to update the progress message while running.

Spinners Galore

There are tons of spinners you can come up with but here are the four I'm going to have available for use.

spinners = {
    "angles": ["◢", "◣", "◤", "◥"],
    "circle": ["◜", "◠", "◝", "◞", "◡", "◟"],
    "dots": ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
    "ticks": ["-", "\\", "|", "/"],
}

Class Structure

I have setup the Spinner class so that it can be used both as a standard generator or a context manager.

class Spinner:
    def __init__(self, style=None, text=None):
        if style is None:
            style = "ticks"
        if text is None:
            text = "Processing..."
        self.style = style
        self.text = text
        self._error = False
        self.spinner = self.frame_generator()

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        if exc_type is not None:
            sys.stdout.write("\r𝘅\n")
        else:
            sys.stdout.write("\r✔\n")
        self.spinner.close()
        self._cleanup()

    def frame_generator(self):
        frames = spinners[self.style]
        i = 0
        while True:
            yield frames[i % len(frames)]
            i += 1

    def update(self, text=None):
        if text is not None:
            self.text = text
        sys.stdout.write(f"\r{next(self.spinner)} {self.text}")

    def error(self, error):
        self._error = True
        sys.stdout.write("\r𝘅\n")
        raise

    def close(self):
        if not self._error:
            sys.stdout.write("\r✔\n")
        self.spinner.close()
        self._cleanup()

    @staticmethod
    def _cleanup():
        sys.stdout.flush()

Using Spinner As A Simple Generator

The most basic usage of the Spinner class is to create an instance of it and then update it each iteration. You can specify the spinner style and the spinner text.

import time

jobs = ["dots spinner", "spinner with exception"]
for job in jobs:
    style = job.split(" ")[0] if "exception" not in job else None
    s = Spinner(style=style, text=job)
    steps = 10
    try:
        for i in range(steps):
            s.update()
            time.sleep(0.25)
            if "exception" in job and i == 6:
                raise ValueError("test exception")
    except Exception as e:
        s.error(e)
    finally:
        s.close()

You could even update the text at a special place in your job progress.

...
if i == steps // 2:
    s.update("half way through")
...

Using Spinner As A Context Manager

The Spinner class can also be implemented as a context manager using the standard with syntax.

with Spinner() as spinner:
    for i in long_running_iteration:
        spinner.update()

And, just as above, you can update the spinner text as you go...

jobs = ["angles spinner", "circle spinner"]
for job in jobs:
    style = job.split(" ")[0]
    with Spinner(style=style) as spinner:
        for i in long_running_iteration:
            spinner.update(f"processing {job} (step {i} of {len(long_running_iteration)})...")

Checkout the full script on Github.

Final Thoughts

There are much better solutions to this problem like tqdm, but since I'm still learning, I like to try and figure out how to do things myself. I definitely learn something each time I do.

Cheers 🍻

The Problem

When working with HTML tables that have lots of rows, finding something particular can be a struggle that involves a lot of scrolling. And, not everyone knows you can do Find within the browser.

The Simple Solution

My first attempt was basic. I typically start all projects and scripts this way... Start simple, get it working, then add features and/or complexity.

Here's the sample HTML table I'll work from...

<table id="search-table">
  <thead>
    <tr>
      <th>Company</th>
      <th>Contact</th>
      <th>Country</th>
    </tr>
  </thead>
  <tbody>
   <tr>
      <td>Apple</td>
      <td>Steve Jobs</td>
      <td>USA</td>
    </tr>
    <tr>
      <td>Microsoft</td>
      <td>Bill Gates</td>
      <td>USA</td>
    </tr>
    <tr>
      <td>Tesla</td>
      <td>Elon Musk</td>
      <td>Mars</td>
    </tr>
  </tbody>
</table>

Setup

First, I'll need an input field with the id search-input for the user query. Then I'll add the id search-input to the table I want to filter. These ids make it easy to select the correct elements in my script.

<input class="form-control" type="text" id="search-input">
<table id="search-table">
  ...
</table>

Now, I can select those two elements inside of my script along with the rows in the table.

const searchInput = document.getElementById("search-input");
const searchTable = document.getElementById("search-table");
const rows = searchTable.querySelectorAll("tbody tr");

I will also go ahead and setup a custom CSS selector to make it easy to hide any rows that don't match the search query.

.hide {
  display: none;
}

Input Listener

Now that I have everything set up and all key elements selected, I need to listen for input in the search-input field.

searchInput.addEventListener("input", function (e) {
  const q = e.target.value.toLowerCase();  
}

And, to make searching through the table easier, I converted the user query to lower case using toLowerCase().

Iterate Over Every Row

With the user input set to variable q, I can iterate over each row using the .forEach() function to check and see if it contains q.

rows.forEach((row) => {
  // do something with each row
});

Checking The Text

How do I check all of the text in the row? The simplest solution I could come up with was to combine the text from each cell in the row into a single string. To do that, I grab each td element in the row using row.querySelectorAll("td").

Now that I have a NodeList of each cell in the row, I can map the textContent of each cell to a new array called matchString.

rows.forEach((row) => {
  const cells = Array.from(row.querySelectorAll("td"));
  const matchString = cells.map((n) => n.textContent.toLowerCase()).join(" ");
});

You'll notice I did two extra things that I didn't mention above. First, I converted the entire string to lower case to match what I did on the user input. Second I joined the resulting array so that I get a single string of all the content separated by the space character.

Now, I can use the includes() method to check whether the user input is found anywhere in the row.

rows.forEach((row) => {
  const cells = Array.from(row.querySelectorAll("td"));
  const matchString = cells.map((n) => n.textContent.toLowerCase()).join(" ");
  const match = matchString.includes(q);
});

CSS To The Rescue

Last step, is to hide the rows that don't match using the .hide class I created in the beginning.

Using the toggle() method, I can add or remove "toggle" a class on any element based off of a variable. I am using the match variable here. So, if the row doesn't match the query (!match) then toggle on the .hide class, if it does match, then toggle off the .hide class.

Best part is, this helps me remove the class when the user query changes and a row now matches that previously didn't.

rows.forEach((row) => {
  const cells = Array.from(row.querySelectorAll("td"));
  const matchString = cells.map((n) => n.textContent.toLowerCase()).join(" ");
  const match = matchString.includes(q);
  row.classList.toggle("hide", !match);
});

As is, this script works great for a simple page. Just embed the script at the bottom of a webpage and go on about your day.

Try it out.

But I needed a little more control...

The Fancy Solution

The portal I was building had lots of pages, and posed two main challenges to the simple script above.

1. Some pages didn't have any tables or an input causing a console error.
2. Some tables had columns that needed to be ignored when filtering.

No Errors For Me

Getting rid of the script querySelector error is simple. Just wrap everything except the first line in an if statement.

const searchInput = document.getElementById("search-input");
if (searchInput != null) {
  ...
}

So, if there is no search input just stop, as there is no need to continue.

Ignoring Columns

Ignoring columns isn't a hard feature addition, I just couldn't decide how I wanted to go about it. I definitely knew I wanted to use data-attributes...

So, I decided that data-attribute-search-ignore-cols would be a comma separated list of index ids (zero based) for the columns that should be ignored (e.g. data-attribute-search-ignore-cols="0,2,7")

const ignoreCols = searchTable.dataset.searchIgnoreCols
  ? searchTable.dataset.searchIgnoreCols.split(",").map(Number)
  : false;

The above allows me to grab the data-attribute if it is present (doesn't have to be if I want all columns searchable), and convert each column id to an integer using the map method.

Now, while iterating over each row and grabbing the textContent, I can check and make sure if any columns should be ignored using the same Array.from() method as above and also paring it with the filter() method this time.

const filteredCols = ignoreCols
  ? Array.from(cols).filter((_, n) => ignoreCols && !ignoreCols.includes(n))
  : Array.from(cols);

This filter says, if data-attribute-search-ignore-cols was specified and if the column id n is in that array, don't include it in the filteredCols array.

The Home Stretch

With "non-ignored" searchable text now in the array filteredCols we can join everything into a string just as before.

const colsText = filteredCols
  .map((n) => n.textContent.toLowerCase())
  .join(" ");

And, then check to see if the query is contained within the string.

row.classList.toggle("hide", !colsText.includes(q));

Putting It All Together

I setup a full working example if you want to check it out.

const searchInput = document.getElementById("search-input");
if (searchInput != null) {
  const searchTable = document.getElementById("search-table");
  const ignoreCols = searchTable.dataset.searchIgnoreCols ? searchTable.dataset.searchIgnoreCols.split(",").map(Number) : false;
  const rows = searchTable.querySelectorAll("tbody tr");
  searchInput.addEventListener("input", function (e) {
    const q = e.target.value.toLowerCase();
    rows.forEach((row) => {
      const cols = row.querySelectorAll("td");
      const filteredCols = ignoreCols ? Array.from(cols).filter((_, n) => ignoreCols && !ignoreCols.includes(n)) : Array.from(cols);
      const colsText = filteredCols.map((n) => n.textContent.toLowerCase()).join(" ");
      row.classList.toggle("hide", !colsText.includes(q));
    });
  });
}

Final Thoughts

I'm no JavaScript wizard but this little script has been very handy lately. Hopefully, you can find use for it in one of your projects.

View the full script with comments on Github.

The Problem

One thing I miss from Safari though is autofilling Two Factor Authentication (2FA) codes. If you use Safari or an iPhone you know how awesome this feature is.

😢 Sadly, Chrome doesn't have this feature...

So, unless you have great eyesight and can quickly read and remember the code before the notification disappears you have to do a multi-step process to retrieve it.

The Solution

If I can work out how to read the notification with OCR (Optical Character Recognition) and extract the code I should be able to recreate 90% of the functionality from Safari.

Enter Keyboard Maestro, the Swiss Army Knife of Mac automation.

Step 1.

The first thing I need to do is read the screen using the OCR Screen action. But, I don't want to OCR the entire screen as that's a waste of resources and could potentially introduce errors later in the macro.

As you can see below, Keyboard Maestro now allows you to define an exact area of the screen to OCR. You'll need to specify how large of an area should be read (Width and Height), and where on the screen Keyboard Maestro should start reading at (Left and Down).

How did I figure out the Width and Height inputs (and Left offset) for the Crop Image function? I sent myself a test notification...

Then, while the notification was still showing, I took a screenshot (Shift-Command-3), opened it in Photoshop, and measured how far the notification was from the top-right corner. It was 361 pixels from the left and 134 pixels from the right so I padded those numbers just a bit to 375 and 150.

You probably also noticed that I used the SCREEN function to calculate the Left input. I often use my MacBook Pro connected to an external monitor so this ensures I provide the correct Left position no matter what monitor I'm using. The - 375 part offsets the area to the left by the width I determined above since we are working from the top-right corner of the screen.

Also note, I'm saving the captured text to the Keyboard Maestro variable OCR so that I can easily access it in later steps.

Step 2.

Below is the text captured during the OCR process. As you can see, it contains the code I'm looking for (934919) from the test notification but it also captured stuff I don't want.

QQ © B&H m4 ZB Tue Nov2 9:56 AM
/ KEYBOARD MAESTRO ENGINE now
Test 2FA Notification
Example: Your 2FA Sign In Code is 934919. Reply
HELP if you didn't request it.

To clean this up I'm using the Search using Regular Expression action on the variable OCR.

This regex is quite simple. The \d matches any digit character (0-9), and the {5,7} is a quantifier for \d that instructs the search to only match groups of consecutive digits between 5 and 7 digits long. The first match the regex finds will be stored in the variable TwoFactorCode.

Why 5 and 7? It's a pretty narrow range and that's to try and minimize errors. Lots of 2FA notifications include the sender phone number in one of two formats, ###-###-#### or ##########. So, if the lower bound of the quantifier range is less than 5, it would capture the parts of the segmented phone number, and if the upper bound of the quantifier range greater than 8 it would capture the non-segmented phone number.

So, why not use 8 for the upper bound then? The quick answer is that I have yet to receive a notification over 7 digits so I'm just trying to eliminate as many potential errors as possible.

Step 3.

Now that I have captured the code, I place it on the system clipboard so it can easily be pasted into a webpage.

Step 4.

Finally, I display the captured code really large just in case I can't paste it directly into the webpage. This is much easier to read than the small notification and stays on the screen even while you type the code.

Eventually I may turn this particular action off as it can be annoying at times 🤷‍♂️...

Potential Problems

So, what happens if a code isn't found?

If the regex can't find a matching code in the OCR'd text the macro gets canceled and Keyboard Maestro sends a notification like below.

If you find this happening often you may need to adjust your OCR Area placement from Step 1 or you may adjust your lower and upper bounds of the regex quantifier in Step 2.

Final Macro

Here's the final macro in all its glory 🙌.

It's really simple but quite useful. You can download it here if you think it could help make your life a bit easier. It's set up to be triggered by the Hyper Key + 2 (Shift-Control-Option-Command-2). The number 2 is easy to remember for "2FA" and also simple to press quickly with your left hand. ✌️

The Problem

Depending on the level of the puzzle, words can go in two, four, or eight cardinal directions... But, due to the number of words provided and how they fit into the puzzle, not all directions for each level are always used.

I needed a way to sort all of the directions actually used by words during puzzle generation so that they display in the same order as a compass.

What I'm Working With

So, I have an answer key for each puzzle that's a dictionary of all contained words along with their start location and direction.

>>> key
{"CAT": {"start": (1, 34), "direction": "SE"},
 "CHICKEN": {"start": (46, 26), "direction": "E"},
 "DOG": {"start": (32, 45), "direction": "NE"},
 "ROOSTER": {"start": (32, 12), "direction": "N"},
 "SHEEP": {"start": (30, 2), "direction": "S"},
 "GOAT": {"start": (29, 48), "direction": "W"},
 "HORSE": {"start": (16, 26), "direction": "SE"},
 "LAMB": {"start": (25, 10), "direction": "N"}}

The Solution

First, I need to get all the directions from the dictionary.

>>> dirs = {v["direction"] for v in key.values()}
["NE", "N", "S", "W", "SE", "E"]

You'll notice that only six of the eight possible cardinal directions were used in this particular puzzle, and if I use the default sorted() method they aren't in the order I need them.

>>> sorted(dirs)
["E", "N", "NE", "S", "SE", "W"]

A Little Helper

To help out, I setup a new variable which has all eight possible cardinal directions in the order they are on a compass (starting at the top and going clockwise).

>>> sort_by = ("N", "NE", "E", "SE", "S", "SW", "W", "NW")

Now, when we I call sorted(), I can provide the key parameter that lets Python know how I want the sorting performed. But I can't just provide sort_by as they key. Python requires a "function or other callable".

Enter Lambdas

The key I'm using to sort by is the lambda function key=lambda d: sort_by.index(d).

My lambda takes each direction from dirs as variable d, looks up its index in sort_by and returns that number. Python then uses that number to determine the sorting placement.

The Result

Finally, if I supply Python's sorted() function with my new key I get exactly what I was looking for.

>>> sorted(dirs, key=lambda d: sort_by.index(d))
["N", "NE", "E", "SE", "S", "W"]

👌 Perfecto! If you follow a compass clockwise, you'll find each direction in the correct order.

Extra Credit

Need a weighted sort based on how many times an item is present?

# list to sort by count
>>> dirs = ["W", "N", "E", "W", "E", "W"]
# ascending
>>> sorted(set(dirs), key=lambda d: dirs.count(d))
["N", "E", "W"]
# descending
>>> sorted(set(dirs), key=lambda d: dirs.count(d), reverse=True)
["W", "E", "N"]

How about sorting by word length?

>>> words = ["nine", "one", "twelve", "seventeen"]
>>> sorted(set(words), key=lambda word: len(word))
["one", "nine", "twelve", "seventeen"]

And, if your information is formatted correctly you can use the Operator Module Functions itemgetter and attrgetter.

>>> from operator import itemgetter, attrgetter
>>> student_grades = (("Ella", 76), ("Dave", 92), ("Jess", 97), ("Bob", 84))
# sort students by grade from highest to lowest using itemgetter
>>> sorted(student_grades, key=itemgetter(1), reverse=True)
[("Jess", 97), ("Dave", 92), ("Bob", 84), ("Ella", 76)]

Now, using attrgetter to sort by a specific object attribute.

# setup a Pet class to structure the objects
>>> class Pet:
...     def __init__(self, name, age, weight):
...         self.name = name
...         self.age = age
...         self.weight = weight
...     def __repr__(self):
...         return repr((self.name, self.age, self.weight))
# create some pets
>>> pets = [
...     Pet("Maddie", 8, 62),
...     Pet("Harper", 13, 15),
...     Pet("Greta", 10, 9),
>>> ]
# sort the pets by weight
>>> sorted(pets, key=attrgetter("weight"))
[("Greta", "10", 9), ("Harper", "13", 15), ("Maddie", "8", 62)]
# sort the pets from oldest to youngest
>>> sorted(pets, key=attrgetter("age"), reverse=True)
[("Harper", 13, 15), ("Greta", 10, 9), ("Maddie", 8, 62)]

Final Thoughts

There are many other ways to do sorting in Python but I think these few are pretty slick. Check out the Python Docs on Sorting for more information and examples. ✌️

Backstory

Previously, I tracked overall time for each project in a "duration" field that I would manually update every time I did any work. And, up until recently non of my time-tracked projects lasted more than week so this method worked just fine... Well, until last month.

See, I bill my clients monthly and some their projects started spanning more than one month, making it hard to determine what I time had already billed when the next month comes around.

To fix this, I created a new table titled "Time Entries" which links back to individual jobs. Every time I work on a project now, I create a new time entry with the date and time that I worked. Each time entry also has a "checkbox" field titled "Invoiced". Now, when the end of the month comes, I can just bill for the time entries that are not checked as "Invoiced".

The Problem

This new method works well, but I got annoyed today when I had to click off sixty-four linked time entries for one client. I do my invoicing from a custom view in the "Jobs" table so this process takes way too long... You have to click the linked record, scroll down and click the "Invoiced" checkbox, then click out of the linked record pop-up.

I know I could create a filtered view in the "Time Entries" table that's grouped by customer but that's not ideal for me.

The Solution

I've recently been learning some JavaScript and knew Airtable had scripting capabilities so I figured I could whip up something to help me out.

Before I started scripting I switched to my custom "Invoicing" view in the "Jobs" table that I mentioned above. This view only shows jobs with "uninvoiced" time entries and has all records grouped by client so things are easier to see.

To this view, I added a new button field that will run my script on the current record when clicked.

Time to Script

Before I start scripting I like to make a list of everything I'm trying to accomplish. This time the list is short but I find it helps me stay on track...

Scripting Steps:

1. Get all time entries for a particular job
2. Loop through all matching time entries
3. Check to make sure the time entry hasn't been invoiced
4. Mark it as invoiced

If you are new to Airtable Scripting like me, here's their Scripting Documentation for reference.

Getting Setup

First I'll need to get the two tables I'm working with as objects so that I can reference and query them. And, I'll also go ahead and query all of the time entries so I can update the "uninvoiced" ones that match the job I'm invoicing.

let jobsTable = base.getTable("Jobs");
let timeEntriesTable = base.getTable("Time Entries");
let timeEntriesQuery = await timeEntriesTable.selectRecordsAsync();

I'll be running this script via a button like I mentioned above, but it can also be ran right from the scripting menu so I need to have a way to choose a record in that case.

let record = await input.recordAsync("Choose a record", jobsTable);

1. Get all time entries for a particular job

Airtable makes it easy to get all of the linked entries for a record by getting its cell value. This provides me with a list of each linked record as an object.

let linkedTimeEntries = record.getCellValue("Time Entries") || [];
output.text("Found " + linkedTimeEntries.length + " total time entries");

2. Loop through all matching time entries

Now that I have each linked time entry, I can loop through them and make sure I'm getting the correct info.

// loop over all time entries for record
if (linkedTimeEntries.length > 0) {
  for (let i = 0; i < linkedTimeEntries.length; i++) {
    let record = timeEntriesQuery.getRecord(linkedTimeEntries[i].id);
    output.text(record.getCellValue("Date"));
  }
}

3. Check to make sure the time entry hasn't been invoiced

While looping, I'll need to make sure that each time entry hasn't already been invoiced, If the boolean value of the "Invoiced" field is false then I'll output the date of the entry as a check.

// loop over all time entries for record
if (linkedTimeEntries.length > 0) {
  for (let i = 0; i < linkedTimeEntries.length; i++) {
    let record = timeEntriesQuery.getRecord(linkedTimeEntries[i].id);
    // if time entry not invoiced
    if (!record.getCellValue("Invoiced")) {
      output.text(record.getCellValue("Date") + " not invoiced");
    }
  }
}

4. Mark it as invoiced

If a time entry hasn't been "invoiced", I will check it off using the updateRecordAsync() function.

await timeEntriesTable.updateRecordAsync(record.id, {
  Invoiced: true,
});

Putting It All Together

Now that all of the steps I laid out above are covered, I can put everything together and give it a test run.

// get the two tables I need to work on
let jobsTable = base.getTable("Jobs");
let timeEntriesTable = base.getTable("Time Entries");
// get all time entries for later reference
let timeEntriesQuery = await timeEntriesTable.selectRecordsAsync();
// when run via button, automatically use that record otherwise choose
let record = await input.recordAsync("Choose a record", jobsTable);
// get all linked time entries for record
let linkedTimeEntries = record.getCellValue("Time Entries") || [];
output.text("Found " + linkedTimeEntries.length + " total time entries");
// loop over all time entries for record
if (linkedTimeEntries.length > 0) {
  for (let i = 0; i < linkedTimeEntries.length; i++) {
    let record = timeEntriesQuery.getRecord(linkedTimeEntries[i].id);
    // if time entry not invoiced
    if (!record.getCellValue("Invoiced")) {
      // check "Invoiced"
      await timeEntriesTable.updateRecordAsync(record.id, {
        Invoiced: true,
      });
      output.text("✅ " + record.getCellValue("Date"));
    }
  }
}

If you are trying something similar, I would highly recommend using a copy of your production Airtable base, or at least make a test "job" with test "time entries".

So, here it is in action.

As you can see, when I want to mark all time entries for a job as "invoiced" I just click the big blue button and the script goes to work. #satisfied

View the full script here

TL;DR

If you just want the final script, here it is with all of the specifics of my project removed. Supply a query string however you want and the script will highlight those tokens in each article element on the page.

// the query of tokens to highlight
var query = "life social page pursuit";
// add regex '|' "or" character in place of spaces
var tokens = query.replace(/ /g, "|");
// regex to find all matching tokens
var match_tokens = new RegExp(tokens, "gi");
// find all articles on the page
var articles = document.querySelectorAll("[id=article]");
// loop through all found articles elements (articles)
for (var i = 0; i < articles.length; i++) {
  // grab the article quote content
  var content = articles[i].innerHTML;
  // loop over the all token matches in content
  content.match(match_tokens).forEach(function (match, i) {
    // replace regex for all whole word token matches
    var replace_tokens = new RegExp(match + "\\b", "gi");
    // actually replace all token matches in content variable
    content = content.replace(replace_tokens, "<mark>" + match + "</mark>");
  });
  // set the innerHTML of the article to the update content
  articles[i].innerHTML = content;
}

From Python To JavaScript

After a visitor successfully submits a search query to my Flask app, I'm capturing their input, sanitizing it, and then passing that query to the search results page as the variable tokens.

Once, the search results page is rendered, I can access that variable via Jinja inside of my JavaScript script.

var tokens = "{{ tokens }}";

Setting Up For Regex

Since, I'll be utilizing Regular Expressions (regex) to find the tokens, I'm going to add regex "or" separators between my tokens using the Jinja Replace Filter.

var tokens = "{{ tokens|replace(' ', '|') }}"; // add regex "|' "or" character

This filter is just like the built-in Python string.replace function, in where it replaces each occurrence of the first argument with the second argument.

You could also do this with the JavaScript string replace method if you are not using Jinja templates.

var tokens = query.replace(/ /g, "|");

Original query string from Jinja:

$ var tokens = "{{ tokens }}";
$ console.log(tokens)
$ "this is a query"

Update query string with regex "or" separators added in:

$ var tokens = "{{ tokens|replace(' ', '|') }}";
$ console.log(tokens)
$ "this|is|a|query"

Cleaning Up The Query

The first issue I encountered were HTML encodings in my string that were added when everything was passed to Jinja.

To remove these, I found a nifty little function from Rob Wu on StackOverflow that strips all HTML encoding so I have a raw string to match.

// remove html encoding from the flask search tokens
// hat tip to https://gomakethings.com/decoding-html-entities-with-vanilla-javascript/
var decodeHTML = function (html) {
  var txt = document.createElement("textarea");
  txt.innerHTML = html;
  return txt.value;
};

Define Regex For Matching Tokens

Since I'll be using regex to find all matching tokens on the page, I'm going to setup a new regular expression that I can apply to my content.

var re_quotes = new RegExp(tokens, "gi");

Limit The Highlights

To make sure I only highlight the search tokens in the areas I want, I'll select all "article" objects on the page.

var quotes = document.querySelectorAll("[id=article]");

Time To Loop

Now that I have all the elements I want to apply my highlighter to, I'll need to iterate over them, find the matches, and apply the <mark> tag.

Iterating Over Any Found Matches

Now that I know I have the correct elements selected, I can iterate over each of them, apply the regex I created earlier to find all matching tokens, and then iterate over those matches.

for (var i = 0; i < quotes.length; i++) {
  var content = quotes[i].innerHTML;
  content.match(re_quotes).forEach(function (match, i) {
    console.log(match);
  });
}

Setting Up The Replacement Regex

To update the found tokens with the correct html tags, I need to setup a replacement regex that I can apply inside of the string replace function.

var re_matches = new RegExp(match + "\\b", "gi");

The "\\b" addition to the token string makes sure I only replace whole word matches.

Updating The Tokens

With my replacement regex setup, I can apply the string.replace method to my content. This adds the opening <mark> and closing </mark> html tags to each token match.

content = content.replace(re_matches, "<mark>" + match + "</mark>");

Applying The Changes On The Page

Lastly, I need to update the page with the newly highlighted content. I can do this by setting the innerHTML of the current quote object of the iteration to the content variable.

quotes[i].innerHTML = content;

The Final Script

Once again, I'm no JavaScript programmer but here's the final working script. It could be shortened a bit by combining some lines and functions, but I find this easier to read and keep up with exactly what's going on.

// remove html encoding from the flask search tokens
// hat tip to https://gomakethings.com/decoding-html-entities-with-vanilla-javascript/
var decodeHTML = function (html) {
  var txt = document.createElement("textarea");
  txt.innerHTML = html;
  return txt.value;
};

// grab all search query tokens from flask
// add regex '|' "or" character in place of spaces
var tokens = "{{ query| replace(' ', '|')}}";
// remove html encoding mess from tokens using function above
var tokens = decodeHTML(tokens);
// setup regex to find all matching tokens
var re_quotes = new RegExp(tokens, "gi");
// find all articles/quotes on the page
var quotes = document.querySelectorAll("[id=article]");

// loop through all found articles elements (quotes)
for (var i = 0; i < quotes.length; i++) {
  // grab the article quote content
  var content = quotes[i].innerHTML;
  content.match(re_quotes).forEach(function (match, i) {
    // loop over the all token matches in content
    // replace regex for all whole word token matches
    var re_matches = new RegExp(match + "\\b", "gi");
    // actually replace all token matches
    content = content.replace(re_matches, "<mark>" + match + "</mark>");
  });
  // set quote content to with updated highlighting
  quotes[i].innerHTML = content;
}

If you would like to give this a try, you can download the script and accompanying files at the gist below.

View the full script here

Well, recently I've just grown tired of the look. There is nothing wrong with the look, I'm just tired of it.

Enter Things 3

Things 3 is gorgeous, and it's a native Mac app, so a few years back, I purchased it from Cultured Code for all of my devices on a whim 🤦‍♂️.

But after trying it out for a few days I wasn't 100% sold on the to-do entry mechanism or their repeating feature, so I never made the switch from Todoist.

The Problem

I often use Todoist as a read-it-later service, so I have a lot of to-dos that need to be moved over to Things 3.

To move over these to-dos correctly, I've have a hurdles to overcome...

Since I enter most of the read-it-later to-dos via the iOS share sheet, the to-do name in Todoist is actually a link in the Markdown link format like below.

Todoist To-do Item With Clickable Link:
[To-do Name](https://website.com)

This looks nice, and also opens the url when you click the to-do name.

If I copy and paste this over in Things 3 it looks crappy.

The better looking way is to put the to-do name first (less the brackets) and then put the url link (less the parentheses) in the notes.

But this way would require a lots of copying and pasting, would be prone to error, and would be a complete pain to do for over 100 items.

The Solution

Now, I could probably hack something together using the Mac Swiss Army knife Keyboard Maestro, but I know that Todoist has an awesome Python API Library and Things 3 has great support for URL Schemes so I should be able to whip something up with Python.

Getting Setup

First, I'll create a new folder for this project and create a virtual environment to work in.

$ mkdir todoist-grabber
$ cd todoist-grabber
$ python3 -m venv venv

Now, I can activate my new virtual environment.

$ source venv/bin/activate

Lastly, I'll create a Python file to hold my code.

$ touch app.py

Todoist API Token

Now I'll need to find my Todoist User API Token which is located in the Todoist app under Settings > Integrations.

I'll save my token as an environment variable in the terminal.

$ export TODOIST_KEY=abunchofgibberish0123456789

Saving environment variables this way is only temporary. As soon as you deactivate your virtual environment, they are lost.

An easier option is to use python-dotenv.

$ pip install python-dotenv

Then, I can load my Todoist API Token into a new '.env' file.

$ echo "TODOIST_KEY=abunchofgibberish0123456789" > .env

Now, whenever I activate the virtual environment for this project my Todoist API Token will automatically be loaded into the environment and accessible in my app.

Todoist Python API library

Doist, the company behind the Todoist app has an official Python API Library. I can install the package using pip.

$ pip install todoist-python

This module will make it easier to interact with the Todoist API, saving me time and effort.

The Code

I'll start off using the Python Interpreter to make sure everything is working correctly with the Todoist API.

>>> import os
>>> from dotenv import load_dotenv
>>> from todoist.api import TodoistAPI

Now that I have everything imported, I'm going to try and get my Todoist token from the environment variable I set earlier.

Next, I need to instantiate python-dotenv to load the environment variables I have setup.

>>> load_dotenv()

Then I can set the variable 'api_key' to my Todoist token.

>>> api_key = os.environ["TODOIST_KEY"]

And, to test out the connection, I'll print the name associated with my token.

>>> api = TodoistAPI(api_key)
>>> api.sync()
>>> print(api.state["user"]["full_name"])
Josh D.

Hey, that's me!

Since this is working, I'll put what I have so far into app.py and start trying to extract my to-dos.

Getting Every To-do from Todoist

I have a lot of to-dos in Todoist, so I'm going to make a function that grabs them all and then stores them in the variable 'todoist_tasks'.

def get_all_tasks():
    return api.state["items"]

todoist_tasks = get_all_tasks()

This way, I don't have to keep reaching out to the API and wasting resources.

My Todoist Projects

Since, I'm only interested in the to-dos inside of my "Review" project, I need to grab all of my projects...

def get_all_projects():
    return api.state["projects"]

todoist_projects = get_all_projects()

And then present a list to pick from...

def pick_project(todoist_projects):
    projects = []
    print("todoist projects")
    for n, project in enumerate(todoist_projects):
        project_name = project["name"].encode(
            "ascii", "ignore").decode("ascii")  # remove emojis
        project_id = project["id"]
        projects.append(project_id)
        print(f"{n + 1}: {project_name}")
    project = int(input("which project id? "))
    return projects[project - 1]

todoist_project = pick_project(todoist_projects)

I'll need this todoist_project variable later as it's the 'id' I will use to find the correct to-dos to move over to Things #.

Finding My Read Later To-dos

This next function will iterate over all of my to-dos and only grab the ones from the "Review" project.

def find_tasks(todoist_tasks, todoist_project):
    tasks = []
    for task in todoist_tasks:
        if task.data["project_id"] == todoist_project:
            content = task.data["content"]
            when = task.data["due"]["date"] if task.data["due"] else ""
            creation_date = task.data["date_added"]
            # if markdown link task then separate out
            if content[0] == "[" and content[-1] == ")":
                title = content.split("](")[0][1:].strip()
                notes = content.split("](")[1][:-1].strip()
            else:
                title = content
                notes = ""
            tasks.append({"title": title, "notes": notes,
                            "when": when, "creation_date": creation_date})
    return tasks

things_tasks = find_tasks(todoist_tasks, todoist_project)

When the function finds a to-do from the "Review" project, it will save the to-do information I need as a dictionary to the list 'tasks'.

Before, appends to the tasks list, the function checks to see if the to-do includes one of the Markdown links I described earlier.

Basically, if the to-do 'content' starts with an opening bracket '[' and ends with a closing parenthesis ')', it's a Markdown link for the purposes of this program.

if content[0] == "[" and content[-1] == ")":
    title = content.split("](")[0][1:].strip()
    notes = content.split("](")[1][:-1].strip()
else:
    title = content
    notes = ""

If the function finds a match for that pattern, it splits the string at the '](' and takes the two parts, title and notes (url).

Things 3 URL Schemes

Now, that I have all of the to-dos that need to be moved, I can use URL Schemes to send the information to Things 3.

To "visit" these special urls, I'll make use of Python's Web-browser controller which will need to be imported into my app.

import webbrowser

Building the Urls

Cultured Code has an awesome URL Scheme Link Builder on it's website. This makes it really easy to figure out the exact url I'll need to create each to-do in Things 3.

Using their Link Builder, I created placeholders for everything I would need to enter and ended up with this url.

things:///add?title=title&notes=notes&when=when&tags=tags&list=list_title&creation-date=creation_date

And with the magic of Python 3's f-Strings I can easily make a custom url for each to-do, I'll just need to have each variable with the curly braces '{}' defined.

f"things:///add?title={title}&notes={notes}&when={when}&tags={tags}&list={list_title}&creation-date={creation_date}"

Covering my A$$

Before I import 100+ to-dos, maybe I should make it easy to find the imported to-dos just in case something goes wrong.

So, I plan to create a new project in Things 3 to hold all of the imported to-dos, which should make them easier to find.

Using the same Link Builder from above, I was able to create this url.

things:///add-project?title=things_project&reveal=true

Visiting this url will create a new project in Things 3 and then reveal that project in the app.

def make_project():
    things_project = f"IMPORT {datetime.now().strftime('%m-%y %X')}"
    purl = f"things:///add-project?title={things_project}&reveal=true"
    webbrowser.open(purl)
    return things_project

As you can see, this function does use the datetime module so I added that to the top of my app.py file.

from datetime import datetime

Next, the function creates the Things 3 url using f-Strings again and visits the url using the webbrowser.open(purl).

The last line returns the name of the new project so that I can use that value when adding my to-dos.

Adding To-dos to Things 3

I have everything in place, now I just need to make a function that creates a custom url for each to-do that needs to be moved.

def add_to_things(things_tasks):
    # create a new project/list to hold the imported tasks
    list_title = make_project()
    # tags must already exist, comma separated
    tags = "todoist"
    for task in things_tasks:
        title = task["title"]
        notes = task["notes"]
        when = task["when"]
        creation_date = task["creation_date"]
        print(f"...moving {title[:30]}...")
        turl = f"things:///add?title={title}&notes={notes}&when={when}&tags={tags}&list={list_title}&creation-date={creation_date}"
        webbrowser.open(turl)
    print(f"tasks moved to things. find them in project {list_title}")

First, I'll call the make_project() function to create and open a new project in Things 3.

Next, I can set whatever tags (must already exist in Things 3) I want to applied to the imported to-dos.

Now the fun starts!

The function iterates over my list of to-dos, grabbing all of the values I need from the dictionary in the things_tasks list to create a custom Things 3 url.

Once, the url is formatted. I visit it using webbrowser.open(turl) and things happen fast.

As you can see, all of the to-dos come flooding in to my new project. Success!

Cleaning Up

Now, I just need to clean up my code and add the if name == main clause so I can use this standalone or on import if need be.

if __name__ == "__main__":
    todoist_tasks = get_all_tasks()
    todoist_projects = get_all_projects()
    todoist_project = pick_project(todoist_projects)
    things_tasks = find_tasks(todoist_tasks, todoist_project)
    print(f"found {len(things_tasks)} matching tasks...")
    cont = input("continue? (y/n) ")
    if cont.lower() != "y":
        print("no tasks were moved.")
        exit()
    else:
        print("starting to move your tasks...")
        add_to_things(things_tasks)

View the full script here

Recently, while reading about Python Type Hints, I wrote a nifty little function to display banners in the terminal.

Backstory

Back in December, while working on the 2020 Advent of Code challenge, I needed an easy way to print what I'm calling "banners" while debugging.

If you've participated in an Advent of Code challenge, you know that while solving the challenges, you print lots of information out to the terminal. And, sometimes you need easily recognizable breaks (what I'm calling "banners") in the output (e.g. new branches in a recursion tree).

I usually do something like this...

>>> print("*" * 40)
>>> print("Thing I'm looking for")
>>> print("*" * 40)
****************************************
Thing I'm looking for
****************************************

Now, there's nothing wrong with this, but it's certainly not pretty.

Let's Make a Function

First, I'll make a new function 'make_banner()' so it's easy to print new banners when needed.

def make_banner(txt):
    print("*" * 40)
    print(txt)
    print("*" * 40)

Now, you just call the function make_banner() and supply your banner text as an argument.

>>> make_banner("Provided as an argument")
****************************************
Provided as an argument
****************************************

Adding Styling

Wouldn't it be nice to have the text centered? That's simple enough...

def make_banner(txt):
    print("*" * 40)
    print(" " * ((40 - len(txt)) // 2) + txt)
    print("*" * 40)

Here, I've subtracted the length of the provided text from 40 (the amount of stars), divided that by 2, and added that many spaces before printing the text.

>>> make_banner("This is a banner")
****************************************
            This is a banner
****************************************

This works, but I notice a few problems.

Problem #1:

If the supplied text is longer than 40 characters, the border stars '*' will end before the text.

>>> make_banner("This is a really really really long banner!")
****************************************
This is a really really really long banner!
****************************************

Problem #2:

If the supplied text length is a negative number, then the padding on the left and right of the text can't be equal.

>>> make_banner("This is a banner!")
****************************************
           This is a banner!
****************************************

Notice there are 11 stars '*' on the left, and 12 on the right. Now, that might not bother you, but as a designer, I just can't 🙈.

Solution:

The fix for Problem #1 is simple enough and as you'll see and it solves Problem #2 as well.

I'll just take the length of the provided string into account when calculating how many stars to print.

def make_banner(txt):
    print("*" * len(txt))
    print(txt)
    print("*" * len(txt))

Running the function give us a better version that works for any length of text and eliminates the centering problem.

>>> make_banner("This is a really really really long banner!")
*******************************************
This is a really really really long banner!
*******************************************

Type Hints

Next, I'll make this function super extra fancy with Python's newish type hints (PEP 484).

Among many things, type hints allow me to specify the type of object my function is expecting to receive. As noted above, this can help with debugging and act as documentation too.

I'll start by specifying that the txt argument should be a string.

def make_banner(txt: str):
    print("*" * len(txt))
    print(txt)
    print("*" * len(txt))

By adding ': str' to the function argument, I'm letting myself/user/type checker/IDE know that the function expects a string to be supplied as the argument. Not a list, or an integer, a string. Now, you could provide something other than a string, but that's not what is expected and doing so could cause problems with the function operation.

At this point, I haven't changed the functionality of make_banner(), but I could definitely add some bell and whistles to make it better.

Optional Arguments

I think the banner would look nicer with padding on each side of the text.

def make_banner(txt: str, padding: int = 5):
    print("*" * (len(txt) + padding * 2))
    print(" " * padding + txt)
    print("*" * (len(txt) + padding * 2))

So, I've added the new argument 'padding' and specified it as an integer with the type hint 'int'. I've also added something else, a default value of 5 '= 5'. This way, if a padding isn't specified in the function call, everything will still look nice.

>>> make_banner("A banner with some padding!")
*************************************
     A banner with some padding!
*************************************

Since I didn't specify any padding, I get the default of five stars '*' on each side of the text.

>>> make_banner("A banner with MORE padding!", 10)
***********************************************
          A banner with MORE padding!
***********************************************

Here, I specified a padding value of 10, so I get ten stars '*' on each side of my banner text.

Let's keep going by adding an optional argument for the border character.

def make_banner(txt: str, padding: int = 5, border: str = "*"):
    print(border * (len(txt) + padding * 2))
    print(" " * padding + txt)
    print(border * (len(txt) + padding * 2))

This new option allows me to change the border character to anything I want. Like before, I set a default of '*', so if nothing is specified, I'll get stars. Let's try it...

>>> make_banner("A banner with some padding!", 3, "-")
---------------------------------
   A banner with some padding!
---------------------------------

Nice! How about a few more?

>>> make_banner("A banner with some padding!", 3, "#")
#################################
   A banner with some padding!
#################################

>>> make_banner("A banner with some padding!", 12, "+")
+++++++++++++++++++++++++++++++++++++++++++++++++++
            A banner with some padding!
+++++++++++++++++++++++++++++++++++++++++++++++++++

A few things to note... If you specify a border that's more than one character, the alignment will be thrown off.

And, even though the 'padding' and 'border' arguments are optional, they must be provided in the order they are defined in the function. If you want to change the border then you must also provide a padding value. So, txt, padding, border, in that order. If you try something like:

>>> make_banner("A banner with some padding!", "+")
TypeError: unsupported operand type(s) for +: 'int' and 'str'

You'll get a TypeError as the function is trying to use the '+' for the padding amount. The workaround for this is simple, just specify which argument you are providing to the function.

>>> make_banner(txt="A banner with some padding!", border="+")
+++++++++++++++++++++++++++++++++++++
     A banner with some padding!
+++++++++++++++++++++++++++++++++++++

By providing the arguments this way, the order actually doesn't matter at all.

>>> make_banner(border="+", padding=10, txt="This is craziness!")
++++++++++++++++++++++++++++++++++++++
          This is craziness!
++++++++++++++++++++++++++++++++++++++

Return Values

You can also specify the return value of your function using type hints. This helps the user know what to expect when running the function.

def make_banner(txt: str, padding: int = 5, border: str = "*") -> str:
    return (
        f"{border * (len(txt) + padding * 2)}\n"
        f"{' ' * padding}{txt}\n"
        f"{border * (len(txt) + padding * 2)}"
    )

You can see the addition of '-> str:' to the end of the function. This is the letting the user/type checker/IDE know a string will be returned.

To make the function correct, I need to return the banner as a string now instead of just printing it out. This is good practice anyway, as I may want to store a banner as a variable instead of printing it right away. I accomplish this by using Python 3's f-Strings.

Now, to store the banner as a variable I can run:

>>> banner = make_banner("Banner as a variable", 4, "#")

Then, to print out the new banner I can run:

>>> print(banner)
##############################
    Banner as a variable
##############################

Or, if I want to print the banner right away I can just put the function call inside of a print statement.

>>> print(make_banner("Print me now! :)", 4, "#"))
########################
    Print me now! :)
########################

Taking It Further

This function could definitely be expansed upon... Maybe implementing some coloring, or vertical padding, but I'll save that for another day.

View the full script here