Uninstall (don’t just disable) Codeium from your VSCode extensions if Copilot inline suggestions aren’t working

As an employee of Morehouse School of Medicine in a research-related position, I qualify for GitHub Education, which in turn gave me free access to GitHub Copilot. I happily used this for a month or so, but was intrigued by Codeium, another VSCode extension that assisted with AI generated, context aware inline suggestions. Though I appreciated the free access, Codeium offered a free tier for all, and I like the idea of marketplace competition, so I started using that regularly instead of Copilot. Fast forward to this month, when GitHub announced its early Christmas present of a free tier for everyone on Copilot!

Deciding it had been enough time (and also on the heels of GitHub Universe where they announced a ton of new features trying to keep up with Cursor), I reinstalled Copilot and disabled Codeium, excited to see how it had improved. Disappointingly, the inline autocomplete was not working. I tweaked settings, refreshed, reinstalled, and searched Stack Overflow. I even ironically asked the in-editor chat window why it wasn't working, but never was able to isolate the issue or find the magic setting that was breaking it.

Finally, I decided to fully uninstall Codeium (whereas I had just disabled it previously) and voilà! Auto-suggestions are working! I'll report back after more use, but my initial impression is that Codeium's are more helpful. The next step is probably trying one of the AI-focused VSCode forks: Cursor or Windsurf which is Codeium's integrated editor.

Let me know in the comments what that magical setting was that was fixed when Codeium was uninstalled. And if you have opinions on Windsurf vs. Cursor let me know!​​​​​​​​​​​​​​​​

What is Playwright?

Playwright is an exceptional package that facilitates automated end-to-end (E2E) testing for your web application. Its standout feature lies in its ability to utilize real browser engines, navigating and interacting with your web app programmatically to explore every corner of your user interface. This approach helps uncover bugs and regressions before they reach your users. If you've worked with Selenium or Puppeteer before, Playwright is similar but excels in allowing usage across multiple browser engines, such as Chromium, WebKit, and more.

Like any good testing tool, it can (and should) be available locally as you code, as well as on CI (continuous integration) to ensure code quality from the entire team, automatically.

What was wrong with the current setup?

When I started as a software engineer on the Health Equity Tracker, there were no frontend-specific E2E tests in place. All QA was done manually by the developers (and helpful department members on big releases), and as you can imagine on a complex dashboard-style app, edge-case bugs often snuck through the review process. I took it as a challenge to a) identify the up-and-coming industry standard for frontend e2e testing and b) implement a testing suite basically on my own.

Overall I am happy to say I succeeded, and I was able to initially add coverage to the most basic parts of the application. However, with the improvement of both my development skills and Playwright as a tool, we have been able to make significant improvements to our E2E testing setup, making the tests harder (less fragile and flaky), better (improved developer experience with increased visibility and maintainability), faster (the tests were taking quite a long time on CI to run and we were able to reduce that time significantly), and stronger (more comprehensive and representative of the actual user experience).

HARDER

Making the tests less fragile and more resilient

My initial setup used Playwright to spin up a Vite development server (npm run dev) regardless of the environment, and then ran the suite of tests against that dev server. This could happen locally or on CI using GitHub Actions. However, running tests against a quick development build (versus a real production build) can be unreliable for a testing situation.

To make our testing setup less fragile, we targeted our deployed, production builds instead of the temporary dev servers. To accomplish this, we needed to dynamically swap the baseUrl that Playwright relies upon, and ensure that all of our tests were using relative URLs. We set these baseUrl strings using either environmental variables or command line arguments, depending on the environment under test. This allows us to run things in the following ways:

The logic for this dynamic baseUrl was straightforward for prod, staging, and local, as each has a consistent URL to test against and its own .env file to store the URL string. However, our CI also uses a unique test URL for every PR opened against main. This enables fully deployed feature testing (e.g., on a real mobile device, or to run ideas by non-technical stakeholders).

Passing this unique deploy preview URL into our test via GitHub Actions required some research and manual trial and error, but we got it working fairly quickly. Some hiccups still need fine-tuning, but overall, I'm pleased to implement this idea that's been in the back of my head for over a year. To set the baseUrl per environment, I added the following to my config:

use: {
    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:3000',
    /* rest of the config stuff... */
}

And set up my .env files like this:

# .env.production
PLAYWRIGHT_BASE_URL=https://healthequitytracker.org

# .env.staging
PLAYWRIGHT_BASE_URL=https://dev.healthequitytracker.org

This allows the specified URLs as needed, falling back to localhost when run locally or if PLAYWRIGHT_BASE_URL isn't set. For the deploy_preview, I used the following GitHub Actions file, with a few tricky bits borrowed from a post by Joran Quinten:

# frontend.yaml
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions

name: Frontend CI

env:
  NETLIFY_SITE_NAME: 'health-equity-tracker'
  GITHUB_PR_NUMBER: ${{github.event.pull_request.number}}

# run on any pushes to main (including merging PRs),
# and any PR creations or updates against main,
# as long as they include changes to files in /frontend
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    paths:
      - 'frontend/**' # Run when changes occur in the frontend subfolder
defaults:
  run:
    working-directory: frontend

jobs:
  tests_e2e_netlify_prepare:
    # third-party action that waits until Netlify deploy URL is ready
    name: Wait for Netlify deploy
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - name: Waiting for Netlify Preview
        uses: josephduffy/wait-for-netlify-action@v1
        id: wait-for-netflify-preview
        with:
          site_name: ${{env.NETLIFY_SITE_NAME}}
          max_timeout: 60

  tests_e2e_netlify:
    # make sure the above job completes first
    needs: tests_e2e_netlify_prepare
    name: Run E2E tests on deploy preview
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    timeout-minutes: 5
    steps:
      # install node, modules, and playwright
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 19
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json
      - name: Install dependencies
        run: npm ci
      - name: Install playwright deps
        run: npx playwright install --with-deps chromium
      # run the tests!
      - name: run E2E_DEPLOY_PREVIEW
        run: npx playwright test --project=E2E_DEPLOY_PREVIEW
        # base url based on the GITHUB_PR_NUMBER + NETLIFY_SITE_NAME
        env:
          PLAYWRIGHT_BASE_URL: 'https://deploy-preview-${{env.GITHUB_PR_NUMBER}}--${{env.NETLIFY_SITE_NAME}}.netlify.app'
      # store test run reports if they fail
      - uses: actions/upload-artifact@v3
        if: ${{ failure() }}
        with:
          name: playwright-report
          path: frontend/playwright-report/
          retention-days: 30

BETTER

Increasing reporting visibility to improve developer experience and velocity

Initial configuration attempts inadvertently failed to pass the required environmental variables. As a result, the React site would load, but the fetches from our data API would fail. This caused endless issues; running the tests locally would pass fine, but running on CI would fail. Lack of visibility into the Playwright reporting on CI made it impossible to debug these failures.

Finally, I properly implemented the reporting feature on CI, and then, importantly, set it to upload the generated reports as artifacts (final step of the GitHub Actions file above). Playwright includes great video replay, screenshot, and stack trace visualizations that allow you to rewatch what was happening when your tests fail. This insight into the CI failures made it immediately where I had been calling the wrong npm script. Going forward, this increased visibility and improved testing structure should allow our team to write tests more easily, have more confidence in their results, and quickly update them when things go wrong.

FASTER

Faster checks result in a happier, more productive team

Several aspects of this effort result in significantly faster test runs:

1. Running against an already deployed site eliminates the need to start the dev server on CI

2. With the CI server no longer serving the dev build and running tests, we can increase the number of workers Playwright uses, enabling parallelization for simultaneous execution of unrelated tests.

3. Switched the report artifact upload step to run only on test failure, reducing unnecessary executions.

As an example, comparing the before and after run results, we see an improvement of over 30%! Not bad considering the new, faster test suite is both more comprehensive AND more reliable.

STRONGER

Increasing coverage of our tests, more realistically replicating user journeys

A major goal was to increase coverage across all public health topics and demographic/geographic disaggregations provided by the tracker. This wasn't possible before due to the flaky, slow configuration. By running tests against real, deployed production builds, we can now navigate our tests with the same confidence we have using the actual app. We have even had our first open-source community contributions from friends and fellow Denver developers Ali and James, whom I would like to personally thank for their efforts!

To easily generate new coverage, we added a new shortcut to package.json, npm run e2e-new, which quickly runs Playwright's fantastic codegen feature. Regrettably, I had overlooked this feature earlier, likely because of my negative experiences decades ago with code generation in early site builders like Frontpage and Dreamweaver. However, Playwright's codegen is not only easy; it writes more reliable steps than I could write myself! It launches a special browser instance and smaller console and then records your steps as you navigate throughout the app, using the most robust locators available. Initially, we don't even need to include expect statements, since a click()action will fail if its target is not available.

What's next?

Going forward, we hope to:

• Ensure coverage for every health topic available on the tracker.

• Include tests with extensive filtering/UI settings across those topics.

• Divide the tests into 'essential' (run every time) and 'non-essential' (only run on production releases), minimizing wait times.

• Implement a matrix of test settings on nightly production runs, allowing a combination of browsers (Edge, Firefox, Safari) and device settings (mobile, tablet, and desktop widths).

• Ensure the development team culture emphasizes adding test coverage whenever a bug is fixed; minimizing regressions.

Thanks for reading! Feel free to follow along or contribute to the open-source HET GitHub repo, and let me know if you have any questions on optimizing your Playwright configuration!

Photo by Rock'n Roll Monkey on Unsplash

Last year, I spent a lot of time improving accessibility, including some open-source contributions upstream to fix the 3rd-party package we are using to render Vega.js using React. My best (somewhat hacky) solution for this data issue though, was to render duplicate invisible text elements with the geography name and data point alongside the visible map shape. This allowed a screen-reader user to "walk" through the listed items on the map and hear each item's information.

This inflated the DOM size, but I didn't realize by how much until recently! I figured there would be roughly twice as many elements... half visible, half not... turns out I was accidentally reproducing the ENTIRE accessible dataset several times: for the primary map as expected, and also for every small territory circle we produce under the main map. This means in some cases I was generating THOUSANDS more invisible elements than expected (56 states and territories 7 Vega.js components up to 10 maps with one per race group in our multimap mode)!!! Even worse than the additional work for the browser caused by that many elements, the screen reader user would have to skip over those additional 6 lists, hearing duplicate information each time.

As you can see from the lighthouse report, there are still TOO MANY ELEMENTS, but cutting back from over 6k to over 3k is a big step in the right direction! Beyond the code improvements, I'm also excited to start incorporating ML in generating human-readable insights from datasets for situations like this (and importantly, to present the "insight" text for ALL users since it could help everyone in understanding the map data). Anyone else working on similar accessibility projects or have innovative data visualization solutions to share?

At the Health Equity Tracker, the largest dataset we work with is a case-level set provided by the CDC with every COVID-19 infection in the United States, along with additional information including race, ethnicity, county, and other symptoms. The data is provided in zipped .csv files in a private GitHub repo (due to patient privacy) and contains several hundred million rows across over a dozen files. Initially, our tracker as coded by Google.org provided only the cumulative "snapshot" of the current rates of disease outcomes by race, age, or sex to the county level.

Last year however, in a big push by our team at Morehouse School of Medicine, we were able to implement time-tracking, whereby we additionally aggregate and plot these disease rates across every month since January 2020.

As the requirements grew, so did the time it took to run the aggregation script, which needed to be done locally by an authorized team member before uploading for further processing and calculations on Google Cloud Run. The CDC releases new datasets regularly, so this entire process easily burned an entire day each month for one of our team members. After starting the script locally on my 2021 MacBook Pro, it would take nearly 3 hours to complete the aggregations.

With a few tweaks, I was able to reduce that 3-hour run-time to ~25 minutes!

Improvements

I love that our codebase is open-source, so you can check out the exact PR here, but below I'll outline the specific steps that sped things up so significantly. To benchmark, I ran the Python script against just a single raw .csv file (instead of all ~20).

Time taken by the original code to process a single file: 313s

Here are the incremental changes I made, and the improved speed measured from each step:

• Two major items: Using a vectorized combine_race_eth() function, which used Pandas' built-in optimized functions rather than mapping/applying a regular Python lambda function against each row, and only reading in the needed columns with the arg usecols in the read_csv: 191s

• The above changes, plus removing some unused string manipulations meant to detect and remove empty quotes "": 180s

• The above changes, plus using chunk_size = 1 million (using chunk size splits the df into chunks so that your machine doesn't have to hold the entire thing in memory; however my computer is fast enough to hold the entire thing so it's faster to have bigger chunks and fewer iterations. : 75s

• Increasing chunk_size to 2 million: 64s

• Increasing chunk_size to 5 million (I left the chunking in place even though the chunk_size effectively doesn't use it, in case the CDC does ever ship us a file over 5 million rows, then this code will use the chunking as needed): 57s

When running against the full set of all raw files, the run time went from 2 hours and 40 minutes down to 34 minutes and produced identical output files: Nearly 5x faster!

Sanity Checks

Of the utmost importance for us as a research institution, particularly one presenting information on underserved populations, is to ensure data integrity every step of the way. To ensure my refactor didn't cause unexpected results, I implemented a "sanity check" and renamed all of the existing .csv results (produced by the old code) with the suffix _old, then wrote a quick bash script that compared every line in the _old and newly refactored results:

•             for new_file in cdc_restricted_by_*.csv; do
                  old_file="old_$new_file"
                  if diff -q "$old_file" "$new_file"; then
                      echo "Files $old_file and $new_file are identical."
                  fi
              done
  

To ensure the check itself was working, I also ran this diff command to compare the county_race file and the state_race file and observed hundreds of differences (as expected).

Abandoned Optimizations

The most common suggestion I found when researching Panda's optimization was to utilize the vectorized methods built-in to Pandas, rather than using .apply() to apply a lambda or function against each row of the dataframe iteratively. In some cases, like refactoring the race and ethnicity -> race/ethnicity function, this did speed up the algorithm significantly. However, there were several further vectorization optimizations I tried out that surprisingly slowed down the process and made it worse. These were all .str dataframe methods, which are a known subset of vectorized methods that can be less efficient than the Python loop-based approach.

One example of an abandoned optimization was dealing with our county FIPS codes that need to be treated as strings, complete with leading zeros (for example Denver County FIPS is 08031, which when treated as a number turns into 8,031.

The type conversion and string formatting are done in the existing code using .map():

df[COUNTY_FIPS_COL] = df[COUNTY_FIPS_COL].map(lambda x: x.zfill(5) if len(x) > 0 else x)

and I tried using the built-in method to accomplish the same thing:

df[COUNTY_FIPS_COL] = df[COUNTY_FIPS_COL].str.zfill(5) # actually slower 😿

Overall, any attempts at optimizations with the data frame .str methods were abandoned as they did not improve performance, and in some cases slowed it down significantly.

Next steps

Although 25 minutes is a lot more manageable than a few hours, and the script is now only run monthly, there are several more steps I am looking into to further optimize this aggregation. If you are reading this and have insight into any of these techniques, let me know in the comments!

• 🧑‍💻Parquet instead of 🧑‍💻CSV: Using the CDC's provided .parquet files instead of the .csv files. From what I understand Parquet files are binary/machine-readable, so slightly more difficult to work with (you can't just peek at the contents in VSCode) but more efficient from a memory standpoint. It's unclear if this would be super helpful though, since each file is only used briefly and not continuously opened and manipulated.

• 🐻‍❄️Polars instead of 🐼Pandas: A more significant change, which would further complicate the codebase, is to introduce a new library for this aggregation called Polars. Its usage is quite similar to Pandas, but it can stream data and manipulate datasets that are larger than the machine's memory. You can load data into a "lazyframe", and perform various aggregations, filters, and calculations, and then the library is clever enough to only deal with the bits of data that are needed for the specified processes. Interestingly, Polars is written in Rust, but the library is available both within Rust AND within Python.

• 🦀Rust instead of 🐍Python: Maybe out of scope for the project, but of course the only option I've started pursuing (mainly because it was exciting to finally have a tech problem that Rust could help me solve and I wanted to check out what all the buzz was about). Since this aggregation is performed on the local development machine, and is quite distinct from the rest of our Airflow data pipelines, I could refactor this entire script into Rust (using Polars as mentioned above).

Here's a little snippet of what I've gotten working... Be nice Rustaceans! I'm sure this is super inefficient!

fn process_lazyframe_into_by_sex_df(lf: LazyFrame) -> Result<DataFrame, PolarsError> {
    let known_sex_groups = vec!["Male", "Female", "Other"];
    let know_sex_series = Series::new("KNOWN_SEX_GROUP", known_sex_groups);
    let is_known_sex_group = col("sex").is_in(lit(know_sex_series));

    let groupby_cols = vec![col("state_postal"), col("sex"), col("time_period")];

    let df = lf
        // "time_period" as cdc col with only YYYY-MM
        .with_column((col("cdc_case_earliest_dt").str().str_slice(0, Some(7))).alias("time_period"))
        // count every row as 1 case
        .with_column(col("time_period").is_not_null().alias("cases"))
        .with_column(col("hosp_yn").eq(lit("Yes")).alias("hosp_y"))
        .with_column(col("hosp_yn").eq(lit("No")).alias("hosp_n"))
        .with_column(
            col("hosp_yn")
                .neq(lit("Yes"))
                .and(col("hosp_yn").neq(lit("No")))
                .alias("hosp_unknown"),
        )
        .with_column(col("death_yn").eq(lit("Yes")).alias("death_y"))
        .with_column(col("death_yn").eq(lit("No")).alias("death_n"))
        .with_column(
            col("death_yn")
                .neq(lit("Yes"))
                .and(col("death_yn").neq(lit("No")))
                .alias("death_unknown"),
        )
        // only keep Male/Female/Other/Unknown options for sex
        .with_column(
            when(is_known_sex_group)
                .then(col("sex"))
                .otherwise(lit("Unknown")),
        )
        // only keep known postal codes; combine rest as "Unknown" for national numbers
        .with_column(
            when(
                col("res_state")
                    .is_null()
                    .or(col("res_state").eq(lit("Missing")))
                    .or(col("res_state").eq(lit("Unknown")))
                    .or(col("res_state").eq(lit("NA"))),
            )
            .then(lit("Unknown"))
            .otherwise(col("res_state"))
            .alias("state_postal"),
        )
        .groupby(groupby_cols)
        .agg(vec![
            col("cases").sum(),
            col("hosp_y").sum(),
            col("hosp_n").sum(),
            col("hosp_unknown").sum(),
            col("death_y").sum(),
            col("death_n").sum(),
            col("death_unknown").sum(),
        ])
        .collect();

    df
}

So far I've gotten it to the point that it:

• Loads all the .csv files in a folder

• Combines them into a LazyFrame

• Performs the column calculations, manipulations, and aggregations needed for the SEX table generations and the produced tables are identical to the full tables produced by our Python code

Run time is well under 5 minutes! Of course, that's only for one of the breakdowns, so it's still not clear if my super newbie Rust code is actually going to save any time or not. I'll follow up once I've had a chance to finish, for now the repo is available on my GitHub. Overall, I've enjoyed messing around in Rust (it feels like when I was learning TypeScript, except I can't just cheat and use any to force things to work when the compiler yells!). And importantly, I've freed up a lot of free time for our small team, allowing us to work on new features for the tracker and waste less time on the waiting for code to run.

In Chrome:
1. ⌘+D to make a new bookmarklet in your bookmarks toolbar
2. Name it whatever, like "Hide PR Whitespace"
3. Paste javascript:document.location+="?w=1" as the URL
4. Click it whenever GitHub is showing you whitespace diff

Ideally, everyone in your repo will end up pushing pre-linted code, which should align styling and white-space issues. In reality this won't always happen, and seeing white space in the diff can be annoying and make the PR looks more massive than it is.

GitHub recently introduced a Pull Request level setting that gets remembered for the life of the PR that allows whitespace to be hidden. This is a pretty useless feature for most of us since it requires 3 clicks to enable and must be done on every new PR.

The other option is to manually append ?w=1 to the pull request URL, which triggers the same white space suppression. Luckily, this can be done automatically via JavaScript plopped into a bookmarklet, allowing us a 1-click option for easier PR reviewing. Follow the steps at the top of this post to make your very own bookmarklet. Enjoy!

Caveat: this won’t work if there are existing params on the URL, since subsequent params require the & rather than the initial param’s ?

Add -- --host to the end of your package manager's start command. Note the extra hyphens!

As a follow-up to my blog on viewing localhost on mobile, I thought I would share how to do the same with Vite specifically. A recent task I completed at work was migrating healthequitytracker.org from create-react-app to Vite. In another article, I'll share the details of how this cut our CI build time by 75%, saving the team over 25 hours per month 🚀, but for now, I'll discuss the not-so-obvious way you can have Vite expose the local server's actual IP address (allowing you to view on another device as explained in my other blog post).

Updating your package.json scripts

"scripts": {
...
 "start": "vite -- --host"
...
}

Vite politely gives you the message Network: use --host to expose when you run the dev server, however it doesn't explain HOW to use that flag. Most likely you have a package.json folder inside your project, and in that JSON is a property called "scripts". These are the scripts that run when you start your local server with npm run start or npm run dev, or whatever your team has set up. If you were running the Vite command directly (and not via npm scripts), you would use the flag as they write: --host, however, to pass the flag along via npm to Vite, you must include the additional double-hyphen, making the needed flag -- --host. By adding that flagged-flag to your script command, you'll tell the script to pass along the flag to Vite, which will then automatically expose the local host address when the server starts up.

Directly from the command line

You can also use this flagged-flag directly on the command line if you only want to expose the IP a single time and not by default, so instead of using npm run dev you would use npm run dev -- --host

Now that you have the address, you can easily view the development server directly on your mobile device.

And yes, if you look closely, I am pleased to finally be working on a feature that will kill a UI carousel that has been in place for far too long. If you're wondering why this is exciting to me, check out Should I Use A Carousel?

Just swap localhost for your machine's local IP address

Update: for vite bundled apps, read my follow up: Expose Vite's local address

Update: for create-react-app you can easily copy it from the terminal where you are running the server

While building sites, your content should always be easily accessible regardless of the user's device size, speed or type. It is much easier to build in the responsive design from the beginning, rather than the trap we often fall into where we develop on blazingly fast desktop machines hooked up to ethernet, and then wonder why the site barely functions on an older mobile phone via crappy 3G connection.

Thankfully, it's pretty painless to view your local development from one machine (like your laptop) on another machine (like your iPhone). Follow the steps below (for Mac but they'd be similar on any OS) to start seeing your dev site on a true mobile device!

1. Find your computer's local IP address:

2. Open “Network settings”

   

3. Highlight and copy the IP address (using right click -> copy, NOT cmd-C)

   

4. Start your local dev server, launch browser and view the site in progress. For create-react-app it would be localhost:3000

5. Replace localhost with the computer's IP address, but keep the port (the :3000), and confirm the same site loads. My app’s new url would be 192.168.1.192:3000

6. Done! Copy-paste that new address and send it to any iPhone, Android, tablet, smartTV, whatever! As long as the device is on the same network as your computer running the dev server, it should work.

There was! ffmpeg is a super powerful CLI that allows extremely flexible video processing. I was able to run this command in the terminal ffmpeg -i ./path/to/my/bigvideo.mp4 ./path/to/my/shrunkenVideo.mp4 and it would shrink it nicely.

However, I personally hate switching contexts between GUI stuff (screen recordings, browser based tools, etc) and CLI stuff (like ffmpeg). I wanted to be able to simply right-click on the video file in question on my desktop and click "Shrink Video".

Enter Automator Quick Actions! Here's how I configured my right-click "Shrink Video" option:

1. Open Automator from your Applications
2. Select the gear icon "Quick Action" and click "Choose"
3. Scroll down the list and drag "Run Shell Script" (with a little terminal icon) onto the right-hand "workflow" box
4. Make the phrase say: "Workflow receives current movie files in Finder.app"
5. Inside the "Run Shell Script" box, select "Pass Input: as arguments"
6. Paste this script in the text box:

   export PATH=/usr/local/bin:$PATH
   for f in "$@"
   do
    cd ~/Desktop
    ffmpeg -i "$f" "$f"-shrunk.mp4
   done
   

7. CMD-S to save; I used the quick action name "Shrink Video"
8. Find a video file, right-click on it, and the new Option should appear under "Quick Actions" and/or "Services".

Next step: figure out the flags in ffmpeg to limit the output size to 10mb, compressing the original file as much as necessary to make it fit.

Try to connect to the Starbucks WiFi and then visit http://captive.apple.com/hotspot-detect.html

Image by Jon Tyson on Unsplash

On the site are some existing animations which are pretty, but purely decorative. Due to their motion effects, they could potentially trigger vestibular disorders in some users, resulting in nausea, dizziness, etc. Thankfully, we have an easy way to account for these animation preferences in pure CSS, however in React and in particular while rendering various images, it requires a different approach.

The step-by-step is outlined clearly on Josh's post, but in short I created a new hook called usePrefersReducedMotion in our /utils folder, and then instantiated that hook on the two components where animated gifs are rendered. Then, I use a ternary to render either the fully animated gif or a single frame still image, based on the Boolean result of the function call:

<AimToGoItem
  src={ prefersReducedMotion 
    ? "img/HET-fields-no-motion.gif" 
    : "img/HET_Fields_1_v2_1000px.gif"
  alt=""
  title="Empower policy makers"
  text="We plan to develop policy templates for local, state, and
federal policy makers, and help create actionable policies
with diverse communities."
/>

Also, note I have included blank alt text to the image using alt="". This is best practice for situations like this where the images are decorative, and a screen reader user would have no use for knowing what the images contains. However, you do need to specify the blank string as the attribute, otherwise leaving off the alt entirely will result in the screen reader trying to parse the element by reading the file name or similar.

I am still quite new to the world of accessibility (commonly referred to as A11y), so if anything you see here is not in fact best practice I would love to know; leave a comment or direct message me here or on Twitter.

Photo by Jacob Granneman on Unsplash

Some tricky configuration is required, and the existing Python-specific documentation is sparse and buggy (or simply not written for a production setting). My eventual solution involves using a Google Cloud Platform service account and a custom Heroku buildpack

The Problem

Little Cabin (my final project for my recently completed General Assembly bootcamp), provides tools for extended families to securely share their vacation property’s logistics and memories. One key feature is allowing the in-app scheduling to sync with a Google Calendar, and though I assumed it would be a simple matter of hooking up to the Google Calendar API, it was by far the most difficult problem to solve.

The Project Setup

To get myself started, I've followed along with my two previous blog posts:

• Setup a new Django app
• Deploy it to Heroku

I have also created a blog example repo on my GitHub that includes all of the steps in this entire tutorial, so feel free to clone that repo and have a look at the code. You'll still need to do a lot of person configuration to get it working, including creating your own service account, google calendar, Heroku project, .env files and Heroku config vars, etc.

Calendar Access Module

We will start by creating a new module (just a separate .py file) to contain all of the Calendar API access methods. Python automatically exports, but you must explicitly import them into any code that needs access.

In your main_app/ folder, create a file called calendar_API.py. In that blank file:

• touch main_app/calendar_API.py
• then in VSCode, add the following to the blank file:

def test_calendar():
    print("RUNNING TEST_CALENDAR()")
    test_event1 = {"start": {"date": "2022-01-01"}, "end": {"date": "2022-01-07"}, "summary":"test event 1"}
    test_event2 = {"start": {"date": "2022-02-01"}, "end": {"date": "2022-02-07"}, "summary":"test event 2"}
    events = [test_event1, test_event2]

    return events

Add Route to URLs

In VSCode, open main_app/urls.py and add the following the following item to the urlpatterns[] array below the existing "home" route. This will give us two pages in total, our "Home" and our "Demo" which will demonstrate the connection to Google Calendar API

• path('demo/', views.demo, name='demo'),

Add To Views

In your views.py, import the module method at the top of the file using:

• from .calendar_API import test_calendar

Now add a second method which will display the demo template (later on we'll fill in the code that actually does some work)

def demo(request):
    results = test_calendar()
    context = {"results": results}
    return render(request, 'demo.html', context)

Add To Templates

Create the html template that will serve as the HTML for eventually displaying the fetched results from the API:

• touch main_app/templates/demo.html

Add the following to to the blank demo.html file in VSCode:

<!DOCTYPE html>
<html>
  <head> </head>
  <body>
    <h1>Demo</h1>
    <ul>
      {% for result in results %}
      <li>{{result.start.date}}{% if result.end.date %}-{% endif%}{{result.end.date}}: {{result.summary}}</li>
      {% endfor %}
    </ul>
  </body>
</html>

Now, edit your home.html to include a link to this new demo.html. Add the following line after the <h1>Home</h1> line:

• <a href="{% url 'demo' %}">Connect to Google Calendar</a>

Install Dependencies

In your terminal, run the following commands to install needed packages and save those as project dependencies:

• pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
• pip3 freeze > requirements.txt

TEST IT!

Let's make sure the plumbing is working before we add more logical complexity!

In your terminal, start the local server (make sure you're in your activated env):

• python3 manage.py runserver

In your browser

• Visit localhost:8000
• Click on the "Connect to Google Calendar" link
• Confirm the headline "Demo" is displayed

Setting up Calendar Access

These instructions draw heavily on this amazing Stack Overflow answer

Register for Google Service Account

• Follow Google's directions to setup the new credentials here: developers.google.com
• You can skip the section entitled: "Delegating domain-wide authority to the service account"
• Save the credentials file somewhere memorable; you'll be using these locally and later when setting up Heroku config vars

Configure a Test Calendar

• View your Google Calendar
• In the sidebar will be a list of your calendars; click the "+" button and select "Create New Calendar" from the dropdown
• Fill in a name "Example", and click the "Create Calendar" button
• Hover over this newly created calendar back in the sidebar, and click the three vertical dots, and select "Settings and Sharing" from the dropdown
• Scroll down to "share with specific people"
• Add your newly created service account email address (it will be "client_email" in your saved credentials file)
• Scroll down to "Integrate Calendar" and copy the Calendar ID string, then paste it somewhere safe as you'll need it again soon

Manipulate Calendar from Local Django App

Setup Local Config Vars

• Open your local environmental variables file; in this setup it's example/.env.
• Add the following:

  # Google API
  CAL_ID={{{THE CAL ID YOU COPY-PASTED FROM YOUR GOOGLE CALENDAR SETTINGS PAGE}}}
  

Create Your Local Credentials File

• touch google-credentials.json
• Copy paste the entire JSON object from your downloaded credentials file into this newly created .json file. As an example, mine looks like this:

  {
  "type": "service_account",
  "project_id": "example",
  "private_key_id": "BLAHBALH",
  "private_key": "-----BEGIN PRIVATE KEY-----\nSUUUUUUPER------LONG-------STRING\n-----END PRIVATE KEY-----\n",
  "client_email": "USERNAME@EXAMPLE.iam.gserviceaccount.com",
  "client_id": "1234567890987654321",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/username%40example.iam.gserviceaccount.com"
  }
  

Update Your .gitignore

• in VSCode open your .gitignore file
• Ensure all of the following lines are present, which will prevent git from indexing sensitive information (and later distributing it publicly on your GitHub)

# this hidden folder contains your local, virtual environment
.env

# this hidden file contains sensitive keys and environmental config vars
# if you've named your primary project folder something other than
# 'example' please adjust the following line as needed 
example/.env

# this token contains your sensitive google service account info
google-credentials.json

Important!

Please ensure both example/.env and the newly created google-credentials.json appear greyed out in VSCode

Add The API Calls

• Open calendar_API.py, and replace the existing code with everything in the following block (basically replacing our test logging function with the real API calls)

from decouple import config
from google.oauth2 import service_account
import googleapiclient.discovery
import datetime

CAL_ID = config('CAL_ID')
SCOPES = ['https://www.googleapis.com/auth/calendar']
SERVICE_ACCOUNT_FILE = './google-credentials.json'


def test_calendar():
    print("RUNNING TEST_CALENDAR()")

    credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)
    service = googleapiclient.discovery.build('calendar', 'v3', credentials=credentials)

    # CREATE A NEW EVENT
    new_event = {
    'summary': "Ben Hammond Tech's Super Awesome Event",
    'location': 'Denver, CO USA',
    'description': 'https://benhammond.tech',
    'start': {
        'date': f"{datetime.date.today()}",
        'timeZone': 'America/New_York',
    },
    'end': {
        'date': f"{datetime.date.today() + datetime.timedelta(days=3)}",
        'timeZone': 'America/New_York',
    },
    }
    service.events().insert(calendarId=CAL_ID, body=new_event).execute()
    print('Event created')

 # GET ALL EXISTING EVENTS
    events_result = service.events().list(calendarId=CAL_ID, maxResults=2500).execute()
    events = events_result.get('items', [])

    # LOG THEM ALL OUT IN DEV TOOLS CONSOLE
    for e in events:

        print(e)

    #uncomment the following lines to delete each existing item in the calendar
    #event_id = e['id']
        # service.events().delete(calendarId=CAL_ID, eventId=event_id).execute()


    return events

Test It, Again!

At this point, running the local server (make sure you're in your activated env):

• python3 manage.py run server and viewing localhost:8000 in browser should display the same button as before. However, now clicking the button should trigger the series of API calls we added above:
• Create a new test event on your test calendar
• Download ALL events from that calendar (there's probably only the one unless you manually added any on the Google Calendar site)
• Display those downloaded events both as console logs and render them onto the HTML page under the "DEMO" heading

If that's all working locally, the next big step is adjusting everything so that it works in production on Heroku.

Connecting the Deployed App

These steps come mainly from this excellent DevDojo.com blog post

Add Custom Buildpack

• In your browser, head to Heroku and log in
• Open up the existing App that you've deployed (perhaps you followed my previous blog post: Deploying Django to Heroku?
• Choose "Settings" from the nav bar
• Scroll down and click the "Add Buildpack" button (there should already be "heroku/python" listed as installed
• Paste https://github.com/buyersight/heroku-google-application-credentials-buildpack into the text input box labeled "Enter Buildpack URL"
• Click "Save changes"

Add Heroku Config Vars

• Scroll up just a bit and click the "Reveal Config Vars" buttons
• You will now be adding all of the keys and corresponding values from your local .env file, along with some addition Heroku only entries.
• In the KEY box, paste CAL_ID, and in the corresponding VALUE box, paste the string that occurs after the = in your local .env. In my case it looks like this fF43grgewefwFWeww1231233r23rwq@group.calendar.google.com. Make sure there are no quotation marks or spaces before and after the string
• Click "Add"
• In the new blank KEY box, paste GOOGLE_APPLICATION_CREDENTIALS, and in the corresponding VALUE box paste google-credentials.json
• Click the "Add" button
• In the new KEY box, paste GOOGLE_CREDENTIALS, and in the corresponding VALUE box, paste the entire JSON object. You can literally copy all of the code that is now in your local google-credentials.json, starting with a { and ending with a }
• Click the "Add" button

Deploy to Heroku

• Head back into your terminal, and save your progress in your local git:
• git add .
• git commit -m "getting ready for deploy"
• Optionally push to your GitHub if you have added a remote repo
• Deploy using git push heroku main (or master if you haven't yet switched your local git to default to the main branch)

Confirm Credentials Were Created

Once you're notified the deploy was successful, you can use the terminal to manually explore your project's Heroku server and confirm that the credentials file was created automagically by the build pack and those config vars.

• heroku run bash (wait a few seconds for it to log in)
• ls
• You should see google-credentials.json listed on the floor of your project. Yay!
• exit will bring you back onto your local machine

Run It!

Head to your deployed Heroku site, and see if the button still works to populate / print out the Google Calendar events. If so, great job! If not, scope the last paragraph here for some potential debugging tricks.

As noted in the previous article Deploying Django to Heroku, it can be helpful to configure your Django project and Heroku to give more detailed error logging. Check out the instructions on this stackoverflow where they explain adding DEBUG_PROPAGATE_EXCEPTIONS = True and a LOGGING = { ... } library to their settings.py

Sundial Photo by Marian Kroell on Unsplash

If you've written full stack applications in JavaScript using Node, Express, perhaps Mongoose for accessing a database, maybe some packages like Passport to help manage user authentication and authorization, etc, you quickly find yourself repeating the same setup patterns over and over. The only differences come in when you accidentally misconfigure a setting or a route and spend hours debugging. Django aims to, if not replace all of those steps, at least condense those disparate processes into one.

The following step-by-step guide will assist a beginning Python developer in launching a Django project on their local development server (and then deploying it to Heroku in the next blog post).

If you’re starting a brand new project, skip this section. Otherwise if you are downloading someone else’s project, run the following commands instead to properly configure it on your machine. This is the equivalent of running npm i when freshly cloning someone else's repo. When finished, continue at step "Creating a Home Page" below

1. python3 -m venv .env
2. source .env/bin/activate
3. pip3 install -r requirements.txt
4. python3 manage.py migrate
5. python3 manage.py runserver
6. Visit localhost:8000 in your browser

Having issues?

• if your project contains environmental variables, add them to an .env file inside your inner project folder (mine is pedalcollector_project/.env)
• try reseting your database (you'll lose anything you've added so be careful!) DROPDB {{{your_database}}} and CREATEDB {{{your_database}}}
• in settings.py, to run locally you'll want DEBUG=True; to deploy securely you'll have to change to DEBUG=False. I manually set an env variable in each environment and then DEBUG will be set automatically.

Django Environment Setup (New Project)

Python can and should be run in a virtual environment; this relates to the fact that your actual operating system utilizes Python code and by safely keeping your projects in a protected environment, you minimize the risk of accidentally misconfiguring your entire system. In short, you'll be simulating a mini-computer inside your computer, and running your Django project from there. You can quickly tell when your terminal is inside of the virtual environment by looking for the (.env) at the beginning of your terminal prompt:

New Folder

Create and navigate into a new folder that will contain your entire project

• mkdir your_cool_thing
• cd your_cool_thing

Setup Local Git Repo

• git init
• git add .
• `git commit -m "initialize a cool thing"
• optionally connect to a remote Github repo at this point

Virtual Environment

Create a virtual environment

• python3 -m venv .env

Activate it

• source .env/bin/activate

Database

Create a postgres database. You'll need this exact name again soon, so write it in your project notes somewhere you'll remember.

• createdb example-db

example-db is the example I'll be using; you can use whatever you want throughout this post, just be consistent!

If you have weird errors while testing things and somehow perhaps have corrupt data in your database, you can easily remove and re-add the database with the following commands in your terminal:

1. dropdb example-db
2. createdb example-db
3. python manage.py createsuperuser

Dependencies

Install Django and dependencies. Psycopg2 helps Python interact with your postgres DB (similar to how Mongoose allowed Node to easily interact with MongoDB)

• pip3 install django-extensions
• pip3 install Django
• pip3 install psycopg2

  if that didn’t work run: psycopg2-binary.

• pip3 install python-decouple

  please note there is a difference between _pythondecouple and decouple, you need the former.

Record those settings: requirements.text is the Django equivalent of your Node app's package.json, informing everyone what settings and packages must be configured to function.

• pip3 freeze > requirements.txt

Project Setup

Django projects can contain multiple Django apps.

New Project

Create a new project

• django-admin startproject example .

Make a file to secretly store your local environmental variables (a.k.a. config vars)

• touch example/.env

Make a git ignore file

• touch .gitignore

Specify the files and folders to ignore

• Open the blank .gitignore file in VSCode

For a comprehensive .gitignore file like you might get from a create-react-app, you can visit gitignore.io and select Django. This will generate a complete file for you: click to view Django .gitignore

• Whether you build your gitignore or copy and paste from the site above, be sure it includes the following items:

# this hidden folder contains your local, virtual environment
.env

# this hidden file contains sensitive keys and environmental config vars 
example_project/.env

Setting Up Environmental Variables

• in VSCode, open settings.py (inside your example/ folder)
• scroll down to the line that declares the SECRET_KEY=, and cut the entire line (CMD+x)
• open the newly created example_project/.env file (it should be currently empty)
• paste in the secret key from above, but be sure to remove the empty spaces around the = and remove all quotes from the value after the =. You could also use any random secret string you like
• add in ENVIRONMENT=development on a new line
• add in DATABASE_NAME=example-db (or whatever you named your db that I told you to write down for later!)

Your .env file should end up looking like this:

ENVIRONMENT=development
SECRET_KEY={{{your_secret_key}}}
DATABASE_NAME=example-db

Reading In Env Variables

Now, we want to make our app read these sensitive or configuration dependent variables, whether it is in production (e.g. deployed to Heroku) or development (working locally on your own computer). To read variables from the .env file you created and filled in the last step:

• open settings.py
• add from decouple import config at the top (right below the existing import)
• where you removed the SECRET_KEY line in settings.py, add back this line which will now read it dynamically (from your .env locally or your deployed config vars): SECRET_KEY = config('SECRET_KEY')
• scroll to the line that says DEBUG=True and replace with the following block:

  if config('ENVIRONMENT') == "production":
    DEBUG=False
  if config('ENVIRONMENT') == "development":
    DEBUG=True
  

• below, replace the line with ALLOWED_HOSTS with ALLOWED_HOSTS = ['herokuapp.com','.localhost', '127.0.0.1', '[::1]']

  If you will be deploying this somewhere else, replace Heroku with your actual app URL

Main App

Back in your terminal (which should still have the environment activated), create a second app within this project called main_app

• python3 manage.py startapp main_app

If you're having issues, make sure:

• you included the . at the end of the start project command
• you might need to use the command python instead of python3; this seemed to occur on newer Macs or machines where python --version and python3 --version both referenced the same release of Python. The error popping up was a raise ImportError with the message couldn't import django no module found

Let Django know about your 2nd app:

• Open the project in VSCode: code .
• Open your project settings: example_project/settings.py
• Scroll down to Installed_Apps and add main_app, as the new first element in the array. Remember the comma!

Development Server

Start up the development server on your local machine

• python3 manage.py runserver
• Open a browser and visit localhost:8000

Development Database

Configure the project for postgres by changing the database entry in settings.py, and reading the database name as an environmental variable.

# new database info
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': config('DATABASE_NAME'),
    }
}

Migrations

Stage the db migrations (kind of like git adding and committing, but for changes to the database schema as the app evolves over time

• stop the development server by going back to your terminal and pressing CTRL+C
• python3 manage.py makemigrations (this probably won't do anything)
• python3 manage.py migrate (this should run through the models in the app like the built in users, and add this info to your database)

Restart your server (you can do this regularly while debugging)

• start your server again: python3 manage.py runserver

Creating a Home Page

Add a home route

Routes are defined in the urls.py file(s); you could add all of your routes to example_project/urls.py, but it is best practice for each Django app to define its own and include a link to the new URLs file in the project's URLconf:

• stop the server: CTRL+C
• touch main_app/urls.py
• Open the newly created file in VSCode
• Set up the imports and basic route using the code below:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    # more routes will go here
]

Using an empty string "" as the first parameter in path() is telling Django to route the base URL with no added paths to the home view (e.g. your-project.com/ Later we will add more routes, for example using "about/" as the first argument in the new route, and linking that to an about page, which the user will access by going to your-project.com/about

Now, include this new file in the existing project’s urls.py

• Open example_project/urls.py
• Add a new item to the urlpatterns array, making sure the items are separated by commas
• Also you will need to import the include function before calling it in the array
• It will end up looking like this:

from django.contrib import admin
# from django.urls import path
# add include to your imports from django.urls
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    # add this line below
    path('', include('main_app.urls')),
]

Add a home view

Now that the home route knows where to direct the client, you need to make a home view as a connector between the current route and the correct template to render. Open up your views.py and add the following method:

def home(request):
    return render(request, 'home.html')

Add a home template

Starting very simply, you'll create the home.html file

• mkdir main_app/templates
• touch main_app/templates/home.html
• Open home.html in VSCode and paste in some valid HTML as a starting point:

Tip: to save a step, in VSCode you could right click on main_app in the navigation bar, and select "New File", and then add the line templates/home.html. This will create the templates folder and also the html file in one command

<!DOCTYPE html>
<html>
    <head>

    </head>
    <body>
        <h1>Home</h1>
    </body>
</html>

Back in your browser, visit localhost:8000 and refresh to view your sweet new home page. If it doesn't work, remember to restart your Django server:

• python3 manage.py runserver

Done!

You should now have a functioning (very simple) Django app within your project, viewable on your local machine. To continue building, follow the next steps:

• Adding more routes, templates, and rendered data (blog post currently being written)
• Reading from your database (blog post currently being written)
• Deploying your Django app on Heroku

Cover Photo by Jukan Tateisi on Unsplash Pedalboard Photo by Jonathan Dubon on Unsplash

In the previous Django - Getting Started post, we set up a new Django app, basically creating a fullstack Python Hello World.

In this post, we will deploy this very basic app to Heroku (a free hosting platform which can run a Django server along with other types of web services). There are many ways to deploy Django, but not a single tutorial I've found online actually worked for me as written. Therefor, I've collected the process that finally did the trick and have outlined it below. A lot of the process comes from our bootcamp instructors, with some customization found several layers deep on Stack Overflow and Reddit (and eventually some personal manipulation). Please let me know if this works for you, and comment below if you have any questions!

Deploy Process

Get Ready

• Load up your terminal and cd into the floor of your Django project. Running the command ls should your requirements.txt, manage.py, main_app folder, and example_project, amongst several others. My example is below (some of these files will be created in the following steps)

Log In With Heroku CLI

You will need to have a Heroku account for this process. It used to be free to sign up, and you should also install the CLI (command line interface) from Heroku to complete the following steps:

• heroku login and press any key to launch a browser window which will allow you to sign in to Heroku

Procfile

This file will tell Heroku what actions to take when it receives a web request:

• create a blank file with no file extension: touch Procfile

  ensure the capitalization is exact on Procfile; if you accidentally mixed the casing up you can fix it using this method I wrote about

• open the new Procfile in VSCode, and add this line. If you followed along with part one the project is called example. There should be 3 folders inside your local directory, a .env, a main_app/ that was created most recently that contains your home route/view and a example/ that was created initially and contains a route to your admin, and a settings.py. You want the last one of these.

  web: gunicorn example.wsgi
  

Runtime

This file simply tells Heroku which exact version of Python to use:

• python3 --version displays your current version of Python locally
• copy that exact series of numbers; mine is 3.9.2
• touch runtime.txt and open it in VSCode
• type python- and then paste (no space in between) the exact version. Mine ends up as python-3.9.2

More Packages

Why re-invent the wheel? Someone already got all this cool stuff working; use it!

• pip3 install django-on-heroku
• pip3 install gunicorn
• pip3 install whitenoise
• open settings.py
• add import django_on_heroku near the top of your file under your other import statements
• scroll the very bottom of settings.py
• add django_on_heroku.settings(locals())

Update Dependencies

• pip3 freeze > requirements.txt

Deploy

• heroku create example --buildpack heroku/python

  This will try and create a Heroku project with the URL example.herokuapp.com. If someone has already taken your preferred name you can change to anything else that you want

• heroku addons:create heroku-postgresql:hobby-dev - adds a free postgreSQL database to your free Heroku account

Set Heroku Config Vars

In the previous post, we set our app's local config vars in an .env file and read them out dynamically. Please ensure your app is set up properly to use the following commands and allow Heroku to store its own config vars

• heroku config:set DISABLE_COLLECTSTATIC=1 - prevents one problem, seems to cause some others 🤦‍♂️ (see note at the end for a potential fix)
• heroku config:set DATABASE_NAME=example-db
• heroku config:set ENVIRONMENT=production
• heroku config:set SECRET_KEY=whatever_your_secret_key_is

Push to Production

• git add .
• git commit -m "fingers crossed"
• git push heroku main - this will push your app up to the newly created Heroku project, rather than pushing to GitHub or some other remote as you normally would with git push origin main

  If you are still using master branch instead of main, you'll want to swap that word, and it must be from one of those two named branches that you initiate the push

Fix Deployed Database

Now, you'll tunnel in to the Heroku server with your command line, so you can see what's going on in there and make needed updates to the free database they gave you.

• heroku run bash
• once inside, run python3 manage.py makemigrations. As before, there might not be any changes after this step
• python3 manage.py migrate - this brings your database up to date with the built-in user models that Django provides
• exit gets you out of Heroku and back on to your local machine

See If It Works!

• heroku open will launch the site in a browser.

  If you have problems, typing heroku logs --tail will let your terminal log all sorts of difficult to decipher messages, including some that will help you figure out what's wrong. To exit this logging feature, use CTRL+C.

To view even more helpful errors, follow the instructions on this stackoverflow where they explain adding DEBUG_PROPAGATE_EXCEPTIONS = True and a LOGGING = { ... } library to their settings.py. And as Deepak Raj mentioned in the comments, you may also need to run python manage.py collectstatic (or python3 manage.py collectstatic) in your terminal with your project's virtual environment activated before git committing and redeploying. This fixes some of Django's issues finding static files.

Photo by Rodion Kutsaev on Unsplash

Some Terminology

Understanding a new concept is often frustrating as the resources you reference might include unfamiliar terminology. Even worse are the circular definitions where they “explain” one term you don’t know by using 3 other terms you also have never heard of. Here is a brief run down of the key elements of a hash map and how they relate to one another:

• Hash (Hash Function): a process of converting an item (or value) into a key (or location index) in a predictable way; in this case determining a table location based on some property of the item that needs to be stored there
• Hash Map: a data structure that stores items efficiently by using a hash function to determine items locations
• Hash Table: an implementation of a Hash Map that specifically uses a table-like structure (as opposed to another type of data structure)
• Collision: when your Hash function assigns the same location to multiple items
• Probing: one way of resolving a collision: iterate through the rest of your table (looping around to the beginning if needed) until you find a new, open location for the item that caused the collision
• Chaining: another way of resolving a collision; insert the new colliding item into the location along with the existing item(s), and chain them together using a linked list or similar sub-structure

Getting Started

I personally start these computer science coding exercises the same way I start my web application projects: by writing my user stories. What exactly will I, as a user of this data structure, want it to do? Once I have these stories in place, I start to determine what classes I might use to best represent the entities involved. Then, it's a matter of creating methods for the relevant classes that will allow me, as a user, to interact with this object. The final step is creating a test program that can instantiate this class and test its functionality by walking through the execution of each user story. I look forward to learning more about Jest, PyTest, and other similar automated testing tools to improve this part of my process.

User Stories

These are the basic things someone would want a hash map to do:

• accept a value and store it using a hash function
• inform you whether a value is present in the map or not
• remove a particular value from the map (if it is present)

Classes

The classes I used in my implementation were pretty limited:

• Hash_Map()
• Stack() - in a previous blog post, I had created a stack structure utilizing a linked list. It needed some updates, but worked well for resolving collisions using chaining
• Node - I had already created this class when creating the stack with linked list implementation, and didn't even need to touch it for this exercise. Modularity!

Functionality

Brainstorming

I find it helpful to sketch out all of the functionality I can think of that might be needed for each user story. Sometimes it's 1-to-1, but often a story might contain several steps that can be broken down. In my case, all of these functions will technically be methods since they will exist as properties of the classes I defined above. Some of these class methods will be public and accessible directly by the user, while others will be private and simply accessed internally by other class methods.

To start, I often just create empty placeholder functions which log their own name:

def hash(self, value):
     # placeholder method - but this will eventually do something cool!
     print(f'Hash')
     return

When I start to flesh out those functions, I'll write out the steps in #comments to visualize my logic flow. Another helpful step is to log any passed arguments with some descriptive text: print(f'Hash(): hashing {value}"). Once these are logging properly, it will be much easier to isolate future errors as being in the business logic rather than in the routing or setup.

Class Methods of Hash_Map()

Public Methods

(called by the user in our test.py or any implementation program)

• insert() - User Story #1. Accepts an item, hashes to calculate the key, and places the item in the structure (in my code, a list within Hash_Map called referenced with self.table)
• search() - User Story #2. Accepts an item, and returns a Boolean (True or False) indicating whether the item was found in the hash map.
• remove() - User Story #3. Accepts an item which it removes and returns if found, otherwise returns False

Internal Methods

(called from other methods within the same instantiated class)

• get_hash() - take an item and calculate a key or table index based on the item's value(s).

  Python Note: hash is already a keyword in Python so don't try and name this method hash() as I initially did; it was causing some very strange errors until I realized my mistake

• __str__() - this is a special method in Python, referred to as a "dunder" method (double-underscores), and will allow you to add a customized response when your object is converted to a string (using print(object) or str(object) in the test code for example). Normal Python behavior for objects of instantiated classes would be to return a memory address, but we would like to return a formatted string so we can actually view our beautiful new hash map!

Class Methods of Stack()

Since our Hash_Map class will rely on inner linked lists (to resolve collisions), we will load up a previously written stack with a linked list module using from linked_list_stack import Stack. We can eliminate some of the methods from Stack as they won't be needed, e.g. reverse(), to_list(), and peek().

We will also need to add some additional methods to complete the user stories' search() and remove() methods, specifically those in table locations that are storing more than one item. So Hash_Map.search() will find the correct location on the table where the item should be, but Stack.contains() will then check every item stored at that particular location's Stack for a match.

Note: I decided to implement a Stack() on every table location, regardless of the number items at that location. This may be inefficient; I'll continue my studying and see if it's better practice to store an item "naked" at first, and then place the naked item and any new items into a linked list only as needed to resolve collisions.

Public Methods

(called from within Hash_Map)

• push() - classic stack behavior which plops the value on top of the stack. This continues the work of Hash_Map.insert() in my code
• contains() - walks node by node through the particular stack looking for a match.
• remove() - similar to contains() in that it walks through the stack checking for a match (and then removing it if found). However, the implementation gets a bit trickier; first, you must check your match against the next node in line, not the current, since to remove the current you'll need to connect the previous node to the next. This is very similar to the idea of "don't drop your rope" I discussed in Reverse a Stack with Python; you need to take care not to lose track of your previous and next nodes as those are the connections that hold the chain together
• __str__(): similar to the special method within our hash map class, we need a custom method when an instance of our stack is converted to a string

Note: as in our Snake Tac Toe game; it's very easy as a beginner to get tripped up by referring to an instantiated object, when you really meant to refer to a particular property of that object. Here, in both contains() and remove(), we need to compare the search item (a string) to the string value of each particular node, not to the node itself. In my code there are two ways I do this, the first is by calling .value on the node, other places I use str(node), which internally calls the special __str__() method we added. Either way, you must be sure you are comparing values of the same type. You can confirm a variable's type by logging: print(type(a_variable)) and seeing what you are actually dealing with.

def contains(self, item):
        current_head = self.head
        while current_head != None:

            # 👎This won't work 👎
            # if current_head == item: return True

            if current_head.value == item: return True
            # 👍 But this will! 👍  

            current_head = current_head.next

        return False

Testing our Hash Map

I try to keep my class definitions in their own .py files when possible. They can easily be imported into other files and scripts as needed. For this project, I am using 3 files:

1. hash_table.py - contains our new hash map class, utilizing a table full of stacks internally
2. linked_list_stack.py - contains our Stack class and the very simple Node class, which is used to create the links in our linked list stack
3. test.py - starts with some arbitrary data; instantiates an object of class Hash_Map(); then adds, finds and removes various data from that structure

To import one file into another, you can just use the import statement (as opposed to JavaScript where you must also explicitly export within the file to be imported).

Performance and Big O()

A rule of thumb recommendation is to make your table about 30% larger than your data set when hash mapping; this helps to minimize wasted resources by having the table too large and with lots of empty locations or too small and resulting in many collisions. We therefor send in the TABLE_SIZE as a calculated argument using this line: TABLE_SIZE = int(len(data) * 1.3)

A properly hashed table should be nearly as fast as a basic array, since the values are mostly a single lookup. This means the time complexity would be BigO(1) for arrays, and also for absolute best-case hash maps. However, if the table you choose is too small, there will be more collisions (multiple items overlapping and stored in the same locations). Our insert() method still will be BigO(1) since it's just the single operation to get to the correct location and the second operation to push our item on to the top of that stack. Retrieving and deleting that item though could require walking through every item within a particular stack. It's possible that every item we need to store could somehow end up in the same table location, meaning our hash map is really just one giant linked list. In this worst-case scenario, our hash map would have BigO(n), since it would walk through every single item we added to the structure.

More To Come...

Overall, this implementation is very simple, as my goal was really to just to get it working. The hash algorithm I chose is not very sophisticated; it tallies the ascii value of a string's characters and then chops the sum down until that number fits inside the table. There are many other hash methods, which can optimize performance and minimize required space in memory. I'm excited to have this basic version up and going, and a more complete mental model of what is happening. I plan to continue implementing these data structures and algorithms in the languages I'm learning, and would love to hear from you if you have any comments, corrections or feedback. Thanks for reading!

To view the code or suggest changes, visit the GitHub repo.

Photo in cover image by Jan Baborák on Unsplash

If your projects start generically and later grow into something cool (or the focus changes completely) it's easy to change their names and stay organized. It requires renaming locally: mv {{{ OLD_FOLDER_NAME/ }}} {{{ NEW_FOLDER _NAME/ }}}, renaming remotely on GitHub (via their web interface), and updating the connections between the two: git remote set-url origin {{{NEWGITHUB.GIT_URL}}}

Two Repos

The biggest thing to understand when you're first starting off with git and GitHub is that they are two different things! Like Java and JavaScript, just because one name contains the other doesn't mean they are the same. Git is the program that runs on your machine and keeps track of incremental changes to selected projects. GitHub is an online company (owned by Microsoft now) that allows you to store and share your git repositories online. It also allows for all sorts of wonderful collaboration via the web interface.

Specifically, if you have a project on your computer that's also on GitHub, you are managing two distinct git repos. You are likely keeping the two syncing by using git pull and git push from your local machine. If you decide to change the name of a project, there are a few simple but crucial steps you need to take to keep everything consistent for your own organization and for this connection to be maintained.

Rename the remote repo

You could do these steps in any order, but I like to start with the visual interface provided by the GitHub website. Head to the GitHub repo page for the project you'd like to change the name of.

Rename on GitHub using the web interface

• Click on "settings" (next to "insights" on the horizontal navbar)
• Type in a new name in the "Repository Name" box. In general, avoid using spaces or weird symbols in any file or project names
• If that name is available (i.e. you haven't used that exact name before) you'll see a green check mark, and you can then click "Rename"

Copy the new URL

• You'll be redirected back to your repo page
• Click on the green "Code" button/dropdown

• Click the clipboard icon button, which will copy the project's .git url to your computer's clipboard. This will be the new URL for your remote repo.

Rename the local repo on your computer (using terminal)

Back on your computer, load up your terminal and cd your way into your local project folder. Note: by default .git files are hidden, meaning using ls in terminal will not show your .git folder. You can type ls -a to confirm you're in the right folder when you see your .git folder displayed.

Set your new git remote

• Once you confirm you're in the correct folder in your terminal, type git remote -v. This will display all of your remotely connected .git repos. Below mine only shows the old GitHub repo, but if you have deployed to Heroku or Netlify using their CLIs, you will see other remote locations beside origin

origin    https://github.com/benhammondmusic/generic-project-1.git (fetch)
origin    https://github.com/benhammondmusic/generic-project-1.git (push)

• Since these old remote links are now out of date from our GitHub project's new name, we need to set the new url . git remote set-url origin {{{PASTE_THE-COPIED_GITHUB_URL_HERE}}}. In my example, the full command is git remote set-url origin https://github.com/benhammondmusic/cool-new-name.git. Make sure your URL ends with ".git".
• If you have a different setup, or are trying to change a different repo (for instance on Heroku, etc), replace the word origin with the name of of your remote location (e.g. heroku).
• Test that the git remotes have been updated properly by again running git remote -v. It should show the updated remote URLs:

origin    https://github.com/benhammondmusic/cool-new-name.git (fetch)
origin    https://github.com/benhammondmusic/cool-new-name.git (push)

Important! If you have you collaborators on this project, they will each need to update their local git remotes using this same command!

Rename your local repo

You could leave everything as is now, and be able to git push and git pull your changes between the local and remote repos with no problem. However, personally I like to update my project's local folder to match the new name of the remote repo.

• Confirming you are still in the same folder as the above step (at the level where your .git file is), type cd .. to go up one level.
• Confirm you're in the right place by typing ls and viewing your old project folder name in the displayed list of folders and files
• Change the folder's name by using mv {{{ OLD_FOLDER_NAME/ }}} {{{ NEW_FOLDER _NAME/ }}}. In my example, my command is mv generic-project-1/ cool-new-name/
• Again, confirm by using ls and your new project name should be displayed instead of the old name

Things to note:

• mv command can be used to move files and folders, or to rename them. It's weird, but it's just the way it is
• Confirm that both of your {{{ FOLDER_NAME/ }}} names above end in a trailing slash: mv generic-project-1/ cool-new-name/ not mv generic-project-1 cool-new-name. The trailing slash tells the command it's a folder, not a file

Bonus Points: Update the GitHub project's "About"

This is one aspect of GitHub that gets neglected but can make a big difference in your presentation. You should, of course, be including a README.md file to explain the whats, whys and hows of your projects, but don't forget to keep the little sidebar "about" section up to date as well.

• Click the gear icon (not the gear on the "settings" tab though) and update the description field.
• Make sure you include any URL where the app is deployed as well!

If you need help deploying, I have several blog posts detailing how to complete that process:

• Deploying a Create-React-App to Netlify
• Deploying an Express Backend to Heroku
• Deploying a React App Frontend to Heroku
• Connecting MERN Fullstack Heroku Deployments

Hopefully this has helped you in keeping your projects updated and organized! Let me know if you have any issues or suggestions on better ways to do this. Thanks!

Photo by Helena Hertz on Unsplash

Big Picture

A stack is a collection of data where items are added and removed according to the "LIFO" acronym: Last In, First Out. Meaning, the last item that was pushed to the stack will be the first one to be popped off. I think of it like a Pez dispenser.

So what would we do if we needed to turn the whole thing around? A simple singly-linked list contains a series of nodes, and those nodes only contain 2 piece of information: the node's value, and the location of the next node in the list. To reverse, we would have to make all of our next pointers point to the previous node. This is where things get tricky however, because we can simply swap them or we would lose track of the next node's next, and the remainder of the list would just be floating around our computer somewhere, untethered and unreachable.

Don't Drop the Rope!

I've used this rock climbing metaphor previously but it's so fitting: when a climber leads and reaches the top of a pitch, they need to be able to get back down to the ground. Their belayer can lower them, but now they've left a carabiner at the top of the pitch (the one that's functioned as their "pulley" and allowed them to be softly lowered to the ground). A common solution to this problem is rappelling down (a.k.a. abseiling), instead of belaying; rather than the climber leaving gear at the top, they actually thread their rope through the fixed-bolt into the mountainside, and then are able to use specialized gear to carefully lower themselves down the fixed rope, finally pulling the rope free from it's threaded anchor once they're safely on the ground.

Climbing specifics aside, this switch over from belay to rappel is extremely dangerous if done incorrectly, and requires careful attention to each simply step. At some point between untying their knot from their harness (on belay) and tying it back on (on rappel), the climber will be unprotected by their safety line, and could easily fall and be killed. For this reason, climbers carry small loops of nylon and extra carabiners, and are able to go "in direct" and have a 2nd, temporary connection to the mountainside that will protect them if they fall. To stretch this metaphor further, a climber will literally tie the end of their safety rope to their harness somewhere, to prevent the untied rope from slipping through the hands or gear and falling to the ground, leaving them stranded on the pitch.

Though far less dramatic, the same applies when reversing a linked-list; you must have a temporary variable to hold the "rope" of your remaining list, while you switch the current node's next pointer to reference the previous node, and the next node's next to reference the current node.

            temporary = current.next
            current.next = previous
            previous = current
            current = temporary

Notice how at each step, the 2nd variable becomes the first variable of the next line. This also reminds me of how you swap the primitive values of two variables:

# task: swap the values of variables a and b

a=1
b=2

# you can't just use a = b or b = a to start because then you'll lose the value stored in the overwritten variable

# instead, use a temporary variable

x = a
a = b
b = x

We are doing basically the same thing in our linked-list loop, but each variable is instead a node with a value and a pointer to next; this loop continues until you reach the end of the linked list;

Linked List Reversal: Function vs Class Method

There is one final step left: assign the list's head value to point to the last item you found in the list, which would be our previous. I followed along with a great blog post in working through this concept, and this last step was what tripped me up the most; I couldn't quite figure out why they were sending in the head node and returning just the last previous node. Some experimenting allowed me to discover the missing step (for my implementation) of explicitly assigning the new head. As you can read in the comment's of their post; their particular case was not adding a reverse() method to a listed link stack class like mine, instead they were making a function which would reverse a linked list given that list's first node. In that case you'd presumably want the result of the function to be the new "first" node (the head) of this newly reversed linked list.

The complete reverse() method

    # reverse: reverse the linked list
    def reverse(self):

        # start at the top of the stack
        current = self.head

        # initialize
        temporary = None
        previous = None

        # walk through the linked list
        while (current != None):

            # don't let go of your rope (the rest of your linked list)!
            temporary = current.next

            # swap the link direction
            current.next = previous

            # attach current to the next nodes "previous"
            previous = current

            # step to what used to be the "next" node; which is stored in temp
            current = temporary


        # once reached the end/bottom of the stack
        # it's important to make that bottom item the new head
        self.head = previous

Thanks for following along! Hopefully you didn't get too lost on my rock climbing analogies, and hopefully you will do some more research before implementing my rock climbing advice in real life! No warranties or guarantees implied of the performance of your climbing or data structure performance.

Photo in cover image by Brook Anderson on Unsplash

<^ CTRL> + <⌘ CMD> + <SPACE BAR> loads the MacOS emoji menu

Emojis are exciting; honestly one of the most reliable to ways to convey emotional content in the written word. They might not be viewed as professional, but I honestly feel that moderate use can increase productivity and streamline communications.

Until recently, I'd only been incorporating emojis into my writing while typing on my iPhone; iOS makes it clear and easy how to access the menu. Now that I am blogging, writing //comments and texting regularly from my laptop, I desired a way to implement emojis directly from MacOS. The first solution I found was Rocket , a clever app that listens to your keyboard input and offers a popup menu when you type : followed by a search term. This works well, despite popping-up unwanted during some JS ternary operator implementations. The other issue was the lack of search; I believe he offers a paid upgrade to add searching, but as it stands the emoji pop-up only displays a few options based off of the actual name for each emoji. It's difficult to get the exact emoji you want at times, since the real names for each emoji can be somewhat obscure.

Then I happened upon a blog post that showed what I'd been seeking all along: built-in MacOS support for emojis! Simply press <CONTROL> + <COMMAND> + <SPACE BAR>, and a floating menu pops up with categorized tabs, search functionality, and your frequently used (my top 5 right now: 💩🤦‍♂️😀🐍😂). I've since disabled Rocket from loading on startup, but I will leave it installed for now, just in case. Otherwise, this "hidden" secret functionality seems perfect. What other "secret" keyboard shortcuts have you been using? 👩‍💻🎸

Photo in cover image by Vanessa Bucceri on Unsplash

Python Tic-Tac-Toe on the Command Line, coded in 2 hours as a group project

Today in class we dug into object-oriented programming in Python using classes. I had recently investigated this a bit on my own while implementing a stack using linked lists in Python. Though I would have preferred a different game since I somewhat recently coded React-Tac-Toe, it was another fun experience to work as a group; thinking out loud through our issues and bouncing ideas off of one another. Also, since the basics of the game were pretty clear, we could focus more on how to implement classes, functions and magic "dunder" methods like __str__() and how they can be helpful in a Python application.

Tech

• Python

Classes

We were required to implement classes in this Python coding exercise, so our group started by brainstorming the various entities present in a game of Tic Tac Toe, and which of those would be best represented by a class, vs. properties of a class instance. The two classes we decided on were:

• Game: would represent rounds of the game, and would keep track of whose turn it was, which squares were filled, etc.
• GamePiece: would represent the individual objects filling each square on the Game's gameboard[] list.

Tricky Bits

Making Game "Playable" in Command Line

There's a neat little snippet of code that's been helpful while we are mainly coding on the terminal with no GUI or view engine. It's a one-liner (plus a package import) that clears the terminal (similar to CMD+K or clear). If you'd like your code to display a clear screen (it actually just autoscrolls it down), simply:

1. import os
2. use os.system('clear') (on Mac)

We utilized this to clear the screen before each redraw of the screen in our Game's while() loop.

Checking for Win

The logic behind win a "win" relies on iterating over an array of all possible win conditions, and checking the current state of the board against each. We struggled getting these checks to work, until we finally isolated the bug: we were comparing the string 'O' or 'X' to the object GamePiece, rather than the string propertyGamePiece.mark as we intended.

Checking for Tie

Another issue with the logic involved the tie condition; there were two ways we discussed that could check for a tie:

• Track total played pieces, and if it reaches 9 and there's no winner, it's a tie
• Scan for empty spaces; once 0 (and no winner), it's a tie

I had implemented the first technique in my React-Tac-Toe, but for this code the 2nd seemed quicker to integrate.

Cat's Eye

I truly enjoy working in groups, and in particular pair-programming exercises. Being able to have one person "think" through their typing, while the other can theorize more abstractly, and even go off to google for deeper research without interrupting the coding flow. Obviously another key benefit is simply having more eyeballs on your code; as long as communication is good and you aren't second-guessing each other too often, you can exterminate bugs before they can take hold, saving hours if not days of frustration. I look forward to continuing collaboration with fellow member of my General Assembly cohort, during the remainder of this course and long after.

Code

• GitHub

Photo in cover image by Sid Verma on Unsplash

Part of my "Learn Computer Science by Coding" series; also check out some of my posts on bubble sort, binary search and recursive merge sort algorithms using JavaScript.

Coding in Python instead of JavaScript

We have been completing modules on computer science topics in the course of my General Assembly bootcamp, and I have been making a point to implement some of the most famous data structures and algorithms from scratch, using actual code. This process continues to be super helpful in understanding the concepts at a deeper level, and I'd recommend it to anyone learning (or relearning) these ideas.

Since we just started a new course unit on Python (which is famous for its ability to work with data), I thought it'd be an interesting challenge to step out of my new JavaScript comfort zone and explore Python while also learning these data structure concepts. I had used Python a few years ago to cobble together my GigUploader project, but my coding skills in general are so much stronger now that I was excited to see my progress in this language.

Getting Started

I already had a pretty decent mental model for arrays, linked lists, stacks and queues, from various college courses and several videos. Making the connection between how they work in theory to how they work in code can be quite a challenge however, and I did rely on several resources to finally get this implemented. The first was this tutorial implementing a linked list stack in Javascript which was super useful as a "cheat sheet" that I needed to translate into Python. They also clearly outlined the methods that a stack offers, which served as my user stories to get the ball rolling:

• Push: Adds the item in the stack at the top.
• Pop: Removes the top item from the stack and returns it.
• Peek: Shows the top item from the stack.
• toArray: Convert the stack to the array.
• size: Returns the size of the stack.
• isEmpty: Returns true if stack is empty, false other wise.
• clear: Clears the stack.

from learnersbucket.com

Using Classes

Despite covering the idea of classes early on, the concept certainly isn't front and center in my programming brain. Even once we started working in React with the idea of small, self-container reusable object, we touched on the "old way" of using class-based components and then quickly shifted focus to using hooks and functional components. I have even heard that JavaScript classes aren't technically classes, and simply exist to appease programmers migrating in from other class-based object-oriented languages like Java and C. This is somewhat unclear to me since JavaScript is considered "object-oriented", however the objects it's oriented towards are at the prototypes level, rather than the class level.

Two classes: Stack and Node

In any case, this low-level concept of a linked list seemed a good opportunity for using classes, and I assumed Python must use them as a true object-oriented language. In object-oriented programming (OOP), you can define a class for each conceptual entity in your program (similar to how we define our models/schemas when working with MongoDB). In a stack implemented using a linked list, there's the stack at the top level, and then the links of the linked list (usually referred to as 'nodes').

Python Class Idiosyncrasies: __init()__ and self

This one took some careful copy-pasting 😂, but eventually it became clear what was actually going on: the constructor method (the one that automatically runs once any time a member of a class is instantiated) is called __init()__ in Python (short for initialization?). In JavaScript we instead call it the constructor.

Also interesting was how we need to explicitly include self as an argument within the definition of every class method. self seems to function very similarly to JavaScript's this, but must be present in those incoming arguments.

Class Methods

Beyond the actual coding differences, it's been a small challenge to try and maintain a pythonic style: for instance using the word list instead of array, and naming variables and functions with snake_case and not camelCase (e.g. to_list() in Python vs. toArray() in JavaScript). Now that I had my "nouns" defined with classes Node and Stack, it's time to flesh out the "verbs" using class methods.

is_empty()

This was the first method I implemented, as the logic from several other methods would depend on the state of the stack. It was also pretty simple: check if the current head is equal to None, and if so it's empty! Note: None in Python is similar (but not identical) to the ideas of undefined and null in JavaScript. It's a thing that represents nothing.

push() and pop()

I'll admit I needed to frequently reference the tutorial to get these working; I just had a bit of trouble wrapping my head around the syntax and how self, head, next and value were all connected. Here's what I ended up with:

• self: the current stack
  • head: the "top" of the stack
    • next: the pointer that connects the current node to the next one
      • value: the data or item that is being stored in each node

The processes for push() and pop() are very similar, and require care to not break the links of the chain. It actuals reminds me of rock-climbing, when you are switching from secure anchor #1 to secure anchor #2, you must assure #2 is connected before you disconnect from #1. Similarly, when you create a new node, you set its next to point to the current head first, and then swap the value of head to reference this new node after.

peek() and display()

Also related, these methods allow you to view the first and the entire stack respectively. peek() simply returns the head.value if the stack isn't empty, while display() continues to walk through each node->next->node->next->node and display each node's value as it gets there.

size() and to_list()

These two methods both involve keeping track of a variable outside of your node-traverse, and updating that variable as you walk through: the integer stack_size for size(), and the list stack_as_list[] for the to_list() method (described as toArray() in the JavaScript implementation.

I also needed to reverse the final list before returning from the method; since the items are extracted one-by-one from the last item added and added to the end of the tally list using append(), I needed to do a final stack_as_list.reverse() to put items in the correct order. Another approach would be to directly place the items into beginning of the tally list using stack_as_list.insert(0, item) where 0 specifies the first position (stack_as_list[0] since Python lists are zero-indexed ).

clear()

To finish the set of methods listed at the beginning, we'll finish as simply as we began by simply clearing the array. This mimics the behavior of the stack's __init__() method, by simply setting the head to None. I suspect this might require some sort of garbage collection since all those nodes are still in memory, just simply no longer connected to our stack. If anyone has answers please let me know, and I'll update as I learn more!

Conclusion

Thanks again for reading; I will be attempting some more data structure implementations using Python in future blog posts so stayed tuned. Here are some more of the pages I referenced while learning this material:

• Python Classes and Objects
• Gist from Dinesh
• W3Schools Python Classes
• Geeks for Geeks

Photo in cover image by Fabrizio Conti on Unsplash