Project structure · More
Python package and CLI project structure
Opens with creditsA command line tool published to PyPI, laid out the way the Python Packaging User Guide and uv recommend: a src layout, one pyproject.toml for metadata and every tool, a thin Typer CLI over plain, testable modules, and releases uploaded by GitHub Actions with trusted publishing. The example is mdlinks, a tool that finds broken links in Markdown files. For students who have written Python scripts and want to ship one that strangers can pip install.
Curated by Tauseef FayyazIntermediate135 files and foldersPython 3.11 to 3.14 (3.15 tested as a pre-release), uv 0.12 with the uv_build backend, Typer 0.27Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you14 files and folders
- 2GrowingWhat a real app with features and tests adds+58 files and folders
- ProductionWhat running it for real users adds+26 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+37 files and foldersOpens with credits
How it is organised
- Use the src layout: code lives in `src/mdlinks/`, so tests run against the installed package and catch files missing from the wheel.
- One pyproject.toml holds the package metadata, dependencies and the settings for pytest, Ruff, mypy and coverage. One file to read when CI and your laptop disagree.
- The CLI is a thin shell: it parses flags, calls plain functions, prints results and picks an exit code. The logic never prints, never calls `sys.exit()` and is usable from Python code.
- Decide your public API on purpose: the names in `__all__` are a promise, everything else (and every module starting with `_`) can change freely.
- Exit codes and machine-readable output (`--format json`) are part of your contract with scripts and CI. Change them only in a major release.
- Runtime dependencies are few and loosely pinned (`>=`), because users install your package next to theirs. Exact pins belong in uv.lock, which is for your development and CI only.
- Test in layers: many fast unit tests, CLI tests through CliRunner, and one end to end test that installs the built wheel. Property, snapshot and benchmark tests come when the tool has users.
- Release from CI only, with trusted publishing: no PyPI token on any laptop, and every file on PyPI traceable to the workflow run that built it.
At the top of the project
Open one in the explorer for the full story
- mdlinks/
- .git/Git history for the project. `uv init` creates the repository for you.
- .venv/The project virtual environment that uv creates and keeps in sync with uv.lock.
- .vscode/Shared VS Code settings: the project interpreter, Ruff as formatter, pytest as test runner.2 inside
- .pytest_cache/pytest's cache: which tests failed last time, for `--last-failed`.
- .ruff_cache/Ruff's cache of already-checked files.
- .mypy_cache/mypy's incremental cache.
- .coverageRaw coverage data written by pytest-cov.
- dist/Built distributions: the `.tar.gz` sdist and the `.whl` wheel from `uv build`.
- htmlcov/The browsable HTML coverage report from `coverage html`.
- site/The built documentation website from `mkdocs build`.
- docs/The documentation site sources: Markdown pages that MkDocs turns into a website.7 inside
- src/Holds the import package. The "src layout" that `uv init --package` creates.1 inside
- tests/pytest tests, organised by kind: unit, CLI, end to end, and later property, snapshot and benchmark tests.4 inside
- .editorconfigIndentation, line endings and final newline rules for every editor.
- .gitignoreKeeps the venv, caches, build output and coverage files out of Git.
- .pre-commit-config.yamlRuns Ruff (lint and format), whitespace fixes and a uv.lock check before every commit.
- .python-versionThe Python version uv uses for local development, for example 3.14.
- LICENSEThe license text, for example MIT or Apache-2.0.
- README.mdThe front page on GitHub and on PyPI: what it does, install, one example, link to the docs.
- mkdocs.ymlMkDocs config: site name, Material theme, navigation and the mkdocstrings plugin.
- pyproject.tomlPackage metadata, dependencies, the console script, the build backend, and every tool's settings.
- uv.lockThe exact resolved version of every dependency for every platform, written by uv.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Python package and CLI.
- Roadmap· PythonProgramming foundations roadmapFirst language, Git, CS basics
- RoadmapOpen source roadmapFirst contribution to programmes
- RoadmapLinux, terminal and Git roadmapShell, Git, SSH and your dev setup
- RoadmapQA and test automation roadmapManual testing to automated suites
- Cheat sheetProgramming foundations cheat sheetFirst language, Git, CS basics.
- Cheat sheetOpen source cheat sheetFirst contribution to programmes.
- Cheat sheetLinux, terminal and Git cheat sheetShell, Git, SSH and your dev setup.
- FYP idea· BeginnerHallucinated Package Guard for AI Coding Assistants (Slopsquatting Defence)AI coding assistants sometimes suggest packages that do not exist. Attackers can register those names and wait. Build a guard that checks every new dependency added to a project, by a person or an AI, against the real registry: does it exist, how old is it, who maintains it, does it look like a typo of a popular package, and was it suggested by an AI? It runs in the editor, as a pre-commit hook and in CI.
- FYP idea· AdvancedDependency Upgrade Impact Checker That Finds Which of Your Calls a Breaking Change HitsBuild a tool for TypeScript projects that compares the public API of two versions of an npm package, finds the breaking changes, then searches your own code for the exact call sites they affect. Dependabot and Renovate open upgrade pull requests but cannot say whether a major version bump touches anything you use. This tool answers that question with a list of files and lines, so small teams stop putting off upgrades.
See 10 moreShow fewer
- FYP idea· IntermediateInstruction File Linter for AI Coding Agents: AGENTS.md, CLAUDE.md, Cursor Rules and Copilot InstructionsBuild a command-line tool and CI check that reads the instruction files AI coding agents load, AGENTS.md, CLAUDE.md, .cursor/rules and .github/copilot-instructions.md, and checks them against the real repository: commands that no longer exist, paths that moved, glob patterns that match nothing, rules that contradict each other across files, and files too long to be followed. Teams using several AI tools get one report that keeps their agents working from the truth.
- FYP idea· IntermediateSigned Build Provenance Gate for a Company's Internal Packages and Container ImagesBuild a gate that lets a small company prove every internal package and container image was built by its own CI from a reviewed commit, and blocks anything that was not. It uses keyless signing from the Sigstore project and SLSA-style provenance, wrapped into a setup a team can adopt in an afternoon. Deployments and installs check the signature and the build record before they proceed.
- QuestionShould I learn TypeScript or Python first in 2026?Learn Python first if you are new to programming or drawn to data and AI. Learn TypeScript first only if you already know some JavaScript or are certain about web development, and even then learn plain JavaScript for a few weeks before the types. The second language is much easier than the first.
- QuestionWhat projects should I build in my first year of university?Build small, finished projects that solve problems you or people around you actually have: a script that automates a chore, a command line tool, a simple website for a society or family business. First year is about finishing things and using Git, not about impressive ideas.
- QuestionWhat should I learn first to become a software engineer in 2026?Learn one language properly, then Git, the command line, how the web works and basic SQL, and build small things with them from week one. AI tools change how you write code, not what you need to understand. Pick a direction only after the foundations feel boring.
- Resource· Tooluv DocumentationThe official docs for uv, the fast Python package and project manager from Astral. It replaces pip, virtualenv, pip-tools and pyenv for most projects, and its lockfile is what makes an ML project install the same way on your laptop, in CI and in a Docker image. Free, open source and quick to learn.
- Resource· Guidepytest DocumentationThe official documentation for pytest, the most widely used Python testing framework. It shows how to write tests as plain functions with ordinary assert statements, share setup through fixtures, run one test against many inputs, and extend the tool with plugins. The twenty-minute getting started guide is enough to put tests around a small project, and the rest works as a reference as your suite grows.
- Resource· GuidePython Design Patterns GuideBrandon Rhodes's free guide to design patterns in Python, which is honest about which Gang of Four patterns Python makes unnecessary and which still matter. Its essay on composition over inheritance is one of the clearest explanations of Adapter, Bridge and Decorator written in any language.
- Resource· GuideGitHub Actions DocumentationThe official documentation for GitHub Actions, GitHub's built in CI/CD and automation system: workflow syntax, triggers, runners, caching, artifacts, environments, secrets and OpenID Connect deployments to AWS, Azure and Google Cloud. Actions is free for public repositories on standard runners, so it is the CI tool most students and open source projects learn first. It suits developers setting up tests and deployments for the first time.
- Resource· RoadmapSefism Open Source RoadmapA six-stage plan from how open source projects are run to maintaining a project of your own: the contributor Git workflow, a first merged pull request, becoming a regular on one project, and a proposal for Google Summer of Code, Outreachy or LFX Mentorship. It suits students and engineers who can already build small programs and want public, reviewed work in real codebases. By the end you have at least three merged pull requests in a project you did not start and a maintained repository with CI, templates and tagged releases.
Checked against 19 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- uv: Creating projects
- uv: Building and publishing a package
- uv: Using uv in GitHub Actions
- Python Packaging User Guide: Packaging Python projects
- Python Packaging User Guide: src layout vs flat layout
- Python Packaging User Guide: Writing your pyproject.toml
- Python Packaging User Guide: Publishing with GitHub Actions
- PyPI: Trusted publishers
- PyPI: Attestations
- pypa/gh-action-pypi-publish
- Typer documentation
- pytest: Good integration practices
- Ruff: Configuring Ruff
- mypy: The mypy configuration file
- Material for MkDocs
- mkdocstrings
- nox documentation
- release-please
- Python release schedule (PEP 790)
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Code Review Best PracticesCode review best practices for reviewers and authors: the approval standard, what to look for, review speed, writing kind and useful comments, handling disagreement and small changes.
- Software Testing Best PracticesTesting best practices for unit, integration and end-to-end tests: test design, test doubles, flaky tests, coverage and fast CI, with examples in TypeScript and Python.
- Python Best PracticesWrite Python that stays maintainable: supported versions, pyproject and lockfiles, Ruff, type hints, errors, logging, concurrency, pytest and security.
Checklists
See all- Pull Request Checklist: Before You Open a PRA pull request checklist to run before you ask for review: scope and size, a clean diff, tests, a clear description, safe releases and a tidy branch, each with a way to verify it.
- Career Switch into Tech ChecklistMove into software from another field step by step: choose a direction, follow a learning plan, build proof of skill, use your previous domain, network, plan your runway and target a first role.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com