---
layout: post
title:  "tbl: structuring the project"
author: mjadud
commit: https://github.com/jadudm/pytbl/tree/4433e25769f8ee70da0de363d6589f3c77a96a53
tags:
  - cc-sa
  - tbl
  - blog
  - "2020"
  - 2020-03
date: 2020-03-09
---

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](https://docs.python-guide.org/writing/structure/) 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](http://bit.ly/2v6zyON) 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](https://github.com/facebookresearch/hydra) library from Facebook (I think I'm going to need it later) and the [requests](https://requests.readthedocs.io/en/master/) 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`.