tbl: structuring the project

It helps, early, to structure a project well.

Having written a version of tbl in another language once before, and now revisiting the design and implementation in Python, I know I should think about how the project is structured from the start.

I find The Hitchhiker’s Guide to Python to be a wholly remarkable book, like it’s namesake (The Hitchhiker’s Guide to the Galaxy). As a result, I’ll restructure the code around their recommended format for a Python module at this point. tbl will become a module that I want to pip install, so it makes sense to clean it up now.

the layout

First, I’m going to move some things around. The project directory looks like this:

drwxr-xr-x 9 jadudm jadudm 4096 Mar  8 20:10 .
drwxr-xr-x 7 jadudm jadudm 4096 Mar  8 20:07 ..
drwxr-xr-x 2 jadudm jadudm 4096 Mar  8 20:08 docs
drwxr-xr-x 8 jadudm jadudm 4096 Mar  9 08:47 .git
-rw-r--r-- 1 jadudm jadudm   25 Mar  8 15:03 .gitignore
-rw-r--r-- 1 jadudm jadudm 1093 Mar  8 14:42 LICENSE
-rw-r--r-- 1 jadudm jadudm  239 Mar  8 20:42 lobsters.py
-rw-r--r-- 1 jadudm jadudm   79 Mar  8 20:11 Makefile
drwxr-xr-x 2 jadudm jadudm 4096 Mar  8 15:01 __pycache__
-rw-r--r-- 1 jadudm jadudm 1762 Mar  9 08:47 README.md
-rw-r--r-- 1 jadudm jadudm   15 Mar  8 14:45 requirements.txt
drwxr-xr-x 3 jadudm jadudm 4096 Mar  9 08:07 tbl
drwxr-xr-x 2 jadudm jadudm 4096 Mar  8 20:08 tests
drwxr-xr-x 6 jadudm jadudm 4096 Mar  8 13:53 venv
drwxr-xr-x 3 jadudm jadudm 4096 Mar  9 08:12 .vscode

Because I want this to become a library that I can pip install, I’ve taken a few necessary steps in that direction. First, I’ve created a subdirectory called tbl, and in that directory, I moved the file previously called main.py and called it __init__.py. The secret here is that, in Python, any directory containing a file called __init.py is considered a module. Modules are the fundamental unit of organization for libraries of code, so this is a clear and necessary step.

Running ls -al tbl:

(venv) jadudm@lego:~/git/pytbl$ ls -al tbl/
total 20
drwxr-xr-x 3 jadudm jadudm 4096 Mar  9 08:07 .
drwxr-xr-x 9 jadudm jadudm 4096 Mar  8 20:10 ..
-rw-r--r-- 1 jadudm jadudm 2077 Mar  9 08:19 __init__.py
drwxr-xr-x 2 jadudm jadudm 4096 Mar  9 08:14 __pycache__
-rw-r--r-- 1 jadudm jadudm  406 Mar  9 08:14 util.py

I also, in the last commit, created a small utility library. I’ll blog about that later.

At the top level, there are directories for tests and docs, which I’ll begin filling in soon.

The .gitignore is an important file; it says which files and directories I never want to put under version control. For example, my venv is something I never want to see in the repository… it’s a local working environment for my Python interpreter, so that when I install libraries to support the use of tbl, I don’t install them globally… instead, they get installed in the venv directory. (This, too, is probably a good subject for another post… or, at least, a few more links.)

The requirements.txt says which libraries are needed to support tbl. Right now, I have the hydra library from Facebook (I think I’m going to need it later) and the requests library, which makes working with content over the ‘net a lot easier.

It turns out (for those following along) that the structure of code is often as important, if not moreso, than the code itself. If I don’t place files in the right places, with the right names, then my code is not, and cannot, become a Python library. Similarly, if I want to write an application in Java for Android… some files have to be named specific ways, and be placed in particular places in order for them to be assembed into an app. This is a critical, but sometimes invisible, part of writing code that is too often glossed over when students are getting started programming.

structure, complete

This is a first step in shifting the structure of the project around. There will be more, but for now it brings tbl one step closer to being installable as a Python package via pip.