Python Secrets Management

The instinctive first reaction to noticing a committed secret — delete the line and commit that fix — does not actually solve the problem, and understanding precisely why is essential. Git tracks the *complete history* of every commit, and a new commit removing a line doesn't erase that line from the *earlier* commit where it was added; that earlier commit, with the secret fully intact, remains a permanent, retrievable part of the repository's history, accessible via git log -p, git show <commit>, or simply checking out that earlier commit directly.

This means a secret committed even once is effectively permanently exposed to anyone with access to the repository's history — which, for a public repository, means anyone on the internet, and for a private repository, means every current and former collaborator, plus anyone who cloned it during the window before the secret was 'removed.' The actual, only reliable fixes once a secret has been committed are: rewriting git history to genuinely purge the secret from every commit (a disruptive, coordination-heavy operation using tools like git filter-repo, affecting every collaborator's local clone), or — the more universally reliable response — rotating the secret, meaning revoking the exposed credential entirely and issuing a brand new one, since a rotated credential renders the exposed old one useless regardless of how many places it's still recoverable from.

The practical lesson this establishes: prevention is dramatically cheaper than remediation. A secret that's never committed in the first place requires none of this — no history rewriting, no coordination with every collaborator, no rotation under time pressure — which is exactly why the patterns in the rest of this lesson focus specifically on keeping secrets out of source control from the very start.

os.environ["API_KEY"] reads a value from the process's runtime environment — a value that's set *outside* the codebase entirely, typically via the shell (export API_KEY=...), a deployment platform's dedicated secret/environment configuration (nearly every cloud provider and PaaS offers this), or a CI system's encrypted secrets store. Because the actual secret value never appears anywhere in the source code itself, it structurally cannot end up in git history — there's simply nothing secret-related for git to ever track.

Using os.environ[key] (subscript access, which raises KeyError if the variable is missing) rather than os.environ.get(key) (which returns None silently) is a deliberate choice for genuinely required secrets: a missing, required API key should fail the application immediately and clearly at startup — KeyError: 'API_KEY' — rather than silently proceeding with None as the credential and producing a much more confusing failure later, deep inside whatever code first actually tries to use the missing value (an authentication failure against an external API, far removed from the actual root cause).

This pattern — reading configuration and secrets from the environment rather than hardcoding them — is also precisely what the Twelve-Factor App methodology (a widely-referenced set of best practices for building deployable, portable applications) specifically recommends, and it generalizes cleanly across every deployment context: the exact same code runs correctly in local development, staging, and production, with each environment simply providing its own appropriate secret values through the environment, never through a difference in the code itself.

Manually export-ing several environment variables in every fresh terminal session during local development is genuine friction, which is precisely the problem python-dotenv (and its .env file convention) solves: a .env file holds key-value pairs for local development, and load_dotenv() reads that file and populates os.environ from it at application startup — the *rest* of the code still reads secrets via plain os.environ[key], completely unaware of whether the values ultimately came from a .env file or genuine shell/platform environment variables.

The absolutely non-negotiable rule this convenience requires: `.env` must always be listed in `.gitignore`, exactly like the virtual environment directories covered in the Virtual Environment Best Practices lesson. A .env file, by its very purpose, contains real (even if development-only) secret values — committing it defeats the entire purpose of environment-variable-based secret management, recreating precisely the permanent-git-history exposure problem this lesson opened with, just via a different file.

A .env.example (or .env.template) file, *without* real secret values — just the variable names and placeholder or dummy values (API_KEY=your-key-here) — is the standard, safe-to-commit companion: it documents exactly which environment variables a new developer needs to set up locally, without ever containing an actual, usable secret itself. This gives new team members clear, discoverable guidance on what to configure, while keeping the actual, real secret values entirely out of version control at every point in the workflow.

Deleting a secret in a new commit doesn't delete it from git history — it's still sitting in every earlier commit, permanently. The only real fix is never committing it in the first place.

A hardcoded secret in source code ends up in git history PERMANENTLY -- even if a later commit removes it, it's still recoverable from earlier commits.

Checkpoint: If a hardcoded API key is committed, then removed in a LATER commit, is the secret actually safe now?

• →No — it remains permanently recoverable from the earlier commit still in git history, unless history itself is rewritten and the key is also rotated/revoked
• →Yes — removing it in a later commit fully removes it from the repository

Environment variables keep secrets OUT of source code entirely -- os.environ reads them from the runtime environment, never from a committed file.

Checkpoint: Why does os.environ["API_KEY"] (using [ ], not .get()) raising KeyError on a missing variable count as a GOOD thing here?

• →It fails immediately and loudly if the required secret is genuinely missing, rather than silently proceeding with no credential and failing confusingly later
• →It's a faster lookup than os.environ.get()

python-dotenv loads a LOCAL .env file into environment variables for development -- and .env must ALWAYS be in .gitignore, never committed.

Secrets management protects your credentials; Safe File Handling is the next lesson, protecting the filesystem operations your code performs.

Read a Real Secret from the Environment. Finish get_api_key(): reading from the environment keeps a secret out of source code entirely.