DEV Community: PyShine

Learn Cryptography in a Single Post: A Complete Tutorial From Symmetric and Asymmetric Encryption to Hashing, TLS, and Applied Security

PyShine — Thu, 23 Jul 2026 12:42:46 +0000

Learn Cryptography in a Single Post: Complete Tutorial From Symmetric and Asymmetric Encryption to TLS and Applied Security

Cryptography is the math and engineering that lets two parties communicate securely over an insecure channel — where anyone can listen. It's the foundation of every HTTPS page, every SSH login, every secure message, and every password you've ever stored. This single post teaches the whole field in five stages, with hand-drawn diagrams and runnable examples.

Learning Roadmap

The roadmap moves from the fastest kind of encryption (Stage 1), through the key-exchange solution to its key-sharing problem (Stage 2), to the integrity/authentication layer (Stage 3), the protocols that combine them (Stage 4), and the applied layer you build with (Stage 5).

Stage 1 — Symmetric Encryption

One shared key

Symmetric encryption uses one key for both encryption and decryption. It's fast (AES hardware-accelerated on every modern CPU) and the workhorse of all bulk data encryption.

encrypt(key, plaintext)  ->  ciphertext
decrypt(key, ciphertext) ->  plaintext

from cryptography.hazmat.primitives.ciphers.aead import AESGCM
key = AESGCM.generate_key(bit_length=256)    # 32-byte key
aesgcm = AESGCM(key)
nonce = os.urandom(12)                        # 12-byte nonce, unique per encryption
ciphertext = aesgcm.encrypt(nonce, b"secret message", None)
plaintext  = aesgcm.decrypt(nonce, ciphertext, None)   # b"secret message"

AES and modes

AES (Advanced Encryption Standard) is the standard symmetric cipher, with 128/192/256-bit keys. But AES alone is a block cipher — it encrypts one 16-byte block. A mode of operation turns it into a general-purpose cipher:

Mode	What it does
GCM (Galois/Counter Mode)	AEAD — encrypts + authenticates in one pass. The default choice.
ChaCha20-Poly1305	an AEAD alternative to AES-GCM, fast in software (no AES-NI needed)
CBC	encrypts blocks chained together; needs a separate MAC for integrity
CTR	turns AES into a stream cipher; needs a MAC for integrity

AEAD (Authenticated Encryption with Associated Data) is the key concept: it encrypts and authenticates in one operation. If someone tampers with the ciphertext, decryption fails — you don't need a separate MAC. Always use an AEAD mode (GCM or ChaCha20-Poly1305); CBC/CTR alone don't detect tampering.

Pitfall: The nonce (number used once) must be unique per key — never reuse a nonce with the same key in GCM/CTR. Reusing a nonce leaks the key's keystream, breaking the encryption entirely. Generate a random nonce per message, or use a counter.

The key-sharing problem

Symmetric encryption has one weakness: both sides need the same key, but how do they share it over an insecure channel? That's what asymmetric cryptography (Stage 2) solves.

Stage 2 — Asymmetric Encryption

Two keys: public and private

Asymmetric encryption uses a key pair: a public key (shared freely) and a private key (kept secret). What one encrypts, the other decrypts.

Two operations:

Encrypt with public key → only the private key can decrypt. Anyone can send you a secret; only you can read it.
Sign with private key → anyone can verify with the public key. Only you could have signed it; it proves authenticity.

Algorithms

Algorithm	Use	Notes
RSA (2048+ bits)	encryption + signatures	the classic; large keys, slower
ECC (Elliptic Curve)	key exchange + signatures	X25519 for exchange, Ed25519 for signatures; smaller keys, faster
Diffie-Hellman (DH / ECDH)	key exchange	two parties derive a shared secret without ever sending it

Key exchange — the solution to the key-sharing problem

Diffie-Hellman (and its elliptic-curve variant ECDH) lets two parties derive a shared secret over an insecure channel, without ever transmitting the secret itself. Each side generates a key pair, exchanges public keys, and computes the same shared secret from their own private key + the other's public key:

Alice:  shared = ECDH(Alice_private, Bob_public)
Bob:    shared = ECDH(Bob_private, Alice_public)
# both compute the SAME shared secret, but no one listening can

That shared secret becomes the symmetric key for AES — so you get the speed of symmetric encryption with the key-sharing solution of asymmetric. This is how TLS, SSH, and Signal all establish their session keys.

Pitfall: DH/ECDH alone is vulnerable to a man-in-the-middle (Mallory intercepts both public keys and substitutes her own). You need authentication — a way to prove the public key is really theirs (certificates in TLS, host keys in SSH). Without authentication, key exchange is secure against eavesdroppers but not against active attackers.

Stage 3 — Hashing, HMAC, Signatures, Passwords

Cryptographic hashes

A hash function takes any input and produces a fixed-size digest (e.g. SHA-256 → 256 bits). Properties:

One-way — you can't reverse a hash to get the input.
Deterministic — same input always produces the same hash.
Avalanche — changing one bit changes ~half the output bits.
Collision-resistant — hard to find two inputs with the same hash.

import hashlib
hashlib.sha256(b"hello").hexdigest()   # 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
hashlib.sha256(b"hello ").hexdigest()  # completely different (space added)

HMAC — keyed hashing

HMAC (Hash-based Message Authentication Code) is a hash with a key: HMAC-SHA256(key, message) → tag. The recipient verifies the tag with the same key. If it matches, the message is authentic and untampered. This is symmetric message authentication.

Digital signatures

A digital signature combines hashing + asymmetric: sign hash(message) with your private key; anyone verifies with your public key. It proves who sent it (authentication) and that it wasn't modified (integrity), with non-repudiation (you can't deny signing).

sign:  signature = RSA-PSS(private_key, SHA-256(message))
verify: RSA-PSS-verify(public_key, message, signature) -> true/false

Modern signature algorithms: Ed25519 (fast, small, recommended for new systems), ECDSA (used in TLS), RSA-PSS (classic).

Password storage

Passwords must never be stored in plaintext or even as a plain SHA-256 hash (rainbow tables + GPU brute-force crack SHA-256 fast). Use a slow, salted hash:

import bcrypt
hashed = bcrypt.hashpw(b"password123", bcrypt.gensalt())   # $2b$12$...
bcrypt.checkpw(b"password123", hashed)                      # True

Salt — a random per-user value mixed in, so two users with the same password get different hashes. Prevents rainbow tables.
Slow — bcrypt/scrypt/argon2 are deliberately slow (cost factor adjustable), so brute-force takes years, not seconds. SHA-256 is fast — wrong for passwords.
argon2 — the current recommendation (memory-hard, resists GPU/ASIC attacks).

Pitfall: Never roll your own crypto, and never store passwords with SHA-256(password). Use bcrypt, scrypt, or argon2 with a per-user salt. The library handles the salt (it's embedded in the hash output). And rate-limit login attempts — even a slow hash falls to unlimited online guessing.

Stage 4 — Protocols: TLS, HTTPS, SSH, PKI

TLS 1.3 — the protocol behind HTTPS

TLS (Transport Layer Security) is how HTTPS works. The handshake (simplified):

Client Hello → client offers cipher suites + a random.
Server Hello + Certificate → server picks a cipher, sends its certificate (public key + identity, signed by a CA).
Key exchange → ECDHE: both derive a shared secret (the session key) — never sent over the wire.
Finished → both switch to encrypted communication with AES-GCM, using the session key.

TLS 1.3 (the current standard) collapses this to one round-trip and supports zero-round-trip resumption. It combines everything from Stages 1-3: asymmetric for key exchange, symmetric for the bulk data, hashing/HMAC for integrity, certificates for authentication.

SSH

SSH uses a similar handshake: key exchange (curve25519), server authentication via host keys (a server's public key, stored in ~/.ssh/known_hosts — trust on first use), and user authentication via public key (your ~/.ssh/id_ed25519.pub on the server, private key signs a challenge). Never use password auth over SSH; disable it in sshd_config.

PKI — Public Key Infrastructure

PKI is the system of certificate authorities (CAs) that vouch for public keys. A certificate binds a public key to an identity (a domain name) and is signed by a CA whose root your browser trusts. The chain: root CA → intermediate CA → leaf certificate (your site). If any link is broken, the cert is invalid.

X.509 — the certificate format.
Let's Encrypt — free, automated CA for HTTPS (ACME protocol).
Revocation — CRL (certificate revocation list) or OCSP (online status) to invalidate a compromised cert before expiry.

Pitfall: A self-signed certificate encrypts the channel but doesn't prove identity — anyone can generate one. Without a CA-validated chain, you're vulnerable to MITM. Use Let's Encrypt (free) or a real CA; never self-sign in production.

Stage 5 — Applied Cryptography

JWT (JSON Web Tokens)

A JWT is a signed token: a header + payload + signature, base64-encoded. The server signs it (HMAC or RSA); the client sends it back on each request; the server verifies the signature. It's stateless auth — the server doesn't need to look up a session, just verify the signature. Never put secrets in a JWT — the payload is base64 (not encrypted); only the signature prevents tampering.

OAuth 2.1 / OIDC

OAuth 2.1 is the delegated-authorization standard: "let app X access my data on service Y, without giving app X my password." It uses access tokens + refresh tokens + authorization codes. OIDC (OpenID Connect) adds identity (who the user is) on top. Use a library; the spec has many sharp edges (PKCE for public clients, exact redirect-URI matching, token lifetimes).

End-to-end encryption

E2EE (e.g. the Signal Protocol) means only the endpoints can decrypt — not the server, not the network provider. It combines key exchange (X3DH), ratcheting (double ratchet for forward secrecy), and AEAD. The result: even if the server is compromised, old messages stay unreadable.

Zero-knowledge proofs

A zero-knowledge proof lets you prove a statement is true without revealing why. "I know the password" without sending it; "I'm over 18" without revealing my age; "this transaction is valid" without revealing the amount. Used in Zcash (private blockchain), Tornado Cash, and increasingly in auth (WebAuthn / passkeys prove possession of a key without the server ever seeing the private key).

Quick-Start Checklist

Use a library, never roll your own crypto — cryptography (Python), ring/rustls (Rust), Go's crypto/*.
Use AES-GCM or ChaCha20-Poly1305 for symmetric encryption (AEAD — encrypts + authenticates).
Never reuse a nonce with the same key in GCM/CTR.
Use ECDH (X25519) for key exchange; authenticate with certificates (TLS) or host keys (SSH).
Use Ed25519 for signatures (fast, small, modern).
Store passwords with bcrypt/argon2 + salt, never SHA-256 or plaintext.
Use TLS (Let's Encrypt) for all web traffic; never HTTP, never self-signed in prod.
Use SSH key auth, not passwords; disable password auth.
JWT: sign, don't encrypt — the payload isn't secret; never put secrets in it.
Rate-limit auth endpoints — crypto doesn't stop online brute-force; limits do.

Common Pitfalls

Rolling your own crypto — the #1 rule: don't. Use vetted libraries and standard protocols.
Reusing a nonce in GCM/CTR — leaks the keystream, breaks everything.
SHA-256 for passwords — too fast; use bcrypt/argon2 (slow, salted).
No salt in password hashing — rainbow tables crack unsalted hashes.
Self-signed certs in production — encrypts but doesn't authenticate; MITM-vulnerable.
CBC/CTR without a MAC — no integrity; attacker can tamper undetected. Use AEAD.
Secrets in JWT payload — base64 isn't encryption; anyone can read the payload.
Storing the private key in Git — id_ed25519 is a secret; gitignore it.
Password SSH auth — brute-forceable; use keys, disable PasswordAuthentication.
No rate limiting on login — even a slow hash falls to unlimited online guessing.

Related guides

Cryptography underpins every secure system — these PyShine tutorials connect to it:

Learn Computer Networking in One Post — TLS sits at layer 4-6 of the OSI model; networking is the substrate.
Learn REST API in One Post — HTTPS/TLS is the transport; JWT/OAuth the auth.
Learn Python in One Post — the cryptography + bcrypt libraries are Python.
Learn Rust in One Post — ring / rustls are the Rust crypto stack; Rust's safety makes it a popular crypto language.
Learn System Design in One Post — encryption-at-rest, mTLS, and secret management are system-design concerns.

Cryptography is the one field where "it works" is not enough — it must work against an adversary, and the failure mode is silent (you don't know you're broken until it's too late). The five stages here — symmetric, asymmetric, hashing, protocols, applied — cover the whole map from a single AES key to a zero-knowledge proof. The two rules that pay off forever: never roll your own crypto (use vetted libraries and standard protocols), and use AEAD + slow password hashes + TLS + key-based auth — the defaults that are almost always right. Install the cryptography library, encrypt a message with AES-GCM, hash a password with bcrypt, and set up a Let's Encrypt cert — once you've done those three, you understand the foundation of every secure system.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Data Structures and Algorithms in a Single Post: A Complete DSA Tutorial From Big-O to Trees, Graphs, and Dynamic Programming

PyShine — Thu, 23 Jul 2026 12:42:33 +0000

Learn Data Structures and Algorithms in a Single Post: Complete Tutorial From Big-O to Dynamic Programming

Data structures and algorithms (DSA) is the grammar of computing. Every program stores data some way and processes it some way; DSA is the study of which ways are fast, which are slow, and why. It's also the bedrock of technical interviews and the lens through which you read any codebase. This single post teaches the whole subject in five stages, with hand-drawn diagrams and runnable snippets.

Learning Roadmap

The roadmap moves from complexity analysis (Stage 1), through the linear data structures (Stage 2), to trees and graphs (Stage 3), the classic algorithms (Stage 4), and the advanced patterns that tie them together (Stage 5).

Stage 1 — Big-O + Basics

Big-O notation

Big-O describes how an algorithm's time or space grows as the input n grows — dropping constants and lower-order terms. It's about scale, not exact speed.

Complexity	Name	Example
O(1)	constant	array index access
O(log n)	logarithmic	binary search
O(n)	linear	scan an array
O(n log n)	linearithmic	efficient sorts (quicksort, mergesort)
O(n²)	quadratic	nested loops, bubble sort
O(2ⁿ)	exponential	naive recursion (naive Fibonacci, N-queens)
O(n!)	factorial	all permutations

Pitfall: Big-O drops constants, so O(100n) is O(n). That's why a "slower" O(n) algorithm can beat an O(n²) one on small inputs — the constant matters below a threshold. Big-O tells you what wins as n → ∞.

Arrays and strings

An array is a contiguous block of memory; indexing is O(1) because the address is computed directly. Inserting in the middle is O(n) because every later element shifts.

nums = [1, 2, 3, 4, 5]
nums[2]            # O(1) access
nums.append(6)     # amortized O(1)
nums.insert(0, 0)  # O(n) — shifts everything

A string is (conceptually) an array of characters — immutable in Python/Java, so s += "x" is O(n) (builds a new string). Use a list + "".join for repeated concatenation.

Complexity analysis rules

A loop over n items: O(n).
A nested loop over n × n: O(n²).
A loop that halves the range each step (binary search): O(log n).
A sort followed by a linear scan: O(n log n) + O(n) = O(n log n) (dominant term).
Recursion: O(branching_factor ^ depth) if pure recursion; reduced by memoization.

Stage 2 — Linear Structures

Linked lists

A linked list stores nodes with a value + a pointer to the next node. O(1) insert/delete given a node pointer, but O(n) access (you walk from the head).

class Node:
    def __init__(self, val, next=None):
        self.val, self.next = val, next

# singly linked list: 1 -> 2 -> 3
head = Node(1, Node(2, Node(3)))

# reverse it
def reverse(head):
    prev = None
    while head:
        nxt = head.next
        head.next = prev
        prev, head = head, nxt
    return prev

Pitfall: A classic interview trap — losing the rest of the list by reassigning head.next before saving head.next. Always save the next pointer first (as nxt above).

Stacks (LIFO)

A stack is last-in-first-out: push/pop are O(1). Use for undo, expression evaluation, balanced-parentheses, and DFS.

stack = []
stack.append(1); stack.append(2)
stack.pop()   # 2

Queues (FIFO)

A queue is first-in-first-out: enqueue/dequeue are O(1). Use for BFS, scheduling, buffering. In Python use collections.deque (O(1) on both ends); a plain list's pop(0) is O(n).

from collections import deque
q = deque([1, 2, 3])
q.append(4); q.popleft()   # 1

Hash maps (dictionaries)

A hash map gives O(1) average lookup/insert/delete by hashing the key to a bucket. Worst case O(n) if all keys collide (rare with a good hash). This is the workhorse of "seen it before" problems (two-sum, frequency counts, caching).

seen = {}
for i, x in enumerate(nums):
    if target - x in seen:
        return [seen[target - x], i]
    seen[x] = i

Pitfall: Hash maps don't preserve order (pre-3.7 Python, and in most languages). If you need order + O(1), use an ordered dict or a separate list.

Data structures + access costs

Stage 3 — Trees + Graphs

Binary search tree (BST)

A BST keeps ordered data: left subtree < node < right subtree. Search/insert/delete are O(log n) if balanced — O(n) if degenerate (like a linked list). Self-balancing variants (AVL, red-black) guarantee O(log n).

class TreeNode:
    def __init__(self, val, left=None, right=None):
        self.val, self.left, self.right = val, left, right

# in-order traversal of a BST yields sorted order
def inorder(node):
    if not node: return []
    return inorder(node.left) + [node.val] + inorder(node.right)

Heaps

A heap is a complete binary tree with the heap property (min-heap: parent ≤ children). The root is the min (or max). push/pop are O(log n); peek is O(1). Use for priority queues, top-K, and as the backbone of heapsort.

import heapq
h = []
heapq.heappush(h, 3); heapq.heappush(h, 1)
heapq.heappop(h)   # 1 (smallest)
# top-K largest: push into a min-heap of size K

Tries

A trie (prefix tree) stores strings by shared prefixes. Lookup/insert is O(L) where L is the word length — independent of how many words are stored. Used for autocomplete, dictionaries, IP routing.

Graphs

A graph is nodes (vertices) + edges. Represent as:

Adjacency list — graph[u] = [v1, v2, ...] (sparse graphs; the default).
Adjacency matrix — n × n matrix (dense graphs; O(1) edge lookup but O(n²) space).

# adjacency list
graph = {
    'A': ['B', 'C'],
    'B': ['D'],
    'C': ['D'],
    'D': [],
}

BFS — breadth-first search

Level by level, using a queue. Finds shortest path in an unweighted graph.

from collections import deque
def bfs(graph, start):
    visited, q, order = set(), deque([start]), []
    while q:
        node = q.popleft()
        if node in visited: continue
        visited.add(node); order.append(node)
        for n in graph[node]:
            if n not in visited: q.append(n)
    return order   # ['A','B','C','D']

DFS — depth-first search

Go deep first, using recursion (or an explicit stack). Used for connected components, topological sort, cycle detection.

def dfs(graph, node, visited=None):
    if visited is None: visited = set()
    visited.add(node)
    for n in graph[node]:
        if n not in visited: dfs(graph, n, visited)
    return visited

BFS vs DFS: BFS = shortest path (unweighted), level order; O(V+E). DFS = connectivity, topo sort, cycle detection; O(V+E). Both are O(V+E) with an adjacency list.

Stage 4 — Sorting + Searching

Sorting

Algorithm	Avg	Worst	Stable?	Notes
Quicksort	O(n log n)	O(n²)	no	in-place, fast in practice
Mergesort	O(n log n)	O(n log n)	yes	needs O(n) extra space
Heapsort	O(n log n)	O(n log n)	no	in-place
Counting sort	O(n + k)	O(n + k)	yes	when keys are small ints

Pitfall: sorted() in Python and Arrays.sort() in Java are O(n log n) and stable — just use them. Writing your own sort in an interview is rarely the point; knowing when each algorithm wins is.

Quicksort (the one to know)

def quicksort(a):
    if len(a) <= 1: return a
    pivot = a[len(a) // 2]
    left  = [x for x in a if x < pivot]
    mid   = [x for x in a if x == pivot]
    right = [x for x in a if x > pivot]
    return quicksort(left) + mid + quicksort(right)

Binary search

On a sorted array, binary search is O(log n). The bug-prone part is the boundary conditions.

def binary_search(a, target):
    lo, hi = 0, len(a) - 1
    while lo <= hi:
        mid = (lo + hi) // 2
        if a[mid] == target: return mid
        elif a[mid] < target: lo = mid + 1
        else: hi = mid - 1
    return -1

Pitfall: mid = (lo + hi) // 2 can overflow in languages with fixed ints (C/Java). Use mid = lo + (hi - lo) // 2. Python ints don't overflow, but it's the right habit.

Two pointers

A sorted-array pattern that turns O(n²) into O(n): one pointer at the start, one at the end, move them toward each other.

def two_sum_sorted(a, target):
    lo, hi = 0, len(a) - 1
    while lo < hi:
        s = a[lo] + a[hi]
        if s == target: return [lo, hi]
        elif s < target: lo += 1
        else: hi -= 1

Sliding window

For subarray/substring problems, a window [left, right] that expands and contracts — O(n) instead of O(n²).

def max_subarray_sum_k(a, k):
    window = sum(a[:k]); best = window
    for i in range(k, len(a)):
        window += a[i] - a[i - k]
        best = max(best, window)
    return best

Stage 5 — Advanced Patterns

Dynamic programming

DP solves problems with overlapping subproblems and optimal substructure by caching subproblem results (memoization top-down, or tabulation bottom-up).

Fibonacci (the canonical example)

# naive recursion: O(2^n) — recomputes the same values
def fib_naive(n):
    return n if n < 2 else fib_naive(n-1) + fib_naive(n-2)

# memoization (top-down): O(n)
from functools import cache
@cache
def fib(n):
    return n if n < 2 else fib(n-1) + fib(n-2)

# tabulation (bottom-up): O(n), O(1) space
def fib(n):
    a, b = 0, 1
    for _ in range(n): a, b = b, a + b
    return a

0/1 Knapsack (the classic DP)

def knapsack(weights, values, capacity):
    dp = [0] * (capacity + 1)
    for w, v in zip(weights, values):
        for c in range(capacity, w - 1, -1):   # iterate backward for 0/1
            dp[c] = max(dp[c], dp[c - w] + v)
    return dp[capacity]

Pitfall: The 0/1 knapsack iterates c backward (so each item is used once); the unbounded knapsack iterates forward (items can repeat). Getting the direction wrong silently changes the answer.

Greedy

Greedy picks the locally optimal choice at each step. It works when the problem has the greedy-choice property (a local optimum is part of the global optimum) — e.g. activity selection, Huffman coding, Dijkstra. It fails when a locally bad choice would unlock a globally better one.

Divide and conquer

Split the problem, solve the halves, combine. Quicksort, mergesort, and binary search are all divide-and-conquer. The Master Theorem gives the complexity: T(n) = aT(n/b) + f(n).

Backtracking

Explore all possibilities by trying a choice, recursing, then undoing it. Used for permutations, combinations, N-queens, Sudoku. Pruning (skipping branches that can't improve) is what makes it tractable.

def permutations(a):
    result = []
    def backtrack(path, remaining):
        if not remaining: result.append(path); return
        for i, x in enumerate(remaining):
            backtrack(path + [x], remaining[:i] + remaining[i+1:])
    backtrack([], a)
    return result

Interview prep

The patterns above cover the overwhelming majority of interview questions. The standard path:

NeetCode 150 / Blind 75 — curated problem set that maps to these patterns.
Practice one pattern at a time (not random problems) until you recognize the pattern from the problem statement.
Always say the time/space complexity out loud before coding — that's what interviewers grade.

The Toolchain

Practice: LeetCode, HackerRank, Codeforces, Codewars.
Visualizers: VisuAlgo, USFCA Data Structure Visualizer, Big-O Cheat Sheet.
Languages: Python (concise, interview-friendly), C++ (fast, STL), Java, Rust.
Interview prep: NeetCode 150, Blind 75, Cracking the Coding Interview.

Quick-Start Checklist

Learn Big-O cold — know O(1)/O(log n)/O(n)/O(n log n)/O(n²)/O(2ⁿ) and recognize them in code.
Master arrays + hash maps first — they solve most easy problems.
Learn the two-pointer and sliding-window patterns — they turn O(n²) into O(n) on sorted/contiguous data.
Know one sort (quicksort) and binary search — and their boundary bugs.
Learn BFS and DFS on graphs — they're the same algorithm with a queue vs a stack.
Learn one tree (BST) and one heap — and when to use each.
Start DP with Fibonacci, then knapsack — memoization first, tabulation second.
Practice by pattern, not randomly — NeetCode 150 groups problems by pattern.
Always state time + space complexity before coding — it's the interview grade.
Visualize on VisuAlgo when a data structure doesn't click — seeing a heap push is worth a paragraph.

Common Pitfalls

Off-by-one in binary search — lo <= hi vs lo < hi, and the +1/-1 on the bounds. Decide inclusive vs exclusive and stay consistent.
Integer overflow in mid — use lo + (hi - lo) // 2 in C/Java.
Modifying a list while iterating it — skip/delete bugs. Iterate over a copy, or use a separate result list.
O(n) pop(0) on a Python list — use collections.deque.
String concatenation in a loop — O(n²) for immutable strings; build a list and join.
Forgetting to mark nodes visited in BFS/DFS — infinite loops on cyclic graphs.
0/1 vs unbounded knapsack direction — backward vs forward iteration.
Greedy on a problem that needs DP — check for the greedy-choice property before reaching for greedy.
Naive recursion without memoization — O(2ⁿ) when O(n) is a @cache away.

Related guides

DSA underpins efficient code in every language — these PyShine tutorials apply it:

Learn Python in One Post: Complete Tutorial — the snippets above are Python; pair DSA with Python's collections (deque, Counter, heapq).
Learn C++ in One Post: Complete Tutorial — STL containers (vector, unordered_map, priority_queue) are the interview-standard DSA toolkit.
Learn Rust in One Post: Complete Tutorial — ownership makes linked structures harder; learn Rust's Vec/HashMap/BinaryHeap approach.
Learn SQL in One Post: Complete Tutorial — query planning is applied DSA (B-trees, hash joins, sort-merge).
Learn Go in One Post: Complete Tutorial — Go's built-in sort, container/heap, and maps are DSA in the standard library.

DSA is the subject where reading is no substitute for doing. The five stages here — Big-O, linear structures, trees and graphs, sorting and searching, advanced patterns — cover the whole map, but each only clicks once you've solved ten problems that use it. Spend a week per stage on NeetCode 150, state the complexity out loud every time, and within two months you'll read a problem and know the pattern before you've finished the prompt. Run every snippet above; then go to LeetCode and solve the easy version of each pattern today.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Deep Learning in a Single Post: A Complete Tutorial From Neural Networks and CNNs to Transformers and PyTorch Training

PyShine — Thu, 23 Jul 2026 12:42:19 +0000

Learn Deep Learning in a Single Post: Complete Tutorial From Neural Networks to Transformers and PyTorch Training

Deep learning is the branch of machine learning that uses neural networks — stacks of layers that learn hierarchical representations from data. It's the technology behind image recognition, speech transcription, machine translation, and every large language model (GPT, Claude, Gemini). This single post teaches the whole field in five stages, with hand-drawn diagrams and runnable PyTorch.

Learning Roadmap

The roadmap moves from the neuron (Stage 1), through how it learns (Stage 2), the architectures for images and sequences (Stages 3-4), and the practical framework + deployment (Stage 5). The ML basics tutorial is the prerequisite — this post goes deep.

Stage 1 — Neural Networks

The neuron

A neuron is the unit of a neural network: it takes weighted inputs, sums them, adds a bias, and applies a non-linear activation function:

y = activation(w1*x1 + w2*x2 + ... + b)

Weights (w1, w2, ...) — learned parameters; they're what the network learns.
Bias (b) — a learned offset.
Activation function — the non-linearity that lets the network learn complex patterns. Without it, a stack of linear layers is still linear (a composition of linear functions is linear).

Common activations

Function	Formula	Use
ReLU	`max(0, x)`	the default for hidden layers; simple, fast, no vanishing gradient for positive values
Sigmoid	`1 / (1 + e^-x)`	squashes to (0,1); binary classification output; vanishing gradient problem in deep nets
Tanh	`(e^x - e^-x) / (e^x + e^-x)`	squashes to (-1,1); similar vanishing issue
GELU	`x * Phi(x)`	used in transformers (smoother than ReLU)
Softmax	`e^xi / sum(e^xj)`	multi-class output (probabilities summing to 1)

Layers = stacked neurons

A layer is a set of neurons that all receive the same input and produce outputs that feed the next layer. A network is a stack of layers: input → hidden → hidden → ... → output. The "deep" in deep learning = many layers, each learning progressively more abstract features.

import torch.nn as nn

model = nn.Sequential(
    nn.Linear(784, 128),   # input (28x28 pixels) -> 128 neurons
    nn.ReLU(),             # activation
    nn.Linear(128, 64),    # 128 -> 64
    nn.ReLU(),
    nn.Linear(64, 10),     # 64 -> 10 classes
)

The forward pass

The forward pass pushes input through the layers to get a prediction: y = model(x). Each layer transforms its input; the output of one layer is the input of the next.

Stage 2 — Training

The training loop

Training is a loop, repeated many times (epochs) over the dataset:

Forward pass — predictions = model(inputs)
Loss — compare predictions to true labels: loss = loss_fn(predictions, labels)
Backpropagation — compute the gradient of the loss w.r.t. every weight: loss.backward()
Update — nudge weights to reduce loss: optimizer.step()

import torch
import torch.nn as nn
import torch.optim as optim

model = nn.Sequential(nn.Linear(784, 128), nn.ReLU(), nn.Linear(128, 10))
loss_fn = nn.CrossEntropyLoss()
optimizer = optim.Adam(model.parameters(), lr=1e-3)

for epoch in range(10):
    for X_batch, y_batch in dataloader:
        pred = model(X_batch)              # forward
        loss = loss_fn(pred, y_batch)      # loss
        optimizer.zero_grad()
        loss.backward()                    # backprop (gradients)
        optimizer.step()                   # update weights
    print(f"epoch {epoch}, loss {loss.item():.4f}")

Loss functions

Loss	When
MSE (mean squared error)	regression (predict a number)
Cross-entropy	classification (predict a class)
Binary cross-entropy	binary classification
CTC	sequence-to-sequence with alignment (speech)

Gradient descent + optimizers

Gradient descent: w -= lr * gradient — step in the direction that reduces loss. The learning rate (lr) is the step size — too big and you overshoot/diverge; too small and you crawl. The optimizer decides how to step:

Optimizer	How
SGD	vanilla `w -= lr * grad`
SGD + momentum	add a running average of past gradients (smoother, faster)
Adam	adaptive per-parameter learning rate + momentum — the default
AdamW	Adam + decoupled weight decay (L2 regularization) — the modern default

Backpropagation

Backpropagation is the algorithm that computes all gradients efficiently using the chain rule: starting from the loss, it walks backward through the network, computing the derivative of the loss with respect to each weight layer by layer. PyTorch's autograd does this automatically — you call loss.backward() and every weight's .grad is populated.

Regularization — preventing overfitting

Technique	How
Dropout	randomly zero out neurons during training (forces redundancy)
L2 regularization (weight decay)	add `lambda * sum(w^2)` to the loss (penalize large weights)
Early stopping	stop when validation loss starts rising
Data augmentation	transform training data (flip, crop, rotate) to effectively get more
Batch normalization	normalize layer inputs per-batch (stabilizes training)

Pitfall: The learning rate is the single most important hyperparameter. Too high → the loss diverges (NaN). Too low → training takes forever. Start with 1e-3 for Adam, and use a learning rate schedule (warmup + decay) for large models. Always watch the training + validation loss curves.

Stage 3 — CNNs (Convolutional Neural Networks)

Why CNNs for images

A fully-connected layer on an image would need millions of weights (every pixel to every neuron). A CNN uses convolutional filters — small learned kernels (e.g. 3x3) that slide across the image, detecting local patterns with far fewer parameters. Early layers detect edges; later layers detect shapes, then objects.

Convolution, pooling, and a typical architecture

import torch.nn as nn

cnn = nn.Sequential(
    nn.Conv2d(3, 32, 3, padding=1),    # 3 channels -> 32 filters, 3x3
    nn.ReLU(),
    nn.MaxPool2d(2),                    # downsample by 2
    nn.Conv2d(32, 64, 3, padding=1),
    nn.ReLU(),
    nn.MaxPool2d(2),
    nn.Flatten(),
    nn.Linear(64 * 8 * 8, 10),           # fully-connected -> 10 classes
)

Conv2d — convolution: in_channels → out_channels filters.
MaxPool2d — downsampling (take the max in each window); reduces spatial size, adds invariance.
Flatten + Linear — convert the feature maps to a vector, then classify.

Famous CNN architectures

Architecture	Innovation
LeNet (1998)	the first CNN (handwritten digit recognition)
AlexNet (2012)	deep CNN + ReLU + GPU; started the deep learning era
ResNet (2015)	residual connections (skip connections) that enable very deep networks (50-152 layers)
EfficientNet	scaled width/depth/resolution together
Vision Transformer (ViT)	transformers applied to image patches (the modern alternative)

Stage 4 — Transformers

The problem with RNNs

RNNs (recurrent neural networks) process sequences one step at a time, carrying hidden state — but they're sequential (can't parallelize) and suffer from vanishing gradients on long sequences. LSTMs added gates to fix the gradient issue, but not the sequentiality.

The Transformer: self-attention

The Transformer (2017, "Attention Is All You Need") replaced recurrence with self-attention: each position in the sequence attends to (weighs) all other positions simultaneously. This is parallelizable (process all positions at once on a GPU) and captures long-range dependencies far better.

Self-attention in one line: for each token, compute a weighted average of all tokens, where the weights are learned from the query-key dot product:

Attention(Q, K, V) = softmax(Q @ K^T / sqrt(d)) @ V

Q (query) — "what am I looking for?"
K (key) — "what do I contain?"
V (value) — "what information do I carry?"
softmax(Q @ K^T) — how much each position should attend to each other
Multi-head attention — run multiple attention heads in parallel, each learning a different pattern

Transformers → LLMs

A large language model (GPT, Claude, Gemini) is a transformer trained on massive text:

GPT-style (decoder-only): predicts the next token; autoregressive generation.
BERT-style (encoder-only): bidirectional; used for understanding (classification, search).
The model learns language, facts, and reasoning from the training data; fine-tuning + RLHF adapt its behavior.

Diffusion models

Diffusion (Stable Diffusion, DALL-E) generates images: add Gaussian noise to an image step by step, then train a neural network (often a U-Net) to reverse the process. At generation, start from pure noise and denoise into an image, conditioned on a text prompt (via a CLIP encoder).

Pitfall: Transformers are data-hungry — they need millions/billions of examples to train well. On small datasets, a CNN or a tree-based model (XGBoost) often wins. The "scale is all you need" approach only works with the data and compute to match.

Stage 5 — Frameworks, Training Loop, GPU, Deploy

PyTorch — the dominant framework

PyTorch is the default for research and increasingly production: eager execution (debuggable), dynamic graphs, a rich ecosystem (HuggingFace Transformers, torchvision, torchaudio). TensorFlow/Keras (Google) and JAX (functional, XLA-compiled) are alternatives.

# GPU
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = model.to(device)
X_batch, y_batch = X_batch.to(device), y_batch.to(device)

# mixed precision (2x faster, half the memory)
scaler = torch.amp.GradScaler()
with torch.amp.autocast():
    pred = model(X_batch)
    loss = loss_fn(pred, y_batch)
scaler.scale(loss).backward()
scaler.step(optimizer)
scaler.update()

The training loop (full)

for epoch in range(num_epochs):
    model.train()                          # training mode (dropout active)
    for X, y in train_loader:
        X, y = X.to(device), y.to(device)
        pred = model(X)
        loss = loss_fn(pred, y)
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()

    model.eval()                           # eval mode (dropout off, batchnorm fixed)
    with torch.no_grad():                  # no gradients (saves memory)
        val_loss = sum(loss_fn(model(Xv), yv) for Xv, yv in val_loader)
    print(f"epoch {epoch}: train {loss:.4f} val {val_loss:.4f}")

Deploy

# export to ONNX (interchange format, runs on CPU/mobile/server)
torch.onnx.export(model, dummy_input, "model.onnx")
# or TorchScript for production serving
scripted = torch.jit.script(model)
scripted.save("model.pt")
# serve: TorchServe, NVIDIA Triton, or a FastAPI endpoint wrapping the model

Quick-Start Checklist

Install PyTorch (pip install torch torchvision); verify GPU with torch.cuda.is_available().
Write a 3-layer MLP on MNIST; train it for 5 epochs; watch the loss drop.
Learn the training loop: forward → loss → backward() → step().
Use Adam (lr=1e-3); if the loss diverges, lower the lr by 10x.
Watch train vs val loss — if val rises while train drops, you overfit (add dropout/early stop).
Build a CNN on CIFAR-10; see convolutions outperform the MLP.
Try a pretrained model — torchvision.models.resnet18(pretrained=True); fine-tune on your data.
Use HuggingFace Transformers — load a pretrained BERT/GPT in 3 lines.
Train on GPU with mixed precision; it's 2-5x faster.
Export to ONNX and serve; or use a pre-trained model from HuggingFace Hub.

Common Pitfalls

Learning rate too high — loss goes to NaN; reduce by 10x.
Learning rate too low — loss barely moves; increase or use a schedule.
Overfitting — train loss down, val loss up; add dropout, data augmentation, early stopping.
Not setting model.train() / model.eval() — dropout and batchnorm behave differently; forgetting eval() gives wrong validation results.
Forgetting optimizer.zero_grad() — gradients accumulate across batches; stale gradients corrupt training.
Not using torch.no_grad() in evaluation — wastes memory computing gradients you don't need.
Data on CPU, model on GPU — every batch transfer is a bottleneck; move data to GPU once.
Small data + big model — a transformer on 1,000 examples overfits instantly; use a pretrained model + fine-tune, or a simpler architecture.
Not normalizing inputs — unnormalized data (pixels 0-255 instead of 0-1) makes training unstable.

Related guides

Deep learning builds on programming + math fundamentals — these PyShine tutorials connect to it:

Learn Machine Learning in One Post — the prerequisite; ML basics before going deep.
Learn Python in One Post — the language every DL framework uses; NumPy tensors are Python.
Learn Data Structures and Algorithms in One Post — Big-O for model complexity; matrix math fundamentals.
Learn PostgreSQL in One Post — pgvector stores and searches DL embeddings.
Learn Docker in One Post — containerize model training and serving.

Deep learning's power is the same idea repeated at scale: a layer learns a representation, the next layer builds on it, and a deep stack learns hierarchical features no human designed. The five stages here — neural networks, training, CNNs, transformers, frameworks — cover everything from a single neuron to a billion-parameter LLM. The two habits that pay off: start with a pretrained model and fine-tune (don't train from scratch unless you have the data), and watch the training + validation loss curves — they tell you everything about what's happening. Install PyTorch, train a 3-layer net on MNIST for 5 epochs, and watch the loss drop — that's the moment it clicks.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn FastAPI in a Single Post: A Complete Tutorial From Path Operations and Pydantic to Async Databases and Production

PyShine — Thu, 23 Jul 2026 12:42:05 +0000

Learn FastAPI in a Single Post: Complete Tutorial From Path Operations and Pydantic to Async Databases and Production

FastAPI is the modern Python web framework: it takes Python type hints, turns them into automatic request validation, serialization, and interactive API docs, and runs on an async (ASGI) runtime for high concurrency. It's become the default for new Python APIs — replacing Flask for anything that wants async, validation, or OpenAPI for free. This single post teaches the whole framework in five stages, with hand-drawn diagrams and runnable Python.

Learning Roadmap

The roadmap moves from basics (Stage 1), through the Pydantic models that make FastAPI work (Stage 2), routing + dependencies (Stage 3), async + databases (Stage 4), and production (Stage 5). You'll want solid Python and REST API fundamentals first.

Stage 1 — Basics

A first app

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"hello": "world"}

@app.get("/users/{user_id}")
def read_user(user_id: int, q: str | None = None):
    return {"user_id": user_id, "q": q}

Run it:

pip install "fastapi[standard]"
fastapi dev main.py        # hot-reload dev server at http://localhost:8000
# then open http://localhost:8000/docs  <- automatic interactive docs!

Path operations

A path operation is a route: a decorator (@app.get, @app.post, ...) on a function.

@app.post("/items")
def create_item(item: Item):           # body validated via Pydantic (Stage 2)
    return item

@app.put("/items/{item_id}")
def update(item_id: int, item: Item):    # path param + body
    return {"id": item_id, **item.model_dump()}

@app.delete("/items/{item_id}", status_code=204)
def delete(item_id: int):
    return

Parameters — types do the work

FastAPI reads your type hints and converts them:

Path params (user_id: int) — parsed from the URL, validated as int (a string here returns 422).
Query params (q: str | None = None) — optional query string.
Request body (item: Item, a Pydantic model) — parsed + validated JSON.
Headers/cookies — via Header / Cookie defaults.

from fastapi import Query
@app.get("/search")
def search(q: str = Query(min_length=1, max_length=50), limit: int = 10):
    return {"q": q, "limit": limit}

The request/response flow + auto docs

Validate -> Handler -> Response + Auto Docs" width="800" height="400">

Every request is validated by Pydantic before your handler runs (invalid → 422 with a precise error), the handler runs, and the response_model serializes and filters the output. Swagger UI at /docs and ReDoc at /redoc are generated automatically from your types — no separate spec to maintain.

Pitfall: Because validation is from type hints, a missing annotation (def f(x): with no type) means FastAPI treats x as a query param with no validation — silently. Always annotate. Run mypy/pyright in CI to catch missing hints.

Stage 2 — Pydantic

Pydantic is the engine under FastAPI: typed data models that validate, coerce, and serialize. Your request bodies and responses are Pydantic models.

A model

from pydantic import BaseModel, Field, EmailStr

class UserCreate(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    email: EmailStr
    age: int = Field(ge=0, le=150)
    tags: list[str] = []           # default empty list (safe - not mutable-shared)

# validation happens on construction:
UserCreate(name="Ada", email="a@b.com", age=30)       # ok
UserCreate(name="", email="bad", age=999)             # ValidationError (precise)

Validation, coercion, serialization

Coercion — UserCreate(age="30") coerces the string "30" to int 30 (controlled; use Strict to disable).
Validation — Field(min_length=1, ge=0) constraints; type mismatches raise ValidationError with the exact failing field/loc.
Serialization — .model_dump() (dict) and .model_dump_json() (JSON); response_model filters to only the declared fields.

u = UserCreate(name="Ada", email="a@b.com", age=30)
u.model_dump()          # {'name': 'Ada', 'email': 'a@b.com', 'age': 30, 'tags': []}

class UserOut(BaseModel):
    id: int
    name: str
    email: EmailStr       # no 'age' or 'tags' -> response_model filters them out

@app.post("/users", response_model=UserOut)
def create(u: UserCreate):
    return UserOut(id=1, name=u.name, email=u.email)   # age/tags never leak

Custom validators

from pydantic import field_validator
class Item(BaseModel):
    price: float
    @field_validator("price")
    @classmethod
    def positive(cls, v): 
        if v < 0: raise ValueError("price must be positive")
        return v

Settings (config from env vars)

from pydantic_settings import BaseSettings
class Settings(BaseSettings):
    db_url: str = "postgresql://localhost/app"
    debug: bool = False
    model_config = SettingsConfigDict(env_prefix="APP_")   # APP_DB_URL, APP_DEBUG
settings = Settings()    # reads env vars, typed

Pitfall: A mutable default (tags: list[str] = []) is safe in Pydantic (it copies per instance), unlike plain Python class attributes where it'd be shared. Still, prefer Field(default_factory=list) for clarity in older code.

Stage 3 — Routing + Dependencies

APIRouter — split routes into modules

from fastapi import APIRouter
router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}")
def get_user(user_id: int): ...

# main.py
from users import router as users_router
app.include_router(users_router)

Dependency injection via `Depends`

Depends is how FastAPI shares logic — a function whose return value is injected into your handler. It's composable and cached per-request by default.

from fastapi import Depends

def get_db():           # yields a DB session, closes it after the request
    db = SessionLocal()
    try: yield db
    finally: db.close()

@app.get("/users/{id}")
def read_user(id: int, db = Depends(get_db)):
    return db.query(User).get(id)

Use Depends for: DB sessions, auth (get current user), settings, pagination params, rate limiting. It's cleaner than globals and testable (override in tests).

Middleware

@app.middleware("http")
async def add_timing(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    response.headers["X-Process-Time"] = str(time.perf_counter() - start)
    return response

Auth

from fastapi.security import OAuth2PasswordBearer
oauth2 = OAuth2PasswordBearer(tokenUrl="token")

async def current_user(token: str = Depends(oauth2)):
    user = decode_jwt(token)
    if not user: raise HTTPException(401, "invalid token")
    return user

@app.get("/me")
def me(user = Depends(current_user)):
    return user

fastapi.security provides OAuth2, JWT, API keys, HTTP basic — wired into the auto-docs so the "Authorize" button works.

Stage 4 — Async + Databases

Why async

The DB call is the bottleneck in most APIs. With async + await, the worker thread is released while waiting on I/O, so one event loop serves many in-flight requests. This is FastAPI's main advantage over Flask.

An async handler with an async DB session

from sqlalchemy.ext.asyncio import AsyncSession

async def get_db():
    async with AsyncSessionLocal() as db:
        yield db

@app.get("/users/{id}")
async def read_user(id: int, db: AsyncSession = Depends(get_db)):
    user = await db.get(User, id)
    if not user: raise HTTPException(404)
    return user

Async DB options

Tool	When
SQLAlchemy 2.0 async	the default ORM; async sessions
asyncpg	raw, fast async Postgres driver
SQLModel	SQLAlchemy + Pydantic fused (by the FastAPI author)
aioredis / redis-py async	async Redis for cache/sessions

HTTP clients + background work

import httpx
async def fetch(url): 
    async with httpx.AsyncClient() as c: 
        return (await c.get(url)).json()

# fire-and-forget background job (for simple cases; use a queue for real)
from fastapi import BackgroundTasks
@app.post("/send")
async def send(email: str, tasks: BackgroundTasks):
    tasks.add_task(send_email, email)   # runs after the response
    return {"queued": True}

Pitfall: A blocking call in an async handler (requests.get, time.sleep, sync DB) freezes the whole event loop, not just one request — exactly like Node. Use async libraries (httpx, asyncpg), or offload with run_in_threadpool / a real queue (Celery, RQ, Dramatiq) for heavy work.

Stage 5 — Production

Run: uvicorn + gunicorn

# dev
fastapi dev main.py
# production (Linux): gunicorn managing uvicorn workers, one per core
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

Each uvicorn worker is an async event loop; gunicorn manages worker processes (restart on crash, graceful reload). Use 2-4× CPU cores for I/O-bound; tune for your load.

Migrations: Alembic

pip install alembic
alembic init alembic
alembic revision --autogenerate -m "create users"
alembic upgrade head

Never create_all in production; use Alembic to version and migrate the schema. See the PostgreSQL tutorial for the migration mindset.

Testing

import pytest
from httpx import AsyncClient, ASGITransport
from app import app

@pytest.fixture
async def client():
    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
        yield c

@pytest.mark.anyio
async def test_root(client):
    r = await client.get("/")
    assert r.status_code == 200
    assert r.json() == {"hello": "world"}

Use httpx.AsyncClient with ASGITransport (no network needed). Override Depends in tests to swap the DB for a test DB or mocks.

The toolchain

Concern	Tool
Run	uvicorn, gunicorn, hypercorn, Docker
DB + migrate	SQLAlchemy (async), asyncpg, Alembic, Tortoise
Test + docs	pytest + httpx, TestClient, /docs + /redoc, mypy/pyright
Auth + extras	OAuth2/JWT, CORS + middleware, background tasks, serverless (Lambda, Cloud Run)

Deploy

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000"]

Or go serverless: FastAPI on AWS Lambda (via Mangum), Google Cloud Run, or Vercel — the ASGI design makes it portable.

Quick-Start Checklist

Install pip install "fastapi[standard]" and run fastapi dev main.py.
Open /docs — your types already generated Swagger UI. That's the FastAPI wow moment.
Define Pydantic models for request bodies and response_model.
Annotate every param — path, query, body; types do the validation.
Split routes into APIRouters; app.include_router(...).
Use Depends for the DB session, auth, settings — not globals.
Go async for DB/HTTP; use asyncpg/SQLAlchemy async/httpx.
Never block the loop — no sync I/O in async handlers.
Set up Alembic for schema migrations; never create_all in prod.
Test with httpx AsyncClient; run uvicorn via gunicorn in production.

Common Pitfalls

Missing type hints — no annotation = no validation, treated as a plain query param. Annotate everything; run mypy.
Blocking calls in async handlers — requests, time.sleep, sync DB freeze the event loop. Use async libs or offload.
response_model omitted — without it, extra fields leak and the OpenAPI schema is wrong. Always set it.
Mutable default shared — rare in Pydantic, but watch Field(default_factory=...) in older code.
create_all in production — no migrations; use Alembic.
One uvicorn worker — underuses multi-core; let gunicorn manage N workers.
Not overriding Depends in tests — test against a real/seeded DB or a mock, via app.dependency_overrides.
Trusting client input — Pydantic validates shape, not business rules; add @field_validator and auth.

Related guides

FastAPI is the Python backend layer — these PyShine tutorials are its stack:

Learn Python in One Post — the language; type hints and async are FastAPI's foundation.
Learn REST API in One Post — methods, status codes, idempotency; FastAPI implements REST.
Learn PostgreSQL in One Post — what SQLAlchemy/asyncpg talks to; Alembic migrates it.
Learn Redis in One Post — cache, sessions, rate limiting behind FastAPI.
Learn Docker in One Post — containerize and ship the app (the Dockerfile above).

FastAPI's pitch is simple: type hints in, production API with docs and validation out. The five stages here — basics, Pydantic, routing + deps, async + DB, production — cover everything from a "hello world" to a containerized, migrated, tested, async API backed by Postgres + Redis. The two habits that pay off: annotate everything (it's where the magic comes from), and never block the event loop (use async libs or offload). Run fastapi dev main.py, open /docs, and watch your types become an interactive API — that's the moment the framework clicks.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn GitHub Actions in a Single Post: A Complete Tutorial From Workflows and Jobs to Runners, Secrets, and Reusable Pipelines

PyShine — Thu, 23 Jul 2026 12:41:51 +0000

Learn GitHub Actions in a Single Post: Complete Tutorial From Workflows and Jobs to Runners, Secrets, and Reusable Pipelines

GitHub Actions is GitHub's built-in CI/CD: you write a YAML file, push it to your repo, and GitHub runs your build, test, deploy — on every push, every pull request, on a schedule, or on demand. It's the CI/CD most open-source and many private projects use, because it's free for public repos, integrated into the platform you already use, and has a marketplace of thousands of pre-built actions. This single post teaches the whole system in five stages, with hand-drawn diagrams and runnable YAML.

Learning Roadmap

The roadmap moves from the workflow file (Stage 1), through jobs and steps (Stage 2), the reusable action ecosystem (Stage 3), where it runs (Stage 4), and the security + reuse layer (Stage 5). You'll want the Git tutorial and basic YAML as prerequisites.

Stage 1 — Workflows

What a workflow is

A workflow is a YAML file in .github/workflows/ that describes an automated process. GitHub reads it and runs it when its trigger (on:) fires.

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]        # trigger: run on push and PR

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

That's a complete CI pipeline: on every push or PR, GitHub checks out your code, installs deps, and runs tests — on a fresh Ubuntu VM, for free (public repos). Push the file and it runs.

Triggers — the `on:` field

on:
  push:
    branches: [main, 'release/*']     # only these branches
  pull_request:
    types: [opened, synchronize]        # on PR open + update
  schedule:
    - cron: '0 2 * * *'                 # nightly at 2am UTC
  workflow_dispatch:                    # manual "Run workflow" button
    inputs:
      env: { type: choice, options: [staging, prod] }
  release:
    types: [published]                  # on release publish
  paths:
    - 'src/**'                          # only if src/ changed (skip docs)

The trigger is the entry point. workflow_dispatch adds a manual button in the Actions tab (great for deploys). schedule uses standard cron. paths filters to only run when relevant files change.

Pitfall: on: [push] runs on every push to every branch. Usually you want on: push: branches: [main] to avoid running CI on every feature branch push (or you might want it — be deliberate).

Stage 2 — Jobs + Steps

The hierarchy: workflow → job → step

Job -> Step -> Action/Run" width="799" height="436">

Workflow — the YAML file; defines triggers and contains jobs.
Job — a set of steps that run on the same runner (VM). Jobs run in parallel by default; use needs: to serialize them into a DAG.
Step — one task: either an action (uses:) or a shell command (run:). Steps run sequentially within a job.

Jobs: parallel and sequential

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  build:
    needs: test                      # wait for test to pass
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'   # only on main
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploying"

Without needs:, jobs run in parallel. With needs:, they form a DAG — test → build → deploy. If test fails, build and deploy don't run.

Steps: `uses` (actions) and `run` (shell)

steps:
  - uses: actions/checkout@v4       # an action (from the marketplace)
  - name: Install deps
    run: npm ci                       # a shell command
  - name: Test
    run: npm test
    env:
      CI: true                        # env var for this step
  - uses: actions/upload-artifact@v4
    with:
      name: coverage
      path: coverage/

uses: runs a pre-built action (from the marketplace or a repo). run: executes a shell command (bash on Linux/macOS, PowerShell on Windows). Each step gets name, with: (inputs), env: (env vars).

Pitfall: actions/checkout@v4 is the first step of almost every job — without it, your runner has an empty workspace. Forget it and every run: npm ... fails with "package.json not found."

Stage 3 — Actions

What an action is

An action is a reusable unit: a step you uses: instead of writing run:. The GitHub Marketplace has thousands — checkout, cache, upload-artifact, setup-node, docker build, slack notify, deploy to AWS/Vercel/Cloudflare...

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 20
  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
  - run: npm ci

Pin to a version

- uses: actions/checkout@v4           # major version (recommended for public)
- uses: actions/checkout@v4.1.0       # exact version (most reproducible)
- uses: actions/checkout@<commit-sha>  # SHA pin (most secure, supply-chain safe)

Pitfall: @main or @master on a third-party action means it can change silently — a supply-chain risk. Pin to a major version (@v4) at minimum; for sensitive workflows, pin to a SHA. GitHub's Dependabot can keep your action versions up to date.

Composite actions — bundle steps

A composite action packages multiple steps into one reusable action:

# .github/actions/setup-and-test/action.yml
name: Setup and Test
inputs:
  node-version: { required: true }
runs:
  using: composite
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with: { node-version: ${{ inputs.node-version }} }
    - run: npm ci && npm test
      shell: bash

# in a workflow
- uses: ./.github/actions/setup-and-test
  with: { node-version: 20 }

Custom actions (Docker / JS)

You can write actions in JavaScript (fast, cross-platform) or as a Docker container (any language, any tool). For most teams, the marketplace + composite covers it; custom is for when you need a tool the marketplace doesn't have.

Stage 4 — Runners

Where it runs

runs-on: ubuntu-latest      # GitHub-hosted: ephemeral Ubuntu VM
# or:
runs-on: [self-hosted, linux, x64]   # your own machine

GitHub-hosted runners are ephemeral VMs GitHub manages — ubuntu-latest, windows-latest, macos-latest. Free for public repos (2,000 min/month free for private). No setup; limited customization.

Self-hosted runners are your own machines (a VM, a k8s pod, a physical box). Full control, can run on your network, no per-minute cost — but you maintain and secure them (apply OS updates, rotate tokens, isolate workloads). Never use self-hosted on public repos with untrusted PRs without sandboxing — a PR can run arbitrary code on your runner.

Matrix — test across combinations

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [18, 20, 22]
runs-on: ${{ matrix.os }}
steps:
  - uses: actions/setup-node@v4
    with: { node-version: ${{ matrix.node }} }

This creates 9 jobs (3 OS × 3 Node versions) — each runs your tests in one combination. Use fail-fast: false to see all failures, not just the first.

Caching and artifacts

# cache npm deps across runs
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: ${{ runner.os }}-npm-

# pass build output to another job
- uses: actions/upload-artifact@v4
  with: { name: build, path: dist/ }
# in the deploy job:
- uses: actions/download-artifact@v4
  with: { name: build, path: dist/ }

Caching cuts install time dramatically (skip re-downloading node_modules on every run). Artifacts pass build outputs between jobs (build → upload → download → deploy) and are stored for 90 days.

Pitfall: The cache key must include something that changes when deps change (hashFiles('**/package-lock.json')). A static key serves a stale cache forever; a too-dynamic key never hits.

Stage 5 — Secrets + Environments

Secrets

# set in repo Settings -> Secrets and variables -> Actions
steps:
  - run: docker push ${{ secrets.REGISTRY }}/app:latest
    env:
      DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}

Secrets are encrypted in the repo/org settings, masked in logs, and available to workflows via ${{ secrets.NAME }}. Never commit secrets to code; never echo them (they'll be masked, but don't risk it). For org-wide secrets, use Organization secrets with selected-repo access.

Environment variables

env:
  CI: true
  NODE_ENV: test
jobs:
  deploy:
    env:
      ENVIRONMENT: production
    steps:
      - run: echo ${{ env.ENVIRONMENT }}

env: at the top level applies to all jobs; at the job level to all steps in that job; at the step level to that step.

Environments (gates + protection)

jobs:
  deploy-prod:
    environment: production     # protected environment
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

An environment (Settings → Environments) can require manual approval, restrict to specific branches, and hold its own secrets. Use environment: production on a deploy job so a human must approve before it runs — a deployment gate.

OIDC — cloud auth without stored keys

permissions:
  id-token: write        # request an OIDC token
  contents: read
jobs:
  deploy:
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123:role/github-actions
          aws-region: us-east-1
      - run: aws s3 cp build/ s3://my-bucket/

OIDC lets GitHub Actions authenticate to your cloud (AWS, GCP, Azure) without storing long-lived keys. GitHub mints a short-lived token; your cloud trusts GitHub's OIDC provider. No key to leak, no rotation — this is the modern, secure way to deploy from CI.

Reusable workflows

# .github/workflows/ci-lib.yml
name: CI Library
on:
  workflow_call:          # callable from other workflows
    inputs:
      node-version: { type: string, required: true }
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: ${{ inputs.node-version }} }
      - run: npm ci && npm test

# .github/workflows/ci.yml — calls the reusable workflow
jobs:
  call-ci:
    uses: ./.github/workflows/ci-lib.yml
    with: { node-version: 20 }

Reusable workflows (workflow_call) let you DRY your CI across many repos or many jobs — define once, call everywhere.

The ecosystem

Concern	Tool/Pattern
Marketplace	checkout, cache, upload-artifact, docker/build-push, slack notify
Reuse	`workflow_call` (reusable workflows), composite actions
Security	secrets, environments (approval gates), OIDC (no stored keys), `permissions:` (least privilege)
Patterns	`needs:` (DAG), `if:` (conditional), `concurrency:` (cancel old runs), `matrix` (combinatorial)

Pitfall: Set permissions: to least-privilege in every workflow. The default token has write access to your repo; a compromised action or a typosquatted dependency could push to your branches. permissions: { contents: read } is the safe default.

Quick-Start Checklist

Create .github/workflows/ci.yml — on: [push], one job, checkout + npm test. Push it.
Watch it run in the Actions tab. Green? You have CI.
Add pull_request trigger so PRs are gated.
Use needs: to build a DAG: test → build → deploy.
Pin action versions (@v4 or SHA), never @main on third-party.
Cache deps with actions/cache keyed on the lockfile hash.
Upload artifacts to pass build outputs to the deploy job.
Store secrets in repo settings, reference via ${{ secrets.X }}.
Add an environment with required approval for production deploys.
Use OIDC for cloud deploys — no stored keys.

Common Pitfalls

Forgetting actions/checkout — the runner starts with an empty workspace; every step that needs your code fails without it.
on: [push] on every branch — usually want branches: [main] to limit runs.
Unpinned third-party actions (@main) — supply-chain risk; pin to a version or SHA.
No cache key or a static key — stale cache or never hits; key on the lockfile hash.
Secrets in logs — they're masked, but don't echo them; don't put them in env var names.
Over-broad permissions: — default token can write to the repo; set contents: read unless you need write.
Self-hosted runners on public repos — a PR can run arbitrary code on your machine; isolate or sandbox.
No concurrency: — pushing rapidly runs redundant workflows; concurrency: { group: ${{ github.ref }}, cancel-in-progress: true } cancels old runs.
Long-lived cloud keys — use OIDC instead; no key to leak or rotate.

Related guides

GitHub Actions is the CI/CD layer that ties the DevOps stack together — these PyShine tutorials connect to it:

Learn Git in One Post — Actions runs on Git events (push, PR, tag); know Git first.
Learn Docker in One Post — CI builds and pushes Docker images; the docker/build-push-action is standard.
Learn Kubernetes in One Post — CI deploys to K8s; kubectl apply from a workflow.
Learn Bash in One Post — every run: step is a shell script; know Bash.
Learn Node.js + Express in One Post — npm ci, npm test are the steps in most JS CI.

GitHub Actions is the CI/CD that's already where your code is — no separate server, no extra account, just a YAML file in your repo. The five stages here — workflows, jobs + steps, actions, runners, secrets + environments — cover everything from a 5-line test job to a matrix-tested, OIDC-authenticated, environment-gated deploy pipeline with reusable workflows. The two habits that pay off: pin your actions (supply-chain safety) and set permissions: to least privilege (the default token is too powerful). Write a ci.yml, push it, watch the green checkmark, and you've got CI — then layer in caching, artifacts, and a gated deploy as you grow.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn HTML and CSS in a Single Post: A Complete Tutorial From Semantic Markup and the Box Model to Flexbox, Grid, and Responsive Design

PyShine — Thu, 23 Jul 2026 12:32:59 +0000

Learn HTML and CSS in a Single Post: Complete Tutorial From Semantic Markup to Flexbox, Grid, and Responsive Design

HTML is the structure of every web page; CSS is how it looks. Together they're the foundation of all frontend development — and unlike frameworks that come and go, the core has been stable for two decades. This single post teaches both in five stages, with hand-drawn diagrams and runnable snippets you can paste into a .html file and open in a browser.

Learning Roadmap

The roadmap moves from HTML structure (Stage 1), through CSS fundamentals (Stage 2), to layout (Stage 3), responsive design (Stage 4), and modern CSS + tooling (Stage 5).

Stage 1 — HTML: Structure

A minimal page

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Page</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <h1>Hello, HTML!</h1>
  <p>This is a paragraph.</p>
  <script src="app.js"></script>
</body>
</html>

<!DOCTYPE html> triggers standards mode. <head> holds metadata (title, charset, viewport, stylesheet links — not shown on the page); <body> holds the visible content. The viewport meta tag is mandatory for responsive design on mobile.

Elements, tags, attributes

Element — a piece of content wrapped in tags: <p>text</p>. Most elements have opening and closing tags; a few are void (self-closing): <img>, <br>, <input>, <meta>, <link>.
Attributes — key/value pairs on the opening tag: <a href="...">, <img src="..." alt="...">, <input type="text" required>.
Nesting — elements contain elements; the result is a tree.

Semantic HTML

Use elements that describe meaning, not appearance. Semantic HTML helps accessibility (screen readers), SEO (search engines understand structure), and maintainability:

Semantic	Use for
`<header>` / `<footer>`	page or section header/footer
`<nav>`	navigation links
`<main>`	the main content (one per page)
`<article>`	a self-contained composition (a blog post, a card)
`<section>`	a thematic grouping
`<aside>`	tangentially related (sidebar, ad)
`<h1>`–`<h6>`	headings (one `<h1>` per page)
`<figure>` / `<figcaption>`	an image with a caption
`<time>`	a date/time

Avoid <div> and <span> when a semantic element fits — they carry no meaning. Use them only as generic containers for styling.

From HTML to the DOM

DOM -> Render" width="800" height="400">

The browser parses your HTML into a tree called the DOM (Document Object Model), then applies CSS, lays out boxes, and paints pixels. JavaScript manipulates the DOM; DevTools (the Elements panel) shows it live. Every "frontend bug" is ultimately about the DOM, the CSS applied to it, or the layout it produces.

Stage 2 — CSS Basics

Selectors and the cascade

CSS targets elements with selectors and applies declarations (property: value):

/* element selector */
p { color: #333; }

/* class (.name) — reusable */
.button { padding: 8px 16px; }

/* id (#name) — unique, high specificity, avoid for styling */
#hero { background: #f0f0f0; }

/* descendant */
nav a { text-decoration: none; }

/* pseudo-class (state) */
a:hover { color: blue; }
input:focus { border-color: blue; }

/* combinators */
h1 + p { margin-top: 0; }   /* adjacent sibling */
.list > li { ... }           /* direct child */

Specificity

When two rules target the same element, specificity decides which wins — not "which comes later." The score is (inline, IDs, classes/attrs/pseudo-classes, elements):

* → 0,0,0,0
p → 0,0,0,1
.button → 0,0,1,0
#hero → 0,1,0,0
style="..." (inline) → 1,0,0,0
!important → overrides everything (avoid)

Pitfall: "My CSS isn't applying!" is almost always a specificity loss or a typo in the selector. Use the DevTools Elements panel — it shows every rule applied to an element and which won, with the losers struck through. Don't reach for !important; fix the specificity.

The box model

Every element is a box with four layers:

content — the text/image itself.
padding — space inside the border (background fills this).
border — the line around padding.
margin — space outside the border (transparent; collapses with neighbors).

.box {
  width: 200px;
  padding: 20px;
  border: 2px solid #333;
  margin: 16px;
  box-sizing: border-box;   /* width INCLUDES padding + border */
}

Pitfall: By default, width sets the content box, so width: 200px + padding: 20px + border: 2px = 244px wide — surprises everyone. Set box-sizing: border-box globally (*, *::before, *::after { box-sizing: border-box; }) so width includes padding and border. It's the first line of every modern stylesheet.

Stage 3 — Layout

Normal flow

Without CSS, elements stack in normal flow: block elements (<div>, <p>, <h1>) stack vertically and take full width; inline elements (<span>, <a>, <strong>) flow like text. display changes this: display: block, inline, inline-block (inline but accepts width/height).

Flexbox (1D layout)

Flexbox lays items in one direction (a row or column) and aligns them. It's the default for navbars, card rows, and centering.

.nav {
  display: flex;
  justify-content: space-between;  /* main axis: spread items */
  align-items: center;             /* cross axis: vertically center */
  gap: 16px;
}
.nav .logo { margin-right: auto; }  /* push the rest to the right */

Key properties: flex-direction (row/column), justify-content (main-axis alignment), align-items (cross-axis alignment), gap (spacing between items), flex (grow/shrink on children). The modern centering one-liner: .parent { display: grid; place-items: center; } or .parent { display: flex; align-items: center; justify-content: center; }.

CSS Grid (2D layout)

Grid lays items in two dimensions (rows and columns). Use it for page layouts and dashboards:

.page {
  display: grid;
  grid-template-columns: 200px 1fr;   /* sidebar + flexible main */
  grid-template-rows: auto 1fr auto;
  gap: 16px;
  min-height: 100vh;
}

1fr is "one fraction of the remaining space"; auto sizes to content. grid-template-areas lets you name regions for a visual layout. Rule of thumb: Grid for page-level 2D structure, Flexbox for 1D component layout.

Positioning

position takes an element out of normal flow:

Value	Behavior
`static` (default)	normal flow
`relative`	offset from its normal position; keeps its space
`absolute`	positioned relative to nearest positioned ancestor; removed from flow
`fixed`	positioned relative to the viewport (stays on scroll)
`sticky`	normal flow until it hits a threshold, then sticks (sticky headers)

Pitfall: position: absolute without a positioned ancestor positions relative to the viewport-ish root, surprising everyone. Set position: relative on the parent you want it anchored to.

Stage 4 — Responsive Design

The viewport meta tag

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Without this, mobile browsers render the desktop layout at ~980px and zoom out — tiny and unusable. This tag makes the layout match the device width.

Media queries

/* base: mobile-first (smallest screens) */
.card { grid-template-columns: 1fr; }

/* tablets and up */
@media (min-width: 600px) {
  .card { grid-template-columns: 1fr 1fr; }
}

/* desktops */
@media (min-width: 900px) {
  .card { grid-template-columns: repeat(3, 1fr); }
}

Mobile-first means the base styles target small screens and min-width queries add complexity for larger ones. It's simpler and faster on mobile (less CSS to override) than desktop-first with max-width.

Fluid units

% — relative to the parent.
vw / vh — 1% of viewport width/height.
rem — relative to the root font size (scales with user zoom; prefer for text and spacing).
em — relative to the element's own font size (cascades; tricky for spacing).
clamp(min, ideal, max) — fluid value with bounds: font-size: clamp(1rem, 2.5vw, 2rem).

h1 { font-size: clamp(1.5rem, 5vw, 3rem); }   /* grows with viewport, bounded */
img { max-width: 100%; height: auto; }         /* never overflow container */

Pitfall: Hardcoded width: 800px overflows on phones. Use max-width + relative units so content shrinks to fit. Test by resizing the browser window to ~360px wide — your layout should survive.

Stage 5 — Modern CSS + Tooling

Custom properties (CSS variables)

:root {
  --brand: #2563eb;
  --space: 16px;
  --radius: 8px;
}
.button {
  background: var(--brand);
  padding: var(--space);
  border-radius: var(--radius);
}
.button:hover { background: color-mix(in srgb, var(--brand), black 10%); }

Variables cascade (override in a scope), theme dynamically ([data-theme="dark"] { --brand: #58a6ff; }), and reduce duplication. This site's own dark theme uses them — see the categories page fix for a real example.

Transitions and animations

.button { transition: background 0.2s ease, transform 0.2s ease; }
.button:hover { background: #1e40af; transform: translateY(-1px); }

@keyframes spin { to { transform: rotate(360deg); } }
.spinner { animation: spin 1s linear infinite; }

transition smoothly interpolates between states; @keyframes define multi-step animations. Respect users who prefer reduced motion: @media (prefers-reduced-motion: reduce) { * { animation: none !important; transition: none !important; } }.

The toolchain

Browsers: Chrome (Blink/V8), Firefox (Gecko), Safari (WebKit) — test in all three; they render differently.
DevTools: Elements (inspect DOM/CSS live), Console (JS), Network (requests), Performance (flame graph). F12 / Cmd+Opt+I. The Elements panel is your primary debugging tool.
Frameworks: React/Vue/Svelte (component-based JS frameworks that generate HTML), Tailwind (utility-class CSS), Bootstrap (component CSS).
Build + check: Vite/Webpack (bundle + dev server), PostCSS (transform CSS — autoprefixer, nesting), ESLint/Stylelint (lint), Lighthouse (audit performance + accessibility).

Accessibility (a11y)

Good HTML is mostly accessible by default: use semantic elements, real <button>/<a> (not <div onclick>), alt on images, label on inputs, sufficient color contrast (4.5:1 for text). Test with the keyboard (Tab through) and a screen reader. Lighthouse scores accessibility automatically.

Quick-Start Checklist

Write a minimal page — <!DOCTYPE html>, head with viewport, body, link a CSS file. Open it in a browser.
Use semantic HTML — <header>, <nav>, <main>, <article>, <h1>–<h6> over <div>.
Set box-sizing: border-box globally — it's the first line of your CSS.
Learn selectors + specificity — and debug with the DevTools Elements panel, not !important.
Center things with Flexbox/Grid — display: grid; place-items: center;.
Use Grid for 2D page layout, Flexbox for 1D components.
Make it responsive — viewport meta, max-width + relative units, mobile-first media queries.
Use CSS variables for colors, spacing, radii — theme by overriding in a scope.
Test in Chrome, Firefox, Safari and at 360px width.
Run Lighthouse — it audits performance, accessibility, and SEO in one click.

Common Pitfalls

No viewport meta tag — the page is unusably tiny on mobile. Always include it.
width without box-sizing: border-box — padding + border make the box bigger than expected. Set border-box globally.
!important to force a style — a specificity loss you're patching; fix the selector instead.
<div onclick> instead of <button> — breaks keyboard navigation and screen readers. Use real interactive elements.
Hardcoded px widths — overflow on small screens. Use max-width + relative units.
position: absolute without a positioned parent — anchors to the wrong reference. Set position: relative on the intended parent.
Forgetting alt on images — fails accessibility and SEO. Decorative images get alt="".
Desktop-first media queries — more CSS to override on mobile; go mobile-first with min-width.
Low color contrast — text on a low-contrast background is unreadable; aim for 4.5:1.

Related guides

HTML/CSS is the foundation of all web work — these PyShine tutorials build on it:

Learn JavaScript + TypeScript in One Post — JS manipulates the DOM this post describes; the two are inseparable.
Learn REST API in One Post — the frontend fetches data from these APIs.
Learn Computer Networking in One Post — HTTP, the browser, and the request lifecycle under every page load.
Learn SQL in One Post — the data behind most pages.
Learn Bash in One Post — curl, build scripts, and the CLI around your frontend tooling.

HTML and CSS are unusual in tech: the fundamentals you learn today will still be valid in twenty years. The five stages here — structure, styling, layout, responsive, modern — cover everything you need to build any web page, and the frameworks (React, Vue, Tailwind) are all conveniences on top of these primitives. Spend a day per stage, build a real page (a portfolio, a blog), resize the browser to 360px, run Lighthouse, and fix what it flags. The skills only stick once you've fought a layout into working at every width — so open a text file and start.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Kubernetes in a Single Post: A Complete K8s Tutorial From Pods and Deployments to Services and Production Operations

PyShine — Thu, 23 Jul 2026 12:32:47 +0000

Learn Kubernetes in a Single Post: Complete Tutorial From Pods and Deployments to Services and Production

Kubernetes is the operating system of the cloud. It takes the container idea from Docker and adds orchestration at scale: it schedules containers across a cluster of machines, restarts them when they fail, scales them on demand, load-balances traffic, and rolls out new versions without downtime. This single post teaches the whole platform in five stages, with hand-drawn diagrams and runnable manifests.

Learning Roadmap

The roadmap moves from understanding why Kubernetes exists (Stage 1), through the core workload objects (Stage 2), networking and storage (Stage 3), scheduling and scaling (Stage 4), to production operations (Stage 5).

Stage 1 — Fundamentals: Why Kubernetes, Pods, kubectl

Why Kubernetes?

Docker runs containers on one machine. The moment you have more than one machine — or you need your containers to survive crashes, scale with load, or update without downtime — you need an orchestrator. Kubernetes (K8s) is the standard: it runs your containers across a cluster, keeps the desired state reconciled against reality, and exposes a single API.

Pods: the atom of Kubernetes

A Pod is the smallest deployable unit — one or more containers that share a network namespace (same IP, same port space) and storage volumes. You almost never create a Pod directly; you create a Deployment, which creates a ReplicaSet, which creates Pods.

# a single Pod (rarely written by hand)
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
    - name: nginx
      image: nginx:1.27-alpine
      ports:
        - containerPort: 80

Cluster architecture

A cluster has two planes:

Control plane (master) — the brain: kube-apiserver (the API you talk to), etcd (the cluster's key-value store of record), kube-scheduler (decides which node runs which Pod), kube-controller-manager (reconciles state), and the cloud-controller-manager (talks to your cloud).
Worker nodes (data plane) — where your Pods run: each has kubelet (talks to the control plane), kube-proxy (networking), and a container runtime (containerd).

kubectl basics

kubectl get pods                    # list pods in the default namespace
kubectl get pods -A                # all namespaces
kubectl get pods -o wide           # more detail (node, IP)
kubectl describe pod nginx         # deep inspect (events, state)
kubectl logs nginx                 # stdout of the pod's container
kubectl logs -f nginx              # follow (tail)
kubectl exec -it nginx -- sh       # shell into the container
kubectl apply -f manifest.yaml      # create/update from a file
kubectl delete -f manifest.yaml     # delete
kubectl delete pod nginx           # delete one pod (a Deployment will recreate it)
kubectl get all                    # everything in the namespace

Pitfall: kubectl delete pod <name> when the Pod is owned by a Deployment just kills that Pod — the ReplicaSet immediately creates a replacement. To actually scale down, change the Deployment's replicas.

Stage 2 — Workload Objects: Deployment, ReplicaSet, Job

The Pod-ReplicaSet-Deployment-Service hierarchy is the core mental model.

Deployment

A Deployment declares the desired state (image, replicas, ports) and the controller reconciles reality to it. Updating the image triggers a rolling update; the old ReplicaSet is scaled down as the new one scales up, with automatic rollback if the rollout fails.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:           # the Pod template every replica uses
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: myapi:1.0
          ports:
            - containerPort: 8000
          resources:
            requests: { cpu: "100m", memory: "128Mi" }
            limits:   { cpu: "500m", memory: "512Mi" }

kubectl apply -f deployment.yaml
kubectl rollout status deployment/api
kubectl set image deployment/api api=myapi:1.1    # rolling update
kubectl rollout undo deployment/api               # rollback
kubectl scale deployment/api --replicas=5          # manual scale

ReplicaSet

The Deployment creates a ReplicaSet to guarantee replicas copies are running. You rarely touch ReplicaSets directly — the Deployment owns them. Each rollout creates a new ReplicaSet; old ones are kept (scaled to 0) for rollback history.

Job and CronJob

For work that runs to completion (batch, migrations, backups), use a Job; for scheduled work, a CronJob:

apiVersion: batch/v1
kind: Job
metadata: { name: db-migrate }
spec:
  backoffLimit: 3            # retries on failure
  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: migrate
          image: myapi:1.0
          command: ["./migrate.sh"]

Stage 3 — Networking + Storage

Service

Pods are ephemeral (they die and get recreated with new IPs). A Service gives them a stable IP + DNS name and load-balances across the matching Pods:

apiVersion: v1
kind: Service
metadata: { name: api }
spec:
  selector:
    app: api          # routes to pods with this label
  ports:
    - port: 80
      targetPort: 8000

Three Service types:

ClusterIP (default) — reachable only inside the cluster.
NodePort — exposes on each node's IP at a port (30000–32767).
LoadBalancer — provisions a cloud load balancer (AWS ELB, GCLB).

Ingress

For HTTP(S) routing by host/path, use an Ingress (needs an Ingress controller like nginx-ingress or Traefik):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata: { name: api }
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: { name: api, port: { number: 80 } }

ConfigMap and Secret

Decouple config from images. A ConfigMap holds non-sensitive config; a Secret holds sensitive data (base64 — not encryption by default).

apiVersion: v1
kind: ConfigMap
metadata: { name: api-config }
data:
  LOG_LEVEL: "info"
  DB_HOST: "db.default.svc"
---
apiVersion: v1
kind: Secret
metadata: { name: api-secret }
type: Opaque
stringData:
  API_KEY: "super-secret"      # stringData avoids manual base64

Mount them as env vars or as files in a volume:

spec:
  containers:
    - name: api
      envFrom:
        - configMapRef: { name: api-config }
        - secretRef:    { name: api-secret }

Volumes, PersistentVolume, PersistentVolumeClaim

Pod filesystems are ephemeral. For persistent data, a PersistentVolumeClaim (PVC) requests storage; Kubernetes binds it to a PersistentVolume (PV) provisioned by a CSI driver:

apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: data }
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests: { storage: 10Gi }

spec:
  containers:
    - name: db
      volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
  volumes:
    - name: data
      persistentVolumeClaim: { claimName: data }

Stage 4 — Scheduling + Scaling

Labels and selectors

Labels are key/value pairs on objects; selectors query them. This is how Services find their Pods and how Deployments manage their ReplicaSets.

metadata:
  labels:
    app: api
    tier: backend
    env: prod

kubectl get pods -l app=api,env=prod

Probes: liveness and readiness

Probes tell Kubernetes whether a container is healthy and whether it's ready to receive traffic:

livenessProbe:
  httpGet: { path: /health, port: 8000 }
  initialDelaySeconds: 10
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /ready, port: 8000 }
  initialDelaySeconds: 5
  periodSeconds: 5

Liveness — fails → restart the container (recovers from deadlock).
Readiness — fails → remove the Pod from the Service's endpoints (stops routing to it, but doesn't restart).

Horizontal Pod Autoscaler (HPA)

The HPA scales a Deployment based on CPU/memory (or custom metrics):

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: api }
spec:
  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: api }
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }

Resources, affinity, and node affinity

Always set resources.requests and resources.limits — without them the scheduler can't place your Pod sanely and a runaway container can starve a node. Node affinity/anti-affinity controls which nodes a Pod can land on; pod anti-affinity spreads replicas across nodes.

Stage 5 — Production + Operations

Core objects overview

Beyond Deployments, learn these as needed: StatefulSet (databases — ordered, stable identity), DaemonSet (one Pod per node — logging agents), Namespace (logical partition + RBAC scope), ServiceAccount (Pod identity for API access), HPA/VPA (horizontal/vertical autoscaling).

Helm: the package manager

Helm packages manifests into reusable charts with templated values:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install my-db bitnami/postgresql --set auth.postgresPassword=secret
helm upgrade my-db bitnami/postgresql --set replicaCount=3
helm uninstall my-db

Kustomize: overlay patches

Kustomize composes overlays (dev/staging/prod) over a base without templating:

kubectl apply -k overlays/prod

RBAC

Role-Based Access Control scopes what a user or ServiceAccount can do:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: { name: pod-reader, namespace: dev }
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list"]

Bind it to a ServiceAccount with a RoleBinding.

Observability + GitOps

Metrics: Prometheus (scrapes kubelet/cAdvisor) + Grafana.
Logs: Loki or ELK aggregating container stdout.
Tracing: OpenTelemetry / Jaeger.
GitOps: ArgoCD or Flux watches a Git repo and applies changes to the cluster — the repo is the source of truth, not kubectl apply from a laptop.

The toolchain

Interface	What it standardizes	Examples
CRI (Container Runtime Interface)	how K8s runs containers	containerd, CRI-O
CNI (Container Network Interface)	pod networking	Calico, Cilium, Flannel
CSI (Container Storage Interface)	persistent volumes	Longhorn, Rook, cloud CSI
CLI / packaging	how you drive K8s	kubectl, helm, kustomize, k9s

Quick-Start Checklist

Get a cluster — kind (Kubernetes-in-Docker) or minikube for local; a managed cluster (GKE/EKS/AKS) for real.
Run kubectl — kubectl get nodes, kubectl get pods -A. Understand the cluster is up.
Apply a Deployment — the nginx example above, then kubectl get pods.
Expose a Service — kubectl expose deployment api --port=80 --type=LoadBalancer.
Add a liveness/readiness probe so unhealthy Pods self-heal.
Set resource requests/limits on every container.
Add a ConfigMap + Secret and mount them as env/volume.
Attach a PVC for persistent data.
Install something with Helm (e.g. bitnami/postgresql) to see packaging.
Roll out an update and kubectl rollout undo it — see rolling updates work.

Common Pitfalls

No resource requests/limits — the scheduler can't place Pods sanely; one container can starve a node. Always set them.
Missing readiness probe — traffic routes to a Pod before it's ready, or stays pointed at a dead Pod. Both probes matter.
Deleting a Pod owned by a Deployment — the ReplicaSet just recreates it. Change the Deployment, not the Pod.
Secrets aren't encrypted by default — base64 only. Enable etcd encryption at rest and use a secrets manager (External Secrets, Vault) for production.
Forgetting namespaces — objects in different namespaces can't reach each other by short DNS name; use svc.namespace.svc.cluster.local.
NodePort in production — use Ingress or LoadBalancer; NodePort exposes random high ports on every node.
:latest image tag — K8s won't pull a new image on apply if the tag is unchanged and imagePullPolicy defaults. Pin versions or set imagePullPolicy: Always.
No PodDisruptionBudget — voluntary disruptions (drains) can take down all replicas at once. Add a PDB for HA workloads.

Related guides

Kubernetes is the capstone of the container + DevOps stack — these PyShine tutorials lead into it:

Learn Docker in One Post: Complete Tutorial — K8s runs containers; Docker is the prerequisite. A Pod is one or more containers.
Learn Git in One Post: Complete Tutorial — GitOps (ArgoCD/Flux) drives clusters from a Git repo.
Learn Bash in One Post: Complete Tutorial — kubectl pipelines, deploy scripts, and k9s are all shell-driven.
Learn YAML / REST API in One Post — every K8s manifest is YAML; the control plane is a REST API.
Learn Go in One Post: Complete Tutorial — Kubernetes itself is written in Go; operators are too.

Kubernetes has a reputation for complexity, but its core is a small set of ideas: desired state in manifests, controllers that reconcile reality to it, and labels that wire objects together. Spend a day per stage and you'll move from "I can run kubectl get pods" to "I can write a Deployment with probes, expose it via a Service and Ingress, persist its data with a PVC, and roll out a new version with a rollback ready." From there, Helm, Kustomize, and GitOps are the production layer. Run every manifest above against a kind or minikube cluster; K8s is learned by applying, not by reading.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Linear Algebra for Machine Learning in a Single Post: A Complete Tutorial From Vectors and Matrices to SVD and Neural Network Weights

PyShine — Thu, 23 Jul 2026 12:32:31 +0000

Learn Linear Algebra for Machine Learning in a Single Post: Complete Tutorial From Vectors and Matrices to SVD and Neural Network Weights

Linear algebra is the language of machine learning: every neural network is a series of matrix multiplications, every embedding is a vector, every gradient is a vector, and every dimensionality reduction is a matrix decomposition. If you understand vectors, matrices, and their operations, you can read the internals of any ML framework. This single post teaches the whole subject in five stages, with hand-drawn diagrams and runnable NumPy.

Learning Roadmap

The roadmap moves from vectors (Stage 1), through matrices (Stage 2), transformations (Stage 3), decomposition (Stage 4), and the ML applications that tie it all together (Stage 5).

Stage 1 — Vectors

What a vector is

A vector is an ordered list of numbers — a point in space, a direction, or a data point. In ML, a vector is how you represent a data sample (its features) or a learned parameter (a weight vector).

import numpy as np

v = np.array([3, 4])          # a 2D vector
w = np.array([1, 2, 3])      # a 3D vector

Magnitude (length)

The magnitude (or norm) of a vector is its length: ||v|| = sqrt(sum(vi^2)).

np.linalg.norm(v)             # 5.0 (3-4-5 triangle)

Dot product — the most important operation

The dot product of two vectors measures their alignment: a · b = sum(ai * bi). It's the foundation of similarity, attention, and projection.

a = np.array([1, 2, 3])
b = np.array([4, 5, 6])
np.dot(a, b)                   # 1*4 + 2*5 + 3*6 = 32

Geometric meaning: a · b = ||a|| ||b|| cos(θ). If the dot product is:

Positive → vectors point roughly the same direction (acute angle).
Zero → vectors are orthogonal (perpendicular; 90°).
Negative → vectors point roughly opposite (obtuse angle).

This is why cosine similarity (dot product of normalized vectors) measures how similar two embeddings are — it's the cosine of the angle between them.

Angle and cosine similarity

cos_sim = np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
# = cos(angle between a and b)
# 1 = identical, 0 = orthogonal, -1 = opposite

Projection

The projection of a onto b is the shadow of a cast onto the line of b:

proj = (np.dot(a, b) / np.dot(b, b)) * b

Projection is how PCA finds the directions of maximum variance — it projects data onto principal axes. It's also how attention works: the query projects onto the keys.

Stage 2 — Matrices

What a matrix is

A matrix is a 2D grid of numbers — a collection of vectors (rows or columns), or a linear transformation (a function that maps vectors to vectors). In ML, a matrix is a weight layer, a batch of data, or a covariance.

A = np.array([[1, 2], [3, 4]])    # 2x2 matrix
B = np.array([[5, 6], [7, 8]])    # 2x2

Matrix multiplication

C = A @ B — the inner dimensions must match: (m × n) @ (n × p) → (m × p). Each element C[i,j] is the dot product of row i of A with column j of B.

C = A @ B                       # (2x2) @ (2x2) -> (2x2)
# [[19, 22],
#  [43, 50]]

Matrix multiplication is composition: applying B then A is A @ B. Order matters — AB ≠ BA in general (non-commutative). This is why the order of layers in a neural network matters.

Key matrix properties

Property	Formula	Meaning
Identity	`I: A @ I = A`	does nothing (like multiplying by 1)
Transpose	`A^T: swap rows/cols`	flips the matrix
Inverse	`A^-1: A @ A^-1 = I`	undoes the transform (if it exists)
Determinant	`det(A)`	volume scaling factor; 0 = singular (no inverse)

A.T                              # transpose
np.linalg.inv(A)                # inverse (if det != 0)
np.linalg.det(A)                 # determinant
np.eye(3)                        # 3x3 identity

Pitfall: Not every matrix has an inverse. A matrix with det = 0 is singular — its columns are linearly dependent (one is a combination of others). This is why collinear features in ML cause numerical instability.

Stage 3 — Linear Transformations

A matrix is a transformation

Multiplying a vector by a matrix transforms it: rotates, scales, shears, or projects it. The matrix is the function; the vector is the input.

# rotation by 45 degrees
theta = np.pi / 4
R = np.array([[np.cos(theta), -np.sin(theta)],
              [np.sin(theta),  np.cos(theta)]])
v = np.array([1, 0])
R @ v                            # rotated vector

Transform	Matrix (2D)	Effect
Rotation	`[[cos, -sin], [sin, cos]]`	rotates by angle θ
Scaling	`[[s, 0], [0, s]]`	stretches/shrinks
Reflection	`[[-1, 0], [0, 1]]`	flips
Shear	`[[1, k], [0, 1]]`	slides one axis
Projection	onto a subspace	reduces dimensionality

Eigenvectors and eigenvalues

An eigenvector of a matrix A is a vector that only scales (doesn't rotate) when transformed: A v = λ v. The eigenvalue λ is how much it scales.

eigenvalues, eigenvectors = np.linalg.eig(A)
# eigenvalues: the scaling factors
# eigenvectors: the directions that don't rotate

Eigenvectors are the natural axes of a transformation. This is the foundation of PCA (Stage 4) — the principal components are the eigenvectors of the covariance matrix, and the eigenvalues tell you how much variance each captures.

Pitfall: Not every matrix has real eigenvalues. A rotation by 90° has no real eigenvector (every vector rotates). Symmetric matrices (like covariance matrices) always have real eigenvalues — which is why PCA always works.

Stage 4 — Decomposition: SVD, PCA, Rank

SVD (Singular Value Decomposition)

SVD decomposes any matrix A into three matrices: A = U Σ V^T:

U — left singular vectors (output directions)
Σ — singular values (diagonal; how much each direction matters)
V^T — right singular vectors (input directions)

U, S, Vt = np.linalg.svd(A)
# A = U @ np.diag(S) @ Vt

SVD is the most general decomposition — it works on any matrix (even non-square, even singular). It reveals the "structure" of the matrix: the singular values tell you the rank (how many independent directions) and the importance of each.

Rank-k approximation

Keep only the top k singular values → a rank-k approximation that captures the most information with the fewest dimensions:

k = 2
A_approx = U[:, :k] @ np.diag(S[:k]) @ Vt[:k, :]
# compresses A to its k most important directions

This is how image compression, denoising, and recommendation systems (Netflix prize) work — truncate to the top-k singular values.

PCA (Principal Component Analysis)

PCA is SVD applied to centered data — it finds the directions (principal components) of maximum variance:

from sklearn.decomposition import PCA
pca = PCA(n_components=2)
X_2d = pca.fit_transform(X)      # 1000D -> 2D, preserving max variance
print(pca.explained_variance_ratio_)  # how much each PC captures

PCA centers the data (subtract the mean), computes the covariance matrix, eigendecomposes it, and projects onto the top-k eigenvectors. It's SVD on centered data — the same math, applied to find the most informative axes.

Rank

The rank of a matrix is the number of linearly independent rows/columns — the number of genuinely different directions. A rank-1 matrix is an outer product of two vectors; a full-rank square matrix has an inverse. Rank deficiency (rank < dimensions) means redundant information.

Pitfall: PCA assumes linear relationships and that high-variance directions are the most informative. If your data's structure is non-linear (clusters, manifolds), PCA won't find it — use t-SNE, UMAP, or an autoencoder instead.

Stage 5 — ML Applications

Neural network weights are matrices

A neural network layer is literally a matrix multiplication + a bias + an activation:

y = activation(W @ x + b)
# W: weight matrix (out_dim x in_dim)
# x: input vector (in_dim)
# b: bias vector (out_dim)
# y: output vector (out_dim)

The forward pass of a deep network is a sequence of matrix multiplications. A batch of B inputs is a B × in_dim matrix, and the layer is W @ X^T (or X @ W^T depending on convention). GPUs are fast at matrix multiplication — this is why deep learning runs on GPUs (and why NVIDIA is worth what it is).

Embeddings are vectors

An embedding (word2vec, GPT, CLIP) turns a discrete object (a word, an image, a user) into a vector in a continuous space where similar things are close. Similarity is the dot product (or cosine), and nearest-neighbor search is finding the closest vectors. The pgvector extension stores and searches these.

Attention is dot products

Self-attention in a transformer is literally batched matrix multiplications of dot products:

Attention(Q, K, V) = softmax(Q @ K^T / sqrt(d)) @ V

Q @ K^T is a matrix of dot products — every query attends to every key. The softmax normalizes to attention weights, then @ V takes the weighted combination. The entire transformer is linear algebra: matrix multiplications, element-wise operations, and nonlinearities.

Gradient descent is vector math

The gradient of the loss is a vector pointing in the direction of steepest ascent. Gradient descent steps in the opposite direction: w -= lr * gradient. The Hessian (second derivative) is a matrix giving curvature information. Stochastic gradient descent, Adam, and all optimizers are linear-algebra operations on the loss landscape.

Covariance and correlation

The covariance matrix of a dataset is X^T X / (n-1) (after centering) — it captures how features vary together. Its eigenvectors are the principal components (PCA). Correlation is normalized covariance. These are the statistics that PCA, factor analysis, and portfolio optimization build on.

Quick-Start Checklist

Install NumPy — pip install numpy; it's the linear algebra library for Python.
Play with vectors — np.array, np.dot, np.linalg.norm, cosine similarity.
Multiply matrices — A @ B; understand the dimension rule and non-commutativity.
Compute eigendecomposition — np.linalg.eig on a symmetric matrix; verify A @ v = λ v.
Run SVD — np.linalg.svd on a real matrix; reconstruct it from U Σ V^T.
Do PCA — sklearn.decomposition.PCA; reduce a high-D dataset to 2D; plot it.
Trace a neural network layer — see that nn.Linear is W @ x + b.
Understand attention — trace Q @ K^T as a matrix of dot products.
Read gradient descent — w -= lr * grad as a vector operation.
Use cosine similarity on real embeddings — measure how close two word vectors are.

Common Pitfalls

Dimension mismatch in matmul — (m × n) @ (n × p); the inner dims must match. The #1 NumPy bug is a shape error from forgetting to transpose.
Non-commutativity — AB ≠ BA; the order of matrix multiplication matters (and so does the order of neural network layers).
Singular matrix — det = 0 means no inverse; collinear features cause this and numerical instability.
Confusing row vs column vectors — NumPy is row-major; v is 1D (no row/column distinction), but v.reshape(-1, 1) makes it a column. Mind the shapes.
PCA on non-centered data — PCA centers internally, but if you do SVD by hand, center first or the first component is the mean, not a direction of variance.
Assuming PCA finds non-linear structure — PCA is linear; clusters and manifolds need t-SNE/UMAP/autoencoders.
Floating point in linear algebra — A @ inv(A) isn't exactly I due to floating point; use np.allclose not ==.

Related guides

Linear algebra is the math layer under ML and DL — these PyShine tutorials apply it:

Learn Machine Learning in One Post — PCA, embeddings, and model weights are all linear algebra.
Learn Deep Learning in One Post — every layer is a matmul; attention is Q·K; gradients are vectors.
Learn Python in One Post — NumPy is the Python linear algebra library.
Learn PostgreSQL in One Post — pgvector stores and searches embedding vectors.
Learn Data Structures and Algorithms in One Post — matrix chain multiplication is a classic DP; graph algorithms use adjacency matrices.

Linear algebra is the math that makes ML computable: vectors represent data and parameters, matrices represent transformations, and decompositions reveal structure. The five stages here — vectors, matrices, transformations, decomposition, ML applications — cover everything from a dot product to the attention mechanism in a transformer. The two habits that pay off: always mind the shapes (dimension mismatch is the #1 bug), and think geometrically — a dot product is an angle, a matrix is a transformation, an eigenvector is a natural axis. Open a Python REPL, create two vectors, take their dot product, compute the cosine similarity, and watch a · b / (||a|| ||b||) give you the angle between them — once you see the geometry, the algebra makes sense.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Machine Learning in a Single Post: A Complete Tutorial From Supervised Learning and Clustering to Neural Networks and the ML Workflow

PyShine — Thu, 23 Jul 2026 12:31:28 +0000

Learn Machine Learning in a Single Post: Complete Tutorial From Supervised Learning to Neural Networks and the ML Workflow

Machine learning is the practice of building systems that learn patterns from data instead of being explicitly programmed. It powers search ranking, recommendation, fraud detection, speech recognition, self-driving perception, and every modern AI product. This single post teaches the whole field in five stages, with hand-drawn diagrams and runnable Python snippets — from the simplest linear model to what a neural network actually does.

Learning Roadmap

The roadmap moves from the core concepts (Stage 1), through the three paradigms (Stages 2-4), to the end-to-end workflow that ties them together (Stage 5). You'll want Python and basic linear algebra as prerequisites.

Stage 1 — Core Concepts

What is machine learning?

A model is a function f(x) -> y that maps inputs (features) to outputs. Learning is the process of finding the f that best fits your data, by minimizing some measure of how wrong it is. You don't write f by hand — you define a family of possible functions (linear, tree, neural net) and an optimization process searches for the best member of that family.

Features, labels, examples

Example / sample — one data point (a row).
Features (X) — the inputs: the things you measure. For a house: square footage, bedrooms, zip code.
Label (y) — the output you're predicting, if you have one: the house's sale price.
Dataset — a collection of (X, y) pairs (supervised) or just X (unsupervised).

Train / validation / test

You train on one set of data, validate (tune) on another, and test (final honest evaluation) on a third you've never touched. The cardinal sin: evaluating on data you trained on — the model has memorized it, so the score is meaningless.

from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

Bias-variance and overfitting

Overfitting — the model fits the training data perfectly (memorizes noise) but fails on new data. Symptom: train loss goes down while validation loss goes up.
Underfitting — the model is too simple; it can't capture the pattern. Symptom: both losses are high.
Bias-variance tradeoff — a model with high bias underfits (too rigid); high variance overfits (too flexible). The goal is the sweet spot: enough capacity to capture the pattern, not enough to memorize the noise.

Pitfall: Overfitting is the #1 beginner mistake. If your model gets 99% on training and 60% on validation, you overfit. Fixes: more data, simpler model, regularization (L1/L2), dropout (for NNs), early stopping.

Stage 2 — Supervised Learning

The paradigms

Supervised learning has labels. Two task types:

Regression — predict a continuous number (house price, temperature). Loss: MSE (mean squared error), MAE.
Classification — predict a discrete class (spam/not, dog/cat/bird). Loss: cross-entropy. Metrics: accuracy, precision/recall/F1, AUC.

A first model: linear regression

from sklearn.linear_model import LinearRegression
model = LinearRegression()
model.fit(X_train, y_train)         # "learn" the weights
predictions = model.predict(X_test)  # apply to new data

fit runs the optimization (ordinary least squares for linear regression) to find the weights that minimize MSE on the training set.

A first classifier: logistic regression

from sklearn.linear_model import LogisticRegression
model = LogisticRegression()
model.fit(X_train, y_train)
model.predict(X_test)           # predicted class
model.predict_proba(X_test)      # probability per class

Logistic regression is a classifier (despite the name): it outputs a probability via the sigmoid function, then thresholds.

The model zoo

Model	Good for	Notes
Linear / logistic regression	baselines, interpretable	the starting point; rarely the ending point
Decision trees	interpretable, non-linear	prone to overfit alone
Random forest / gradient boosting	tabular data, strong	the default for structured data; XGBoost/LightGBM win Kaggle
k-NN	small, simple	lazy; scales poorly
Naive Bayes	text, baselines	fast, independence assumption
Neural networks	images, text, audio	when data is unstructured and large

Pitfall: On tabular data (rows and columns), gradient-boosted trees (XGBoost, LightGBM) usually beat neural networks. Reach for deep learning when the data is unstructured (images, text, audio) or enormous. Don't default to a neural net for a 50-column spreadsheet.

Metrics (classification)

from sklearn.metrics import accuracy_score, classification_report, confusion_matrix
accuracy_score(y_test, y_pred)               # fraction correct
print(classification_report(y_test, y_pred)) # precision, recall, F1 per class

Accuracy — fraction correct. Misleading on imbalanced data (99% accuracy if 99% are one class).
Precision — of predicted positives, how many are real? (avoid false alarms)
Recall — of real positives, how many did we catch? (don't miss cases)
F1 — the harmonic mean of precision and recall (balance).
AUC — area under the ROC curve; threshold-independent ranking quality.

Pitfall: Accuracy on an imbalanced dataset lies. If 1% of transactions are fraud, a model that always says "not fraud" is 99% accurate and useless. Use precision, recall, F1, or AUC.

Stage 3 — Unsupervised Learning

Unsupervised learning has no labels — you find structure in the data itself.

Clustering

k-means groups points into k clusters by minimizing within-cluster distance:

from sklearn.cluster import KMeans
kmeans = KMeans(n_clusters=5, random_state=42)
labels = kmeans.fit_predict(X)   # assign each point to a cluster

Other algorithms: DBSCAN (density-based, finds arbitrary shapes, no need to set k), hierarchical clustering (dendrogram).

Dimensionality reduction

PCA (principal component analysis) projects high-dimensional data onto fewer axes that capture the most variance — for visualization, compression, or as a preprocessing step:

from sklearn.decomposition import PCA
pca = PCA(n_components=2)
X_2d = pca.fit_transform(X)   # 100-dim -> 2-dim for plotting

Embeddings

An embedding is a learned dense vector representation of something (a word, a user, an image) where similar things are close in vector space. Word2vec, GloVe, and the embeddings inside transformers (Stage 4) turn discrete objects into continuous vectors so similarity (cosine distance) and analogies ("king - man + woman ≈ queen") work. Embeddings are the foundation of modern search, recommendation, and LLMs — the pgvector extension in Postgres stores and searches them.

Stage 4 — Deep Learning

What a neural network is

A neural network is a stack of layers; each layer is a linear transformation followed by a non-linear activation function. The "deep" in deep learning = many layers. Each layer learns progressively more abstract features: pixels → edges → shapes → parts → objects.

Forward pass, loss, backprop, update

Training is a loop:

Forward pass — push inputs through the layers, get predictions.
Loss — compare predictions to labels (MSE, cross-entropy).
Backpropagation — compute the gradient of the loss with respect to every weight, using the chain rule, layer by layer from output back to input.
Update — nudge each weight in the direction that reduces the loss: weight -= learning_rate * gradient (gradient descent).

Repeat over the whole dataset for many epochs. The main knobs: learning rate (step size — too big diverges, too small crawls), batch size (examples per update), and the architecture (how many layers, how wide).

A first neural net in PyTorch

import torch
import torch.nn as nn

model = nn.Sequential(
    nn.Linear(784, 128),   # input (28x28 pixels) -> 128
    nn.ReLU(),             # non-linear activation
    nn.Linear(128, 10),    # 128 -> 10 classes
)

loss_fn = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)

for epoch in range(10):
    for X_batch, y_batch in dataloader:
        pred = model(X_batch)                    # forward
        loss = loss_fn(pred, y_batch)            # loss
        optimizer.zero_grad()
        loss.backward()                          # backprop (compute gradients)
        optimizer.step()                         # update weights

Architectures by data type

Data	Architecture	Why
Images	CNN (convolutional)	convolutions capture spatial patterns (edges, shapes) with few parameters
Sequences (text, time)	RNN/LSTM (legacy) → Transformer	transformers attend to all positions at once, parallelizable
Text (modern)	Transformer (GPT, BERT, Claude...)	self-attention; the architecture behind every LLM
Tabular	usually gradient boosting > NNs	trees handle structured data better

Pitfall: For most real problems, start simple (linear/logistic regression, then a tree model) and only reach for deep learning when you have unstructured data and enough of it. A neural net on a small tabular dataset usually loses to XGBoost and takes 10x longer to train.

Stage 5 — The ML Workflow

The end-to-end pipeline

Building a model is ~20% of the work; the rest is the pipeline around it:

Data — collect, clean, label, split. "Garbage in, garbage out" is the #1 ML truth. Most ML time is spent here.
Features — transform raw data into what the model consumes: scale numerical features, encode categories (one-hot, embedding), handle missing values, create derived features.
Train — fit the model; tune hyperparameters (learning rate, tree depth) using the validation set.
Evaluate — report metrics on the test set (the one you never touched). Do error analysis: look at where it's wrong, not just the aggregate score.
Deploy — serve the model (REST, batch, on-device). Monitor for drift — when the real-world data distribution shifts from training, accuracy silently degrades. Retrain on a schedule.

Pitfall: A model that scores great in a notebook but isn't monitored in production will silently degrade as the world changes. Drift detection (track input distributions + prediction distributions over time) is how you catch it before users do.

Feature engineering and scaling

from sklearn.preprocessing import StandardScaler, OneHotEncoder
from sklearn.pipeline import Pipeline

pipeline = Pipeline([
    ('scaler', StandardScaler()),       # normalize numerical features to mean 0, std 1
    ('model', LogisticRegression()),
])
pipeline.fit(X_train, y_train)

Scale your features. Many models (linear, NNs, k-NN) behave badly when features are on different scales (a feature in millions dominates one in decimals). Tree models don't care; everything else does.

Cross-validation

from sklearn.model_selection import cross_val_score
scores = cross_val_score(model, X, y, cv=5)   # 5-fold CV
print(scores.mean(), scores.std())

Cross-validation splits the data into k folds, trains on k-1 and validates on the held-out one, rotating — a more robust estimate of generalization than a single train/test split.

MLOps

The deployment + monitoring layer:

Versioning — track which model version is serving (MLflow, Weights & Biases).
Serving — REST endpoint (FastAPI + the model), batch scoring, or on-device.
Monitoring — drift detection, prediction latency, input schema validation.
Retraining — schedule retraining as data drifts; A/B test new models against the current one.

Quick-Start Checklist

Install scikit-learn + pandas — pip install scikit-learn pandas matplotlib.
Load a dataset — sklearn.datasets.load_iris() (classification) or load_diabetes() (regression).
Split train/test — always hold out a test set you never touch until the end.
Start with a baseline — logistic regression or a decision tree. Beat it before going complex.
Pick the metric for the problem — F1 for imbalanced classification, MSE for regression.
Cross-validate — don't trust a single split.
Try gradient boosting (XGBoost/LightGBM) for tabular data — usually the winner.
Reach for PyTorch only when data is unstructured (images, text) or large.
Scale features for anything that isn't a tree.
Set up drift monitoring before you ship — a model degrades silently.

Common Pitfalls

Evaluating on training data — the model has seen it; the score is meaningless. Always hold out a test set.
Overfitting — train loss down, val loss up. Regularize, get more data, or simplify.
Accuracy on imbalanced data — misleading; use precision/recall/F1/AUC.
Not scaling features — breaks linear models, NNs, k-NN; trees are immune.
Data leakage — scaling/encoding on the whole dataset before splitting leaks test info into training. Fit preprocessors on train only; transform test with the fitted transformer (use a Pipeline).
Defaulting to deep learning — for tabular data, trees usually win and train 10x faster.
Ignoring drift — a great model in the notebook silently degrades in production as the world changes.
No baseline — start with the simplest model; if a linear regression gets 90%, a neural net that gets 91% isn't worth the complexity.

Related guides

ML is the applied-math layer on top of programming fundamentals — these PyShine tutorials connect to it:

Learn Python in One Post — the language every ML library uses; NumPy, pandas, scikit-learn, PyTorch are all Python.
Learn Data Structures and Algorithms in One Post — Big-O and the fundamentals you need to reason about model complexity.
Learn SQL in One Post — ML models train on data; most of it lives in a database.
Learn PostgreSQL in One Post — the pgvector extension stores and searches ML embeddings.
Learn Docker in One Post — containerize model training and serving.

Machine learning is less a single skill than a stack of decisions: what paradigm (supervised? unsupervised?), what model family (trees? neural nets?), what metric, what preprocessing, what monitoring. The five stages here — concepts, supervised, unsupervised, deep learning, the workflow — cover the whole map from "what is a feature" to "how do I detect drift in production." The habit that separates a beginner from a practitioner is start with a baseline and beat it: a logistic regression or a tree, cross-validated, with the right metric, before you ever reach for a neural network. Load load_iris(), run the snippets above, and watch a model go from random to useful in ten lines — that's the moment the field clicks.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Node.js and Express in a Single Post: A Complete Tutorial From the Event Loop and Modules to Middleware and Production

PyShine — Thu, 23 Jul 2026 12:31:15 +0000

Learn Node.js and Express in a Single Post: Complete Tutorial From the Event Loop to Middleware and Production

Node.js is JavaScript on the server: it takes the V8 engine from Chrome, adds non-blocking I/O via an event loop, and lets you write networked backends in the same language as the frontend. Express is the minimal web framework most Node servers are built on. Together they're the default entry point to backend JavaScript. This single post teaches both in five stages, with hand-drawn diagrams and runnable snippets.

Learning Roadmap

The roadmap moves from the runtime model (Stage 1), through modules (Stage 2), async (Stage 3), Express (Stage 4), and production (Stage 5). You'll want solid JavaScript first — Node is JS.

Stage 1 — The Runtime

What Node is

Node is a runtime, not a language: it runs JavaScript using the V8 engine (the same one in Chrome), plus a set of C++ bindings for I/O (files, network, crypto) and libuv, the library that provides the event loop and a thread pool.

The event loop and the single thread

Your JavaScript runs on one thread. The event loop keeps that thread busy with I/O callbacks: when a network request arrives, or a file read completes, libuv notifies the loop, which runs your callback. Because the loop never blocks on I/O, a single thread can handle thousands of concurrent connections.

The hard rule: never block the event loop. A CPU-bound loop (while(true){}), a synchronous file read (fs.readFileSync of a big file), or a heavy computation freezes every connection, not just the one doing the work.

The libuv thread pool

Some operations can't be made non-blocking at the OS level (file I/O on some platforms, crypto.pbkdf2, DNS lookups). Node offloads these to a thread pool (default 4 threads, configurable via UV_THREADPOOL_SIZE) so the event loop keeps running. Your callback still runs on the single main thread when the work completes.

Pitfall: The thread pool is not parallelism for your JS — it's for the C++ I/O work. If you need real parallel CPU work in JS, use worker threads (worker_threads) or a child process; the thread pool won't help you.

Stage 2 — Modules

CommonJS vs ES Modules

Node historically used CommonJS (require/module.exports); modern Node also supports ES Modules (import/export). Use ESM for new code; CommonJS still works for legacy.

// CommonJS (legacy)
const fs = require('fs');
function add(a, b) { return a + b; }
module.exports = { add };
// const { add } = require('./math');

// ES Modules (modern) — package.json: "type": "module"
import fs from 'fs';
export function add(a, b) { return a + b; }
// import { add } from './math';

	CommonJS	ESM
Syntax	`require` / `module.exports`	`import` / `export`
Resolution	runtime, synchronous	static, hoisted
Extension	`.cjs` or default	`.mjs` or `"type":"module"`
Top-level await	no	yes
Tree-shaking	no	yes

npm and `package.json`

{
  "name": "my-api",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "start": "node index.js", "dev": "nodemon index.js", "test": "vitest" },
  "dependencies": { "express": "^4.19.0", "pg": "^8.11.0" },
  "devDependencies": { "nodemon": "^3.1.0", "vitest": "^2.0.0" },
  "engines": { "node": ">=20" }
}

npm install express            # add a runtime dep
npm install --save-dev nodemon # add a dev dep
npm install                    # install everything from package.json + lockfile
npm run dev                    # run the "dev" script

node_modules/ holds installed packages; package-lock.json pins exact versions for reproducibility (commit the lockfile). For speed, use pnpm (dedupes via symlinks) or Bun.

Pitfall: npm install <pkg> without -D puts a build tool into dependencies, shipping it to production. Use --save-dev / -D for anything only needed at build/test time.

Stage 3 — Async

Callbacks -> promises -> async/await

Node's async story evolved: callbacks (error-first) -> promises -> async/await. Use async/await; it reads top-to-bottom like sync code but never blocks.

// callback (legacy, error-first)
fs.readFile('f.txt', (err, data) => { if (err) return handle(err); use(data); });

// promise + async/await (modern)
import { readFile } from 'node:fs/promises';
async function load() {
  try {
    const data = await readFile('f.txt', 'utf8');  // suspends, doesn't block
    return JSON.parse(data);
  } catch (err) { handle(err); }
}

Always handle errors — an unhandled promise rejection crashes the process (since Node 15). Wrap await in try/catch or attach .catch().

Streams

Streams process data in chunks as it arrives, instead of buffering it all in memory — essential for large files, uploads, or piping:

import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';

// pipe a file through a transform to stdout
await pipeline(createReadStream('big.log'), process.stdout);

// HTTP response is a writable stream
res.write('chunk 1\n'); res.write('chunk 2\n'); res.end('done\n');

Use stream.pipeline (not .pipe()) so errors propagate and resources clean up.

Pitfall: .pipe() doesn't forward errors — one stream can fail silently while the other keeps going. Use pipeline() from stream/promises.

Stage 4 — Express

Express is a minimal web framework: it routes HTTP requests to handler functions, with a middleware pipeline in between.

A minimal server

import express from 'express';
const app = express();

app.use(express.json());                  // body parser middleware

app.get('/', (req, res) => res.json({ ok: true }));

app.post('/users', (req, res) => {
  const { name } = req.body;
  res.status(201).json({ id: 1, name });
});

app.listen(3000, () => console.log('http://localhost:3000'));

The middleware pipeline

Middleware -> Route -> Response" width="800" height="418">

Every request flows through a chain of middleware functions, each getting (req, res, next) and calling next() to pass control onward. One handler eventually sends the response.

// a logging middleware
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();                          // pass control to the next middleware/route
});

// order matters: this runs before routes defined after it
app.get('/users', authMiddleware, getUsers);   // route-specific middleware

Request and response objects

req.method, req.url, req.path, req.query, req.params
req.headers, req.get('Authorization')
req.body (after express.json())
res.json(obj), res.send(str), res.status(404).send(...), res.redirect(url)

Error handling

A middleware with four arguments (err, req, res, next) is an error handler. Define it last, after all routes:

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(err.status || 500).json({ error: err.message });
});

Pass errors to it with next(err) or by throwing in an async handler (wrap async routes in a helper — an unhandled rejection from a route handler won't reach Express automatically):

// wrap async handlers so rejections reach the error middleware
const wrap = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
app.get('/users/:id', wrap(async (req, res) => {
  const user = await db.findUser(req.params.id);
  if (!user) { const e = new Error('not found'); e.status = 404; throw e; }
  res.json(user);
}));

Pitfall: A thrown error in an async route handler, unhandled, becomes an unhandled rejection — not an Express error. Use express-async-errors or the wrap helper so it reaches your error middleware.

Routers

For larger apps, split routes into Router modules and mount them:

import { Router } from 'express';
const users = Router();
users.get('/', listUsers);
users.get('/:id', getUser);
app.use('/users', users);   // mount at /users

Stage 5 — Production

Clustering

A single Node process uses one CPU core. The cluster module (or PM2) forks one worker per core, all sharing a port — this is how you use a multi-core machine:

import cluster from 'node:cluster';
import os from 'node:os';
if (cluster.isPrimary) {
  for (let i = 0; i < os.cpus().length; i++) cluster.fork();
} else {
  // each worker runs the server
  app.listen(3000);
}

In practice, use PM2 (pm2 start app.js -i max) or run behind a container orchestrator with one process per container — don't hand-roll clustering in production.

Testing

import { test, expect } from 'vitest';
import request from 'supertest';
import app from './app.js';

test('GET / returns ok', async () => {
  const res = await request(app).get('/');
  expect(res.status).toBe(200);
  expect(res.body).toEqual({ ok: true });
});

Vitest (unit/integration) + supertest (HTTP) is the standard combo. For e2e, Playwright drives a real browser.

Deploy and security

PM2 for process management on a VM; Docker + your orchestrator for containerized deploys.
Security headers: use helmet. CORS: use cors. Rate limiting: express-rate-limit. Input validation: zod or joi.
Never trust req.body without validation; never interpolate user input into SQL/shell (injection).
Set NODE_ENV=production (faster V8 optimizations, less verbose errors).

Databases

SQL: pg (raw), Prisma (typed ORM), Drizzle (typed, lightweight).
MongoDB: Mongoose.
Cache: ioredis / node-redis.

The ecosystem

Concern	Tool
Runtime + packages	node, npm, pnpm, nvm
Dev	nodemon, tsx, vitest, eslint/prettier
Frameworks	Express (minimal), Fastify (fast + schema), Hono (edge), NestJS (structured DI)
DBs + deploy	pg/Prisma, Mongoose, Redis, PM2/Docker

Quick-Start Checklist

Install Node (LTS) via nvm or the installer; verify with node -v.
Init a project: npm init, install Express, add a "type": "module" + a dev script.
Write a 10-line server with one GET route; node index.js and hit it with curl.
Add express.json() and a POST route; test with curl -d.
Add a logging middleware + an error-handling middleware (four-arg).
Use async/await with try/catch (or wrap async routes) for DB calls.
Validate input with Zod before it touches your DB.
Add helmet, cors, express-rate-limit for baseline security.
Test with Vitest + supertest in CI.
Run behind PM2 or in Docker with NODE_ENV=production.

Common Pitfalls

Blocking the event loop — a sync loop or readFileSync freezes all connections. Keep the loop free.
Unhandled promise rejections — crash the process. try/catch every await, or attach .catch().
async route handlers that throw — don't reach Express's error middleware without wrapping. Use wrap() or express-async-errors.
.pipe() without error handling — use stream/pipeline so errors propagate.
Dev deps in dependencies — bloats production. Use -D / --save-dev.
Not committing the lockfile — non-reproducible installs. Commit package-lock.json.
Trusting req.body — always validate with Zod/joi; never build SQL/shell from it.
Single process on multi-core — use clustering (PM2 -i max) or one process per container.
NODE_ENV unset in production — slower V8, verbose errors. Set NODE_ENV=production.

Related guides

Node + Express is the backend JS stack — these PyShine tutorials are its prerequisites and companions:

Learn JavaScript + TypeScript in One Post — Node is JS; async/await and the event loop are JS concepts first.
Learn REST API in One Post — Express implements REST; know methods, status codes, idempotency.
Learn SQL in One Post — what your Express handlers query (via pg/Prisma).
Learn Docker in One Post — containerize and ship the Node server.
Learn React + Next.js in One Post — the frontend that calls this backend.

Node's power is its simplicity: one language front-to-back, one thread, an event loop, and a tiny core you can hold in your head. The five stages here — runtime, modules, async, Express, production — cover everything from a "hello world" server to a clustered, tested, containerized API. The single most important habit is never block the loop: once that's a reflex, the rest is standard web-backend work. Run every snippet above, write one endpoint, hit it with curl, wrap it in Docker, and you've built your first production Node service.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Observability in a Single Post: A Complete Tutorial From Metrics, Logs, and Traces to OpenTelemetry and SLO Alerting

PyShine — Thu, 23 Jul 2026 12:30:59 +0000

Learn Observability in a Single Post: Complete Tutorial From Metrics, Logs, and Traces to OpenTelemetry and SLO Alerting

Observability is the ability to ask questions of your system from the outside, without shipping new code to answer them. Monitoring tells you a thing is wrong; observability lets you find out why, fast — across metrics, logs, and traces, correlated by a shared trace ID and labels. It's the difference between "the site is slow" and "the /checkout path is 3x slower because the payments DB is doing full-table scans." This single post teaches the whole subject in five stages, with hand-drawn diagrams and runnable snippets.

Learning Roadmap

The roadmap moves from metrics (Stage 1), through logs (Stage 2) and traces (Stage 3), to the unified OpenTelemetry pipeline (Stage 4), and the SLO + alerting discipline that makes it actionable (Stage 5).

Stage 1 — Metrics

The three pillars

Observability rests on three pillars: metrics (numbers over time — what + how much), logs (discrete events — why), and traces (a request's journey — where time went). Together, correlated by labels and trace IDs, they let you answer any question.

Metric types

Type	What it is	Example
Counter	monotonically increasing	`http_requests_total` (request count)
Gauge	a value that goes up and down	`memory_bytes`, `queue_depth`, `active_connections`
Histogram	distribution of values in buckets	request latency, with quantile estimation
Summary	pre-computed quantiles (legacy)	use histograms instead in most cases

# Prometheus client (Python)
from prometheus_client import Counter, Histogram, start_http_server

REQUESTS = Counter('http_requests_total', 'Total requests', ['route', 'method'])
LATENCY  = Histogram('http_request_duration_seconds', 'Latency', ['route'])

@LATENCY.time()
def handle(route):
    REQUESTS.labels(route=route, method='GET').inc()
    ...

Prometheus — the pull model

Prometheus scrapes your apps: each app exposes a /metrics endpoint, and Prometheus pulls from it on a schedule (15s by default). This pull model means no agent in your app pushing data — the app is dumb, Prometheus is smart.

# prometheus.yml
scrape_configs:
  - job_name: 'my-app'
    static_configs: [{ targets: ['app:8000'] }]
  - job_name: 'kubernetes-pods'
    kubernetes_sd_configs: [{ role: pod }]   # auto-discover K8s pods

PromQL — query the time series

# requests/sec over the last 5 minutes
rate(http_requests_total[5m])

# p99 latency
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

# error rate
sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))

# per-route
sum by (route) (rate(http_requests_total[5m]))

Labels are dimensions. Every metric carries labels (route, method, status, env); PromQL groups and filters by them. Design labels deliberately — they're how you slice the data.

Pitfall: High-cardinality labels (a label per user ID, request ID, or email) blow up the time-series database — millions of series, Prometheus OOMs. Labels should have a small, bounded set of values. Put unique IDs in logs/traces, not metric labels.

Stage 2 — Logs

Structured logs

A log entry should be structured (machine-parseable JSON with fields), not free text:

{"ts":"2026-07-14T12:00:01Z","level":"error","msg":"payment failed",
 "trace_id":"abc123","user_id":"u42","order_id":"o99","amount":49.99,"error":"card_declined"}

Fields (user_id, order_id, trace_id) let you filter and correlate — "show me all logs for trace abc123" or "all payments for user u42." Free text "payment failed for user 42" is a string-search nightmare.

Levels

debug → info → warn → error → fatal. In production, ship info and above; debug is for development. Don't log at error what's expected (a 404, a retry) — it drowns real errors in noise and trains people to ignore the page.

Log aggregation

Loki — like Prometheus for logs: indexes labels (not full text), cheap, integrates with Grafana.
ELK (Elasticsearch + Logstash + Kibana) — full-text indexing, powerful search, heavier.
Cloud: Cloud Logging (GCP), CloudWatch Logs (AWS).

Pitfall: Logging sensitive data (PII, passwords, tokens) is a security incident. Scrub secrets before logging; structure logs so a scrubber can find fields by name.

Stage 3 — Traces

What a trace is

A trace is the end-to-end journey of one request through your system. It's a tree of spans: each span is a unit of work (an HTTP call, a DB query, a function), with a start, duration, and attributes. Spans carry a trace ID (shared across the whole request) and a span ID (unique per span), and a parent span ID — the tree structure.

trace abc123 (HTTP GET /checkout)  ─── 220ms total
├── span: validate cart            ─── 5ms
├── span: POST /payments            ─── 180ms   ← the slow one
│   └── span: DB INSERT charge       ─── 175ms  ← the real cause
└── span: render receipt            ─── 3ms

A trace shows you where time went and the call graph — the single best tool for "why is this slow?"

Distributed tracing

In a microservice system, a trace spans services: service A calls B calls C. Each service contributes spans to the same trace (via propagated headers: traceparent). OpenTelemetry (Stage 4) is how spans get created and propagated; Jaeger, Tempo, or Zipkin store and visualize them.

Sampling

You can't trace 100% of traffic at scale (too much data). Sampling traces a fraction:

Head-based — the first service decides (random %), same decision for the whole trace. Simple, but misses rare errors.
Tail-based — sample after the trace completes (e.g. keep all errors, 1% of successes). Smarter, more expensive.

Pitfall: If sampling is inconsistent across services, a trace breaks mid-journey. Use a consistent sampling decision (head-based, propagated) so the whole trace is kept or dropped together.

Stage 4 — OpenTelemetry

The problem OTel solves

Before OpenTelemetry, every vendor (Datadog, New Relic, Jaeger, Honeycomb) had its own instrumentation library. Switching backends meant re-instrumenting your whole codebase. OpenTelemetry (OTel) is the vendor-neutral standard: instrument once, export to any backend.

SDK -> Collector" width="800" height="409">

The pipeline

Instrumentation — auto (library integrations that create spans/metrics for HTTP, DB, etc.) + manual (custom spans, attributes).
SDK — configures the instrumentation, batches, and exports.
Collector — a standalone process that receives OTLP, processes (batch, filter, add attributes), and exports to backends (Prometheus, Jaeger, Loki, Datadog, any).

# Python: OTel SDK setup
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, OTLPSpanExporter

trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="otel-collector:4317"))
)

# manual span
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("process_payment") as span:
    span.set_attribute("order_id", order_id)
    charge(order_id)

The Collector

The OTel Collector is the heart of a production pipeline: it decouples your apps from the backends. Apps export OTLP to the collector; the collector fans out to Prometheus (metrics), Jaeger/Tempo (traces), Loki (logs) — or to a SaaS vendor. Change backends by reconfiguring the collector, not your apps.

# otel-collector config (simplified)
receivers:   { otlp: { protocols: { grpc: { endpoint: 0.0.0.0:4317 } } } }
processors: { batch: {}, resource: { attributes: [{ key: env, value: prod }] } }
exporters:
  prometheus: { endpoint: 0.0.0.0:8889 }   # metrics -> Prometheus scrapes
  otlp/tempo: { endpoint: tempo:4317 }       # traces -> Tempo
  loki: { endpoint: loki:3100 }             # logs -> Loki
service: { pipelines: { ... } }

Pitfall: Don't point every app directly at every backend. Run a collector (or a gateway collector in front of it). It batches, retries, drops on overload, and lets you swap backends without touching apps.

Stage 5 — SLOs + Alerting

SLI, SLO, error budget

SLI (service-level indicator) — a measured metric: "99.5% of /checkout requests complete in < 200ms."
SLO (service-level objective) — the target for the SLI over a window: "99% over 30 days."
Error budget — the 1% gap (100% − 99%) = how much unreliability you can "afford." It's the room for deploys, experiments, and risk.

The error budget reframes reliability as a product decision: if you're burning it slowly, you can ship faster; if you're burning it fast, you freeze feature work and fix reliability.

Burn-rate alerting

Don't alert on "CPU > 80%" — that's a cause you guessed, and it may not matter. Alert on symptoms (user impact) via burn rate: how fast you're spending the error budget.

# page if spending budget 14x faster than allowed over 1h AND 5m
# (multi-window multi-burn-rate — the SRE standard)
job:slo_errors:ratio_rate5m > 14 * (1 - 0.99)
and job:slo_errors:ratio_rate1h > 14 * (1 - 0.99)

Multi-window burn-rate alerts fire only when the budget is genuinely at risk over both a short and long window — far fewer false pages than raw-threshold alerts.

On-call + runbooks

An alert that pages a human must:

Be actionable (the human can do something about it).
Have a runbook (the steps to diagnose and fix).
Auto-recover if possible (the alert should also fire when it self-resolves).

Pitfall: Alert fatigue is how on-call dies. If a page fires and the right response is "ignore it," you've trained the team to ignore all pages — including the real one. Every noisy alert is a bug; fix it or delete it.

Quick-Start Checklist

Expose a /metrics endpoint (Prometheus format) with a counter + histogram.
Run Prometheus to scrape it; open the Prometheus UI and run a rate() query.
Add Grafana, point it at Prometheus, build a dashboard.
Emit structured JSON logs with a trace_id field; aggregate in Loki.
Add OpenTelemetry — auto-instrumentation for your framework; export to a collector.
Run the OTel Collector fanning out to Prometheus (metrics) + Tempo/Jaeger (traces).
Define one SLI + SLO (e.g. 99% of /api requests < 200ms over 30d).
Set a burn-rate alert on that SLO, paging to a channel.
Write a runbook for the alert; test it by triggering the condition.
Review alerts monthly — delete or fix every noisy one.

Common Pitfalls

High-cardinality metric labels (user ID, request ID) — explodes the TSDB; put those in logs/traces.
Free-text logs — unsearchable; emit structured JSON with fields.
Logging secrets/PII — a security incident; scrub before logging.
Cause-based alerts ("CPU high") — alert on symptoms (user impact) instead.
Alert fatigue — every non-actionable page erodes trust; delete noisy alerts.
No runbook — a page with no instructions wastes on-call time; write the steps.
Inconsistent sampling — breaks distributed traces; propagate one decision.
Every app -> every backend — use a collector so swapping backends is config, not code.
error level for expected events — drowns real errors; log those at info/warn.

Related guides

Observability is the ops layer that watches the rest of the stack — these PyShine tutorials connect to it:

Learn Kubernetes in One Post — Prometheus + Grafana are the K8s monitoring default; the kube-prometheus-stack Helm chart sets it up.
Learn Docker in One Post — containerize Prometheus, Grafana, and the OTel collector with Compose.
Learn GitHub Actions in One Post — alert on-call from CI when a deploy breaks an SLO.
Learn System Design in One Post — SLOs and error budgets are system-design concepts applied to production.
Learn Python in One Post / Learn Node.js in One Post — instrument these backends with OTel.

Observability is what separates a system you operate from one that surprises you. The five stages here — metrics, logs, traces, OpenTelemetry, SLOs + alerting — cover everything from a single counter to a vendor-neutral, SLO-driven, burn-rate-alerted production setup. The two habits that pay off forever: emit structured logs with a trace ID (so you can always follow a request), and alert on symptoms via burn rate, not on guessed causes (so the page always means something). Expose one /metrics endpoint, scrape it with Prometheus, draw one dashboard in Grafana — once you've watched a request's latency show up in a graph, the rest follows.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

Learn Operating Systems in a Single Post: A Complete Tutorial From Processes and Scheduling to Virtual Memory and Concurrency

PyShine — Thu, 23 Jul 2026 12:30:46 +0000

Learn Operating Systems in a Single Post: Complete Tutorial From Processes and Scheduling to Virtual Memory and Concurrency

An operating system is the program that makes a computer usable: it manages the CPU, memory, disks, and devices so that dozens of programs can run at once without colliding, and so that a crash in one doesn't take down the rest. Whether you're debugging a hang, reasoning about a data race, or sizing a server, the OS concepts are the substrate under everything. This single post teaches the whole subject in five stages, with hand-drawn diagrams and runnable commands.

Learning Roadmap

The roadmap moves from processes (Stage 1), to how the CPU is shared (Stage 2), to how memory is shared and faked (Stage 3), to the hardest part — concurrency (Stage 4), and finally I/O and filesystems (Stage 5).

Stage 1 — Processes

A process is a running program: an instance of an executable plus its address space, open files, registers, and scheduling state. The OS keeps each process's metadata in a Process Control Block (PCB) — the PID, registers, program counter, stack pointer, open file table, memory map, and scheduling info.

Process states

A process moves among states:

New → Ready (admitted)
Ready → Running (dispatched by the scheduler)
Running → Ready (time-slice expires, preempted)
Running → Waiting/Blocked (asks for I/O, or waits on a lock)
Waiting → Ready (I/O completes, lock released)
Running → Terminated (exit)

The context switch

Switching the CPU from process A to process B means saving A's full state (registers, PC, memory map) into A's PCB and loading B's state from B's PCB. This is pure overhead — the CPU does no useful user work during a switch — so the scheduler balances "don't switch too often" against "don't let one process hog the CPU."

`fork`, `exec`, `wait`

On Unix, creating a process is two steps:

fork() — duplicates the calling process; the child gets a copy of the parent's memory (copy-on-write, so it's cheap until either writes).
exec(path) — replaces the current process image with a new program (the child now runs a different binary).
wait() — a parent blocks until a child exits (and reaps its exit status, preventing a zombie).

ps -ef                # see processes (PID, PPID, state, command)
top / htop            # live process view, sorted by CPU/mem
strace -p <pid>       # trace the syscalls a process makes

Pitfall: A child that exits but whose parent never wait()s becomes a zombie (it's done, but its entry stays until reaped). A parent that dies leaves children as orphans, re-parented to init (PID 1). The classic leak in long-running servers is not reaping children.

Stage 2 — Scheduling

The scheduler decides which ready process runs next. Goals: fairness (no starvation), responsiveness (low latency for interactive work), throughput (high overall work/sec), and honoring priorities.

Preemptive vs cooperative

Cooperative — a process runs until it voluntarily yields (calls a blocking syscall). A buggy/infinite-loop process freezes the machine. (Early Windows, old Mac.)
Preemptive — the OS sets a timer interrupt and forcibly takes the CPU back after a time slice (quantum, ~1–10 ms). Every modern general-purpose OS is preemptive.

Algorithms

Algorithm	Idea	Tradeoff
FCFS	first-come, first-served	simple, but short jobs wait behind long ones (convoy effect)
Round-robin	each ready process gets a quantum, then rotates	fair, responsive; context-switch overhead
Priority	highest priority first	starvation of low priority (fix: aging)
SJF / SRTF	shortest job first	optimal throughput, but you can't know job length
Multilevel feedback	queues by priority; demote CPU hogs, promote I/O-bound	what real OSes approximate (Linux CFS)

Pitfall: Priority inversion — a low-priority process holds a lock a high-priority process needs, and medium-priority processes keep running so the high one waits indefinitely. Fix with priority inheritance (the lock holder temporarily inherits the waiter's priority). This bit the Mars Pathfinder rover in 1997.

Stage 3 — Memory

Virtual memory

Every process sees its own virtual address space (e.g. 0 to 2⁴⁸), as if it had the whole machine to itself. The OS + MMU translate virtual addresses to physical frames via a page table. This gives isolation (a process can't touch another's memory) and the illusion of more RAM than exists (via demand paging + swap).

Pages, TLB, page faults

Memory is divided into fixed-size pages (typically 4 KB); physical RAM into frames of the same size. The page table maps virtual page number → physical frame number.

TLB (translation lookaside buffer) — a hardware cache of recent translations. A TLB hit makes translation free; a miss walks the page table in RAM (slow). This is why page size and locality matter.
Page fault — the CPU accesses a virtual page not currently in RAM (it's on disk/swap). The OS pauses the process, fetches the frame from disk, updates the table, and retries. This is demand paging — pages are loaded only when touched.
Swap — when RAM is full, the OS evicts pages to disk (swap space). A system that's swapping is catastrophically slow (disk is ~10,000× slower than RAM).

Pitfall: Thrashing — if the working set (pages in active use) exceeds RAM, every access faults, the OS swaps in a page that immediately gets evicted, and the system spends all its time swapping instead of computing. The fix is more RAM or a smaller working set, not a faster CPU.

Replacement policies

When a frame must be evicted, which one? LRU (least recently used) is good but expensive to track exactly; OSes approximate it (clock algorithm, second-chance). FIFO is simple but can evict a page that's about to be used. Belady's (optimal, evict the one not used for longest) is unimplementable (you can't see the future) but is the benchmark.

Stage 4 — Concurrency

Threads vs processes

A thread is a unit of execution within a process. Threads in the same process share memory (code, heap, open files); each has its own stack and registers. Creating a thread is cheaper than a process (no address-space copy), but shared memory is the source of most concurrency bugs.

Race conditions and locks

When two threads read-modify-write a shared variable without synchronization, the result depends on timing — a race condition. count++ is not atomic: it's load → add → store, and a thread can be preempted between any two steps. The fix is a mutex (mutual exclusion lock): only one thread holds it at a time, so the critical section runs atomically.

import threading
lock = threading.Lock()
with lock:          # acquire; auto-release on exit
    count += 1

Synchronization primitives

Primitive	Use
Mutex	one thread at a time in a critical section
Semaphore	N threads at a time (counting)
Condition variable	a thread waits for a condition; another signals when it's met
Read/write lock	many readers OR one writer
Atomic	lock-free single-word read-modify-write (`atomic_int`, `compare_and_swap`)
Barrier	all threads wait until everyone reaches a point

Pitfall: Hold a lock for the shortest time possible. Long critical sections kill concurrency and scalability. If you must do slow work, copy the data out under the lock and do the work unlocked.

Deadlock

Deadlock is when threads are stuck waiting on each other forever. The four Coffman conditions that together cause it:

Mutual exclusion — a resource is held by one thread.
Hold and wait — a thread holds one resource while waiting for another.
No preemption — you can't force-release a held resource.
Circular wait — A waits on B, B waits on C, C waits on A.

Break any one condition to prevent deadlock. The common technique: acquire locks in a consistent global order (so a circular wait can't form), or use lock timeouts / try-lock with backoff.

Pitfall: The single most common deadlock cause is acquiring two locks in opposite orders in two code paths (lock A then B vs lock B then A). Pick a project-wide lock ordering and never violate it.

Livelock and starvation

Livelock — threads aren't blocked but keep reacting to each other and make no progress (two people in a hallway both stepping aside in sync forever).
Starvation — a thread never gets scheduled (e.g. a low-priority thread behind high-priority ones). Fix with aging (raise priority the longer a thread waits).

Stage 5 — I/O + Filesystems

File descriptors

On Unix, everything is a file — regular files, pipes, sockets, devices — all accessed via an integer file descriptor (fd). A process has an fd table; read/write/close work on fds. fds 0/1/2 are stdin/stdout/stderr.

ls /proc/$$/fd        # your process's open file descriptors
lsof -p <pid>          # what files/sockets a process has open

Buffers and the page cache

The OS caches disk reads in the page cache (RAM). A read() may return from the cache (fast) or trigger a disk I/O (slow). Writes are buffered and flushed later — fsync() forces a flush so the data survives a crash. This is why databases call fsync on commit: otherwise a power loss could lose acknowledged writes.

Pitfall: A write() returning success means "in the OS buffer," not "on disk." For durability you need fsync() (or open with O_SYNC). Losing acknowledged data on a power fault is a classic data-loss bug.

Inodes and filesystems

A file's metadata (size, permissions, timestamps, block pointers) lives in an inode; the directory is just a map from name → inode number. The filesystem (ext4, APFS, NTFS, XFS) manages how inodes and data blocks are laid out on disk. Hard links (same inode, multiple names) vs symlinks (a file containing another path).

`/proc` and introspection

Linux exposes per-process and kernel state as virtual files under /proc:

/proc/<pid>/status — memory, state, threads.
/proc/<pid>/maps — virtual memory layout.
/proc/meminfo, /proc/cpuinfo, /proc/loadavg — system-wide.

Syscalls

The user/kernel boundary is crossed by syscalls: read, write, open, close, fork, exec, mmap, socket, brk, ioctl. Each is a (relatively expensive) context switch into kernel mode. Tools like strace show every syscall a process makes — invaluable for debugging "what is my program actually doing?"

The Toolchain

Kernels: Linux (monolithic + loadable modules), Windows NT (hybrid), macOS XNU (hybrid + Mach microkernel core), FreeBSD.
Syscalls: the user/kernel API. strace/dtrace/frace trace them.
Inspect: /proc, strace, lsof, perf, vmstat, iostat.
Shell + FS: bash/sh (userland), inodes, fd tables, page cache.

Quick-Start Checklist

Learn process states and the context switch — every perf conversation starts here.
Understand fork/exec/wait — how Unix spawns, and the zombie/orphan pitfalls.
Know preemptive scheduling and why round-robin + priorities approximate real OSes.
Master virtual memory: pages, TLB, page faults, swap, and why thrashing kills.
Know threads vs processes — cheap vs isolated, and why shared memory causes races.
Protect shared state with locks, and acquire locks in a consistent global order.
Name the four deadlock conditions and how breaking one prevents it.
Remember write() ≠ on-disk — fsync() for durability.
Use strace, lsof, /proc when "what is my program doing?" isn't obvious.
Reason about the page cache — most "slow disk" problems are actually cache misses.

Common Pitfalls

Zombies / orphans — not reaping children with wait(). Fix with a SIGCHLD handler or explicit reaping.
Priority inversion — a low-priority holder blocks a high-priority waiter. Fix with priority inheritance.
Thrashing — working set > RAM; adding CPU doesn't help, adding RAM does.
Holding locks across I/O — serializes all threads on a slow operation; copy-and-release instead.
Lock-ordering deadlocks — acquire locks in a consistent order across all code paths.
Trusting write() durability — buffer ≠ disk; fsync() to be sure.
Spinlocks on single-core — a spinlock holding the only CPU starves everyone; use a blocking lock.
Assuming atomicity — x++ is not atomic; use an atomic primitive or a lock.

Related guides

OS concepts underpin every systems topic — these PyShine tutorials apply them directly:

Learn Linux CLI in One Post — processes, file descriptors, permissions are the userland surface of the OS.
Learn Computer Networking in One Post — sockets are file descriptors; the network stack is kernel-side OS.
Learn Bash in One Post — pipes, redirects, signals, and background jobs are OS primitives driven from the shell.
Learn Rust in One Post — Rust's ownership model is a compile-time answer to the data races this stage is about.
Learn Go in One Post — goroutines (M:N scheduled) are the language-level take on OS threads.
Learn Docker in One Post — containers are OS namespaces + cgroups; this is the underlying mechanism.

Operating systems is the subject where "it works on my machine" stops being an acceptable answer. The five stages here — processes, scheduling, memory, concurrency, I/O — are the mental model a senior engineer uses every time a server is slow, a program hangs, or a deploy misbehaves. Spend a day per stage, run strace on a real process, watch a page fault, and write a program that deadlocks then fix it. The concepts only stick once you've felt the bugs they prevent.

Originally published on pyshine.com. The full tutorial with all 5 hand-drawn diagrams lives there — this cross-post is kept in sync via canonical URL.

DEV Community: PyShine

Learn Cryptography in a Single Post: A Complete Tutorial From Symmetric and Asymmetric Encryption to Hashing, TLS, and Applied Security

Learn Cryptography in a Single Post: Complete Tutorial From Symmetric and Asymmetric Encryption to TLS and Applied Security

Learning Roadmap

Stage 1 — Symmetric Encryption

One shared key

AES and modes

The key-sharing problem

Stage 2 — Asymmetric Encryption

Two keys: public and private

Algorithms

Key exchange — the solution to the key-sharing problem

Stage 3 — Hashing, HMAC, Signatures, Passwords

Cryptographic hashes

HMAC — keyed hashing

Digital signatures

Password storage

Stage 4 — Protocols: TLS, HTTPS, SSH, PKI

TLS 1.3 — the protocol behind HTTPS

SSH

PKI — Public Key Infrastructure

Stage 5 — Applied Cryptography

JWT (JSON Web Tokens)

OAuth 2.1 / OIDC

End-to-end encryption

Zero-knowledge proofs

Quick-Start Checklist

Common Pitfalls

Further Reading

Related guides

Learn Data Structures and Algorithms in a Single Post: A Complete DSA Tutorial From Big-O to Trees, Graphs, and Dynamic Programming

Learn Data Structures and Algorithms in a Single Post: Complete Tutorial From Big-O to Dynamic Programming

Learning Roadmap

Stage 1 — Big-O + Basics

Big-O notation

Arrays and strings

Complexity analysis rules

Stage 2 — Linear Structures

Linked lists

Stacks (LIFO)

Queues (FIFO)

Hash maps (dictionaries)

Data structures + access costs

Stage 3 — Trees + Graphs

Binary search tree (BST)

Heaps

Tries

Graphs

BFS — breadth-first search

DFS — depth-first search

Stage 4 — Sorting + Searching

Sorting

Quicksort (the one to know)

Binary search

Two pointers

Sliding window

Stage 5 — Advanced Patterns

Dynamic programming

Fibonacci (the canonical example)

0/1 Knapsack (the classic DP)

Greedy

Divide and conquer

Backtracking

Interview prep

The Toolchain

Quick-Start Checklist

Common Pitfalls

Further Reading

Related guides

Learn Deep Learning in a Single Post: A Complete Tutorial From Neural Networks and CNNs to Transformers and PyTorch Training

Learn Deep Learning in a Single Post: Complete Tutorial From Neural Networks to Transformers and PyTorch Training

Learning Roadmap

Stage 1 — Neural Networks

The neuron

Common activations

Layers = stacked neurons

The forward pass

Stage 2 — Training

The training loop

Loss functions

Dependency injection via `Depends`

Triggers — the `on:` field

Steps: `uses` (actions) and `run` (shell)