Dan Morgan • Blog Feed

Automated Testing and Linting for Python Projects

Sun, 02 Aug 2020 00:00:00 GMT

I don't work on Python projects very often, so when I do, I usually need to start from scratch and look up the latest (read: easiest) way to setup automated tests and linting. Luckily, open-source libraries and continuous integration platforms have made the process quick and free. After testing a few different combinations, I've found a solution that works well for me and I hope you'll find it similarly helpful.

First, we'll configure Pytest and Flake8 in our application. Second, we'll integrate those into our local Git workflow using Git hooks (via pre-commit). Third, we'll mirror our local testing in a GitHub Action which will run against pull requests and ensure no wonky code makes it into our main branch.

Prerequisites

In order to dive right in, you'll need to have Python3, a local git repo, and a remote GitHub repo. If you have those already, skip ahead to the next section.

Python 3: To check whether Python 3.x is installed, run which python3 in terminal. If the command is not found, follow the official guide.
GitHub repo: If needed, create a GitHub repo.
Local repo: If you're starting from scratch, clone the GitHub repo created in the step above. If you already have a local project but haven't linked your remote Git repo, see the GitHub docs for steps.

Install Dependencies

In the root of your project, create a requirements.txt file and add pytest, flake8, and pre-commit project dependencies:

####### requirements.txt #######
pytest
flake8
pre-commit

Next, run the following command to install with pip:

python3 -m pip install -r requirements.txt

Run Test Command

After installing Pytest and Flake8, create a sample test to ensure everything is working as expected. First, create src/main.py and add a sample function:

# main.py
def add(a, b):
    return a + b

Next, create src/main_test.py and add the following test assertion:

# main_test.py
from main import add

def test_success():
    assert add(2, 2) == 4

We're now ready to run the test suite. In terminal, you should see a success message when running the following command:

➜  pytest
========================== test session starts ==========================
platform darwin -- Python 3.7.5, pytest-5.3.2, py-1.8.1, pluggy-0.13.1
rootdir: /Users/dan/projects/python-app-testing-and-linting
collected 1 item

src/main_test.py .                                                [100%]

=========================== 1 passed in 0.01s ===========================

Before continuing, add an intentionally failing test to ensure it is also picked up by the pytest command. You should now see something like following:

➜  pytest
========================== test session starts ==========================
platform darwin -- Python 3.7.5, pytest-5.3.2, py-1.8.1, pluggy-0.13.1
rootdir: /Users/dan/Sites/experiments/python-app-testing-and-linting
collected 2 items

src/main_test.py .F                                               [100%]

=============================== FAILURES ================================
_____________________________ test_failure ______________________________

    def test_failure():
>       assert add(3, 2) == 4
E       assert 5 == 4
E        +  where 5 = add(3, 2)

src/main_test.py:9: AssertionError
====================== 1 failed, 1 passed in 0.06s ======================

Before going back and fixing the failing test, leave it as-is in its failing state. We'll come back to it later.

Run Lint Command

Next we'll identify undesirable formatting within our code. To do so, edit your test file and remove the line breaks from in-between the sample tests and save.

# main_test.py
from main import add
def test_success():
    assert add(2, 2) == 4
def test_failure():
    assert add(3, 2) == 4

If your editor is automatically applying standard formatting as you save, that's great. It will make things easier going forward. That said, for this next example, humor me and bypass it temporarily. If you're using VS Code, select File: Save without Formatting from the command palette:

Now run flake8 in terminal and observe the formatting issues it discovered:

➜  flake8
./src/main_test.py:2:1: E302 expected 2 blank lines, found 0
./src/main_test.py:4:1: E302 expected 2 blank lines, found 0

Instead of going back and fixing the issues, keep reading. We'll setup an automatic Git hook in the next section where they'll serve as a useful example.

Add Commit Hook

To automatically validate formatting before code is checked-in to version control, we'll set up a pre-commit hook (using the aptly named pre-commit package). In your project root, create .pre-commit-config.yaml and add the following:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: check-yaml
      - id: end-of-file-fixer
      - id: trailing-whitespace
  - repo: https://gitlab.com/pycqa/flake8
    hooks:
      - id: flake8

Next, run pre-commit's install script to add the hook:

➜  pre-commit install
pre-commit installed at .git/hooks/pre-commit

We're now ready to commit the changes in a new Git branch and in doing so, test the newly installed hook. To do so, follow the commands below:

➜  git checkout -b add-tests-and-linting
Switched to a new branch 'add-tests-and-linting'

➜  git add .

➜  git status
On branch add-tests-and-linting
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   .pre-commit-config.yaml
        new file:   requirements.txt
        new file:   src/main.py
        new file:   src/main_test.py

➜  git commit -m "Add test and linting configuration"
Check Yaml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
flake8...................................................................Failed
- hook id: flake8
- exit code: 1

src/main_test.py:2:1: E302 expected 2 blank lines, found 0
src/main_test.py:4:1: E302 expected 2 blank lines, found 0

If you retained the intentional formatting errors from the previous section, your attempt to commit should be rejected based on the flake8 formatting check. Go back to the test file, fix the formatting (but leave the failing test), and retry the commit. This time, it should succeed as expected.

➜  git add .

➜  git status
On branch add-tests-and-linting
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   .pre-commit-config.yaml
        new file:   requirements.txt
        new file:   src/main.py
        new file:   src/main_test.py

➜  git commit -m "Add test and linting configuration"
Check Yaml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
flake8...................................................................Passed
[add-tests-and-linting 66ebd44] Add test and linting configuration
 4 files changed, 28 insertions(+)
 create mode 100644 .pre-commit-config.yaml
 create mode 100644 requirements.txt
 create mode 100644 src/main.py
 create mode 100644 src/main_test.py

Note: If you're adding this to an existing project, pre-commit's docs recommend running pre-commit run --all-files to run lints against existing files as a baseline. By default, it will only run against the files updated in a commit.

Before setting up the GitHub Action in the next section, push the newly created branch and open a pull request:

➜  git push origin add-tests-and-linting
Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Delta compression using up to 8 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (7/7), 853 bytes | 853.00 KiB/s, done.
Total 7 (delta 0), reused 0 (delta 0)
remote:
remote: Create a pull request for 'add-tests-and-linting' on GitHub by visiting:
remote:      https://github.com/xdmorgan/python-app-testing-and-linting/pull/new/add-tests-and-linting
remote:
To https://github.com/xdmorgan/python-app-testing-and-linting.git
 * [new branch]      add-tests-and-linting -> add-tests-and-linting

Add GitHub Action

Now that everything is working as expected locally, we'll add a slightly modified version of this community GitHub action to run the test suite and linting in a continous integration environment. To get started, create .github/workflows/python-app.yaml with the following contents:

name: Python application
on:
  push:
    branches: [master]
  pull_request:
    branches: [master]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python 3.8
        uses: actions/setup-python@v2
        with:
          python-version: 3.8
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Lint with flake8
        run: |
          # stop the build if there are Python syntax errors or undefined names
          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
      - name: Test with pytest
        run: |
          pytest

Once the workflow file is created, commit it, and push the branch to update the open pull request in GitHub. Upon refresh, there should now be a check that was started automatically.

Depending on how you look at it, this is either a disappointing or desirable outcome, all checks have failed. Click Details and check the output in the Actions tab.

If you're following along, you should see the failing test we added earlier. Remove or fix it locally then commit and push the changes to kick-off a new build.

This second time around, all checks should pass. With that, everything is set up both locally and remotely. There's nothing left to do but smash that merge button and go home for the day. Our work here is done.

TL;DR: Link to Code

In a hurry? Want to use the end result as a starting point for your next project? See xdmorgan/python-app-testing-and-linting on GitHub for everything covered above.

As I continue to adjust my workflow, I'll update this periodically. In the meantime, if you find any problems or know of a better way, please feel free to create an issue or open a PR against the demo repo linked above. To suggest an edit to this article, use the link in the sidebar.

Good Reads: April 18, 2020

Sat, 18 Apr 2020 00:00:00 GMT

Since my last update, the brief glimpse of sunshine we were enjoying in the capital has quickly passed and cold rainy weather has returned to the DMV. With most people stuck indoors for a couple of months now, there is a ton of great content being produced and more time than usual to consume it. That said, this one is a bumper edition—Best to make a pot of coffee ☕️

Top Highlight

Josh Comeau's article, A Static Future, does a great job explaining the power of modern static site generators and clarifies some of the strengths and weaknesses of popular libraries like Gatsby and Next.js. It makes for a great introduction if you're new to the topic

Design Systems

“What Has Changed and Where’s it Going?” by Dave Rupert—An Event Apart video: A close runner up for my favorite piece of content this week, Dave's a great speaker and his presentation at An Event Apart here in DC is no exception. He discusses how advancements in browser support have made redundant some previously popular polyfills and support libraries in an effort to slim down page weights whose growth outpaces data limits and connection speeds.
Layout-isolated Components: Facebook's former 'flexbox guy', Emil Sjölander, argues against the use of several properties whose effects extend outside the bounds of a reusable component resulting in unpredictable and inconsistent behavior in different situations.

CSS

CSS Findings From the New Facebook Design: In-depth analysis of techniques used to build the new Facebook UI
Reverse Engineering WhatsApp Web’s CSS: Breakdown of some of the techniques used to build WhatsApp web and an accompanying Codepen rebuild as reference.
Constrained CSS grids without max-width: Clever technique for contstraining grids with variable bookend-columns instead of a max-width setting.
CSS for internationalisation: Amazing deep-dive into HTML and CSS's i18n-friendly properties (e.g. dir, lang, logical-properties, writing-mode)
98.css: Who doesn't love a bit of nostalgia?

JavaScript

Introduction to Next.js 9: This Egghead course was a great way to jump back in after using Gatsby on a handful of recent projects. Recently updated to empower SSG workflows, my favorite part about Next has always been the way the maintainers put careful consideration into API design to simplify complex functionality into easy-to-use solutions like filename-based dynamic routes 🤯 (Egghead subscription required)
Learn ES Modules in Node with Myles Borins: Insightful walkthrough of Node's recently added ES Module support including self-referential imports and export maps.

Speaking of Gatsby: This site is one of those I recently built with Gatsby, it uses a custom theme (gatsby-theme-xdmorgan) to aggregate and configure popular Gatsby plugins (like a toolkit dependency). This isolates dependency management, allows drop-in reuse on side-projects, and provides quickstart support for TypeScript, Sass, MDX, and other opinionated nice-to-haves. Check it out on npm and GitHub.

Tools

This week an invite for the Framer Web beta arrived in my inbox 📬 Being real-time and web-based, it will draw obvious comparisons with Figma. As a code-backed prototyping tool, I'm interested to see how it can be integrated into a design systems component library workflow, more on that soon!

Architecture

Architecture Spotlight: Event Sourcing: Simple explanation of the event sourcing pattern and how the storage of mutation events (instead of their outcomes) can result in an easily audited historical timeline of changes to saved data.

Performance

How to Prepare and Use Variable Fonts on the Web: Step-by-step guide to subsetting and providing fallbacks when migrating to variable fonts. Given this site also uses Inter, I should probably get on that.
Responsive Images the Simple Way: CloudFour have a few helpful guides to responsive images, this one concisely explains srcset and sizes attributes and how/when to use them with <img /> and <picture /> elements.

Conferences

Jamstack Conf Virtual: Organized by Netlify, the next Jamstack conf is going free virtual, see you there 👋

Sources

Sidebar: Daily newsletter
ESNext News: Weekly newsletter

Thanks for reading! Hopefully the next time I write one of these it will be #cans on tyneside. 🤞

Good Reads: April 11, 2020

Sat, 11 Apr 2020 00:00:00 GMT

Something Different

It's a beautiful spring Saturday here in Washington D.C. and as the warmer weather thankfully arrives in the mid-atlantic, chances are you're also experiencing something very different than your usual routine due to the COVID-19 pandemic. Wherever you are, whenever you're reading this, I hope you and your loved ones are safe and well.

While I would usually be watching Newcastle United or playing pick-up soccer on a Saturday morning, neither of those are options today, so as they say: "when life gives you lemons, catch up on your bookmarked reading list."

Though I'm not always able to keep up, I subscribe to a handful of newsletters—some of which are linked below—in an attempt to stay current in topics of interest: UX, UI design, and software development. Unfortunately though, once I'm done reading and the browser tab is closed, I soon find it difficult to retrieve that great content when the topic it discusses later comes up in conversation.

This actually happened just this past week with an amazing demo of Facebook's internal design tooling from a talk given at a Sketch meetup a while back. Thankfully, one of my coworkers was able to find it from the vague description I was able to muster from memory—They've got skills.

So, in an effort to make these things easier to find in the future, I'm going to start publishing roundups of 5-10 resources (articles, conference talks, GitHub repos) that caught my eye. If you find yourself enjoying the content, these roundup posts are conveniently published along with the rest of my blog posts in my site's dedicated RSS feed so smash that subscribe button in your favorite RSS reader, if you're into that sort of thing.

With that said, let's see what we got goin' on this week 👀

Top Highlight

If I had to pick a highlight this week, it would be Twitch's Beyond Purple design system case study. I currently work as a design system maintainer (or gardener, whichever you prefer) so the elegance of their tokens implementation and their customizable creator colors really resonated with me.

Articles

This morning, I serendipitously came across Stu Robson's post describing how to use design tokens to generate utility classes. Great minds think alike obviously, I also maintain an open-source library, Skeletor, so you can generate utility classes for your own system tokens. While the documentation is still a work in-progress, the best practical example of the library's use is this site which is also open-source.

Videos

This week, I'm working through Brian Lonsdorf's new Front End Master's Hardcore Functional Programming course and already looking forward to the the advanced patterns course next. For an introduction to functional concepts in JavaScript, I would highly recommend Will Sentance's Hard Parts: Functional JS Foundations also on Front End masters (FEM subscription required).

References & Sources

Rendering Lists with React

Tue, 24 Mar 2020 00:00:00 GMT

Let's Get It

In this post, we'll be building a declarative React list rendering component inspired by Ant Design's List and React Native's FlatList to use in situations where you may regularly reach for array.map(). While JavaScript's array methods are amazing modern additions to the language—they improve readability and foster immutable data transformation—they're fairly limited when it comes to UI rendering, but we can use them as a foundation for something better!

Over the next few examples, we'll refactor an array.map() example to use a newly created ListView, then start to introduce functionality designed to cut boilerplate required to implement common patterns for organizing collections of data.

List and List.Item

Before we get started, we'll create a couple unstyled List and List.Item components to use in the rest of the examples. To follow along interactively, see this CodeSandbox Project and feel free to fork and customize/style the examples as we go then share them with me on Twitter

import React from 'react'

// The list container
const List = ({ children }) => <ul>{children}</ul>

// An individual list item with a controlled checkbox
const Item = ({ children, ...props }) => (
  <li>
    <label>
      <input type="checkbox" {...props} /> {children}
    </label>
  </li>
)

// Named export of List and static access of List.Item
List.Item = Item
export { List }

Hardcoded List Items

Now we have <List /> and <List.Item /> created, we can use them to create a basic to-do list.

import React from 'react'
import { List } from './list'

export default function Demo() {
  return (
    <main>
      <h2>Daily objectives</h2>
      <List>
        <List.Item checked>Make some coffee</List.Item>
        <List.Item checked>Write blog post</List.Item>
        <List.Item checked={false}>Profit</List.Item>
      </List>
    </main>
  )
}

Using Array.map()

As our list continues to grow, we'll update to use a simple data structure then start rendering a variable amount of items with array.map()—Don't forget the key prop!

import React from 'react'
import { List } from './list'

/*
items = [
  { "id": 2, "title": "Make some coffee", "complete": true }
  { "id": 1, "title": "Write blog post", "complete": true }
  { "id": 3, "title": "Profit", "complete": false }
]
*/

export default function Demo({ items = [] }) {
  return (
    <main>
      <h2>Daily objectives</h2>
      <List>
        {items.map(item => (
          <List.Item key={item.id} checked={item.complete}>
            {item.title}
          </List.Item>
        ))}
      </List>
    </main>
  )
}

New Challenger Approaches

So far, so good. The example above is a valid and standard approach in most React codebases. Over time, there will be other features we want to add to this list, such as filtering, sorting, and pagination. As the project continues to grow, the boilerplate supporting these patterns will get fragmented and inconsistent, unless we have a way to centralize them.

Let's start our alternative approach by creating ListView to be functionally equivalent to array.map()

// list-view.js
import React from 'react'

export const ListView = ({ items = [], render = () => {} }) => (
  <>{items.map(render)}</>
)

We can now refactor our application code to replace our List.Item rendering

import React from 'react'
import { ListView } from './list-view'
import { List } from './list'

export default function Demo({ items = [] }) {
  return (
    <main>
      <h2>Daily objectives</h2>
      <List>
        <ListView
          items={items}
          render={item => (
            <List.Item key={item.id} checked={item.complete}>
              {item.title}
            </List.Item>
          )}
        />
      </List>
    </main>
  )
}

Improving the API

With the foundation in place, let's add a few more props and, in doing so, add support for many more use-cases.

import React from 'react'

export const ListView = ({
  items = [],
  render = () => {},
  as: Wrapper = React.Fragment,
  container: Container = React.Fragment,
  before = null,
  after = null,
}) => (
  <Wrapper>
    {before ? before() : null}
    <Container>{items.map(render)}</Container>
    {after ? after() : null}
  </Wrapper>
)

A quick note on what the newly added props do before we update the example code. In each case, when these optional props are omitted, they leave behind no trace of their existence rendering either null or a Fragment accordingly.

as: Render the whole thing in a wrapper element.
container: Render an element around the list body.
before: Render a block of content before the list body.
after: Render a block of content after the list body.

import React from 'react'
import { ListView } from './list-view'
import { List } from './list'

export default function Demo({ items = [] }) {
  return (
    <ListView
      as="main"
      items={items}
      container={List}
      before={() => (
        <header>
          <h1>Daily objectives</h1>
        </header>
      )}
      render={(item, idx) => (
        <List.Item key={item.id} checked={item.complete}>
          {item.title}
        </List.Item>
      )}
      after={() => (
        <footer>Complete: {items.filter(item => item.complete).length}</footer>
      )}
    />
  )
}

Composition

At this point, the ListView itself is fully functional and gives us a nice declarative API to render the original example entirely. Are we done? Not nearly. Now we're ready to really get started! With a flexible foundation in place, we can now write a series of thin wrapper components to implement custom functionality or styles.

Introducing Pagination

As our list length grows, one of the first additions we'll want to make is the introduction of pagination. To support a traditional pagination pattern, we'll wrap the ListView with a specialized PaginatedListView.

// paginated-list-view.js
import React from 'react'
import { ListView } from './list-view'

// Pagination Hook
export function usePagination(total, perPage, initial) {
  const [current, setPage] = React.useState(initial)
  const numPages =
    total % perPage ? Math.floor(total / perPage) + 1 : total / perPage
  const onPrevious = () => setPage(Math.max(1, current - 1))
  const onNext = () => setPage(Math.min(current + 1, numPages))
  return { current, onPrevious, onNext, numPages, setPage }
}

// Intercept list items, extract the items for or current page
// then render a standard ListView
export function PaginatedListView({
  items,
  perPage = -1,
  currentPage = 1,
  ...props
}) {
  const offset = (currentPage - 1) * perPage
  const paginated = items.slice(offset, offset + perPage)
  return <ListView {...props} items={paginated} />
}

Sidenote: If you're new to React Hooks, this recently updated free course from Kent Dodds & Egghead The Beginner's Guide to React is an excellent introduction to the topic.

To implement this in our example code, we'll need to add the usePagination() Hook, update the component name from ListView to PaginatedListView, then add two new props: currentPage and perPage.

import React from 'react'
import { PaginatedListView, usePagination } from './paginated-list-view'
import { List } from './list'

export default function Demo({ items = [], perPage = 6 }) {
  const { current, onPrevious, onNext, numPages } = usePagination(
    items.length,
    perPage,
    1
  )
  return (
    <PaginatedListView
      currentPage={current}
      perPage={perPage}
      as="main"
      items={items}
      container={List}
      before={() => (
        <header>
          <h1>Daily objectives</h1>
        </header>
      )}
      render={(item, idx) => (
        <List.Item key={item.id} checked={item.complete}>
          {item.title}
        </List.Item>
      )}
      after={() => (
        <footer>
          <div>
            <button onClick={onPrevious} disabled={current <= 1}>
              Previous
            </button>
            <button onClick={onNext} disabled={current >= numPages}>
              Next
            </button>
          </div>
          <div>Complete: {items.filter(item => item.complete).length}</div>
        </footer>
      )}
    />
  )
}

Render a Table Instead?

We sure can. Let's swap out all the HTML in our example and semantically render a table without modifying anything below the surface and keep the pagination free.

import React from 'react'
import { PaginatedListView, usePagination } from './paginated-list-view'

export default function Demo({ items = [], perPage = 6 }) {
  const { current, onPrevious, onNext, numPages } = usePagination(
    items.length,
    perPage,
    1
  )
  return (
    <PaginatedListView
      currentPage={current}
      perPage={perPage}
      as="table"
      items={items}
      container="tbody"
      before={() => (
        <thead>
          <tr>
            <th>Done</th>
            <th>Title</th>
          </tr>
        </thead>
      )}
      render={item => (
        <tr key={item.id}>
          <td>
            <input
              type="checkbox"
              onChange={() => {}}
              checked={item.complete}
              id={`item_${item.id}`}
            />
          </td>
          <td>
            <label htmlFor={`item_${item.id}`}>{item.title}</label>
          </td>
        </tr>
      )}
      after={() => (
        <tfoot>
          <tr>
            <td>{items.filter(item => item.complete).length}</td>
            <td>
              <button onClick={onPrevious} disabled={current <= 1}>
                Previous
              </button>
              <button onClick={onNext} disabled={current >= numPages}>
                Next
              </button>
            </td>
          </tr>
        </tfoot>
      )}
    />
  )
}

Further Improvement

To expand upon the examples above, here's a few features that can be implemented in just few lines in new composing components without modifying the underlying ListView at all:

Add list sorting and filtering by completion status using header controls
Create an alternate pagination pattern which uses an IntersectionOberserver-wrapped footer to support infinite scrolling

Really, the possibilities are endless. Feel free to fork the CodeSandbox Project or give it a shot in your next side-project and let me know what you find!

I hope the examples above help to illustrate the value of a generic list rendering component and the power of React as a tool to standardize UI patterns irrespective of DOM elements rendered on screen.

For more information, be sure to check out Ant Design's List and React Native's FlatList excellent examples too.

Mailchimp Subscriber Interest Groups with V3 API

Thu, 22 Aug 2019 00:00:00 GMT

A client recently asked me to update their PHP Mailchimp integration to support targeting subscribers based on interests. To my surprise, locating the interest ID was more involved than updating the existing API requests.

Before we get started, we'll need an API key which we'll use to access Mailchimp's API playground and authenticate API calls. If you already have an API key, skip ahead to the Finding the Interest ID section below.

Creating an API Key

In order to create new users using we'll first need to create an API key with access to our account. Sign into Mailchimp then go to the Account Settings > Extras > API Keys page then Create a Key.

Finding the Interest ID

Now that we have an API key, we need to find the interest ID. To do that, we'll need to use the Mailchimp API Playground. Using the API Key we just created, log into the API Playground and follow the steps below to navigate through the ensuing screens to find the desired interest.

First, select Lists then use the Subresources dropdown to select interest-categories. Find the relevant category in the list then use the Subresources dropdown again to access interests. You should now be presented with the list of relevant interests, click the name of the one we want an ID for and you should arrive on the screen above with all the information we'll need.

Usage in API Requests

PHP Example

Download this Mailchimp API wrapper class, and save it next to our script so it can be found by the include(./Mailchimp.php) call on line 7 below.

Next, we need the API Token created in the first section, as well as the List ID and Interest ID from the second. Replace API_TOKEN, LIST_ID, and INTEREST_ID in the constant definitions on lines 2–4.

// Define API config constants
define('MAILCHIMP_API', 'API_TOKEN');
define('MAILCHIMP_LIST', 'LIST_ID');
define('MAILCHIMP_INTEREST', 'INTEREST_ID');

// Include the API Wrapper Class
include('./Mailchimp.php');

use \DrewM\Mailchimp\Mailchimp;

// Instantiate class
$Mailchimp = new Mailchimp(MAILCHIMP_API);

// grab email address from request
$email = $_REQUEST['email'];
$result = '';

// if there's an address make the request to mailchimp, store the response
if ($email != '') {
  $result = $Mailchimp->post("lists/" . MAILCHIMP_LIST . "/members", array(
    'email_address' => $email,
    'status' => 'subscribed',
    'interests' => array(MAILCHIMP_INTEREST => true),
  ));
}

// return status
echo json_encode($result);

Node.js Example

Since writing the original version of this post, I was asked to add the same functionality to a Gatsby site hosted on Netlify. After obtaining necessary API information described above, see below for a JavaScript example or see here for a ready-to-use Node serverless function.

// Node SDK
const Mailchimp = require('mailchimp-api-v3')

// Create MC API instance
const mc_api = new Mailchimp(MAILCHIMP_API_KEY)

// Call subscribe func
const response = await create_subscriber({
  email: 'example@email.com', 
  list_id: LIST_ID, 
  status: 'subscribed', 
  interests: [INTEREST_ID]
});

// Create new subscriber
async function create_subscriber({ 
  email, 
  list_id, 
  status, 
  interests, 
  merge_fields = {} 
}, api) {
  const path = `/lists/${list_id}/members`
  let [statusCode, error] = [null, null]

  try {
    await api.post({ 
      path, 
      body: {
        email_address: email,
        status,
        merge_fields,
        ...format_interests(interests),
      } 
    })
  } catch (e) {
    statusCode = e.status
    error = e.message
  }

  return {
    created: !error,
    error_response: { statusCode, error },
    success_response: {
      email,
      subscribed: true,
      existing_member: false,
      profile_updated: false,
    },
  }
}

// convert from String[] to interest object of `{ [id]: status }` shape
function format_interests(arr = []) {
  return { interests: arr.reduce((acc, cur) => ({ ...acc, [cur]: true }), {}) }
}

Dan Morgan • Blog Feed

Automated Testing and Linting for Python Projects

Prerequisites

Install Dependencies

Run Test Command

Run Lint Command

Add Commit Hook

Add GitHub Action

TL;DR: Link to Code

Good Reads: April 18, 2020

Top Highlight

Design Systems

CSS

JavaScript

Tools

Architecture

Performance

Conferences

Sources

Good Reads: April 11, 2020

Something Different

Top Highlight

Articles

Videos

References & Sources

Rendering Lists with React

Let's Get It

List and List.Item

Hardcoded List Items

Using Array.map()

New Challenger Approaches

Improving the API

Composition

Introducing Pagination

Render a Table Instead?

Further Improvement

Mailchimp Subscriber Interest Groups with V3 API

Creating an API Key

Finding the Interest ID

Usage in API Requests

PHP Example

Node.js Example

References & Resources