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.
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.
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
docs, which I’ll begin filling in soon.
.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.)
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.
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