Set up a professional repo

This shell script builds an empty folder into the skeleton of a real Python project — the exact shape professional repos use. Run the lines top to bottom; each && means "only do the next thing if the previous one succeeded".

1. mkdir my-tool && cd my-tool — make a new project folder and step into it. Everything after this happens inside my-tool.
2. mkdir -p src/my_tool tests — create the two standard folders at once. -p means "make parent folders as needed and don't complain if they exist". Your code lives in src/my_tool; your tests live in tests.
3. touch src/my_tool/__init__.py — create an empty file with that special name. Its presence tells Python "this folder is an importable package".
4. printf "…" > .gitignore — write a .gitignore file listing things git should never track (the virtual-env folder, caches, secrets in .env). The \n pieces are line breaks, so each entry lands on its own line.
5. python3 -m venv .venv && source .venv/bin/activate — create an isolated "virtual environment" (a private copy of Python for this project) and switch your shell into it. Now packages you install stay in this project, not your whole computer.
6. pip install pytest requests && pip freeze > requirements.txt — install the test runner and an HTTP library, then record the exact versions into requirements.txt so a teammate can reproduce your setup precisely.

What the output means: No visible result — this script just creates files and folders. Afterwards your prompt usually shows (.venv) at the front, confirming the virtual environment is active.

Try this: Run ls -R after this to see the tree you built, and cat .gitignore to confirm the four ignore lines landed correctly.

This is the actual tool. It has two parts: a pure function that does the real work (counting lines in files) and a thin command-line wrapper around it. Keeping the logic separate from the command-line plumbing is what makes it easy to test later.

1. from pathlib import Path — bring in Python's modern file-path helper. Path(p) turns a plain string like "notes.txt" into an object that knows how to read the file, get its name, check if it exists, etc.
2. summarize(paths) returns a dictionary mapping each file's short name to its line count. The {… for p in paths if Path(p).exists()} is a dict-comprehension: loop over every path, skip ones that don't exist, and for the rest store name → number of lines. It's "pure" because the same inputs always give the same output and it changes nothing else.
3. main(argv=None) is the command-line entry point. argparse reads the arguments a user typed; nargs="+" means "accept one or more file paths". It then prints each count right-aligned in a 6-wide column ({n:6}) and returns 0 to signal success.
4. The last two lines are a quick live demo: write a 3-line file to /tmp/cap.txt, then call summarize on it and print the result.

What the output means: {'cap.txt': 3} — a dictionary with one entry: the file cap.txt has 3 lines. That is the pure function working correctly.

Try this: Add a second file (e.g. write /tmp/two.txt with two lines) and pass both paths to summarize. You should see two entries in the dictionary.

This shows how you prove the tool works — automatically, not by eyeballing output. It re-defines summarize so the snippet runs on its own, but in the real repo you'd import it (see the commented line). The important part is the assert checks.

1. An assert says "this must be true; if it isn't, stop and shout". A passing assert is silent; a failing one raises an error that pinpoints the bug.
2. f = Path("/tmp/cap_test.txt"); f.write_text("one\ntwo\n") — set up a known input: a file with exactly two lines. Tests should create their own predictable data.
3. assert summarize([str(f)]) == {"cap_test.txt": 2} — the happy path: a real two-line file must report a count of 2.
4. assert summarize(["/no/such/file"]) == {} — the edge case: a file that doesn't exist must be skipped, giving an empty dictionary rather than crashing.
5. If both asserts pass, execution reaches print("tests pass").

What the output means: tests pass — both assertions held, so the function behaves correctly on a normal file and on a missing one. If an assert failed you'd instead see an AssertionError and no "tests pass" line.

Try this: Break the code on purpose: change the expected 2 to 3 and re-run. The AssertionError you get is exactly how a test tells you something regressed.

pyproject.toml is the standard packaging manifest — the ID card that turns your loose folder into an installable Python package. [section] headers group related settings; key = value lines set them.

1. [project] — the basic identity: the package name, its version, the minimum Python it needs (requires-python = ">=3.10"), and its runtime dependencies (here requests, pinned to a safe version range).
2. [project.scripts] — the magic that gives you a real command. my-tool = "my_tool.core:main" means "when installed, create a command called my-tool that runs the main function in my_tool/core.py". The comment shows the install step: pip install -e ..
3. [build-system] — tells pip how to build the package. Here it uses hatchling, a common, low-fuss build backend. You rarely change this.

Try this: After pip install -e . in the repo, type my-tool README.md in your terminal. Because of the [project.scripts] mapping, that command now exists and runs your tool.

These git commands put the project under version control, publish it to GitHub, and start a feature branch so your change can go through a pull request (PR) — the professional way to get code reviewed before it joins the main line.

1. git init && git add . && git commit -m "chore: scaffold my-tool" — start tracking this folder, stage every file (add .), and record the first snapshot with a message. chore: is a conventional prefix meaning "setup, not a feature".
2. git branch -M main — name the primary branch main (the modern default).
3. git remote add origin git@github.com:you/my-tool.git — tell git where the online copy lives, nicknaming that address origin.
4. git push -u origin main — upload main to GitHub for the first time. -u links your local branch to the remote one so future pushes are just git push.
5. git switch -c feat/summarize — create and move onto a new branch for your feature, so main stays stable while you work. After committing the tool and tests, the final git push -u origin feat/summarize uploads the branch — GitHub then offers to open the PR.

What the output means: Each command prints a short status line (files staged, branch created, push progress). The payoff is on GitHub: your branch appears with a "Compare & pull request" button.

Try this: Run git log --oneline to see your commit, and git branch to confirm you're on feat/summarize, not main.

This YAML file is a CI (Continuous Integration) pipeline: GitHub runs it automatically on a fresh machine every time you push or open a PR, so tests are checked for you — no one can forget. Indentation defines the nesting, so keep it exact.

1. name: CI and on: [push, pull_request] — name the workflow and set its triggers: run it on every push and on every pull request.
2. jobs: test: defines one job called test; runs-on: ubuntu-latest gives it a clean Linux machine to run on.
3. steps: is an ordered list. The two uses: lines pull in ready-made actions — checkout grabs your code, setup-python installs Python 3.12 on the runner.
4. run: pip install -e . pytest installs your package and the test runner; run: pytest -q runs the tests quietly. If any test fails, the job goes red and, with branch protection on, that blocks the merge — bad code can't reach main.

What the output means: On GitHub you'll see a green check next to the commit when tests pass, or a red X when they fail. The red X is what stops a broken change from being merged.

Try this: Push a commit with a deliberately failing test and watch the Actions tab turn red — then fix it and watch the same pipeline turn green.