just-enough on Computer Freud

Just Enough Python Packaging

Fri, 27 Feb 2026 10:18:24 -0700

Just Enough Python Packaging 🔗

Skip poetry. Skip pip. Do not pass go, jump directly to uv. It is without question the best way to manage python packages in 2026.

uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, venv, poetry, pyenv, and more. If you are still manually managing .venv folders or fighting with poetry lock times, it’s time to take some precious time back.

You need uv.
Follow the official installation guide. You shouldn’t be installing Python any other way than through uv at this point.
Init the project.
Use the --package flag. This sets up a standard src layout which is the industry standard.

uv init my-cool-project --package
cd my-cool-project

Project Layout
Your project should look like this. This is the opinionated guidance that uv init gives you, and you should keep it!

my-cool-project/
├── pyproject.toml   # The brain of the project
├── uv.lock          # The source of truth (don't touch)
├── .python-version  # Managed for you
├── src/
│   └── my_package/  # Your actual code
│       └── __init__.py
└── tests/           # Where the tests live

Dependency Management
Add what you need through command line.

uv add requests

You can also add this in the pyproject.toml. Make sure you uv sync!

Dev tools belong in dev groups.
Don’t pollute your production dependencies with pytest or ruff. Use the --dev flag.

uv add --dev pytest ruff

Extras for the heavy stuff.
If your package has “optional” features (like Excel support or a heavy UI), use extras.

uv add pandas --optional excel

This keeps the base install lightweight. It allows users the freedom to choose what parts of your package to install.

Run your code.
Use uv run. It ensures you’re using the exact versions defined in your lockfile.

uv run python src/my_package/main.py

uvx is magic.
This is the equivalent of npx for Node developers. It’s perfect for tools like Ruff. Ruff is so fast it makes other linters look like they’re from another century. It replaces Flake8, Black, and isort in one go.

uvx ruff check .

TODOs: 🔗

(Research these yourself!) 🔗

uv Workspaces for when your project gets too big.
Building and Publishing - uv build is all you need.
Docker integration - How to stop building 2GB Python images.
Ruff Configuration - Automate your formatting so you never have to think about it again.

Just Enough Hugo

Thu, 10 Jul 2025 17:18:24 -0700

Just Enough Hugo 🔗

Follow the quickstart. Can’t get more straightforward than that.

Do not follow the advice regarding submodules. Submodules are horrible and you should not even think about them. We will discuss that point again later.

Stop before you get there, even if you don’t have a working site yet.

Themes 🔗

As indicated by quickstart, you need a theme.

https://themes.gohugo.io/ is a good place to look, as is github. (many of these will point you to the github repo for the theme anyway).

Sites will indicate to you to do one of two different things; either submodule the theme or clone it to your repo. Both are terrible choices and there is one that’s not discussed upfront.

Hugo Modules 🔗

Newer versions of Hugo do what could only be done with Golang before. There is better documentation for this now.
https://gohugo.io/hugo-modules/use-modules/

When you’re ready for a theme, follow the instructions above. Once you do it this way, you never go back. This is a much more lightweight and malleable approach than Git submodules.

You could technically manage the module with golang directly. It’s probably equivalent at this point.

Config 🔗

https://gohugo.io/getting-started/configuration/ Choose Toml,Yaml,or Json according to your preference.

A good early practice is to start separating config into default, dev, and production configs. You only need to add specific values that you want to override in non-default configs.

config
├── _default
│   └── config.yaml
├── develop
│   └── config.yaml
└── main
    └── config.yaml

You may also need to tie this in to CI in deployments, e.g. based on above: hugo --environment $GIT_BRANCH

It should be pointed out this was written by someone more familiar with the config. convention, which Hugo has apparently changed.

With v0.109.0 and earlier the basename of the site configuration file was config instead of hugo. You can use either, but should transition to the new naming convention when practical.

Development Loop 🔗

Read about archetypes, set them up and add new content.
hugo new my-cool-archetype/something.md

Run hugo server to see your stuff locally.

Deploying to Production 🔗

Look into Vercel, Cloudflare, Netlify, Azure Static Sites or other hosting providers with built-in support.

Connect your repository to it directly. A common pattern is previewing from PR and deploying production from main branch.

There’s no reason to roll-your-own with AWS or another static bucket website unless you’re really insistent to do that.

Just Enough Node.js

Tue, 22 Oct 2024 20:18:24 -0700

Just Enough Node.js 🔗

Create a project folder. Using the command line, cd into it.

You need to get NPM. You want NVM, to get Node, to get NPM. 🔗

Start with having, or setting up NVM. You shouldn’t install Node any other way than this by now.
Once NVM is set up, install a modern-ish version of Node. You might want to catch up on the Node version schedule.

nvm install 18
nvm use 18

As a good practice, create a .nvmrc file in the project root, containing this version number (like 18 or more specific as needed). A more precise approach might be:

node -v > .nvmrc

Init the project with npm:

npm init

You now have a package.json file. Using NPM, you can add a package to it as a dependency, like axios:

npm add axios

You should create a package entrypoint. If you used defaults for npm init this should be index.js:

touch index.js

In index.js, we need to start using Axios. We are going to use this to download a file. We’re going to skip ahead a few steps by using the function below. This also uses the fs module which is a node built-in.

const axios = require('axios')
const fs = require('fs')
const path = require('path')

url = 'https://i.imgflip.com/71soed.jpg'

async function download(url, directory, filename) {
  const newPath = path.resolve(directory, filename)
  const writer = fs.createWriteStream(newPath)
  const response = await axios({
    url,
    method: 'GET',
    responseType: 'stream'
  })
  response.data.pipe(writer)
  return new Promise((resolve, reject) => {
    writer.on('finish', resolve)
    writer.on('error', reject)
  })
}

download(url,"./","image.jpg")

This technically achieves making a request, but to add flavor to our CLI workflow we might want to create a download script. In package.json, add a “scripts” key if not present at the top-level, and add a “download” key to that, referencing index.js. After you do this you could use npm run download to run your command.

"scripts": {
    "download":"node index.js"
}

We have an MVP, but before shipping this we should really consider adding tests. We can start by adding jest as a Dev dependency (using -D).

npm add -D jest

Add jest to your package.json scripts key, so it now looks like:

  "scripts": {
    "download": "node ./index.js",
    "test": "jest"
  },

Fill in a test case in test/index.test.js. We’ll skip ahead some more, and add the following contents to it:

const fs = require('fs')
const index = require('../index.js');

test('a file is downloaded', () => {
    url = 'https://i.imgflip.com/71soed.jpg'
    index.download(url,"./","image.jpg")
    fileExists = fs.existsSync('./image.jpg')
    expect(fileExists).toBe(true);
});

Run your new test with npm test
Ooops! Something failed.
It seems to be that we forgot to export the function from our module, let’s fix that in index.js:

module.exports = {download}

Try again, and relish that you are now a Node.js dev!

npm test

TODOs: 🔗

(Research these yourself!) 🔗

Some more things to think about from here are:

Better abstracting our functions
Logging
Making functions and tests run async
Setup/teardown of tests