From Random Scripts to a Real Python Package (Part 1)

The Moment I Realized My Python Project Wasn't Really a Project

When I first started learning Python, my projects were about as simple as they could be.

project/
├── logic.py
└── main.py

If I wanted to run the program, I simply typed:

python main.py

If I needed another function, I created another file and imported it.

from logic import calculate

Everything worked. At the time, I thought this was what "organizing a Python project" meant. I was wrong.

A Collection of Scripts Is Not a Software Project

Over the past few months, I've been rebuilding Python's built-in functions from scratch as a way to understand how they actually work. Instead of solving algorithm exercises, I implemented functions like:

• map()
• filter()
• any()
• all()
• max()
• min()

One function became ten. Ten became dozens. Soon I wasn't just writing code anymore. I started writing documentation for each implementation. I added tests. I kept notes about design decisions. I experimented with different implementations. Without realizing it, what began as a few learning scripts slowly evolved into a real project. Unfortunately, my project structure never evolved with it.

Documentation Everywhere

At first, I stored documentation wherever it felt convenient. Some notes were inside Markdown files. Some were buried in my note-taking application. Others existed only inside commit messages. Every time I came back to the project, I had to spend several minutes remembering questions like:

• Where did I explain this implementation?
• Which version of this function is the latest?
• Why did I choose this approach?
• Where are the tests?

Nothing was technically broken. But nothing felt organized either. That was when I realized something interesting. The biggest problem wasn't my code. It was the environment surrounding my code.

"Maybe I Should Treat This Like a Real Project"

My first instinct was incredibly simple. Create a folder.

pycore/

Then create a virtual environment.

python -m venv .venv

Problem solved. Or so I thought.

The more I read the official Python Packaging documentation, the more I realized that a virtual environment is only one small piece of a much larger picture. I had always thought "setting up a project" meant creating a folder and installing packages. But a reusable software project needs much more than that.

Questions I had never asked before suddenly became important.

• Where should the source code live?
• How should dependencies be declared?
• Where do tests belong?
• How should documentation be organized?
• How do other people install this project?
• What exactly is pyproject.toml ?

These weren't Python syntax questions. They were software engineering questions.

Learning Packaging Was Really Learning Software Design

At first, I assumed Python Packaging was simply about publishing libraries to PyPI. I wasn't planning to publish anything. I just wanted a clean project structure. Ironically, that decision led me into an entirely different world.

I started reading Packaging User Guide documentation. I discovered concepts like build systems, dependency management, editable installations, source layouts, and package metadata. None of these topics had anything to do with writing better algorithms. Instead, they answered a different question. How should a software project be organized so that both humans and tools can understand it?

Looking back, that was the point where I stopped thinking like someone writing Python scripts and started thinking like someone building software.

What's Next

Before deciding where my code should live or what should go inside pyproject.toml, I first needed to understand something much more fundamental. What actually makes up a Python project's environment? At the time, I thought the answer was simply "a virtual environment." It turns out that was only one piece of the puzzle.

In the next article, we'll build a mental model of a modern Python project by exploring the five concepts that completely changed how I think about Python Packaging.

Top comments (0)