{
  "id": 14375648,
  "title": "Before you read a codebase, draw its shape",
  "url": "https://urgent.news/2026/10/14/before-you-read-a-codebase-draw-its-shape",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-14T05:22:29.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/katyread/before-you-read-a-codebase-draw-its-shape-3220"
  },
  "original_language": "en",
  "account": "When approaching a new codebase, it's easy to feel overwhelmed by the sheer number of files and the complexity of the project. A small tool called shape.py, written in Python, can provide a helpful overview of the repository in a single screen. This tool prints the file count, total size, source size, non-source weight, top-level layout, and the largest source files. By using shape.py, you can quickly get a sense of the project's structure, entry points, and the distribution of files.\n\nFor example, when applied to the OpenAI swarm repository, shape.py revealed that there are only 6 files in the entire framework, making up just 16 KB of the total 962 KB repository. The majority of the codebase consists of examples (236 files, 497.4 KB) and assets (411 KB of images). This distribution highlights that the intimidating size of the repository is primarily due to the various examples and assets rather than the core framework itself.\n\nThe tool also highlights the largest source file, tqdm/std.py, which is 56.7 KB in size. This illustrates that a large file does not necessarily indicate poor code quality. In this case, the extensive file size is due to the battle-tested nature of the tqdm library, which contains numerous edge cases and functionalities.\n\nRunning shape.py on unfamiliar codebases can help you quickly understand where to start and avoid misclassifications of files as source or non-source. However, it is essential to remember that shape.py provides a structural read of the codebase, not a review of its semantics or a guarantee of bug-free code. It is a valuable tool for gaining an initial understanding of the repository's organization, but it should be used as an aid, not a definitive source of information about the code's quality or functionality.",
  "summary": "Open a 300-file repo and the first thing you feel is vertigo. Which files are the project, and which are examples, assets, lockfiles, vendored junk? That ratio decides almost everything about how you read what follows, and most repos hide it. So I wrote a small tool ( shape.py , Python stdlib only) that prints a structural read of any folder in one screen: file count, total size, source size, the…",
  "key_points": [
    "Shape.py provides a quick overview of a codebase in a single screen",
    "OpenAI swarm repository has only 6 files making up 16 KB of the total 962 KB repository"
  ],
  "editors_take": "Visualizing repository structure through tools like shape.py allows developers to distinguish core logic from secondary assets, preventing the intimidation caused by large file counts and complex directory layouts.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}