DEV Community: Otavio Monteagudo

SASS / SCSS in a Nutshell

Otavio Monteagudo — Fri, 25 Apr 2025 15:57:19 +0000

SASS

Notes on Marksheet's SASS chapter, with a few additions of my own: https://marksheet.io/sass-scss-less.html
SASS Documentation: https://sass-lang.com/documentation/syntax/
CSS preprocessor that extends it; LESS is an alternative, so is SCSS
These include variables, functions, reusable components, syntax enhancers in general that generate CSS
We'll use SCSS, since it is very similar to CSS (basically a superset; all valid CSS is valid SCSS)
Main difference between CSS and SASS is that SASS uses indentation-based syntax (no curly braces)

SASS Features

variables: instead of repeating #fce473 throughout your CSS file, just set $yellow: #fce473 once (prevents repeating values)
nesting: CSS rules can be nested within each other (prevents repeating selectors)
partials: import commonly used properties without extra requests or heavier than needed CSS files
mixins: custom functions that can accept parameters and will prevent useless repetitions (prevents repeating properties)
extensions: an easy way to inherit the same properties of another selector (also prevents repeating properties)
operators: adding/substracting/multiplying/dividing values, like 960px / 4 or $space * 2

SASS Variables

Variables can be defined and reused
You can also define a set of variables and then point one variable to another, so say you want to change primary color from yellow to pink, just update $primary-color

// Defining color values
$yellow: #fce473;
$pink: #c71585;
$green: #32cd32;
$blue: #1d90ff;

// Defining color types
$primary-color: $green;

.quote{ border-left: 5px solid $primary-color;}
.button{ background: $primary-color;}
.sidebar a:hover{ border-bottom-color: $primary-color;}
.footer a{ color: $primary-color;}

It is possible to change any type of content with variables:

// Colors
$yellow:              #fce473;
$pink:                #c71585;
$green:               #32cd32;
$blue:                #1d90ff;

$primary-color:       $blue;
$secondary-color:     $yellow;

// Fonts
$serif:               "Lora", "Playfair Display", Georgia, serif;
$sans-serif:          "Roboto", "Source Sans Pro", "Open Sans", Arial, sans-serif;
$monospace:           "Inconsolata", monospace;

$primary-font:        $sans-serif;
$secondary-font:      $serif;

// Spacing
$mobile-space:        10px;
$desktop-space:       35px;

// Also possible to add built-in manipulations for easy color transition & others, for instance:
$primary-blue: #1d90ff;
button {
  background: $primary;
  &:hover { background: lighten($primary-blue, 10%); }
  &:active { background: darken($primary-blue, 15%); }
}

SASS Nesting

Meant to reuse same parent selector
Attempt to replicate HTML's nesting structure in CSS
Rule of thumb is to avoid nesting deeper than 3 levels, which would lead to over-specificity and large CSS output

For instance:

//scss
.parent{
  .child{}
}

// becomes in css
.parent .child{}

So the nested .child element will be applied to elements nested withing elements with the .parent class.

What about elements that must have both classes/states at once?

Note that these generated CSS classes have no space between class names (so it only applies to elements with both classes)

//scss
.parent{
  &:hover{}
  &.other-class{}
}

// becomes in css
.parent:hover{}
.parent.other-class{}

For reference: Generated CSS alongside SCSS selectors:

| CSS Selectors                        | SASS Selectors                      |
|--------------------------------------|-------------------------------------|
| `.post-content{}`                    | `.post-content {`                  |
| `.post-content a{}`                  | `  a {`                            |
| `.post-content a:hover{}`            | `    &:hover {}`                   |
| `.post-content aside{}`              | `  aside {}`                       |
| `.post-content blockquote{}`         | `  blockquote {}`                  |
| `.post-content code{}`               | `  code {}`                        |
| `.post-content h3{}`                 | `  h3 {`                           |
| `.post-content h3 a{}`               | `    a {}`                         |
| `.post-content h4{}`                 | `  h4 {`                           |
| `.post-content h4:before{}`          | `    &:before {}`                  |
| `.post-content h4:after{}`           | `    &:after {}`                   |
| `.post-content p{}`                  | `  p {`                            |
| `.post-content p:first-child{}`      | `    &:first-child {}`             |
| `.post-content p:last-child{}`       | `    &:last-child {}`              |
| `.post-content ul{}`                 | `  ul {`                           |
| `.post-content ul ul{}`              | `    ul {`                         |
| `.post-content ul ul ul{}`           | `      ul {}`                      |
| `.post-content dl{}`                 | `  dl {`                           |
| `.post-content dl:before{}`          | `    &:before {}`                  |
| `.post-content dl dt{}`              | `    dt {}`                        |
| `.post-content dl dd{}`              | `    dd {}`                        |
| `.post-content pre{}`                | `  pre {`                          |
| `.post-content pre code{}`           | `    code {}`                      |
| `.post-content table{}`              | `  table {`                        |
| `.post-content table tr{}`           | `    tr {`                         |
| `.post-content table tr:nth-child(2n){}` | `      &:nth-child(2n) {}`     |
| `.post-content table th,`            | `    th,`                          |
| `.post-content table td{}`           | `    td {`                         |
| `.post-content table th{}`           | `    th {}`                        |
| `.post-content table td.empty,`      | `      &.empty {}`                 |
| `.post-content table th.empty{}`     | `    }`                            |
| `.post-content table code{}`         | `    code {}`                      |
| `.post-content table pre{}`          | `    pre {`                        |
| `.post-content table pre:before{}`   | `      &:before {}`                |

SASS Mixins

A mixin is basically a predefined set of properties and values that can be reused. Example:

@mixin overlay() {
  bottom: 0;
  left: 0;
  position: absolute;
  right: 0;
  top: 0;
}

/** This mixin called within this class... **/
.modal-background{
  @include overlay();
  background: black;
  opacity: 0.9;
}

/** ...will generate the following CSS: **/

.modal-background{
  bottom: 0;
  left: 0;
  position: absolute;
  right: 0;
  top: 0;
  background: black;
  opacity: 0.9;
}

X.7.4.1 Mixin Parameters

Mixins can also accept parameters; ex:

@mixin border-radius($radius) {
  -webkit-border-radius: $radius;
     -moz-border-radius: $radius;
      -ms-border-radius: $radius;
          border-radius: $radius;
}

/** This mixin called within this class... **/

.box{
  @include border-radius(3px);
}


/** ...will generate the following CSS: **/

.box{
  -webkit-border-radius: 3px;
     -moz-border-radius: 3px;
      -ms-border-radius: 3px;
          border-radius: 3px;
}

X.7.4.2 Mixins Default Parameters

It is possible to add default and optional mixin parameters.
For instance, see this one meant to add labels in the top left of code snippet blocks:

@mixin label($text: "Code", $background: $yellow, $color: rgba(black, 0.5)) {
  position: relative;
  &:before{
    background: $background;
    color: $color;
    content: $text;
    display: inline-block;
    font-size: 0.6rem;
    font-weight: 700;
    height: 1rem;
    left: 0;
    letter-spacing: 0.1em;
    line-height: 1rem;
    padding: 0 0.5em;
    position: absolute;
    text-transform: uppercase;
    top: 0;
  }
}

/* used here: */

div.highlighter-rouge{
  @include label(); /* will use default "Code", $yellow and  rgba(black, 0.5) values */
  &.css{ /* will have specific values for codeblocks with css class */
    @include label("CSS", $blue, white);
  }
  &.scss{ /* will have specific values for codeblocks with scss class */
    @include label("SCSS", #c69, white);
  }
}

SASS Extensions and Placeholders

These are very similar to mixins; the difference is that mixins write to css directly, and extensors and placeholders only reference it, so they are "more elegant"
Placeholders are basically silent classes that do not output to CSS unless extended
When in doubt, use mixins as they are the most straightforward
As a rule of thumb, use mixins when you need params and placeholders/extensors when you do not
As a rule of thumb, use extensions when the base class will also be used in HTML and extensions + placeholders when the base class will be absent from the HTML but classes extending from it will be in the HTML
Extend syntax (allows to inherit CSS properties):

// scss
.small-uppercase{
  color: lightslategrey;
  font-size: 10px;
  letter-spacing: 0.1em;
  line-height: 12px;
  text-transform: uppercase;
}

.modal-background{
  @extend .small-uppercase;
}

.product-link{
  @extend .small-uppercase;
}

// generated css
.small-uppercase,
.modal-background,
.product-link,{
  color: lightslategrey;
  font-size: 10px;
  letter-spacing: 0.1em;
  line-height: 12px;
  text-transform: uppercase;
}

Note how .small-uppercase was also generated as a class. What if we don't want to do this, to keep our CSS as flat and clean as possible?

// scss
%small-uppercase{
  color: lightslategrey;
  font-size: 10px;
  letter-spacing: 0.1em;
  line-height: 12px;
  text-transform: uppercase;
}

.modal-background{
  @extend %small-uppercase;
}

.product-link{
  @extend %small-uppercase;
}

.image-pattern{
  @extend %small-uppercase;
}

// generated css
.modal-background,
.product-link,
.image-pattern{
  color: lightslategrey;
  font-size: 10px;
  letter-spacing: 0.1em;
  line-height: 12px;
  text-transform: uppercase;
}

Use Mixins When	Use Extends When
Need parameters	Static styles
Output varies per instance	Reducing duplicated styles

SASS Control Directives

SASS offer directives such as loops and conditionals
These can be used to generate repetitive styles efficiently

// For loops
@for $i from 1 through 4 {
  .mt-#{$i} { margin-top: #{$i * 5}px; }
}

// Each loops
$colors: (primary: blue, secondary: green);
@each $name, $color in $colors {
  .text-#{$name} { color: $color; }
}

// If statements
@mixin theme($dark: false) {
  @if $dark { background: black; }
  @else { background: white; }
}

SASS Imports & Partials

The @import directive allows you to include content of a file into another
This however can create a new HTTP request every time it is called
SASS solves this by including the file in the CSS itself
You can import .sass, .scss and .css files; it does not even need an extention, SASS will treat it as a compatible file.
Prefix partials with an underscore, like "_filename.scss" so they don't get compiled into their own CSS file.
Note that every time you import, code will be duplicated, so keep imports to a minimum. See 7-1 Architecture: https://www.easeout.co/blog/2020-08-25-structuring-your-sass-projects/

/* _colors.scss */
$myPink: #EE82EE;
$myBlue: #4169E1;
$myGreen: #8FBC8F;


/* main.scss */
@import "colors";

body {
  font-family: Helvetica, sans-serif;
  font-size: 18px;
  color: $myBlue;
}

Create Custom Keyboard Shortcuts on your Linux Machine

Otavio Monteagudo — Sun, 23 Feb 2025 21:16:42 +0000

Intro

In this guide we'll explore how to define our own keyboard shortcuts in linux for both standalone and chained commands.

Linux GUIs

Linux is a lot more modular than other OSes and this includes its Graphical User Interfaces. I am for instance using XFCE; you might be using another.

Keyboard shortcuts will most often be defined through the GUI.
If you are unsure which GUI you have, run:

sudo apt install neofetch && neofetch

Defining Keybindings for Commands

In most regularly used GUIs, it will be as simple as looking for Keyboard under Settings, creating a new shortcut, typing which command you want to use and assign the key combination for it. No biggie.

Defining Keybindings for Chains of Commands

If you want to chain commands, you might fall into a gotcha as they will not work.

This is because the system will execute keyboard commands through the system call and not through the shell interpreter, but this only means we'll have to make sure to invoke the interpreter before running the command.

For instance, let's suppose we want to run this command:

scrot -s /tmp/screenshot.png && xclip -selection clipboard -t image/png -i /tmp/screenshot.png && rm /tmp/screenshot.png

It will use scrot to capture a cropped screenshot to a temporary file, then use xclip to copy the file content's to the clipboard, and then it will remove the temporary file. If we assign it directly as a shortcut, nothing will happen. But we can still have a cropped-screenshot-to-clipboard shortcut.

Solution 1: Wrapping Command in a Shell Command

We can assign the shortcut to the shell command and pass the command chain we want to execute as an argument:

sh -c 'scrot -s /tmp/screenshot.png && xclip -selection clipboard -t image/png -i /tmp/screenshot.png && rm /tmp/screenshot.png'

Solution 2: Create a Script File and make it Executable

-First, create a local script:
nano ~/.local/custom-shortcut-commands/screenshot-to-clipboard.sh

Add the shebang to mark an executable script, followed by your command chain:

#!/bin/bash
scrot -s /tmp/screenshot.png && xclip -selection clipboard -t image/png -i /tmp/screenshot.png && rm /tmp/screenshot.png

Give execution permissions:
chmod +x ~/.local/custom-shortcut-commands/screenshot-to-clipboard.sh

Then, add the file location to the keybinding; (~/.local/custom-shortcut-commands/screenshot-to-clipboard.sh in this case) since the script was flagged as an executable, the invocation of the file is enough to invoke the script.

Conclusion

Have fun customizing your Linux installation!

Byte-Pair Tokenization: The Basic Principle Behind Large Language Models

Otavio Monteagudo — Tue, 18 Feb 2025 23:17:06 +0000

Intro

You might have heard that Large Language Models such as DeepSeek, Mistral and GPT are similar to text autocorrect mechanisms. This is not too far off, although they are of course infinitely more complex. Here's a basic condensation on how LLMs work:

1.0 N-Gram Language Models

These are simpler, primitive ancestors of LLMs. Examples are predictive text and plagiarism detectors.

N-gram language models (predict next word by assigning probability to possible next word); context window is N-1 words.
Bigram model: "Markov's Assumption"; predict next word based on last word only. Context window is 1 word.
Trigram model: context window to predict next word is 2 words. N-gram: Limitations: in a 6-word model for instance, you have to type 5 exact words in the exact order that the model has a reference from for it to attempt a prediction of the 6th word. So in a terms and conditions model for instance, you would have to type "please read these terms and" for it to predict "conditions". For example, a plagiarism detection model would have a higher 'n' than a mobile phone's predictive text mechanism.

1.1 How do N-Grams Models Assign Probability?

Bigram models will take an input text and divide it into word pairs.
It will then check for pair frequency and assign probabilities based on it. For example: Input: 'The quick brown fox jumped over the lazy hog; the quick fox then disappeared.' Pair breakdown: ('the', 'quick'), ('quick', 'brown'), ('brown', 'fox'), ('fox', 'jumped'), ('jumped', 'over'), ('over', 'the'), ('the', 'lazy'), ('lazy', 'hog'), ('hog', 'the'), ('the', 'quick'), ('quick', 'fox') ('fox', 'then'), ('then', 'disappeared') Pair frequency: ('the', 'quick') and ('quick', 'fox') both appear twice, all others appear once. So if you sent 'the' as an input to this model, it would predict 'quick'; sending 'quick' would predict 'fox'.
This type of model has pretty obvious limitations, like not being able to infer meaning based on past input, or being able to assign probabilities to words that are not paired in a particular frequency.

2.0 Tokenization

Tokens are smaller and more manageable units of text;
These are the 'words' the LLMs understand;
They are usually smaller than words, but might represent whole words or more;
How a token is defined usually varies with the tokenization strategy;

2.1 Whitespace Tokenization

In the phrase "my robot ate my homework", the word "my" appears twice but an LLM would only store it once as a token in its vocabulary;
This is how a text corpus is broken into units that a model can train on.
Tokenization has many methods; the most obvious is whitespace tokenization, that reads every whitespace as a marker between different tokens.

2.2 Affix Tokenization

Affixes are prefixes and suffixes, parts of words added to word stems in order to specify meaning.
Ex: 'halt' is a stem, 'halting', 'halts' and 'halted' have more specific meanings derived from the stem.
In the input "man, my model really sucked." we have the following tokenization: man|,| my | model | real|ly | suck|ed|.; it treats punctuation, word stems and affixes as individual tokens.
This approach's main drawback is that it is grammar-dependent. For instance, English has more frequent grammatical functions on suffixes while Swahili has more on prefixes; Spanish is an analytical language in which meaning is specified through more use of words, while Hungarian is an agglutinative language in which meaning is specified through chaining of more affixes, etc.

2.3 Byte-Pair Encoding Tokenization

This is the most similar approach to the n-gram model probability assignment, and yet it is the most complex.
In this approach, tokens are not pre-identified and processed, they are built from the characters.
This is how most modern (as of 2025) LLMs operate; by identifying common letters agglutinations then word radicals are formed, and then full words, and then related words in a context identified by combinations of other words.

The Byte-Pair Encoding Cycle

Quick Note: a token is an identified frequency of meaning, a character/letter is a character/letter. A character might be a token but a token not necessarily will be a character. A token corresponds roughly to three characters on average (according to what I've heard or read somewhere).

1) Algorithm splits words into characters, identify individual characters and then maps letter frequencies:

# input
"low lower lowest"
# letter split (notice spaces are considered letters)
l|o|w|(space)|l|o|w|e|r|(space)|l|o|w|e|s|t
# identification of individual tokens (also called the 'vocabulary'):
Initial_Vocabulary: l, o, w, e, r, s, t, (space)
# Most frequent letters in order
Token_Frequencies: l: 3, o: 3, w: 3, (space): 2, e: 2, r: 1, s: 1, t: 1

2) It will then count the frequencies of pairs of adjacent characters:

# Most frequent letter pairs in order
Paired_Tokens_Frequencies_0: lo: 3, ow: 3, w (space): 2, (space)l: 1, er: 1, es: 1, st: 1

3) Merge most frequent pair (lo) into a new token, remaking the vocabulary:

New_Vocabulary_0: lo, w, (space), e, r, s, t
Transformed_Input_0: "lo w lo wer lo west"

4) The process then continues recursively, the transformed input is used as new input and pairs are assigned again.
Note how the pairs lo and ow have agglutinated into low; that's how LLMs rebuild language based on frequency of character agglutination.

Paired_Tokens_Frequencies_1: low: 2, w (space): 2, (space)lo: 1, wer: 1, west: 1
New_Vocabulary_1: low, er, est
Transformed_Input_1: "low low er low est"

5) After n merges, there will be a final vocabulary that might look like this:

Final_Vocabulary: l, o, w, e, r, s, t, low, er, est

If the process kept going, eventually the vocabulary would become the words of the original text.

Advantages of Byte-Pair Encoding (BPE)

Notice that the main advantages of Byte-Pair Encoding (BPE) tokenization is that it reduces vocabulary size compared to word and affix level tokenization and it also generalizes well to recognize otherwise unknown terms.
Also notice that this strategy avoids helps to avoid bizarre, meaningless pairs such as 'lw'.

Note: needless to say, this is a very brief overview. Actual modern LLMs use strategies that, although parting from this principle, are a lot more sophisticated and involve a training complexity only available to the most resourceful institutions and brightest minds of the era. Strategies such as using bytes instead of characters and associating multiple tokens through complex networks of related nodes (see this article on neural networks) are closer to the actual methods being applied, and out of this humble article's scope.

How to Effectively Paste Images on Markdown with VSCode

Otavio Monteagudo — Mon, 20 Jan 2025 09:02:05 +0000

Introduction

Nowadays I use mostly markdown files when taking notes on a subject, and this is often done through VS Code. Markdown is an excellent format for writing standard text and for easy and effective access to special formatting options such as computer code or math notation, however, in many situations it is much more effective to simply paste an image on the document.
The naive way to do so would be to pause your writing, copy an image to your VS Code project space, move this image to a directory and then type the image link to your markdown file. This would completely switch my concentration focus and help to break the thought flow, especially when dealing with multiple images.
After a frustrating Sunday afternoon spent fiddling with abandoned VS Code extensions and going through goofy attempts to create my own, I remembered to resort to two resources that should be much more appreciated by the software community in 2025: simplicity and Stack Overflow.

The Problem We're Trying to Solve

Given the break in cognitive flow during a note-taking process, we need to have a more convenient way to paste images located in our computer, stored at the current clipboard, into our markdown file and then move on.
So our solution should have the following properties:

When focusing on a Markdown document in VS Code, we should be able to paste a file in the document without switching off focus of this document.
Once pasted, the pasted image should be available at the current VS Code project directory tree.
Once pasted, a link to the pasted image in the project should be automatically built in our focused Markdown file, preserving the image's original name if one exists (alt text will be a human responsibility).
The properties of this behavior, such as defining where in the project the image should be stored, should be easily customizable.

How We're Going to Solve It

After reading a 2023 discussion in StackOverflow, I have learned that, since version 1.79, VS Code itself provides a way to paste files from the clipboard into a Markdown document.
The default behavior for this feature is like this:

Once a Markdown file is focused, there is an image stored at the current clipboard and the user pastes this clipboard content in the Markdown document, the clipboard content is copied to the same directory as the focused markdown document, and a markdown link to this pasted content is automatically built, which also preservs the original file name (it defaults to 'image' in case the clipboard image is nameless). This might seem trivial and maybe already solves your problem, but this feature seems to be currently somewhat obscure, and many of us (such as myself) don't really bother to update VS Code, so let's see how to effectively use it.

Usage Example

For starters, make sure your VS Code version is 1.79 or above; I am currently using 1.84 and it works perfectly.
We want to paste our images in a markdown document in a way that they are always stored under the markdown-images directory, and a textual link to the image is automatically added to the document's text.
This is how we can set it up:

Open configurations (Ctrl+, and Cmd+, on a Mac)
Select Open Settings (JSON) at the top-right icon of the settings window
Append the following line to the settings:

"markdown.copyFiles.destination": {
    "**/*": "markdown-images/${fileName}"
}

Basically, the json key "**/*" registers in which markdown file location the feature for pasting images should be applied (in this case, the whole project; see the release notes linked above for an example of a scoped rule) and the json value "markdown-images/${fileName}" specifies where and how to save the image (in this case it states that the image should be saved under a markdown-images directory created at the same level as the markdown file, and that the original file name should be kept).

Before and After Pasting

Let's suppose we copy a file, pasted-markdown-image.png, located somewhere in our computer, and want to paste at the currently focused markdown document.

Take a look at our VS Code before pasting; it only consists of a README.md file, some typed markdown content and the file preview:

Now, after pasting pasted-markdown-image.png to the document:

Note that it is visible in the left screen (the project directory tree explorer) how an image named pasted-markdown-image.png was added under the markdown-images directory.
Also in the middle screen (the Markdown document composition), a link to this pasted image was created and the image's original name was kept; alt text still has to be filled by us, but hey, at least no one shoe-horned chatbots here.
Finally, the screen to the right (the rendered markdown preview) shows us the image of some crowded platforms, confirming it worked.

Final Notes

Notice that this creates links to any type of file, not just still images. Also notice that Mac and Windows both offer ways to transfer screenshots to the clipboard, and your Linux GUI should provide one as well.
In summary, by updating VS Code to version 1.79+ and adjusting a simple configuration, you can streamline your note-taking workflow and easily paste images into Markdown files without losing focus.
Hope this helps you as much as it did help me!

Brief Overview of HTTP, Internet Protocols, and Web Architecture

Otavio Monteagudo — Sat, 12 Oct 2024 00:32:25 +0000

Index

Intro
URLs
URL Components
Internet Protocol (IP) Suite
The DNS Lookup Process
TCP (Transmission Control Protocol)
The Three Way Handshake
HTTP Verbs/Methods
API Endpoints
What is HTTP (HyperText Transfer Protocol)?
Request
Response
HTTP Status Codes
HTTP is Stateless
What is the REST (REpresentational State Transfer) Architecture?
What is the Web Layers Architecture?

Intro

Internet existed since around 1960s
Usage was minimal and restricted
In 1989 (at CERN), Sir Tim Berners-Lee invented HTTP (Hypertext Transfer Protocol); insight was to use the existing hypertext (documents that had links to other documents) could be moved throughout the internet (linking to other documents addresses instead of another document in the same space).
First HTTP version was 0.9

1.0 URLs

Address of a resource on the internet (ex: https://example.com)
Basis of communication with URLs is the request and response pattern.
A client (maybe a web browser, maybe an app, anything that sends requests to servers) requests information to a server which sends a response

1.0.1 URL Components

For https://www.python.org/about

A scheme: https://
A hostname: www.python.org
A(n optional) path: /about

1.1 Internet Protocol (IP) Suite

In the process of sending a request and receiving a response, other tech must work together with the client and server to load the webpage
This is broadly referred to as the internet protocol suite.

1.1.1 The DNS Lookup Process

User types a TLD (Top-Level Domain) http://www.google.com into their web browser
Browser sends request to DNS (Domain Name System) server
DNS lookup occurs (usually the one provided by the user's ISP (Internet Service Provider), can also be a public DNS); human-readable name is mapped to server's IP as registered in the DNS (can be in the cache, if nothing is found then looks up authoritative nameservers)
DNS returns IP address to browser
OS that runs the browser caches the information locally and uses the IP address to connect directly to the website

Note: Most DNS problems (such as unexistent or old versions of websites) are usually on the client-side. These are usually solved by clearing the local DNS cache.

1.1.2 TCP (Transmission Control Protocol)

Once a client has an IP address for a domain, it sets up a consistent connection with a server
This happens via TCP (Transmission Control Protocol) which provides reliable, ordered and error-checked delivery of bytes between two computers
To Establish a TCP connection between two computers, a three-way "handshake" occurs between client and server:

1.1.2.1 The Three Way Handshake

Client sands a SYN asking to establish a connection
Server responds with a SYN-ACK acknowledging the request and passing a connection parameter
Client sends an ACK back to the server to confirm the connection
Once the TCP connection is established, the two computers can start communicating via HTTP

1.1.3 HTTP Verbs/Methods

Every webpage contains an address (URL) and a list of approved actions (HTTP verbs)
Here is a more thorough list, below are the most common ones.

CRUD	HTTP Verb/Methods
Create	POST
Read	GET
Update	PUT
Delete	DELETE

1.1.4 API Endpoints

A traditional website consists of pages with HTML, CSS, images, javascript, etc.
A web API also relies on URLs but instead of serving webpages it produces API endpoints
An endpoint contains data (usually in JSON) and a list of available actions (HTTP Verbs)

1.1.5 What is HTTP (HyperText Transfer Protocol)?

HTTP is a request-response protocol between two computers that have an existing TCP connection.
Client makes requests, server returns responses

1.1.5.1 Request

Example request:

GET / HTTP/1.1
Host: google.com
Accept_Language: en-US

Line 1: request line specifies HTTP method to use, path & HTTP version
Two subsequent one are HTTP headers: Host is the domain name and Accept_Language is the language to use.
See here a more thorough list of HTTP headers Note: HTTP messages might also contain a body, only used with HTTP responses containing data.

1.1.5.2 Response

This assumes that Google's homepage only contains the HTML "Hello, world!".

HTTP/1.1 200 OK
Date: Mon, 24 Jan 2022 23:26:07 GMT
Server: gws
Accept-Ranges: bytes
Content-Length: 13
Content-Type: text/html; charset=UTF-8

Hello, world!

Top line is the response line, specifies HTTP version and response status code
Next 5 lines are HTTP header.
After the line break there is the body content of "Hello, world!"

Note: most web pages contain multiple resources that require multiple HTTP request/response cycles. A webpage with HTML, a linked CSS file and one image has three separate trips back-and-forth between client and server before the complete page can be rendered.

1.1.5.3 HTTP Status Codes

Once a client sends a request, this does not mean the request will simply proceed
There is a vast list of HTTP Status codes. The examples below are the most common ones.

HTTP Status Code	Description
2xx Success	The action requested by the client was received, understood, and accepted
3xx Redirection	The requested URL has moved (usually will be followed by further action, e.g. sending a new request to a new URL returned by the server)
4xx Client Error	There was an error, typically a bad URL request by the client
5xx Server Error	The server failed to resolve a request

2.0 HTTP is Stateless

HTTP is stateless; this means each request/response pair is independent of others. There is no stored memory of past interactions.
This also applies to 3xx responses, as the final result is basically "instructions of what to do next"
This is an engineering decision due to signal loss over time, a very long communication means that everything would potentially fall apart with one error; HTTP as is means that if a single cycle does not go through, it can simply be repeated without problems for the rest of the communication chain

Note: while HTTP itself is stateless, there can be transfer of stateful data among a client and a server, such as user authentication (a browser stores an auth token as a cookie and sends to a specific IP on each request to this IP and the server checks the token validity to authenticate and authorize the user before each response).

3.0 What is the REST (REpresentational State Transfer) Architecture?

REpresentational State Transfer is an architecture proposed in 2000 by Roy Fielding in a dissertation thesis. It is an approach to build APIs on top of the HyperText Transfer Protocol.
This defines how the API will communicate externally; it does not care about internal details or separation of concerns.

Every RESTful API:

is stateless (every request/response cycle is independent; see Websockets for an example of stateful communication)
supports common HTTP verbs on endpoints (GET, POST, PUT, DELETE, etc)
returns data in either JSON or XML formats

4.0 What is the Web Layers Architecture?

This broadly defines the internal composition of the web app (note that APIs will lack the Presentation Layer).
Each layer has specific responsibilities and will communicate with adjacent layers; it is used to promote separation of concerns and modular design.

Presentation Layer (PL):

Handles user interface and user interaction
Typically includes HTML, CSS, and JavaScript
Responsible for displaying data and capturing user input

Example: a rendered webpage with HTML, CSS and Javascript.

Business Logic Layer (BLL):

Contains the core functionality and business rules of the application
Processes data and implements application logic
Sits between the presentation and data layers

Example: a controller function that checks authorization for an user and schedules a particular job on the server to be completed at a later date.

Data Service Layer (DSL):

Acts as an intermediary between the business logic and data access layers
Provides an additional level of abstraction for data operations
Can improve security and modularity of more complex applications

Example: callbacks that perform validations at a model-level before proceeding with data-altering procedures

Data Access Layer (DAL):

Manages data storage and retrieval
Interacts with databases or other data sources
Abstracts data operations from the business logic layer

Example: implementation of CRUD operation functions that will alter or retrieve data from a database.

The Concise Django Tutorial

Otavio Monteagudo — Thu, 26 Sep 2024 22:42:41 +0000

Intro

These are the notes I made while studying the official Django Tutorial.
It is very similar to the tutorial itself. However, it is generally more condensed, but I changed some stuff (for instance, all materials on the Admin interface are in their own section instead of going back and forth to admin-related subjects) and added some more (like the section on having different settings per environment).
I hope you enjoy it and find it is useful.

Command Reference

# Creates a project
django-admin startproject <project_name>
# Runs project in localhost
python manage.py runserver
# Creates an app inside the project
python manage.py startapp <app_name>
# Creates migrations based on existing model files
python manage.py makemigrations <app_name_OPTIONAL> # will work without app name param
# Applies migrations to alter current database
python manage.py migrate
# Outputs DDL SQL that will be generated and applied for a specific migration. Doesn't alter the db.
# ex: params would be `this_is_an_app` & `0001` for '/this_is_an_app/migrations/0001_initial.py'
python manage.py sqlmigrate <app_name> <numeric_mig_file_prefix> 
# Runs app as a console in a python interpreter environment; similar to rails console
python manage.py shell
# Runs SQL shell with project's Database
python manage.py dbshell
# Creates an user for the Admin Interface
python manage.py createsuperuser
# Checks project for common problems. 
# These checks are context-specific and a different settings module can be applied.
# Ex: append --deploy --settings=production_settings --fail-level=DEBUG to 
# use extra deploy checks, with production settings and return non-0 up to DEBUG statements (ERROR level is the default).
python manage.py check
# Output the location of Django source files
python -c "import django; print(django.__path__)"

Initialize Project

# Optional but highly recommended: set-up pyenv version. See: https://dev.to/otamm/python-version-management-with-pyenv-3fig
pyenv local 3.12
# Optional but highly recommended: setup virtual env
python -m venv .venv && source .venv/bin/activate
# installs django to venv context
python -m pip install django~=5.1
# writes libraries and versions to a reusable file
pip freeze > requirements.txt 
# Creates project. DO NOT USE RESERVED NAMES such as python, test, django, etc
django-admin startproject polltutorial
# Optional: setup direnv. See: https://dev.to/otamm/one-environment-per-project-manage-directory-scoped-envs-with-direnv-in-posix-systems-4n3c
touch .envrc && echo 'export VIRTUAL_ENV=."venv" && layout python' >> .envrc && direnv allow

0.1 Project File Structure

polltutorial/ # Project name; can be edited to whatever you want
    manage.py # Collection of command-line utilities to perform common project tasks
    polltutorial/ # Namespaces project
        __init__.py # Declares package: https://docs.python.org/3/tutorial/modules.html#tut-packages
        settings.py # Project-wide settings: https://docs.djangoproject.com/en/5.1/topics/settings/
        urls.py # URL declarations: https://docs.djangoproject.com/en/5.1/topics/http/urls/
        asgi.py # Asynchronous Server Gateway Interface; connects app with your async web server.
        wsgi.py # Web Server Gateway Interface; "legacy", easier to config, adequate for most cases

0.2 Dev Server

Initialize with

python manage.py runserver

It has hot-reload out of the box so your changes will be instantly reflected without the need to restart the server. Runs on port 8000 as default.

1.0 Initialize Apps

This will create a Django app; these can be located anywhere in your PYTHON_PATH.

# Initialize 'polls' app
python manage.py startapp polls

File structure (note that urls.py will have to be created):

polltutorial/ # Project files
    # ...
    polls/ # Root directory for the 'polls' Django app
        __init__.py # Python package indicator, allows importing from this directory
        admin.py # Configuration for the Django admin interface
        apps.py # App configuration file
        migrations/ # Directory for database migrations
            __init__.py # Makes migrations a Python package
        models.py # Defines database models (tables) for the app
        tests.py # Contains test cases for the app
        views.py # Handles the app's views (request/response logic)

Remember to add the app to the project's installed apps setting; we'll revisit the settings soon. Your INSTALLED_APPS setting should look like this:

polltutorial/settings.py

INSTALLED_APPS = [
    "polls.apps.PollsConfig",
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]

1.1 First View

polls/views.py

from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

Most basic view possible, but still must be mapped to an URL:

polls/urls.py

from django.urls import path

from . import views

urlpatterns = [
    path("", views.index, name="index"),
]

It's best to import app URLs all at once at the website's URLs:

polltutorial/urls.py

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("polls/", include("polls.urls")),
    path("admin/", admin.site.urls),
]

1.1.1 `include()` and `path()`

`include()`

include() allows referencing other URLconfs. When Django finds include(), it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing.

This is to make easy to plug-and-play URLs. You can rename the path, such as /fun_polls or /content/polls and it would still work.

Only exception is the admin.site.urls, as you can see just above.

`path()`

path() has four arguments (first two are mandatory):

route: has URL pattern. When a request is processed, Django starts at the first pattern in urlpatterns and goes down until one is matched. Patterns to not search for GET and POST URL parameters or the domain name.
view: when a pattern is matched, Django calls the specified view function with an HttpRequest object as the first argument and any other params as keyword arguments.
kwargs: arbitrary keyword args can be passed as a dict to the target view.
name: allows for unambiguous name to refer to the URL from other parts of the project.

2.0 First look at Settings & Database

polltutorial/settingspy contains a Python module with module-level vars representing configuration settings.
By default, DATABASES uses sqlite, which comes with Python.
It's a good idea to set TIME_ZONE to your time zone as soon as the app is created.
Also note the INSTALLED_APPS setting. It holds names of all Django apps active in this Django project. Apps should be modular and you can package and distribute them for use by others.
These the 6 default ones:

1: django.contrib.admin – The admin site

Provides an automatic, customizable interface for managing your site's content
Offers CRUD (Create, Read, Update, Delete) operations for your models
Includes user authentication and permissions
Allows customization of the admin interface layout and functionality
Generates forms automatically based on your model definitions
Provides a search functionality and filtering options for your data

2: django.contrib.auth – An authentication system

Handles user accounts, groups, permissions, and cookie-based user sessions
Provides views for logging in, logging out, and password management
Includes decorators for controlling access to views based on user permissions
Offers a user model that can be extended for custom user information
Provides password hashing and validation
Includes a system for password reset via email

3: django.contrib.contenttypes – A framework for content types

Enables generic relationships between models
Allows associating content with any model in your Django project
Provides a ContentType model to track all models installed in your project
Enables the creation of reusable components that can work with any model
Supports polymorphic relationships in the database

4: django.contrib.sessions – A session framework

Manages user sessions across requests
Stores and retrieves arbitrary data on a per-site-visitor basis
Supports different session backends (database, file, cache)
Provides middleware to manage session data
Allows customization of session behavior and storage

5: django.contrib.messages – A messaging framework

Provides a way to store messages in one request and retrieve them in a subsequent request
Supports different storage backends (cookies, database, cache)
Includes message levels for different types of messages (debug, info, success, warning, error)
Offers template tags for easy rendering of messages in templates
Allows customization of message behavior and appearance

6: django.contrib.staticfiles – A framework for managing static files

Collects static files from each of your applications into a single location
Provides a management command for collecting static files
Offers a static file serving view for development (not for production use)
Supports different storage backends for serving static files
Includes template tags for easy inclusion of static files in templates
Allows customization of static file handling and storage

2.1 Postgres Setup

TODO

https://docs.djangoproject.com/en/5.1/topics/install/#database-installation

2.2 Migrating

Run to alter database state. If you have no other models, migrations for standard apps will be applied. These apps can be commented out or deleted and their migrations will be skipped.

python manage.py migrate

2.3 Django Models

Models in Django are the single source of truth about data. It contains essential fields and behaviors of data. Data is defined in the data model and information is derived from it, including migrations. After running a command to create migrations, Django will detect changes and create migration files to update the database in order to match current models.

In this app, we'll create two models: Question and Choice. A Question has a question text and a publication date. A Choice has text of the choice and a vote tally. Each Choice is associated with a Question.

polls/models.py

from django.db import models


class Question(models.Model):
    question_text = models.CharField(max_length=200)
    pub_date = models.DateTimeField("date published")


class Choice(models.Model):
    question = models.ForeignKey(Question, on_delete=models.CASCADE)
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)

Each of these classes subclasses django.db.models.Model. These fields above are all declared as class variables, each representing a field in the model.

Each field is a Field instance (like CharField for character fields and DateTimeField for datetimes).

The name of each Field instance is the field's name in machine-friendly format; it'll be used in Python code and as the database field in the model. They also accept an option, human readable name that would be used in Django introspectively and as doc. The machine-readable will be used otherwise.

Some Field classes have required arguments; CharField for instance requires a max_length. This is used both to reflect in the database schema as in Django-level object validation.

A Field can also have many optional arguments; in this case, we set the default value of the IntegerField named votes as 0.

The ForeignKey field defines the relationship; it tells Django each Choice is related to a question. Django supports many-to-one, one-to-one and many-to-many relationships.

These models give Django a lot of information. From it Django is able to create a database schema and Python db-access API call to access Question and Choice objects.

2.4 Django Migrations

With the app installed in the settings and the models declared, we can now generate the migrations:

python manage.py makemigrations polls

You can also inspect the SQL that will be applied for the specific migration file. In this case,

python manage.py sqlmigrate polls 0001

Would output

BEGIN;
--
-- Create model Question
--
CREATE TABLE "polls_question" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "question_text" varchar(200) NOT NULL, "pub_date" datetime NOT NULL);
--
-- Create model Choice
--
CREATE TABLE "polls_choice" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "choice_text" varchar(200) NOT NULL, "votes" integer NOT NULL, "question_id" bigint NOT NULL REFERENCES "polls_question" ("id") DEFERRABLE INITIALLY DEFERRED);
CREATE INDEX "polls_choice_question_id_c5b4b260" ON "polls_choice" ("question_id");
COMMIT;

Run the migrations with this command to have them applied to your database.

python manage.py migrate

NOTE: SQL generated varies depending on DB used. This was generated for SQLite.

2.4.1 Properties of Migrations

Table names are generated by combining app & model names (ex: polls_choice).
Primary keys (IDs) are added automatically.
Foreign key name is foreign_model_name + _ids (ex: question_id). Note that this was generated for a one-to-many relationship and that it uses the model name, not the table's(polls_question).

NOTE: Many of these properties are overridable.

2.5 The Django App Console

First of all, let's define better representation for our models. This is done through the __str__() magic method in each model.

You can see I'm returning a 'main' field + the ID. It is pretty subjective to choose what will best represent the object, but you'll have to return a string.

Let's also add a helper method to return any questions created in the last day.

polls/models.py

class Question(models.Model):
    # ...
    def __str__(self):
        return f"{self.question_text}  ID: {self.id}"

    # returns true if published in the last 24h or false otherwise
    def was_published_recently(self):
        return self.pub_date >= timezone.now() - datetime.timedelta(days=1)


class Choice(models.Model):
    # ...
    def __str__(self):
        return f"{self.choice_text}  ID: {self.id}"

In there you'll choose the field(s) that better represent the object.

2.5.1 Console Interaction

Run it to go to the shell. Below are some examples of what you can do; it is particularly good to create, edit and inspect objects. This will load the python interpreter with the DJANGO_SETTINGS_MODULE set, giving it access to the import paths under polltutorial/settings.py.

python manage.py shell

This is a list of field lookup suffixes you can use to look up objects.

get() will return a single object or an error if none or more than one match the condition.
filter() will return a QuerySet object composed of zero or more objects that match the condition.

# Import the model classes we just wrote.
from polls.models import Choice, Question  
# No questions are in the system yet.
Question.objects.all() # <QuerySet []>
# Create a new Question.
# Support for time zones is enabled in the default settings file, so
# Django expects a datetime with tzinfo for pub_date. Use timezone.now()
# instead of datetime.datetime.now() and it will do the right thing.
from django.utils import timezone
q = Question(question_text="What's new?", pub_date=timezone.now())
# Save the object into the database. You have to call save() explicitly.
q.save()
# It gets an ID once it is persisted in the DB.
q.id # 1
# Access model field values via Python attributes.
q.question_text # "What's new?"
q.pub_date # datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=datetime.timezone.utc)
# Change values by changing the attributes, then calling save().
q.question_text = "What's new?"
q.save()
# objects.all() displays all the questions in the database.
Question.objects.all() # <QuerySet [<Question: What's new? ID: 1>]>
# import timezone module to use time operations
from django.utils import timezone
current_year = timezone.now().year
# looks Questions created in the current year
Question.objects.get(pub_date__year=current_year) # <Question: What's new? ID: 1>
# Uses helper method on Question just created
Question.objects.get(id=1).was_published_recently() # True
# Display any choices from the related object set -- none so far.
q.choice_set.all() # <QuerySet []>
# The create call constructs a new `Choice` object, does the INSERT statement & adds the choice
# to the set of available choices and returns the new Choice object. Django creates
# a set (automatically defined as "choice_set") to hold the "other side" of a ForeignKey
# relation (e.g. a question's choice) which can be accessed via the API.
q.choice_set.create(choice_text="Not much", votes=0) # <Choice: Not much ID: 1>
q.choice_set.create(choice_text="The sky", votes=0) # <Choice: The sky ID: 2>
q.choice_set.create(choice_text="Just hustling again", votes=0) # <Choice: Just hustling again ID: 3>
# Now let's access the choices again:
q.choice_set.all() 
# Note how you can query choices by properties of the parent object:
Choice.objects.filter(question__pub_date__year=current_year) # <QuerySet [<Choice: Not much ID: 1>, <Choice: The sky ID: 3>, <Choice: Just hustling again ID: 3>]>
# It is of course also possible to query them by their own properties.
c = q.choice_set.filter(choice_text__startswith="Just hustling") # <Choice: Just hustling again ID: 3>
c.delete() # removes Choice # 3

2.5.2 Hot Reloading the Console

You can use IPython to have interactive python on steroids.

Install it with pip and then initiate a new shell session:

pip install ipython
python manage.py shell -i IPython # should use IPython automatically. `-i` arg is optional

To have hot-reloading, you have to activate the extension inside the interactive interpreter session:

# Explicitly activate autoreload in IPython's interpreter
In [1]: %load_ext autoreload
In [2]: %autoreload 2 # see list of %autoreload options below
# How it can be used now:
In [3]: from polls.models import Question
In [4]: q = Question.objects.get(id=1)
In [5]: print(q) #=> What's new?  ID: 1
# Change Question's __str__() to `return f"{self.question_text} HEllow  ID: {self.id}"`
In [6]: q = Question.objects.get(id=1) # reloads object in memory
# Executes the redefined method
In [5]: print(q) #=> What's new? HEllow ID: 1

%autoreload
- Reload all modules (except those excluded by %aimport) automatically now.
%autoreload 0
- Disable automatic reloading.
%autoreload 1
- Reload all modules imported with %aimport every time before executing the Python code typed.
%autoreload 2
- Reload all modules (except those excluded by %aimport) every time before executing the Python code typed.
%aimport
- List modules which are to be automatically imported or not to be imported.
%aimport foo
- Import module 'foo' and mark it to be autoreloaded for %autoreload 1
%aimport -foo
- Mark module 'foo' to not be autoreloaded.

3.0 Django Admin

The Django admin is basically a built-in CMS.

To create an admin user, run:

python manage.py createsuperuser # will then prompt for username, password etc

Create your admin and access it in localhost:8000/admin. You can set the default language under LANGUAGE_CODE in polltutorial/settings.py.

It is also necessary to register every model you'll want to perform CRUD on through the admin panel. To do so:

polls/admin.py

from django.contrib import admin

from .models import Question

admin.site.register(Question)

Reload localhost:8000/admin and you'll see the editable Question. Each field type will have a corresponding HTML input widget, sometimes with extra functionalities like the JS calendar popup to input dates for DateTimeFields.

3.1 Customizing the Django Admin

3.1.1 Customizing Display Order of Fields

The Question model is pretty simple, but what if it had dozens of fields? You can customize their order? You can register then specifically in order; let's swap the order of pub_date and question_text and display pub_date first:

You'll have to create a QuestionAdmin class and register it as the second parameter to admin.site.register():

polls/admin.py

# ...
class QuestionAdmin(admin.ModelAdmin):
    fields = ["pub_date", "question_text"]

# ...
admin.site.register(Question, QuestionAdmin)

3.1.2 Creating Fieldsets

You can also create fieldsets to aggregate a model's fields according to your own criteria. Let's split question text and date edition in their own sections, adding no title to the question_text section and adding a Date Information header to the pub_date section:

polls/admin.py

# ...
class QuestionAdmin(admin.ModelAdmin):
    fieldsets = [
        (None, {"fields": ["question_text"]}),
        ("Date Information", {"fields": ["pub_date"]}),
    ]

# ...
admin.site.register(Question, QuestionAdmin)

3.1.3 Adding Related Objects

As you might have noticed, Question does not display options on Choices. We can register Choice just as we did with Question, and since the foreign key to Question is registered in the Choice model we will be able to create them and associate them with a Question.

We can also add the option of creating Choice objects directly in the Question, by adding it as an Inline model:

polls/admin.py

from django.contrib import admin

from .models import Choice, Question


class ChoiceInline(admin.StackedInline):
    model = Choice
    extra = 3 # will add 3 empty Choice forms when editing a choiceless (or sub-3 choice) Question


class QuestionAdmin(admin.ModelAdmin):
    fieldsets = [
        (None, {"fields": ["question_text"]}),
        ("Date information", {"fields": ["pub_date"], "classes": ["collapse"]}),
    ]
    inlines = [ChoiceInline]


admin.site.register(Question, QuestionAdmin)

If you find that this takes way too much space (every Choice field will have its own line), you can switch the StackedInline class with the TabularInline. This will show each choice in a table-like more compact format spreading the fields accross a single line instead of one line per Choice field.

polls/admin.py

# ...
class ChoiceInline(admin.TabularInline):
    model = Choice
    extra = 3
# ...

3.1.4 Customizing the Change List (Question Display in the Admin Panel)

By default, Django displays the __str()__ implementation of each object. What if we wanted to display it as a table, showing each field?

We can use the list_display class variable admin option, which sets a list of field names to display as columns.

This supports not only model fields (that map to instance variables) but also instance methods, such as our previously defined was_published_recently().

polls/admin.py

# ...
class QuestionAdmin(admin.ModelAdmin):
    # ...
    list_display = ["question_text", "pub_date", "was_published_recently"]
# ...

You can click on each field header to sort the table by its value (note that sorting by method output is not supported out of the box).

You can also add decorators to your instance method to refine its display in the admin panel. You can see a more thorough discussion on these possibilities here.

polls/models.py

# ...
from django.contrib import admin
# ...

class Question(models.Model):
    # ...
    @admin.display(
        boolean=True,
        ordering="pub_date",
        description="Was the question published recently?",
    )
    def was_published_recently(self):
        now = timezone.now()
        return now - datetime.timedelta(days=1) <= self.pub_date <= now
# ...

3.1.4.1 Filtering the Change List

You can add a list_filter class variable to the QuestionAdmin to add a filterable field to the admin panel:

polls/admin.py

# ...
class QuestionAdmin(admin.ModelAdmin):
    # ...
    list_filter = ["pub_date"]
# ...

Since this is a date, Django has pre-defined options for a date field, such as filter by date published, the ones published today, in the last 7 days, etc.

You can also declare fields that will be searchable. This will add a search bar to the admin panel for questions, and you can type something in this bar to get results for a lookup of this or these fields.

polls/admin.py

# ...
class QuestionAdmin(admin.ModelAdmin):
    # ...
    search_fields = ["question_text"]
# ...

This is the final admin file with all these options applied:

polls/admin.py

from django.contrib import admin

from .models import Question, Choice

class ChoiceInline(admin.TabularInline):
    model = Choice
    extra = 3 # will add 3 empty Choice forms when editing a choiceless (or sub-3 choice) Question


class QuestionAdmin(admin.ModelAdmin):
    fieldsets = [
        (None, {"fields": ["question_text"]}),
        ("Date information", {"fields": ["pub_date"], "classes": ["collapse"]}),
    ]
    inlines = [ChoiceInline]
    list_display = ["question_text", "pub_date", "was_published_recently"]
    list_filter = ["pub_date"]
    search_fields = ["question_text"]

admin.site.register(Question, QuestionAdmin)

3.2 Customizing the Admin Panel Look

Currently the admin panel has the Django administration title. You can change it, of course.

Create a templates directory under your project directory (polltutorial, the same one containing manage.py).

We'll then need to declare our templates path so Django to look up for our new templates in the file system.

Go to the project settings and find the "DIRS" option under TEMPLATES, and declare the BASE_DIR / "templates" path inside the array.

Comments below further explain the options.

polltutorial/settings.py

# ...
TEMPLATES = [
    {
        # Specifies the template engine to be used
        # DjangoTemplates is the built-in template engine for Django
        "BACKEND": "django.template.backends.django.DjangoTemplates",

        # Defines directories where Django should look for template files
        # BASE_DIR / "templates" points to a 'templates' folder in your project root
        "DIRS": [BASE_DIR / "templates"],

        # If True, Django will also look for templates inside installed apps
        "APP_DIRS": True,

        # Additional options for the template engine
        "OPTIONS": {
            # Context processors add variables to the template context
            # These are functions that return a dictionary of data
            "context_processors": [
                # Adds debugging variables to the context
                "django.template.context_processors.debug",

                # Adds request object to the context
                "django.template.context_processors.request",

                # Adds auth-related variables (like current user) to the context
                "django.contrib.auth.context_processors.auth",

                # Adds message-related variables to the context
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]
# ...

We can then copy the admin templates from the django source code to our newly created templates directory inside the project directory and customize our admin looks directly.

NOTE: the last command below uses relative paths. You should only run it from the base of your project directory (the one with manage.py). This also assumes your project name is polltutorial.

# captures the django installation path in the django_path variable,
# adds the directory where admin views are located as a suffix to the django path,
# copies admin files from django to our project directory to better customize them
django_path=$(python -c "import django; print(django.__path__[0])") && \
source_path="${django_path}/contrib/admin/templates/admin" && \
cp -rf "${django_path}/contrib/admin/templates/admin" ./polltutorial/templates/admin

NOTE: double check that templates is at the project root, so at the level of manage.py and not of settings.py & wsgi.py.

As an example, I'll change the site title (the one visible in the browser tab text) and the header title. You can find these in polltutorial/templates/admin/base_site.html.

Here's the original template:

polltutorial/templates/admin/base_site.html

{% extends "admin/base.html" %}

{% block title %}{% if subtitle %}{{ subtitle }} | {% endif %}{{ title }} | {{ site_title|default:_('Django site admin') }}{% endblock %}

{% block branding %}
<div id="site-name"><a href="{% url 'admin:index' %}">{{ site_header|default:_('Django administration') }}</a></div>
{% if user.is_anonymous %}
  {% include "admin/color_theme_toggle.html" %}
{% endif %}
{% endblock %}

{% block nav-global %}{% endblock %}

Here's the edited version:

polltutorial/templates/admin/base_site.html

{% extends "admin/base.html" %}

{% block title %}CUSTOM TITLE YAHOO!{% endblock %}

{% block branding %}
<div id="site-name"><a href="{% url 'admin:index' %}">CUSTOM HEADER YIPPIE</a></div>
{% if user.is_anonymous %}
  {% include "admin/color_theme_toggle.html" %}
{% endif %}
{% endblock %}

{% block nav-global %}{% endblock %}

4.0 Django Views

A view generally serves a specific function within a specific template. In a blog you can have views such as a homepage displaying latest entries, detail page displaying more info on an entry, a comment action to post user comments, etc.

In the poll project we'll have the following views:

Question index: Display latest questions
Question detail: displays question text, with no results but with a form to cast a vote
Question results: displays results for a question
Vote action: handles voting for a choice

these will all delivered by views. Each view is a function or method (in case of class-based views). Django will select a view by examining the URL requested.

The documentation page for the URL dispatcher structure is here.

Let's add a few more views for the polls app:

polls/views.py

from .models import Question # add the models import

def index(request): # replace the current useless index view with this
    # `[:5]` looks like pure python but is equivalent to a 'LIMIT 5' SQL clause
    latest_question_list = Question.objects.order_by("-pub_date")[:5] # displays last 5 questions in the system
    output = ", ".join([q.question_text for q in latest_question_list])
    return HttpResponse(output)

def detail(request, question_id):
    return HttpResponse("You're looking at question %s." % question_id)


def results(request, question_id):
    response = "You're looking at the results of question %s."
    return HttpResponse(response % question_id)


def vote(request, question_id):
    return HttpResponse("You're voting on question %s." % question_id)

And then declare the URLs:

polls/urls.py

from django.urls import path

from . import views

urlpatterns = [
    # ex: /polls/
    path("", views.index, name="index"),
    # ex: /polls/5/
    path("<int:question_id>/", views.detail, name="detail"),
    # ex: /polls/5/results/
    path("<int:question_id>/results/", views.results, name="results"),
    # ex: /polls/5/vote/
    path("<int:question_id>/vote/", views.vote, name="vote"),
]

You can access these URLs in the browser and they'll render. However, the presentation aspect is unexistent. How to change them?

4.1 Django Templates

First of all, let's create a base template:

polltutorial/templates/base.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}Django Polls App{% endblock %}</title>
    {% block extra_head %}{% endblock %}
</head>
<body>
    <header>
        <!-- You could add some header content here -->
    </header>

    <main>
        {% block content %}
        {% endblock %}
    </main>

    <footer>
        <!-- You could add some footer content here -->
    </footer>

    {% block extra_body %}{% endblock %}
</body>
</html>

Create a templates directory under polls; you also have to create another polls directory inside templates. Final path will be polltutorial/polls/templates/polls/<template files>; Django will look for templates there.

Then, add a template with some logic embedded in the HTML. Note that it is extending from base.html:

polls/templates/polls/index.html

{% if latest_question_list %}
    <ul>
    {% for question in latest_question_list %}
        <li><a href="/polls/{{ question.id }}/">{{ question.question_text }}</a></li>
    {% endfor %}
    </ul>
{% else %}
    <p>No polls are available.</p>
{% endif %}

It is also required to explicitly add the template loader module into the view file that will serve views to templates. So up to now the imports in polls/views.py should be these:

polls/views.py

from django.http import HttpResponse
from django.template import loader # this one should be added now

from .models import Question

def index(request):
    latest_question_list = Question.objects.order_by("-pub_date")[:5]
    template = loader.get_template("polls/index.html")
    context = {
        "latest_question_list": latest_question_list,
    }
    return HttpResponse(template.render(context, request))

# ...

Here is the syntatic-sugar version of the code above. They should be functionally equivalent, but this one uses render():

polls/views.py

from django.http import HttpResponse
from django.shortcuts import render

from .models import Question


def index(request):
    latest_question_list = Question.objects.order_by("-pub_date")[:5]
    context = {"latest_question_list": latest_question_list}
    return render(request, "polls/index.html", context)

# ...

4.1.1 404 Views

Sometimes the requested content won't exist. Let's add this to the detail view in case an unexisting ID for a poll is sent in the URL. Notice that Http404 has to be requested:

polls/views.py

from django.http import Http404 # add this to requests
# ...
def detail(request, question_id):
    try:
        question = Question.objects.get(pk=question_id)
    except Question.DoesNotExist:
        raise Http404("Question does not exist")
    return render(request, "polls/detail.html", {"question": question})
# ...

And now to polls/detail.html:

polls/templates/polls/detail.html

<h1>{{ question.question_text }}</h1>
<ul>
{% for choice in question.choice_set.all %}
    <li>{{ choice.choice_text }}</li>
{% endfor %}
</ul>

There is another shortcutty, syntatic-sugary option to quickly serve 404 as well:

polls/views.py:

from django.shortcuts import get_object_or_404, render # notice the new import

from .models import Question


# ...
def detail(request, question_id):
    question = get_object_or_404(Question, pk=question_id)
    return render(request, "polls/detail.html", {"question": question})
# ...

4.1.2 URL Care

In order to ensure our URL will be correctly mapped, we must sometimes have to make sure Django knows which one is which.
For instance, the same name could be used for different URLs in different apps, an URL path could be changed and etc.

4.1.2.1 Adding Views and Names as `path()` Params

We can specify the view directly in the path() function, and also the name.
This will make sure that the URL is mapped to a specific view, and the name will make it possible to reference this same view

polls/urls.py

# ...
urlpatterns = [
    # ex: /polls/
    path("", views.index, name="index"),
    # ex: /polls/5/
    path("<int:question_id>/", views.detail, name="detail"),
    # ex: /polls/5/results/
    path("<int:question_id>/results/", views.results, name="results"),
    # ex: /polls/5/vote/
    path("<int:question_id>/vote/", views.vote, name="vote"),
]

4.1.2.2 Namespacing URLs

We can namespace a collection of URLs; it is usually a good idea to namespace them with the app's name. So polls/urls.py should now look like this:

# ...
app_name = "polls" # notice this variable assignment
urlpatterns = [
    # ex: /polls/
    path("", views.index, name="index"),
    # ex: /polls/5/
    path("<int:question_id>/", views.detail, name="detail"),
    # ex: /polls/5/results/
    path("<int:question_id>/results/", views.results, name="results"),
    # ex: /polls/5/vote/
    path("<int:question_id>/vote/", views.vote, name="vote"),
]

We can now update our index, from this semi-hardcoded version:

<!-- ... --->
<li><a href="/polls/{{ question.id }}/">{{ question.question_text }}</a></li>
<!-- ... --->

To this much more dynamic one:

<!-- ... --->
<li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li>
<!-- ... --->

You could now even change the path structure without breaking your templates!

5.0 Django Forms

Let's update our detail view to add the ability to cast a vote to it:

polls/templates/polls/detail.html

<form action="{% url 'polls:vote' question.id %}" method="post">
{% csrf_token %}
<fieldset>
    <legend><h1>{{ question.question_text }}</h1></legend>
    {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
    {% for choice in question.choice_set.all %}
        <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}">
        <label for="choice{{ forloop.counter }}">{{ choice.choice_text }}</label><br>
    {% endfor %}
</fieldset>
<input type="submit" value="Vote">
</form>

This will:

Display a rdio button for each choice; value of each is the question choice ID. The ID will be sent on form submission.
Form action is set to {% url 'polls:vote' question.id %} with method="post" (the one used when server-side data is meant to be altered).
Note the CSRF tag just inside the form. This is important to insert in all POST forms targeting internal URLs to prevent Cross Site Request Forgery attacks.

5.1 Casting a Vote

Now let's create the view for this URL here:

polls/urls.py

path("<int:question_id>/vote/", views.vote, name="vote"),

Note that you'll have to import F from django.db.models, HttpResponseRedirect from django.http and reverse from django.urls, and also Choice from your own models.

Notes

request.POST is a dictionary-like object; its values are always strings. Note that django also provides request.GET and etc, we're explicitly using POST to ensure that the data will only be altered through a POST call.
F("votes) + 1 instructs the db to increse vote count by 1.
Note that in a successful vote submission, user will be redirected to the results page; this avoids form resubmission if the user presses back to repeat the last request.
Lastly, note the reverse() function in the HttpResponseRedirect() constructor. It is used to dynamically generate URLs based on URL patterns; more details on this after the code.

polls/views.py

from django.db.models import F
from django.http import HttpResponse, HttpResponseRedirect
from django.shortcuts import get_object_or_404, render
from django.urls import reverse

from .models import Choice, Question

# ...
def vote(request, question_id):
    question = get_object_or_404(Question, pk=question_id)
    try:
        selected_choice = question.choice_set.get(pk=request.POST["choice"])
    except (KeyError, Choice.DoesNotExist):
        # Redisplay the question voting form.
        return render(
            request,
            "polls/detail.html",
            {
                "question": question,
                "error_message": "You didn't select a choice.",
            },
        )
    else:
        selected_choice.votes = F("votes") + 1
        selected_choice.save()
        # Always return an HttpResponseRedirect after successfully dealing
        # with POST data. This prevents data from being posted twice if a
        # user hits the Back button.
        return HttpResponseRedirect(reverse("polls:results", args=(question.id,)))

polls/templates/polls/results.html

<h1>{{ question.question_text }}</h1>

<ul>
{% for choice in question.choice_set.all %}
    <li>{{ choice.choice_text }} -- {{ choice.votes }} vote{{ choice.votes|pluralize }}</li>
{% endfor %}
</ul>

<a href="{% url 'polls:detail' question.id %}">Vote again?</a>

5.1.1 The `reverse()` function

NOTE: there is also reverse_lazy(); this should be used when the reverse() params aren't known beforehand, such as in abstract classes and decorator functions.

The basic syntax of reverse() is as follows:

from django.urls import reverse
# signature
reverse(viewname, urlconf=None, args=None, kwargs=None, current_app=None)
# named URL
url = reverse('news-archive')
# with arguments
url = reverse('arch-summary', args=[1945])
# with keyword arguments
url = reverse('admin:app_list', kwargs={'app_label': 'auth'})

viewname: This can be a URL pattern name or the callable view object 2.
urlconf: Optional. Specifies the URLconf module to use for reversing. By default, it uses the root URLconf for the current thread 2.
args: Optional. A list of positional arguments to be passed to the URL pattern 2.
kwargs: Optional. A dictionary of keyword arguments to be passed to the URL pattern 2.
current_app: Optional. Provides a hint about the application to which the currently executing view belongs 2.

5.2 Generic Views

Our results and detail views are the same, and the index view is pretty similar while rendering various objects instead of one.
Django has generic helpers to keep a common structure. Let's remake most views (except for the vote one) using pre-defined generic Django classes.
We also need to redefine URLs; note that the question_id param was switched to pk (shortcut for Primary Key) in order to be correctly identified by the Django configuration so these changes can work.

polls/views.py

from django.db.models import F
from django.http import HttpResponseRedirect
from django.shortcuts import get_object_or_404, render
from django.urls import reverse
from django.views import generic

from .models import Choice, Question


# Each generic view needs to know what model it will be acting upon. This is provided using either the model attribute 
# (in this example, model = Question for DetailView and ResultsView) or by defining the get_queryset() method (as shown in IndexView)
class IndexView(generic.ListView):
    template_name = "polls/index.html"
    context_object_name = "latest_question_list"

    def get_queryset(self):
        """Return the last five published questions."""
        return Question.objects.order_by("-pub_date")[:5]


class DetailView(generic.DetailView):
    model = Question
    template_name = "polls/detail.html"


class ResultsView(generic.DetailView):
    model = Question
    template_name = "polls/results.html"



def vote(request, question_id):
    # keep it the same
    # ...

polls/urls.py

urlpatterns = [
    # ex: /polls/
    path("", views.IndexView.as_view(), name="index"),
    # ex: /polls/5/
    path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    # ex: /polls/5/results/
    path("<int:pk>/results/", views.ResultsView.as_view(), name="results"),
    # ex: /polls/5/vote/
    path("<int:question_id>/vote/", views.vote, name="vote"),
]

By default, the DetailView generic view uses a template called /_detail.html. In our case, it would use the template "polls/question_detail.html". The template_name attribute is used to tell Django to use a specific template name instead of the autogenerated default template name. We also specify the template_name for the results list view – this ensures that the results view and the detail view have a different appearance when rendered, even though they’re both a DetailView behind the scenes.

Similarly, the ListView generic view uses a default template called /_list.html; we use template_name to tell ListView to use our existing "polls/index.html" template.

In previous parts of the tutorial, the templates have been provided with a context that contains the question and latest_question_list context variables. For DetailView the question variable is provided automatically – since we’re using a Django model (Question), Django is able to determine an appropriate name for the context variable. However, for ListView, the automatically generated context variable is question_list. To override this we provide the context_object_name attribute, specifying that we want to use latest_question_list instead. As an alternative approach, you could change your templates to match the new default context variables – but it’s a lot easier to tell Django to use the variable you want.

Full documentation on generic views is available here.

6.0 Django Tests

Not to extend too much on an indoctrination of why tests are important, but they:

Ensure consistency in the app before and after changes;
Guide development with clear objectives;

Remember, about tests:

Don't test against the framework: create tests for your functionality, not if the framework is working as it should.
Write tests for public interfaces as they will change way less than implementations; you don't want to have headaches every time you refactor something;
One test class for one class (view, model, etc) is a good rule of thumb;
Test method names that are descriptive;

Note: you might notice that some of the tests below might contradict this advice. They are technical examples on how to do this type of test, and not examples of implementation of testing principles on why, which is a lot more context-specific and up to you to determine when and how to follow.

6.0.1 Test Driven Development

TDD is a discipline in which you start a feature development by writing tests. This is good as it uses the test itself to guide the development. Personally in very new apps I often skip it at the beginning, then start implementing it when the app reaches a certain draft stage and then keep further development with TDD, but that's purely subjective.

6.1 Testing a Model

There is a bug in the polls app: Question.was_published_recently() returns True if the question was published within the last day (as it should) but if, say, the publishing date is set for tomorrow, this would also return True, meaning that it checks for the lower bound of time but not the upper:

# create a Question instance with pub_date 30 days in the future
future_question = Question(pub_date=timezone.now() + datetime.timedelta(days=30))
# was it published recently?
future_question.was_published_recently() # True

Add the tests for the correctly working version (recent is a question createn in a time bigger than or equal to 1 day ago and smaller than or equal to this instant):

polls/tests.py

import datetime

from django.test import TestCase
from django.utils import timezone

from .models import Question


class QuestionModelTests(TestCase):
    def test_was_published_recently_with_future_question(self):
        """
        was_published_recently() returns False for questions whose pub_date
        is in the future.
        """
        time = timezone.now() + datetime.timedelta(days=30)
        future_question = Question(pub_date=time)
        self.assertIs(future_question.was_published_recently(), False)

    def test_was_published_recently_with_old_question(self):
        """
        was_published_recently() returns False for questions whose pub_date
        is older than 1 day.
        """
        time = timezone.now() - datetime.timedelta(days=1, seconds=1)
        old_question = Question(pub_date=time)
        self.assertIs(old_question.was_published_recently(), False)


    def test_was_published_recently_with_recent_question(self):
        """
        was_published_recently() returns True for questions whose pub_date
        is within the last day.
        """
        time = timezone.now() - datetime.timedelta(hours=23, minutes=59, seconds=59)
        recent_question = Question(pub_date=time)
        self.assertIs(recent_question.was_published_recently(), True)

Run the test:

python manage.py test

...and it will fail, of course.

Now, let's refactor the model functionality based on the

polls/models.py

# ...
def was_published_recently(self):
    # How it was:
    # return self.pub_date >= timezone.now() - datetime.timedelta(days=1)
    # How it is:
    now = timezone.now()
    return now - datetime.timedelta(days=1) <= self.pub_date <= now
# ...

And now, the tests will pass.

6.2 Testing a View

It is possible to set up publish dates for polls to the future, so they are available at the time when they should. As of now, they are available as the '5 most recent', which means that this will prioritize questions scheduled for the future.

We should show the 5 most recent ones based on the present time, not the future.

6.2.1 The Django Test Client

Django provides a client to simulate a user interecting with the project through a browser.
It is not as comprehensive as tools such as Selenium and Cypress, though.
This is an example of its use:

from django.test.utils import setup_test_environment
setup_test_environment() # sets up a template renderer; double check TIME_ZONE in settings.py as it might affect it
from django.test import Client
client = Client() # instantiates the client
# gets response from '/'
response = client.get("/") # Not Found: /
# we should expect a 404 from that address; if you instead see an
# "Invalid HTTP_HOST header" error and a 400 response, you probably
# omitted the setup_test_environment() call described earlier.
response.status_code # 404
# on the other hand we should expect to find something at '/polls/'
# we'll use 'reverse()' rather than a hardcoded URL
from django.urls import reverse
response = client.get(reverse("polls:index"))
response.status_code # 200
response.content # b'\n    <ul>\n    \n        <li><a href="/polls/1/">What&#x27;s up?</a></li>\n    \n    </ul>\n\n'
response.context["latest_question_list"] # <QuerySet [<Question: What's up?>]>

6.2.2 Implementing the Index View Tests

Let's add some more tests. Every test method should have a descriptive name and probably a further description on what it does.

polls/tests.py

# ...
from django.urls import reverse # dynamically creates URLs

# helper to easily create questions
def create_question(question_text, days):
    """
    Create a question with the given `question_text` and published the
    given number of `days` offset to now (negative for questions published
    in the past, positive for questions that have yet to be published).
    """
    time = timezone.now() + datetime.timedelta(days=days)
    return Question.objects.create(question_text=question_text, pub_date=time)


class QuestionIndexViewTests(TestCase):
    def test_no_questions(self):
        """
        If no questions exist, an appropriate message is displayed.
        """
        response = self.client.get(reverse("polls:index"))
        self.assertEqual(response.status_code, 200)
        self.assertContains(response, "No polls are available.")
        self.assertQuerySetEqual(response.context["latest_question_list"], [])

    def test_past_question(self):
        """
        Questions with a pub_date in the past are displayed on the
        index page.
        """
        question = create_question(question_text="Past question.", days=-30)
        response = self.client.get(reverse("polls:index"))
        self.assertQuerySetEqual(
            response.context["latest_question_list"],
            [question],
        )

    def test_future_question(self):
        """
        Questions with a pub_date in the future aren't displayed on
        the index page.
        """
        create_question(question_text="Future question.", days=30)
        response = self.client.get(reverse("polls:index"))
        self.assertContains(response, "No polls are available.")
        self.assertQuerySetEqual(response.context["latest_question_list"], [])

    def test_future_question_and_past_question(self):
        """
        Even if both past and future questions exist, only past questions
        are displayed.
        """
        question = create_question(question_text="Past question.", days=-30)
        create_question(question_text="Future question.", days=30)
        response = self.client.get(reverse("polls:index"))
        self.assertQuerySetEqual(
            response.context["latest_question_list"],
            [question],
        )

    def test_two_past_questions(self):
        """
        The questions index page may display multiple questions.
        """
        question1 = create_question(question_text="Past question 1.", days=-30)
        question2 = create_question(question_text="Past question 2.", days=-5)
        response = self.client.get(reverse("polls:index"))
        self.assertQuerySetEqual(
            response.context["latest_question_list"],
            [question2, question1],
        )

6.2.3 Implementing the Fix

Here's a reminder of how our get_queryset() method is implemented:

polls/views.py

# ...
class IndexView(generic.ListView):
    template_name = "polls/index.html"
    context_object_name = "latest_question_list"

    def get_queryset(self):
        """Return the last five published questions."""
        return Question.objects.order_by("-pub_date")[:5]
# ...

We'll fix this by:

Finding the current time based on the app's timezone;
Filtering the query with an upper-bound (ordering by publish time with the current instant as the upper-bound)

This is the new implementation:

polls/views.py

# ...
from django.utils import timezone
# ...
def get_queryset(self):
    """
    Return the last five published questions (not including those set to be
    published in the future).
    """
    # __lte suffix = Less Than or Equal to
    return Question.objects.filter(pub_date__lte=timezone.now()).order_by("-pub_date")[
        :5
    ]

6.2.4 Implementing Detail View Tests

The index now prevents the output of future quests. The detail view, however, does not.

We should add tests to the detail view to check that a question with a pub_date in the past can be displayed, one with the pub_date in the future cannot.

polls/tests.py

# ...
class QuestionDetailViewTests(TestCase):
    def test_future_question(self):
        """
        The detail view of a question with a pub_date in the future
        returns a 404 not found.
        """
        future_question = create_question(question_text="Future question.", days=5)
        url = reverse("polls:detail", args=(future_question.id,))
        response = self.client.get(url)
        self.assertEqual(response.status_code, 404)

    def test_past_question(self):
        """
        The detail view of a question with a pub_date in the past
        displays the question's text.
        """
        past_question = create_question(question_text="Past Question.", days=-5)
        url = reverse("polls:detail", args=(past_question.id,))
        response = self.client.get(url)
        self.assertContains(response, past_question.question_text)

Then we need to add the same constraint to the detail view:

polls/views.py

# ...
class DetailView(generic.DetailView):
    # ...
    def get_queryset(self):
        """
        Excludes any questions that aren't published yet.
        """
        return Question.objects.filter(pub_date__lte=timezone.now())

7.0 Static Assets

You might want to serve static files such as css and images.

Create a new static directory, similar to the templates one:

mkdir polls/static
mkdir polls/static/polls
mkdir polls/static/polls/images

And add some color to links under lists. You can also add a background image; note that you'll have to add your own background.png to polls/static/polls/images/background.png.

polls/static/polls/style.css

li a {
    color: green;
}

body {
    background: white url("images/background.png") no-repeat;
}

Finally, you'll have to add the static template tag to your templates. It'll load your static folder.

polls/templates/polls/index.html

{% load static %}

<link rel="stylesheet" href="{% static 'polls/style.css' %}">
<!-- ... --->

The {% static %} template tag generates the absolute URL of static files.

7.1 Final Poll Templates

polls/templates/polls/index.html

{% extends 'base.html' %}
{% load static %}
{% block extra_head %}
    {{ block.super }}
    <link rel="stylesheet" href="{% static 'polls/style.css' %}">
{% endblock %}
{% block content %}
    {% if latest_question_list %}
        <ul>
        {% for question in latest_question_list %}
            <li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li>
        {% endfor %}
        </ul>
    {% else %}
        <p>No polls are available.</p>
    {% endif %}
{% endblock %}

polls/templates/polls/detail.html

{% extends 'base.html' %}
{% load static %}

{% block extra_head %}
    {{ block.super }}
    <link rel="stylesheet" href="{% static 'polls/style.css' %}">
{% endblock %}

{% block content %}
    <form action="{% url 'polls:vote' question.id %}" method="post">
        {% csrf_token %}
        <fieldset>
            <legend><h1>{{ question.question_text }}</h1></legend>
            {% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
            {% for choice in question.choice_set.all %}
                <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}">
                <label for="choice{{ forloop.counter }}">{{ choice.choice_text }}</label><br>
            {% endfor %}
        </fieldset>
        <input type="submit" value="Vote">
    </form>
{% endblock %}

polls/templates/polls/results.html

{% extends 'base.html' %}
{% load static %}

{% block extra_head %}
    {{ block.super }}
    <link rel="stylesheet" href="{% static 'polls/style.css' %}">
{% endblock %}

{% block content %}
    <h1>{{ question.question_text }}</h1>

    <ul>
    {% for choice in question.choice_set.all %}
        <li>{{ choice.choice_text }} -- {{ choice.votes }} vote{{ choice.votes|pluralize }}</li>
    {% endfor %}
    </ul>

    <a href="{% url 'polls:detail' question.id %}">Vote again?</a>
{% endblock %}

8.0 Organizing and Debugging a Django Project

8.1 The Django Debug Toolbar

This is a 3rd party app (one of the most downloaded), not a native part of the Django ecosystem, but it exemplifies very well the modular and pluggable nature of Django apps.

It shows a toolbar while inspecting the app in the browser that shows stuff like request time, SQL queries executed and etc. If you want an API-mode equivalent, check out Django Silk made by the same developers of the django debug toolbar.

Install it in the app:

python -m pip install django-debug-toolbar
pip freeze > requirements.txt

Further installation instructions are here in case these below don't work.

Ensure settings.py have these:

settings.py

INSTALLED_APPS = [
    # ...
    "django.contrib.staticfiles",
    # ...
]
# ...
STATIC_URL = "static/"
# ...
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        # ...
    }
]
# ...

Add 127.0.0.1 (the localhost address) to INTERNAL_IPS.

It is also a good idea to conditionally declare the debug toolbar's middleware and add the debug_toolbar, so the toolbar does not interfere with testing.

polltutorial/polltutorial/settings.py

INTERNAL_IPS = [
    # ...
    "127.0.0.1",
    # ...
]
# ...
from sys import argv

TESTING = "test" in sys.argv
if not TESTING:
    INSTALLED_APPS = [
        *INSTALLED_APPS,
        "debug_toolbar",
    ]
    MIDDLEWARE = [
        "debug_toolbar.middleware.DebugToolbarMiddleware",
        *MIDDLEWARE,
    ]
# ...

Finally, add the URLs to the project URLs, also conditionally to the project running outside the test environment:

polltutorial/polltutorial/urls.py

# ...
from django.conf import settings
from debug_toolbar.toolbar import debug_toolbar_urls

if not settings.TESTING:
    urlpatterns = [
        *urlpatterns,
    ] + debug_toolbar_urls()

8.2 Separating Configs per Environment

It is smart to have an app that prioritizes ease of inspection in development and performance in production.

Let's create a new directory, polltutorial/settings, then add 4 files into it:

mkdir polltutorial/settings && \
touch polltutorial/settings/__init__.py && \ # makes directory a python module
touch polltutorial/settings/base.py && \ # base settings
touch polltutorial/settings/development.py && \ # development-specific settings
touch polltutorial/settings/production.py && \ # production-specific settings

Then, copy all contents of polltutorial/settings.py into polltutorial/settings/base.py.

Finally, add code both in polltutorial/settings/development.py and polltutorial/settings/production.py to import the base settings:

polltutorial/settings/development.py & polltutorial/settings/production.py

from .base import *

Finally, you have to register in manage.py that the default settings module is now polltutorial/settings/development.py instead of polltutorial/settings.py.

Let's add some specific configuration to the development environment.

Find this line:

manage.py

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'polltutorial.settings')

And replace it with this:

manage.py

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'polltutorial.settings.development')

You will also have to redefine the BASE_DIR since our new configuration is one directory deeper from what it was.

So, in settings/development.py, find this line:

settings/development.py

BASE_DIR = Path(__file__).resolve().parent.parent

And replace it with this:

settings/development.py

BASE_DIR = Path(__file__).resolve().parent.parent.parent

Restart your server and if everything went smoothly, the project should work exactly as it was already working, but now with a much better settings organization.

Adding More Detailed Logging to Console

Let's add more detailed logging to the server so we can see stuff such as SQL queries performed and etc in the console when a new view is loaded:

polltutorial/polltutorial/settings/development.py

LOGGING = {
    # Specifies the version of the logging configuration schema
    'version': 1,

    # Keeps any existing loggers from being disabled
    'disable_existing_loggers': False,

    # Defines the handlers for the logging system
    'handlers': {
        # Configures a console handler
        'console': {
            # Uses Python's built-in StreamHandler to output logs to the console
            'class': 'logging.StreamHandler',
        },
    },

    # Configures specific loggers
    'loggers': {
        # Logger for database-related logs
        'django.db.backends': {
            # Specifies that logs from this logger should be sent to the console
            'handlers': ['console'],
            # Sets the minimum log level to DEBUG (will capture all levels of logs)
            'level': 'DEBUG',
        },
        # Logger for request-related logs
        'django.request': {
            # Sends logs to the console
            'handlers': ['console'],
            # Captures all logs of DEBUG level and above
            'level': 'DEBUG',
        },
        # Logger for server-related logs
        'django.server': {
            # Outputs logs to the console
            'handlers': ['console'],
            # Logs all messages of DEBUG level and higher
            'level': 'DEBUG',
        },
    },
}

Run the server:

python manage.py runserver

Now, while navigating through your app in the browser, check the output of the console tab that is running your Django server process; it should be a lot more detailed.

Running App with Production Settings

Edit production.py to add some minimal production-like settings:

production.py

from .base import *

ALLOWED_HOSTS = ['localhost', '127.0.0.1'] # when not in debug mode, hosts must be explicitly authorized

DEBUG = False

And run the app in production mode

python manage.py runserver --settings=polltutorial.settings.production

If you don't see as many logs as before, it means the app is correctly running in production mode.

Congratulations! You have completed the tutorial. Have fun using Django.

Python Version Management with PyEnv

Otavio Monteagudo — Tue, 17 Sep 2024 12:55:20 +0000

Command Reference (Install & Setup instructions below):

# List all versions of python interpreters available to install:
pyenv install -l
# List all versions of CPython (the default interpreter) available to install:
pyenv install -l | grep -E '^\s*[0-9]'
# Install specified version. In this case it installs 3.12.6
pyenv install 3.12.6
# List versions installed locally:
pyenv versions
# See global version
pyenv global
# Set global version to x.x.x; in this case it sets to 3.12.6
pyenv global 3.12.6
# See local version
pyenv local
# Set global version to x.x.x; in this case it sets to 2.7.18
pyenv global 3.12.6

Intro to PyEnv

Management of different language versions and interpreters is somewhat of a gray area in the Pythonic world as of September 2024, but of course the community has "unofficial" solutions that circumvent this problem.
One particular good one is PyEnv, that borrows heavily from ruby's solutions for version management, which is something ruby does very well.
PyEnv is basically a collection of shell scripts that help to install and select a specific python version or interpreter, in both global and localized scopes.
It works by inserting a directory of shims in the PATH and will rehash the shim according to specific conditions in order to map the python binary (as well as other setup such as mapping pip, switching the PYTHON_VERSION env, etc).
This guide will focus on MacOS and the Debian-family linux distros, and will cover setup on both bash and zsh. It will not cover pyenv-win.

Installing PyEnv

MacOS

This assumes that homebrew and the xcode-tools are installed.
First line will install dependencies to install and build python versions.
Second line will install pyenv itself.
Third line is optional and will append a pyenv load before running brew in order to avoid a false positive warning when running brew doctor and to avoid errors in case you are developing brew python packages. Note that it is being placed in .zshrc, your mac should already have zsh enabled by default unless it's an older machine, in which case you should probably append it to .bash_profile.

brew install openssl readline sqlite3 xz zlib tcl-tk && \
brew install pyenv \
&& echo "alias brew='env PATH=\"${PATH//$(pyenv root)\/shims:/}\" brew'" >> ~/.zshrc

Linux (Debian-based)

First, install the dependencies.
Then, clone the public repository into $HOME/.pyenv.

sudo apt update && sudo apt install build-essential \
libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev && \
git clone https://github.com/pyenv/pyenv.git $HOME/.pyenv

Post Install (Both MacOS & Linux)

Add this to your relevant shell config file, .bash_profile if you're using bash, .zshrc if you're using zsh. Find out which with echo $SHELL if you're unsure.

## pyenv configs
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"
fi

Finally, refresh your terminal environment to see changes with exec "$SHELL".

After this setup, your python (not python3!) will be mapped to your python version set up with pyenv.
I'd recommend you to then install a python version (see command reference above) and set it up as your global version.
Check that everything worked with python --version to see if your installed version matches the one you've chosen. If it does not, it likely is still pointing to the system default, so you might have slipped in one of the steps below (likely the part to refresh the terminal, close and reopen your terminal window if you're unsure of what to do).

Have fun with a saner python version management!

Converting Code-Flavored Markdown to PDF

Otavio Monteagudo — Mon, 29 Jul 2024 14:10:28 +0000

Intro

If you are like me, you might like to take markdown notes while doing a video course, reading a technical book or just noting down what worked out in a project and why. You might also want to render these markdown files to PDF format for easy referencing in the future or maybe printing these notes to have a physical reference nearby. Fear not, for this article will spare you some potential trial and error.

Best Method Overall: `Markdown to PDF` VS Code Extension

Of everything I tried, the one that provided the best results out of the box is the Markdown PDF VS Code extension method.
Just install it and, with your markdown file focused on VS Code, spring up the Command Palette with F1 or Ctrl + Shift + P (Cmd + Shift + P on Macs), type 'export' and you'll see the relevant commands provided by this extension prefixed with Markdown PDF: .
Select which format you want to export your content to (pdf and also html and most common image formats).

It will first create a temporary HTML file to be rendered as PDF by the extension's Chromium engine in the background and voilà, you'll likely have your problem solved: the output pdf will be exported to the same directory and with the same name as the markdown file you have highlighted (you can also configure where to send outputs in the extension settings).

The Good

This is the only method that kept syntax highlighting and also broke lines as expected; in the other ones, if a line of code overflowed the width of the designated code block space, they would have just kept on going towards scrolling infinity instead of rendering into a new line.
You can also fiddle with the extension's CSS to have maximum customization. See configuration options in the extension's description.

The Bad

Nothing too bad about it in my opinion; it adds unasked for headers and footers to the output PDF, but this can be turned off in the extension settings.

To turn the headers and footers off, go to the extension settings (File > Preferences > UserSettings or Workspace Settings in VS Code; Code > Settings > Settings in Macs), then find Extensions in the left-side menu and find Markdown PDF in there.

You'll find both "footer template" and "header template" options with some default HTML in there. Just erase the HTML and that's it.

Alternative 1: `Dilliger.io`

Simply access https://dillinger.io and paste your markdown code there. It has the option to export to PDF, as well as some other formats.

The Good

As convenient as it gets. Also supports syntax highlighting.

The Bad

It will break references to any local files you have in your markdown; I had images in mine so this did not work for me. Also has limited customization options.

Alternative 2: Python `grip`

You'll need to have pip installed. Install grip with pip:

pip install grip

Then, use the grip command with the markdown file as input:

grip README.md

You'll see in the command's output a localhost address with an assigned port (usually 5000 or 6419). Go to that address in your chosen browser and you'll see your markdown rendered. Save it as PDF.

The Good

Pretty easy to run, works for simple conversions.

The Bad

No syntax highlighting, and no line breaks inside code blocks.

A Non-noob Javascript Glossary for 2024, with Examples

Otavio Monteagudo — Mon, 19 Feb 2024 17:23:08 +0000

A Non-noob Javascript Glossary for 2024, with Examples

Intro

Much like the JavaScript language, the JavaScript environment can sometimes feel confusing and counter-intuitive.
This non-exhaustive glossary highlights and expands on key concepts related to JavaScript. Its reading should provide the most benefit for programmers who are at least somewhat comfortable using javascript but still get confused with some aspects of the language or its ecosystem. This is a glossary for non-noobs, which doesn't mean it's just for the pros; you can expect explanations about the prototype chain in here, but not what is the definition of an array. It is also focused on JavaScript itself, so no particular attention to frameworks.
At the bottom of the page you will find an index with terms in alphabetical order that you can use to navigate the glossary back-and-forth.
Below is the glossary in no particular order; I tried to order everything at least somewhat logically, having relevant and/or interdependent concepts grouped nearby.

Glossary

ECMAScript

ECMAScript is the standard upon which JavaScript is based. Ever since JavaScript's runtime was confined to browsers, ECMAScript served as the rule book that serves as a foundational blueprint for JavaScript implementation in different domains. It provides a set of agreed-upon functionalities behaviors that implementations should adhere to improve consistency and interoperability of JavaScript code on its environments.

ECMAScript2015/ES6

Sixth edition of the ECMAScript standard, held in 2015 and considered to be the second major definition of the language (first one was in the third edition, held in 1999).
Its main purpose was to address some of the perceived shortcomings of JavaScript.
ES6 introduced widely-used features, the main ones being the let variable definition that addresses hoisting issues, the class keyword to abstract the prototype chain in a syntax more familiar and intuitive to developers coming from other languages, arrow functions, an unified module definition and the (Promise)[#promise] objects which simplify asynchronous programming.

Babel

Babel is an open-source JavaScript transpiler that allows developers to write their code using the latest ECMAScript standards and features, which it then converts into backward-compatible versions of JavaScript for use in various environments. Babel ensures that developers can leverage the newest enhancements in language specifications while maintaining broad compatibility with older browsers and platforms. It offers a range of plugins, presets, and polyfills to streamline development workflows, optimize code, and extend functionality while adhering to the evolving ECMAScript standards.

WASM (WebAssembly)

WebAssembly (WASM) is a low-level, assembly-like language with a compact binary format that provides fast performance and runs on modern web browsers. It allows code written in languages like C, C++, and Rust to run on the web at near-native speed. WASM is designed to work alongside JavaScript, allowing both to work together.

Node.js

Node.js is an open-source, cross-platform runtime environment for executing JavaScript code outside of a browser.
Even though it operates on a single thread using non-blocking Input/Output calls, it has an event-driven architecture and supports concurrency via events and callbacks, enabling it to handle numerous connections with high throughput and making viable the use of JavaScript in, among others, server-side applications.
It is important to mention that node.js wasn't the only or the first attempt to establish a JavaScript runtime outside of browsers. However, due to the great skill and effort of the programmers involved in creating node and JavaScript's growing maturity as a technology (node's first stable release cycle was in 2015, shortly after the definition of ES6 standards), it has arguably been the most successful.

Event-Driven Architecture (EDA)

Software pattern in which flow of the program is determined by ad hoc actions such as user actions, sensor outputs and messages from external programs.
In an EDA, there are typically event producers (which generate events) and event consumers (which react to events). Events are processed asynchronously, meaning the app can continue with other tasks and respond to other events while waiting for a response or completion of a task associated with a past event. This architecture is often associated with scalability strategies for environments which handle multiple concurrent actions and in systems that need to react to changes in real-time.
Other than node.js, examples of EDA systems are user interfaces (handling clicks, keyboard input and etc and triggering specific callbacks for actions), microservices (each communicating to and reacting to each other through events) and Internet of Things devices (for example, devices that handle sensor data changes or specific signals from within or outside the device).
In a nutshell, Event-Driven Architecture is a design paradigm centered around producing, detecting and reacting to events.

V8 Engine

The V8 engine is Google's open source high-performance JavaScript and WebAssembly engine, written in C++. It is used as a JavaScript runtime Chromium-based browsers (including Google Chrome itself) and node.js, among others. V8 compiles JavaScript directly to native machine code before executing it, optimizing code for performance; this process is known as just-in-time (JIT) compilation.
Other notable engines include SpiderMonkey, used in Mozilla, and JavaScriptCore, used in Safari. Mobile apps built in JavaScript often have their own engines, such as Hermes, which powers ReactNative apps.

Call Stack

The call stack is a mechanism for an interpreter (like the JavaScript engine) to keep track of its place in a script that calls multiple functions. When a function is called, the interpreter adds it to the call stack and then starts carrying out the function. Any functions that are called by that function are added to the call stack further up, and run where their calls are reached.

Just-In-Time Compilation

Just-In-Time (JIT) Compilation is a method of executing computer code that involves compilation during the execution of a program – at run time – rather than prior to execution. This means that the JavaScript code is compiled into machine code and executed immediately rather than being interpreted line-by-line, which improves the performance.

Object Oriented Programming Paradigm

Object-Oriented Programming (OOP) is a programming paradigm based on the concept of "objects," which can contain data and code: data in the form of fields (often known as attributes or properties), and code in the form of procedures (often known as methods). OOP models real-world entities as objects that have a state (data) and behavior (methods). It emphasizes the bundling of data with the methods that operate on that data and typically uses classes for defining and creating objects (i.e. a class is the general, abstract case, an object is a specific individual manifestation of the class).
Remember that JavaScript is a multi-paradigm language, so you'll often see both Object Oriented and Functional Programming JS code in the wild.

Class

A class in JavaScript is a type of function, but instead of using the keyword function to initiate it, we use the keyword class; this is an example of syntatic sugar added on top of JavaScript (from the ECMAScript 2015/ES6 standard onwards) to abstract certain JavaScript properties generally regarded as poorly thought out in retrospect, which means that you can forget about this fact most of the time.
In OOP terms, a class is a blueprint for creating objects (instances). A class encapsulates data for the object and methods to manipulate that data. Classes support inheritance, allowing you to create a new class that inherits properties and methods from an existing class.

Object

In JavaScript, an object is a standalone entity, with properties and type; it is usually the specific manifestation of a generalized class, though JavaScript also has the concept of object literals.
Think of it like a 'thing' with characteristics that describe or identify it. An object can be a variable container, where properties are variables and methods are functions that can access and modify these properties. Objects are created using curly braces {} with an optional list of properties.

Functional Programming Paradigm

Functional Programming (FP) is a programming paradigm where programs are constructed by applying and composing functions. It treats computation as the evaluation of functions and avoids changing state and mutable data, instead focusing on a series of input/output trees. FP emphasizes the use of pure/idempotent functions (i.e. functions that do not cause side effects, meaning that for the same input it will always produce the same output) and higher-order functions (functions that take other functions as their arguments).

'map' Functions

In JavaScript, map is a method of the Array prototype. It allows you to transform elements in an array. map takes a function as an argument and applies this function to each element in the array, then returns a new array with the transformed elements without mutating the original array. Mapping functions are a cornerstone of functional programming.

const numbers = [1, 2, 3, 4];
const squares = numbers.map(number => number * number);
console.log(numbers); // Output: [1, 2, 3, 4]
console.log(squares); // Output: [1, 4, 9, 16]

'reduce' Functions

A reducer function in JavaScript is used with the reduce method of the Array prototype. It processes each element of an array to produce a single value. It takes a callback function as an argument, which is called on each element of the array in sequence. This callback function takes an accumulator (which accumulates the callback's return values) and the current element being processed.

const numbers = [1, 2, 3, 4];
const sum = numbers.reduce((accumulator, currentValue) => accumulator + currentValue, 0);
console.log(sum); // Output: 10

`undefined`, `null`

In JavaScript, undefined and null are both primitives, but they have different uses. undefined is a variable that has been declared but not assigned a value (a reference error should be thrown when calling an unassigned variable). null is an assignment value that represents a deliberate non-value and is indicative of a variable with no value.

let uninitializedVariable; // undefined: variable declared but not initialized
console.log(uninitializedVariable); // Output: undefined

let nullVariable = null; // null: explicitly set to 'no value'
console.log(nullVariable); // Output: null

Global Scope

Global scope refers to variables or functions that are accessible from any part of the JavaScript code. Variables defined outside any function, block, or module have global scope.

let globalVar = "I'm global"; // A global variable

function checkGlobalScope() {
    console.log(globalVar); // Accessing the global variable
}

checkGlobalScope(); // Output: "I'm global"

Hoisting

Hoisting is JavaScript's default behavior of moving all declarations to the top of the current scope (either the global or a block scope). This means that you can use variables and functions before actually declaring them. This is also the reason why you should prefer declaring variables with let over var, as a hoisted let will return a reference error if accessed before its declaration and a hoisted var will return undefined, potentially leading to hard to debug errors.

hoisted(); // Outputs: "Hello, World!"

function hoisted() {
  console.log("Hello, World!");
}

'use strict' Directive

The 'use strict' directive in JavaScript enables strict mode, which is basically a restricted version of JavaScript that will throw errors once it detects common mistakes that would otherwise silently fail and lead to hard to debug errors.
Among its restrictions, some notable ones are forbidding value assignment to undeclared variables, disabling redefinition of primitive types (like underfined or NaN), preventing duplicate names in object literals and disallowing the declaration of variables and functions inside eval statements.

// Without strict mode
function foo() {
  x = 10; // Accidentally global
}

// With strict mode
'use strict';
function foo() {
  x = 10; // ReferenceError: x is not defined
}

'use strict';
undefined = 5; // TypeError

'use strict';
var obj = { p: 1, p: 2 }; // SyntaxError

'use strict';
eval('var x = 2');
alert(x); // ReferenceError: x is not defined

Function Expression

A function expression is a way to define a function in JavaScript by assigning a function directly to a variable. Unlike function declarations, function expressions are not hoisted and cannot be used before they are defined.

greet(); // reference error!

const greet = function() {
    console.log("Hello, World!");
};

greet(); // Output: Hello, World!

Higher Order Functions

Higher order functions are functions that operate on other functions, either by taking them as arguments or by returning them. In JavaScript, functions are first-class objects, so they can be passed and returned just like any other value.

// A simple function
const double = x => x * 2;

// A higher-order function that takes a function and a value
const operate = (hoFunc, val) => {
    return hoFunc(val);
};

console.log(operate(double, 5)); // Output: 10

Closures

Closures are a feature in JavaScript where an inner function has access to the outer (enclosing) function’s variables — a scope chain. The closure has three scope chains: it has access to its own scope, the outer function’s variables, and the global variables.

function outerFunction(outerVariable) {
    return function innerFunction(innerVariable) {
        // Closure: innerFunction has access to outerVariable
        console.log(outerVariable, innerVariable);
    };
}

const newFunction = outerFunction("outer");
newFunction("inner"); // Output: "outer inner"

Heap

The heap is a large region of memory used for dynamic memory allocation. In JavaScript, objects are allocated in a heap which is just a name to denote a large, mostly unstructured region of memory.

Pass by Value

"Pass by value" means that a copy of the original parameter value is passed to a narrower scope. Changes made in the other scope to the parameter have no impact in the original value.
All primitive types in JavaScript are passed by value. This includes:

String
Number
Boolean
undefined
null
Symbol (introduced in ES6)
BigInt (introduced in ES2020)

let originalValue = 10;

function changeValue(value) {
    value = 20; // Changing the value inside the function
}

changeValue(originalValue);
console.log(originalValue); // Output: 10 (original value remains unchanged)

Pass by Reference

"Pass by reference" means that instead of passing a copy of the actual value as a parameter to a different scope, a reference to the original data is passed. Therefore, changes made to the parameter produce side-effects in the original object.
In JavaScript, non-primitive types are passed by reference. This includes object, arrays and functions.

let originalObject = { value: 10 };

function changeObject(obj) {
    obj.value = 20; // Changing the object's property
}

changeObject(originalObject);
console.log(originalObject.value); // Output: 20 (object is modified)

Property

A property in JavaScript is a characteristic of an object, often describing attributes associated with a data structure. Properties can be values or functions (methods). Objects in JavaScript are collections of key-value pairs, with the keys being the properties.

const objectWithProperty = {
    myProperty: "value" // Object with a property
};

console.log(objectWithProperty.myProperty); // Output: "value"

'this' Keyword

The JavaScript this keyword refers to the object it belongs to. It has different values depending on where it is used: In a method, this refers to the owner object. Alone, this refers to the global object. In a function, this refers to the global object. In an event, this refers to the element that received the event.

const object = {
    property: "value",
    method: function() {
        console.log(this.property); // 'this' refers to the object
    }
};

object.method(); // Output: "value"

'window' and 'global' Objects

In the context of browsers, the global object is window, meaning all global JavaScript objects, functions, and variables automatically become members of the window object. Global variables are properties and global functions are methods of the window object. This is not available outside of browser environments and is often used as a flag in node.js projects to flag wheter the current code is running in a browser or not.
The global object would be the closest analogous to window, but for a node.js environment. You might use global to define variables or functions that you want available accross all modules in your application, but it will lack browser-only features like methods to manipulate the DOM and properties of the current URL.

// In a browser environment
console.log(window.location.href); // Accesses the global 'window' object

// In Node.js
console.log(global.process.version); // Accesses the global 'global' object

bind

The bind() method allows you to set the this value for a function and returns a new function with the this value set to the value passed, along with any provided arguments leading the arguments list. bind() can also be used to create a new function with pre-filled arguments; this is known as partial application of a function.

// originalFunction: The function to be bound.
// thisArg: The value to be passed as `this` to the target function when the bound function is called.
// arg1, arg2, <...> : Arguments to be pre-filled in the bound function
const boundFunction = originalFunction.bind(thisArg, arg1, arg2, ...);

/* example */
function greet(greeting, punctuation) {
    console.log(greeting + ", " + this.name + punctuation);
}

const person = {
    name: "Alice"
};

const greetAlice = greet.bind(person, "Hello");
greetAlice("!"); // Output: "Hello, Alice!"

'arguments' Object

The arguments object is an array-like object accessible within functions in JavaScript, and contains the values of the arguments passed to that function. This object is useful for functions that need to handle an indeterminate number of arguments, or when you want to work with all arguments passed to the function without explicitly defining them as parameters.
Note that arguments is an 'array-like' object and is not an array: it has a length property and indexed elements, but it lacks array methods like forEach, map or reduce.

function sum() {
    let total = 0;
    for (let i = 0; i < arguments.length; i++) {
        total += arguments[i];
    }
    return total;
}

console.log(sum(1, 2, 3, 4)); // Output: 10

Destructuring Objects

One fundamental utility of objects is to structure data, i.e. to have aggregated key-value pairs (or ordered, numbered elements in the case of arrays) instead of a bunch of variables roaming around. Destructuring is the opposite process: unpacking structured key-value pairs from objects into free variable-name/variable-value ones. Some of its notable uses include extracting a subset of properties of an object and importing specific functionality from modules.

General use:

const person = {
    name: 'John Doe',
    age: 30,
    profession: 'Developer'
};

// Destructuring the object into individual variables
const { name, age, profession } = person;

console.log(name); // Output: John Doe
console.log(age); // Output: 30
console.log(profession); // Output: Developer

Using object destructuring to import a subset of functionality from a large module:

import { useState } from 'react'; // imports only the useState hook instead of the whole react package

Spread Operator

The spread operator (...) allows an iterable such as an array or string to be expanded in places where zero or more arguments (for function calls) or elements (for array literals) are expected. It can also be used to spread object properties into a new object, like when combining objects. One of the common use-cases for the spread operator is when you need to transfer the key-value pairs of an object to tag-value pairs in a React or Svelte component.

Spread operator with arrays:

const numbers = [1, 2, 3];
const moreNumbers = [4, 5, 6];

// Combining arrays using the spread operator
const combined = [...numbers, ...moreNumbers];

console.log(combined); // Output: [1, 2, 3, 4, 5, 6]

Spread operator with objects:

const personDetails = {
    name: 'John Doe',
    age: 30
};

const contactDetails = {
    email: 'john@example.com',
    phone: '1234567890'
};

// Combining objects
const fullProfile = { ...personDetails, ...contactDetails };

console.log(fullProfile);
/* Output:
{
    name: 'John Doe',
    age: 30,
    email: 'john@example.com',
    phone: '1234567890'
}
*/

Spread operator in React:

function UserProfile({ name, age, location }) {
    return (
        <div>
            <h1>{name}</h1>
            <p>Age: {age}</p>
            <p>Location: {location}</p>
        </div>
    );
}

const userInfo = {
    name: 'Alice',
    age: 30,
    location: 'Wonderland'
};

function App() {
    return (
        <div>
            {/* Using the spread operator to pass props */}
            <UserProfile {...userInfo} />
        </div>
    );
}

Arrow Function

Arrow functions are a shorter syntax for writing function expressions. They do not have their own this, do not have prototypes, cannot be used for constructors, and don't have an arguments object. Arrow functions are best suited for non-method functions (meaning, functions that are not a property of an object).

const arrowFunction = () => {
    console.log("This is an arrow function");
};

arrowFunction(); // Output: "This is an arrow function"

Anonymous Functions

Anonymous functions in JavaScript are functions that are defined without a name. They are often used as values and can be assigned to variables or passed as arguments to other functions. They are useful for creating quick, throwaway functions on the fly, and are often used as callback arguments.

setTimeout(function() {
    console.log("Anonymous function executed");
}, 1000); // An anonymous function as a callback

Object Literal

An object literal is a comma-separated list of name-value pairs wrapped in curly braces. Object literals encapsulate data, enclosing it in a tidy package. This minimizes the use of global variables which can cause problems when combining code. They are similar to what in other languages might be called 'dictionaries' or 'hashes'.

const objectLiteral = {
    property1: "value1",
    property2: "value2"
};

console.log(objectLiteral.property1); // Output: "value1"

Object Constructor

An object constructor in JavaScript is a function that defines a type of object. It can be used with the new keyword to create new objects of that type. The constructor is a template for creating similar objects with the same properties and methods.

function Car(make, model) {
    this.make = make;
    this.model = model;
}

const myCar = new Car("Toyota", "Corolla");
console.log(myCar.make); // Output: "Toyota"

Prototype Chain

The prototype chain is a feature in JavaScript that is used to build new types of objects based on existing ones. It is a mechanism for inheriting properties and methods from other objects.
When a property is accessed from an object, JavaScript will traverse up the prototype chain until it finds the property or reaches the end of the chain. The end of the chain, that is, the very first inheritor, is the null prototype.
Every object can have exactly one prototype object, which means that multiple inheritance is not supported by either JavaScript or TypeScript.
Prototype constructors are not really used in everyday JavaScript development, however, it is the basis for the class keyword and essential knowledge if you want to get deeper into the language.

const animal = {
  dna: 'ATCG',
};

const cat = {
  saying: 'meow',
}

Object.setPrototypeOf(cat, animal);

Object.getPrototypeOf(cat) === animal; // true

Object.getPrototypeOf(animal) === Object.prototype; // true

Object.getPrototypeOf(Object.prototype) === null; // true

Inheritance

Inheritance in JavaScript is a mechanism where one object can inherit the properties and methods of another. This is often used to create a hierarchy of types and share code. JavaScript implements inheritance through the prototype chain.

// Class-based inheritance
class Animal {
    speak() {
        return "I'm an animal";
    }
}

class Dog extends Animal {
    speak() {
        return "Woof! Woof!";
    }
}

const myDog = new Dog();
console.log(myDog.speak()); // Output: "Woof! Woof!"

// Prototype-based inheritance
function Animal() {}
Animal.prototype.speak = function() {
    return "I'm an animal";
};

function Dog() {}
Dog.prototype = Object.create(Animal.prototype);
Dog.prototype.speak = function() {
    return "Woof! Woof!";
};

const myDog2 = new Dog();
console.log(myDog2.speak()); // Output: "Woof! Woof!"

Multiple Inheritance

Multiple inheritance is a feature in some object-oriented programming languages where a class can inherit characteristics and behaviors from more than one parent class. This concept allows a derived class to combine and exhibit the properties, methods, and behaviors of multiple base classes, potentially leading to greater functionality and code reuse.
However, multiple inheritance can also introduce complexity and hard to debug errors, notably with the "diamond problem" or "Deadly Diamond of Death", an ambiguity that arises when two classes B and C inherit from A, and class D inherits from both B and C, i.e. when a class inherits the same property from multiple different parent classes.
Some OOP languages like Java, C# and TypeScript don't support multiple inheritance, but implement strategies to achieve similar polymorphism, like for example interfaces.

Polymorphism

'Polymorphism' means 'multiple forms', and class polymorphism allows objects of different classes to be treated as objects of a common super class. It enables a single interface to represent different underlying types, allowing code to be more reusable.
For example, let's think of a website that has a 'Media' object; 'Media' can be browsed, receive comments and etc. 'Song', 'Book' and 'Movie' are child classes of 'Media', each of them will be played or rendered in the browser according to its own specific implementation but all of them will be able to be browsed, receive comments and etc; 'Media' here is the polymorphic clas while 'Song', 'Book' and 'Movie' are the specific ones.
Polymorphism for a class can be achieved in different ways. Multiple inheritance is one of these ways, but let's treat it as a non-option for the JavaScript world and focus instead on three other strategies: interfaces, composition and mixins.

Interfaces

An interface is basically a contract for classes. It specifies a set of methods and properties that a class must implement, without providing the implementation details. Interfaces allow different classes to be treated uniformaly based on a shared interface, making the code more flexible and extensible. See below an example in TypeScript, and note that JavaScript does not support interfaces natively:

/* typescript code */
// Interface for Address
interface Address {
    street: string;
    city: string;
    zipCode: number;
}

// Interface for User
interface User {
    name: string;
    age: number;
    address: Address; // Embedding the Address interface
    greet(): string;
}

// Implementation
const user: User = {
    name: "Alice",
    age: 30,
    address: {
        street: "123 Maple St",
        city: "Anytown",
        zipCode: 12345
    },
    greet() {
        return `Hello, my name is ${this.name} and I live at ${this.address.street}, ${this.address.city}.`;
    }
};

Composition

Composition involves creating objects made of other objects rather than inheriting from parent objects. Composition is based on a "has-a" relationship rather than the "is-a" relationship of classical inheritance. For instance, instead of saying "a car is a vehicle," we say "a car has an engine."
Composition provides greater flexibility and easier maintainability. Changes in one part of the system are less likely to impact others, and behavior can be added or removed at runtime.

function createBird(name) {
    return {
        name,
        fly() {
            console.log(`${this.name} is flying.`);
        }
    };
}

function createSwimmer(name) {
    return {
        name,
        swim() {
            console.log(`${this.name} is swimming.`);
        }
    };
}

const duck = Object.assign({}, createBird('Ducky'), createSwimmer('Ducky'));
duck.fly(); // Ducky is flying.
duck.swim(); // Ducky is swimming.

Mixins and compositions are different: mixins are closer to inheritance where functionalities are added directly to the prototype chain, while composition is about aggregating functionalities by having instances of other objects. For example, a car's replaceable-whell system would be a composition, while its ability to ride would be a mixin.

Mixins

A mixin is a function that accepts a target object or class and adds functionality to it. Mixins provide a means to reuse a set of functionalities across multiple classes or objects.

const flying = {
    fly() {
        console.log(`${this.name} is flying.`);
    }
};

const swimming = {
    swim() {
        console.log(`${this.name} is swimming.`);
    }
};

function Duck(name) {
    this.name = name;
}

Object.assign(Duck.prototype, flying, swimming);

const duck = new Duck('Ducky');
duck.fly(); // Ducky is flying.
duck.swim(); // Ducky is swimming.

Instance Method

An instance method is a function defined within a class that operates on the instances of that class, meaning it can be called on individual objects created from the class and usually accesses or modifies the data of those specific instances.

class MyClass {
    instanceMethod() {
        return "This is an instance method";
    }
}

const myInstance = new MyClass();
console.log(myInstance.instanceMethod()); // Output: "This is an instance method"

Static Method

Static methods are defined on the class itself, and not on the prototype. That means they are called on the class, not on instances of the class. They are typically used for utility functions that don't require a specific object context.

class MyClass {
    static staticMethod() {
        return "This is a static method";
    }
}

console.log(MyClass.staticMethod()); // Output: "This is a static method"

WeakMap & WeakSet

WeakMap and WeakSet are collections in JavaScript that only hold "weak" references to their elements. This means that if there are no other references to the stored object or value, they can be garbage collected. This is unlike regular Maps and Sets which hold strong references to their contents.

// Regular Map
let regularMap = new Map();
let objKey = { id: 1 };
regularMap.set(objKey, "Regular Map Value");
console.log(regularMap.get(objKey)); // Output: "Regular Map Value"

// WeakMap
let weakMap = new WeakMap();
let objWeakKey = { id: 2 };
weakMap.set(objWeakKey, "WeakMap Value");
console.log(weakMap.get(objWeakKey)); // Output: "WeakMap Value"
// WeakMap keys are weakly held, allowing for garbage collection if there's no other reference to the key object.

// Regular Set
let regularSet = new Set();
regularSet.add(objKey);
console.log(regularSet.has(objKey)); // Output: true

// WeakSet
let weakSet = new WeakSet();
weakSet.add(objWeakKey);
console.log(weakSet.has(objWeakKey)); // Output: true
// WeakSet elements are weakly held, similar to WeakMap.

Event Loop

The event loop is an architectural pattern used in JavaScript that continually checks the message queue for ad hoc messages (an event loop). When it finds one, it removes it from the queue and executes its corresponding callback. This mechanism allows JavaScript to perform non-blocking operations, despite being single-threaded.

Synchronous

Synchronous operations in JavaScript are those that block other operations from running until they complete. Synchronous code is executed in sequence – each statement waits for the previous statement to finish before executing.

Asynchronous

Asynchronous operations in JavaScript allow the program to be executed immediately where the synchronous operation will block further execution of the remaining code until it completes. This is essential for operations that rely on external operations or timers.

Thread Pool

A thread pool is a collection of threads that can be used to perform a number of tasks in the background. In JavaScript, particularly in environments like Node.js, a thread pool can handle tasks like file I/O, networking, or any other task that is I/O-bound asynchronously.

Single Threaded

JavaScript is traditionally single-threaded, meaning it processes one command at a time in a single sequence. This is important for understanding how JavaScript handles asynchronous operations, event handling, and concurrency.

Callback

A callback is a function passed into another function as an argument to be executed later. Callbacks are used to continue code execution after an asynchronous operation has completed.

function processData(data, callback) {
    // Process the data (simulated with a timeout)
    setTimeout(() => {
        callback('Processed: ' + data);
    }, 1000);
}

processData('Hello', result => {
    console.log(result); // Output after 1 second: "Processed: Hello"
});
// A callback function is passed and executed after data processing.

Promise

A promise in JavaScript represents the eventual completion (or failure) of an asynchronous operation and its resulting value. Promises provide a cleaner, more robust way of handling asynchronous operations compared to traditional callback functions.

let promise = new Promise((resolve, reject) => {
    // Asynchronous operation
    let success = true; // Simulate success or failure
    if (success) {
        resolve('Operation succeeded');
    } else {
        reject('Operation failed');
    }
});

// promise represents an asynchronous operation that will eventually complete.

Resolve

In the context of Promises, resolve is a method that, when called, changes the status of the promise from "pending" to "fulfilled" and returns a value with which the promise was resolved.

let resolvedPromise = new Promise(resolve => {
    resolve('Resolved value');
});

resolvedPromise.then(value => {
    console.log(value); // Output: "Resolved value"
});
// 'resolve' is used to successfully complete a promise.

Reject

Reject is a method associated with promises. When reject is called, the promise's status changes from "pending" to "rejected," indicating that the operation failed and typically returns a reason or error as to why the promise was rejected.

let rejectedPromise = new Promise((resolve, reject) => {
    reject('Rejected value');
});

rejectedPromise.catch(reason => {
    console.log(reason); // Output: "Rejected value"
});
// 'reject' is used to fail a promise.

Then/Catch

In promises, then is used to schedule a callback to be executed when the promise is successfully resolved. catch is used to schedule a callback to be executed when the promise is rejected. They are methods for handling the fulfillment and rejection of a promise, respectively.

let asyncOperation = new Promise((resolve, reject) => {
    let success = true;
    if (success) {
        resolve('Success');
    } else {
        reject('Error');
    }
});

asyncOperation.then(result => {
    console.log(result); // Runs if promise resolved: "Success"
}).catch(error => {
    console.log(error); // Runs if promise rejected
});
// 'then' and 'catch' handle resolved and rejected promises, respectively.

Async/Await

async/await is syntactic sugar built on top of promises in JavaScript that allows you to write asynchronous code that looks and behaves a bit more like synchronous code, halting the execution of the programing until the promise of the asynchronous statement marked with await is solved or rejected. Note that the function must be declared as an async function in order to support await statements.

async function fetchData() {
    try {
        let response = await fetch('https://api.example.com/data');
        let data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error fetching data:', error);
    }
}
// 'async' function returns a promise, and 'await' waits for the promise to settle.

ES Modules

ES Modules are a module system in JavaScript that allows you to modularize your code into separate files. This system provides a standard way to import and export values between files, making code organization and reuse more straightforward.

Default & Named Import/Export

In ES Modules, a default export is a single value or entity that is exported from the module. Named exports allow multiple named values to be exported from the module. Import statements can correspondingly import these default or named exports into the current file.

// In a module file (module.js)
export default function defaultFunction() { /* ... */ }
export function namedFunction() { /* ... */ }
export const namedConstant = 'value';

// In another file
import defaultFunction, { namedFunction, namedConstant } from './module.js';
// Default imports are imported without braces, named imports with braces.

package.json

package.json is a file used in Node.js applications. It holds metadata relevant to the project and it is used for managing the project's dependencies, scripts, version and a whole lot more.

DOM (Document Object Model)

The DOM is a programming interface for HTML and XML documents. It represents the page so that programs can change the document structure, style, and content. The DOM represents the document as nodes and objects; that way, programming languages can interact with the page.

Document

In the context of the DOM, the document object is the root node of the HTML document and the entry point to the content of the page. It represents the whole web page and can be used to access and manipulate the content, structure, and styles of the web page.

Components

Components are reusable, encapsulated elements that can be used to build dynamic and interactive web applications. They are a fundamental concept in many JavaScript frameworks and libraries, helping developers manage and reuse code efficiently.

Data Binding

Data binding is a technique for synchronizing data between a source (like a JavaScript object) and a destination (like HTML UI elements). It simplifies how you display and interact with data in applications, particularly in frameworks like Angular, Vue, or React.

Module Bundling

Module bundling is the process of taking modules written as separate files and combining them into a single file. This single file can then be loaded onto a web page. Tools like Webpack and Rollup are commonly used for module bundling.

Network Waterfall

Network waterfall refers to the sequence of network requests and how they are processed by the browser. It's a visualization found in browser's development tools that shows the order, timing, and dependencies of network requests.

Dynamic Imports

Dynamic imports in JavaScript are a way to load modules asynchronously and on-demand. This can improve performance by splitting code into smaller chunks and loading them only when needed, rather than loading all scripts at the start.

async function loadModule() {
    let module = await import('./module.js');
    module.defaultFunction();
    module.namedFunction();
}
// Dynamic import() returns a promise for the module, allowing you to import modules dynamically.

Typescript

Typescript is an open-source language that transpiles into JavaScript. It's meant to be "strictly a superset" (meaning that all valid JavaScript code should be valid TypeScript code) and its reason for existence is to address perceived JavaScript pitfalls such as a hacky OOP implementation and unintuitive type system in javascript which can lead to unexpected behavior and hard to debug errors. TypeScript, among others, adds strict types to JavaScript, has a more traditional syntax for OOP and offers strict null checking to avoid unintentional setting of null or undefined.

JSDoc

JSDoc is a popular documentation syntax for JavaScript, used to annotate and describe the structure of JavaScript code. It's essentially a way to add comments to the code that can be easily understood and parsed by documentation generators to produce nicely formatted documentation pages. Some people claim it's a good lightweight alternative to TypeScript for libraries and smaller projects.

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
    this.title = title;
    this.author = author;
}

Test Driven Development

Test-Driven Development (or TDD) is a software development methodology that involves writing tests first and implementing features second. It is particularly effective when building on top of large codebases, once the product is somewhat established and the development directions are more obvious and less flexible.
Tests have three main categories: Unit Tests, Functional/Integration Tests and End-to-End(E2E) Tests.

Unit Tests

Unit tests are the smallest and most foundational type of software testing. They focus on testing individual components or functions in isolation from the rest of the application. The goal is to ensure that each component functions correctly as a standalone unit. Testing a function that takes an input, makes calculations and produces an output is an example of unit testing.
They are often the quickest to execute and won't involve external modules or systems (like databases or APIs).
Popular libraries for unit testing include Mocha and Jest, with Vitest recently gaining ground.

Functional/Integration Tests

Functional and integration tests are mid-level tests that focus on the interaction between different parts of the application. Integration tests check how different modules work together, while functional tests focus on the business requirements of the application. Testing the interaction of an user auth service with the database is an example of functional/integration test.
Their main reason of existence is to ensure different parts of the application work together as expected. It can involve testing the interaction of two or more modules, APIs and database interactions.
Mocha, Jest and Vitest can also be used for integration tests. Other famous libraries include Cypress (more known for E2E tests, can be used for integration tests especially in web apps) and Supertest, which is mostly known for testing HTTP interfaces.

End-to-End (E2E) Tests

E2E tests simulate real user scenarios from start to finish. They are high-level tests that evaluate the entire application's flow and are typically executed in an environment that mimics the production environment as much as possible.
These are the most complex and time-consuming tests and usually should only be executed once all other tests have passed. Testing the entire process of an user signing up, logging in, interacting with the app and then logging out is an example of E2E tests.
Cypress, PhantomJS (deprecated in 2018), Playwright (the de-facto successor of PhantomJS) and Selenium are examples of libraries often used in E2E tests.
Playwright and Selenium have notable differences:

Playwright interacts with browser engines and works as a headless browser and has an uniform API even when representing different browsers.
Selenium uses the WebDriver protocol to communicate with different browsers and will often involve the browser itself. While Playwright is considered lighter and faster than Selenium, Selenium is still considered more adequate to test apps that should focus on older browser support, and is one of the de-facto tools to automate browser actions programmatically.

Glossary Index

Anonymous Functions
'arguments' Object
Arrow Function
Asynchronous
Babel
Bind
Callback
Class
Closures
Components
Composition
Data Binding
Default & Named Import/Export
Destructuring Objects
DOM (Document Object Model)
Document
Dynamic Imports
ECMAScript
ECMAScript2015/ES6
End-to-End (E2E) Tests
ES Modules
Event Loop
Event-Driven Architecture (EDA)
Function Expression
Functional Programming Paradigm
Functional/Integration Tests
Global Scope
Heap
Higher Order Functions
Hoisting
Inheritance
Instance Method
Interfaces
JSDoc
Just-In-Time Compilation
'map' Functions
Mixins
Module Bundling
Multiple Inheritance
Network Waterfall
Node.js
null, undefined
Object
Object Constructor
Object Literal
Object Oriented Programming Paradigm
Package.json
Pass by Reference
Pass by Value
Polymorphism
Promise
Prototype Chain
'reduce' Functions
Reject
Resolve
Single Threaded
Spread Operator
Static Method
Synchronous
Then/Catch
Thread Pool
TypeScript
Unit Tests
'use strict' Directive
V8 Engine
WASM (WebAssembly)
WeakMap & WeakSet
Test Driven Development
this Keyword
window and global Objects

Kitty Terminal Basics + Cheatsheet

Otavio Monteagudo — Tue, 14 Nov 2023 21:48:37 +0000

Intro

Kitty is a terminal emulator for UNIX-based systems that distinguishes itself by leveraging the power of the GPU to deliver faster and smoother screen rendering, making it a faster alternative to many other options. Kitty's key strengths are its low latency, support for modern features like image and Unicode rendering, and its ability to handle multiple windows and tabs efficiently.
Kitty is available to install both from brew and apt package managers.
brew install kitty
or
sudo apt-get install kitty

are enough to get you running with it.

Kitty Terminal Emulator Main Shortcuts

Tab Management

New tab: Ctrl + Shift + T
Close tab: Ctrl + Shift + Q
Next tab: Ctrl + Shift + Right
Previous tab: Ctrl + Shift + Left
Move tab forward: Ctrl + Shift + .
Move tab backward: Ctrl + Shift + ,

Layout Management

Window split: Ctrl + Shift + Enter
Close window: Ctrl + Shift + W
Next window: Ctrl + Tab
Previous window: Ctrl + Shift + Tab
Move window forward: Ctrl + Shift + .
Move window backward: Ctrl + Shift + ,

Font Adjustments

Increase font size: Ctrl + Shift + '+'
Decrease font size: Ctrl + Shift + '-'
Restore font size to original: Ctrl + Shift + Backspace

Clipboard Operations

Copy to clipboard: Ctrl + Shift + C
Paste from clipboard: Ctrl + Shift + V

Searching within the Terminal

Start search: Ctrl + Shift + F
Find next: Ctrl + Shift + N
Find previous: Ctrl + Shift + P

Miscellaneous

Open link: Ctrl + Click
Reload configuration file: Ctrl + Shift + F5
Fullscreen toggle: F11

Customizing Kitty

Even though Kitty is much more lightweight than many of its alternatives, it still has more customization options than most of us will ever fiddle with. You can check these out with nano ~/.config/kitty/kitty.conf or create it if it doesn't exist. The default configuration file has plenty of comments explaining the different options you have.

For instance, if I want to place my tabs at the top of the terminal screen (pretty much like every other terminal) instead of kitty's default bottom, and I want my tab separators to look like ones from a physical file, and I want to use the Mac ripoff of Comic Sans for the terminal font, I'll add this to my kitty.conf:

tab_bar_edge   top
tab_bar_style  slant
font_family    Chalkboard

Don't worry, if you are on Linux you can sudo apt-get install fonts-comic-neue. But I'm joking, this kind of font looks awful on a terminal, I've tried. However, the Ubuntu Mono font makes a mac look like a friendlier environment.

But don't worry: you can still have a more joyful web-browsing experience by rendering Comic Sans everywhere.

Golang Environment: GOPATH vs go.mod

Otavio Monteagudo — Thu, 25 May 2023 16:26:56 +0000

Intro

In this article, we delve into the contrasts between the traditional GOPATH environment and the go.mod based environment for Go programming, as well as their similarities and differences. This distinction has significant implications for how Go developers structure and manage their project workspaces and dependencies.

We start by understanding the GOPATH environment, its organization and its structure; then we explore the go.mod approach, adopted to provide a modular and flexible way of organizing Go projects. Understanding these two environments and the transition from GOPATH to go.mod provides valuable insights into Go's evolving ecosystem.

Single workspace: the GOPATH environment variable

The Go programming language initially delimited a scope for the location of dependencies and custom projects inside a filesystem, defined by the GOPATH environment variable. This means that Go would look for binaries and source code only under the directory pointed by this variable.

The GOPATH variable by default would point to a /go folder defined directly under the user home directory path (~/ in unix-based or %HOMEPATH% on windows-based systems) .GOPATH could also be set to custom paths, and more than one GOPATH could be defined for a single user, which was discouraged due to added difficulties in dependency management.

There are three notable directories under GOPATH: src, pkg, and bin. The src directory holds the source code of both your projects and installed dependencies. When you execute a command such as go get github.com/user/repo, the Go tool fetches the module from the specified location and places it into the src directory under the GOPATH, with a path named after the resource's URL.

For instance, if you were to download a library from a repository owned by "someuser" on GitHub, the library's source code would reside in /home/user/go/src/github.com/someuser/library.

The pkg directory contains compiled package objects (.a files) that your code depends on. When a package is built, the resulting file is placed in the pkg directory. The compiled package files help in reducing compilation time as they can be imported directly in other packages without the need for recompilation.

The bin directory holds the binary executables of your applications. When you build an executable program, the resulting binary file is placed in the bin directory.

File tree for a GOPATH workspace

This assumes the default path for GOPATH:

/home/user/go/         <--- This is your GOPATH
├── bin/
├── pkg/
│   └── linux_amd64/
│       └── github.com/
│           └── someuser/
│               └── somelib.a    <--- Compiled dependency package
└── src/
    ├── github.com/
    │   └── someuser/
    │       └── somelib/         <--- Dependency's source code
    │           └── somelib.go
    └── myapp/                   <--- Your project
        └── main.go

In this structure:

The src directory contains the source code of your projects and the installed dependencies.
The pkg directory contains compiled versions of the packages that your code depends on.
The bin directory contains the compiled binary executables.

The single workspace structure defined by GOPATH means that all your Go code and its dependencies share a single common space. It's worth noting, however, that this approach has evolved with the introduction of Go modules in Go 1.11, mainly to address the lack of a proper versioning system for dependencies and flexibility to store projects under a filesystem.

Modular approach: the `go.mod` file

Starting from go 1.11 (August 2018), the modular option became available as an alternative to a workspace defined by GOPATH. This is delimited by the presence of a go.mod file and also usually a go.sum file, which will be generated once any operation concerning externally hosted packages is executed (like go get <package>).

Before continuing, however, it is important to clarify what is a package and how a module differs from a package:

Packages

A package in Go is the smallest unit of code distribution. They are defined by a directory containing one or more .go source files with the package name declared on top of it. All files in the directory must declare the same package name.

Packages allow code to be organized and reused. They provide a way of encapsulating related code into a single unit, which can be imported and used by other packages. The Go standard library, for example, consists of many packages such as fmt, os, net, etc.

There is a single special package name, main. This package contains the main() function which is the entrypoint for a project. Every project meant to eventually become an executable must contain the main() function, and therefore the main package.

It is a good practice to declare the main package file(s) at the project's root folder and other packages in their own directories.

Modules

A module is a collection of related Go packages that are versioned together as a single unit. Modules record precise dependency requirements and create reproducible builds. A Go module is defined by a go.mod file that resides at the root of the module's directory hierarchy. This file defines the module path, which is the import path prefix for all packages within the module, and it specifies the dependencies of the module, including the required versions of other modules.

They allow for versioning and releasing a set of packages together, and they also make dependency version information explicit and easier to manage. Note that, though versioned, dependencies will still be downloaded under src defined in the GOPATH scope by default.

To summarize, while a package is a way of structuring and reusing code within a Go program, a module is a versioned collection of packages that also handles dependency management. This allows each Go project to have its own isolated and reproducible build environment.

Naming conventions for modules

In Go, module names are used system-wide and therefore should be as specific as possible, especially if you plan on distributing the module to other developers. The module name is specified in the go.mod file, which acts as the module's manifest and is located at the root of the module's directory hierarchy.

Here are some guidelines for module naming in Go:

Module Path: The module path should be a globally unique identifier for the module. It typically takes the form of an internet domain name in reverse order, followed by the module name. For example, github.com/littlejohnny65/example-module. The module path is used as an import path when importing packages from the module.
Module Name: The module name is the last component of the module path. It should be short, descriptive, and adhere to Go's naming conventions. It is recommended to use lowercase letters with no underscores or mixedCaps. For example, examplemodule.
Versioning: The module name itself does not include version information. The version of a module is specified separately in the go.mod file using a module version identifier, such as v1.2.3. The combination of the module path and the version identifier uniquely identifies a specific version of the module.

It's important to choose meaningful and descriptive names for modules, as they are publicly identifiable and may be used as dependencies in other projects. Clear and consistent naming conventions help in understanding the purpose and context of a module.

The go.sum file

When you run a command like go get github.com/user/repo, the Go tooling will fetch the module from that location. This makes it possible to host Go code on any server that supports version control systems like Git, Mercurial, Bazaar, or Subversion.
Considering Go's very flexible and direct approach to download dependencies from external repositories, the solution adopted in order to ensure the dependency's integrity is to create a local file to store a checksum for each dependency. This is what guarantees that the dependency installed is the exact same.

The checksum file is generated by the local Go tooling and should be pushed to external environments such as servers and Dockerfiles if you want to make sure the dependencies will be exactly the same as in your local environment.

File tree for a modular Go project

/home/user/projects/
└── myapp/                         # Your project
    ├── custom/                   # Custom packages
       └── ...                          # .go files defining functionality
    ├── go.mod                     # go.mod file defining dependencies & versions
    ├── go.sum                     # go.sum file that verifies dependency integrity
    └── main.go                    # Entrypoint

File tree for the module cache, assuming the default GOPATH path:

/home/user/go/        # This is your GOPATH
└── pkg/
    └── mod/
        └── cache/
            └── download/
                └── github.com/
                    └── someuser/
                        └── somelib/     # Source code of the dependency
                            └── somelib.go

In this structure:

Your project can live anywhere in your file system. It contains a go.mod file and a go.sum file.
The go.mod file lists the specific versions of the dependencies that your project uses.
The go.sum file provides checksums for the exact contents of each dependency at the time it is added to your module.
The dependencies are stored in the Go module cache, which is shared across all projects on your system.

Module CLI commands

There are several convenient commands available for working with modular Go projects:

go mod init: Initializes a new module in the current directory. It creates a go.mod file that defines the module's path and sets it up for dependency management.
go mod tidy: Adds missing and removes unused modules and dependencies from the go.mod file. It ensures that the go.mod file accurately reflects the required dependencies of your project.
go mod download: Downloads the dependencies defined in the go.mod file and stores them in the module cache. It fetches the specific versions of the dependencies needed for your project.
go mod vendor: Copies the dependencies into a vendor directory within your project. This command is useful when you want to create a self-contained project that includes all its dependencies.
go mod verify: Verifies that the dependencies in the module cache match the expected cryptographic checksums specified in the go.sum file. It ensures the integrity and authenticity of the downloaded dependencies.
go mod graph: Prints the module dependency graph, showing the relationships between modules and their versions. It can be useful for understanding the overall structure of your project's dependencies.
go mod edit: Provides a range of subcommands for making manual edits to the go.mod file. It allows you to add, remove, or update module requirements, replace modules, and more.

These are just a few of the commonly used go mod commands. You can explore more commands and their options by running go help mod or referring to the official Go documentation on modules.

Wrapping up

The modular approach is not radically different from nor incompatible with the single workspace, but it builds on it to bring more flexibility and manageability; modules allow you to have a project wherever you want to in your filesystem and also to have namespaced dependencies for better stability, but it still uses GOPATH as the default location to store dependencies and executables.

In conclusion, the modular environment provided by go.mod is a powerful tool in the Go developer's toolbox, complementing and extending the functionality of the traditional GOPATH environment. It signals Go's adaptation to the increasing complexity and scale of modern software development, demonstrating the language's ongoing evolution to meet the changing needs of its users. As we move forward, it's exciting to imagine what future developments in Go's ecosystem will bring.

Euclidean Algorithm: Breakdown + Golang implementations

Otavio Monteagudo — Sat, 06 May 2023 07:22:52 +0000

Intro

The Euclidean Algorithm is a well-known and efficient method for finding the greatest common divisor (GCD) of two integers. The GCD is the largest number that can divide both integers without leaving a remainder. The algorithm is named after the ancient Greek mathematician Euclid, who presented it in his book "Elements" around 300 BCE.

Some of its uses are solving Diophantine equations, tackling the shortest-vector problem which is the foundation of lattice-based cryptography and also to find common patterns of pixels in images, which among other things is applied to optimize rendering processes and detect different objects in images.

Here's a step-by-step explanation of the Euclidean Algorithm:

Start with two positive integers, a and b, where a >= b. If a < b, simply swap their values. Note that this is meant for a convenient mathematical demonstration, as the implementation also works for a < b.
Divide a by b and find the remainder, r (use the modulo operation, represented as a % b). If r is 0, the GCD is b, and the algorithm terminates.
If r is not 0, set a to b and b to r. Then, repeat step 2.

The algorithm continues to iterate until the remainder is 0. At that point, the last non-zero remainder is the GCD of the original two numbers. The Euclidean Algorithm works because the GCD of two numbers remains unchanged when the larger number is replaced by its remainder when divided by the smaller number.

Here's an example to illustrate the algorithm:

Let's find the GCD of 30 and 9:

a = 30, b = 9
Calculate the remainder: r = a % b = 30 % 9 = 3 (since 3 is not 0, continue to step 3)
Update the values: a = 9, b = 3
Calculate the new remainder: r = a % b = 9 % 3 = 0 (r is now 0)
The GCD of 30 and 9 is 3.

Why does it work?

The greatest common divisor of two integers is the largest positive integer that divides both of them without leaving a remainder; so the algorithm is based on the following key property:

If a and b are two integers, then the GCD of a and b is the same as the GCD of b and a % b, where % represents the modulo operator (the remainder after division).

Mathematically, the key property of the algorithm can be justified using the division algorithm:

Let a and b be two positive integers, such that a >= b. We can write the division algorithm as:

a = bq + r, where q is the quotient and r is the remainder.

Now, let d be a common divisor of a and b. Then, a = d * m1 and b = d * m2 for some integers m1 and m2. We can rewrite the division algorithm as:

d * m1 = (d * m2) * q + r.

Rearranging the equation, we get:

r = d * (m1 - m2 * q).

Since d is a factor of both a and b, and r can also be written as a multiple of d, we can conclude that d is also a divisor of r. This means that the GCD of a and b is also a divisor of r. So, we can replace b with r and keep finding the GCD using this algorithm until b becomes 0.

The Euclidean Algorithm is particularly useful due to its efficiency and simplicity, making it easy to implement in computer algorithms and programming languages.

Let's see some different ways to implement it in Go:

Recursive Implementation

This implementation of the Euclidean Algorithm in Golang is a recursive version that finds the GCD of two integers. Let's go through it step by step:

The function is defined as GCD(a, b int) int. It takes two integer inputs, a and b, and returns an integer output.
The base case of the recursion is checked with if b == 0. If b is 0, the function returns the value of a as the GCD.
If b is not 0, a temporary variable tmp is created and assigned the value of a. This temporary variable is used to store the value of a before updating its value in the next step.
The values of a and b are updated as follows:
- a is assigned the current value of b.
- b is assigned the value of the remainder when tmp (the previous value of a) is divided by the new value of a (which was b before the update).
The function calls itself recursively with the updated values of a and b as input, return GCD(a, b).

The algorithm continues to call itself recursively until the base case is reached, i.e., b becomes 0. At this point, the function returns the GCD, which is the value of a.

// Recursive approach:
func GCD(a, b int) int {
    if b == 0 {
        return a
    }
    tmp := a
    a = b
    b = tmp % a
    return GCD(a, b)
}

For example, let's say we want to find the GCD of 56 and 48:

First call: GCD(56, 48)
- Since b (48) is not 0, update a and b:
  - a becomes 48
  - b becomes 56 % 48 = 8
- The function calls itself with the new values: GCD(48, 8)
Second call: GCD(48, 8)
- Since b (8) is not 0, update a and b:
  - a becomes 8
  - b becomes 48 % 8 = 0
- The function calls itself with the new values: GCD(8, 0)
Third call: GCD(8, 0)
- Now, b (0) is 0, so the function returns a (8) as the GCD.

Iterative Implementation

This implementation of the Euclidean Algorithm in Golang is an iterative version using a loop to find the GCD of two integers. Let's go through the code step by step:

The function is defined as GCD(a, b int) int. It takes two integer inputs, a and b, and returns an integer output.
A loop is used to iterate as long as b is not equal to 0. The loop condition is b != 0; note that this for loop construction in Go is essentially a while loop in many other languages.
Inside the loop, the values of a and b are updated simultaneously using a tuple assignment: a, b = b, a%b. This line does the following:
- a is assigned the current value of b.
- b is assigned the value of the remainder when a is divided by b.
When the loop exits (i.e., b becomes 0), the value of a is returned as the GCD.

The algorithm iterates until the remainder (b) is 0, at which point the GCD is the last non-zero remainder, which is the value of a.

func GCD(a, b int) int {
    for b != 0 {
        a, b = b, a%b
    }
    return a
}

For example, let's say we want to find the GCD of 100 and 64:

Initialize a as 100 and b as 64. Check the loop condition: b (64) is not 0.
Inside the loop, update a and b:
- a becomes 64
- b becomes 100 % 64 = 36 Check the loop condition again: b (36) is not 0.
Inside the loop, update a and b:
- a becomes 36
- b becomes 64 % 36 = 28 Check the loop condition again: b (28) is not 0.
Inside the loop, update a and b:
- a becomes 28
- b becomes 36 % 28 = 8 Check the loop condition again: b (8) is not 0.
Inside the loop, update a and b:
- a becomes 8
- b becomes 28 % 8 = 4 Check the loop condition again: b (4) is not 0.
Inside the loop, update a and b:
- a becomes 4
- b becomes 8 % 4 = 0 Check the loop condition again: Now, b (0) is 0, so the loop exits.
The function returns the value of a (4) as the GCD.

Testing

These tests were created by Jon Calhoun in his free Go Algorithms course. Assuming you defined your GCD function in a file named gcd.go, place these tests in a file named gcd_test.go. Read below how the tests will work:

The function TestGCD is defined, taking a single parameter t *testing.T. The *testing.T is a pointer to a testing.T object that provides methods for reporting test failures and logging additional information.
An array of anonymous structs is defined, called tests. Each struct has three fields: a, b, and want. These structs represent test cases, where a and b are input values for the GCD function, and want is the expected result (correct GCD).
Several test cases are defined in the tests array, covering different scenarios.
A for loop iterates through the tests array. In each iteration, a single test case (struct) is assigned to the variable tc.
The t.Run function is called to run a subtest for the current test case. The first argument is a formatted string that describes the test case (using the input values tc.a and tc.b). The second argument is an anonymous function that takes a *testing.T parameter, similar to the main test function.
Inside the subtest function, the GCD function is called with the input values tc.a and tc.b, and the result is assigned to the got variable.
The got result is compared to the expected result tc.want. If they are not equal, the t.Fatalf function is called to report the test failure and provide an error message with the incorrect result and the expected result.

This test function helps ensure that the GCD function works correctly for various input values and edge cases. Running this test function with the go test command will execute all the test cases and report any failures, which can help identify potential issues with the GCD function implementation.


import (
    "fmt"
    "testing"
)

func TestGCD(t *testing.T) {
    tests := []struct {
        a, b int
        want int
    }{
        {10, 5, 5},
        {25, 5, 5},
        {30, 15, 15},
        {30, 9, 3},
        {100, 9, 1},
        {
            2 * 2 * 3 * 3 * 5,
            2 * 3 * 5 * 7 * 13,
            2 * 3 * 5,
        }, {
            2 * 2 * 3 * 3 * 13,
            2 * 3 * 5 * 7 * 13,
            2 * 3 * 13,
        }, {
            2 * 3 * 5 * 7 * 11 * 13 * 17 * 19,
            3 * 3 * 7 * 7 * 11 * 11 * 17 * 17,
            3 * 7 * 11 * 17,
        },
    }
    for _, tc := range tests {
        t.Run(fmt.Sprintf("(%v,%v)", tc.a, tc.b), func(t *testing.T) {
            got := GCD(tc.a, tc.b)
            if got != tc.want {
                t.Fatalf("GCD() = %v; want %v", got, tc.want)
            }
        })
    }
}

Run the tests, creating different cases as you wish:

go test -v # verbose flag

Conclusion

Hope you had a good time understanding the Euclidean algorithm and its implementation in Go. If you are interested in how these clever tricks work, take a look at the field of Number Theory in mathematics, which is particularly focused on the properties of integers, particularly involving prime numbers.

DEV Community: Otavio Monteagudo

SASS / SCSS in a Nutshell

SASS

SASS Features

SASS Variables

SASS Nesting

SASS Mixins

X.7.4.1 Mixin Parameters

X.7.4.2 Mixins Default Parameters

SASS Extensions and Placeholders

SASS Control Directives

SASS Imports & Partials

Create Custom Keyboard Shortcuts on your Linux Machine

Intro

Linux GUIs

Defining Keybindings for Commands

Defining Keybindings for Chains of Commands

Solution 1: Wrapping Command in a Shell Command

Solution 2: Create a Script File and make it Executable

Conclusion

Byte-Pair Tokenization: The Basic Principle Behind Large Language Models

Intro

1.0 N-Gram Language Models

1.1 How do N-Grams Models Assign Probability?

2.0 Tokenization

2.1 Whitespace Tokenization

2.2 Affix Tokenization

2.3 Byte-Pair Encoding Tokenization

The Byte-Pair Encoding Cycle

Advantages of Byte-Pair Encoding (BPE)

How to Effectively Paste Images on Markdown with VSCode

Introduction

The Problem We're Trying to Solve

How We're Going to Solve It

Usage Example

Before and After Pasting

Final Notes

Brief Overview of HTTP, Internet Protocols, and Web Architecture

Index

Intro

1.0 URLs

1.0.1 URL Components

1.1 Internet Protocol (IP) Suite

1.1.1 The DNS Lookup Process

1.1.2 TCP (Transmission Control Protocol)

1.1.2.1 The Three Way Handshake

1.1.3 HTTP Verbs/Methods

1.1.4 API Endpoints

1.1.5 What is HTTP (HyperText Transfer Protocol)?

1.1.5.1 Request

1.1.5.2 Response

1.1.5.3 HTTP Status Codes

2.0 HTTP is Stateless

3.0 What is the REST (REpresentational State Transfer) Architecture?

4.0 What is the Web Layers Architecture?

Presentation Layer (PL):

Business Logic Layer (BLL):

Data Service Layer (DSL):

Data Access Layer (DAL):

The Concise Django Tutorial

Intro

Command Reference

Initialize Project

0.1 Project File Structure

0.2 Dev Server

1.0 Initialize Apps

1.1 First View

1.1.1 include() and path()

include()

path()

2.0 First look at Settings & Database

1: django.contrib.admin – The admin site

2: django.contrib.auth – An authentication system

3: django.contrib.contenttypes – A framework for content types

4: django.contrib.sessions – A session framework

5: django.contrib.messages – A messaging framework

6: django.contrib.staticfiles – A framework for managing static files

2.1 Postgres Setup

2.2 Migrating

2.3 Django Models

1.1.1 `include()` and `path()`

`include()`

`path()`

4.1.2.1 Adding Views and Names as `path()` Params

5.1.1 The `reverse()` function

Best Method Overall: `Markdown to PDF` VS Code Extension

Alternative 1: `Dilliger.io`

Alternative 2: Python `grip`