Phrasewood: Setting Up the Development Environment

In which I set up my local environment, a remote repository, and design a rough repository structure.

Recap

In my previous article, I shared my motivation to create a modern Python engine for text-based video games. I reflected on my career change from the food service industry to the tech world, which eventually led me back to this exciting project I envisioned years ago. Now, let’s dive into the initial steps of bringing Phrasewood to life.

Designing My Directory Structure

Phrasewood is an ambitious project with three primary goals: an open-source library, a web-based GUI for developing games, and a web platform for sharing and playing games. To lay a strong foundation, I began with the development of the Python library.

The first step was to design a directory structure tailored to this purpose.

For this project, I decided to construct and package my Python library using setuptools and a pyproject.toml file (see the setuptools documentation and this helpful guide for more info on this approach). I took this approach because it is a structure I’ve used before, for my ChunkGPT library. While I’ll be making important, unfamiliar decisions later in this project, sticking with what I know for now seemed prudent.

The skeleton directory for this project looks like this:

├── phrasewood_env/           -- Python virtual environment
│   ├── ...
├── dist/                     -- home for all future dist files
│   ├── ...
├── examples/                 -- home for example game files
│   ├── ...
├── src/                      -- top-level directory for library
│   ├── phrasewood/           -- home for all packaged library code
│   │   ├── __init__.py
│   │   ├── core/             -- home for all core modules
│   │   │   ├── __init__.py
│   │   ├── tests/            -- home for all tests
│   │   ├── docs/             -- home for all documentation
├── .gitignore
├── LICENSE
├── pyproject.toml            -- package configurations & metadata
├── README.md
├── requirements.txt

Setting Up the Local Environment

To actually create this file structure, I created a local directory, added all the files/directories listed above, and set up a virtual environment within it. This keeps all project-specific library dependencies isolated.

mkdir ~/code/projects/phrasewood
cd ~/code/projects/phrasewood
python3 -m venv phrasewood_env
source phrasewood_env/bin/activate

Setting Up the Remote Repository

Next, I established a remote repository on GitHub, keeping the repository public with the intent to make Phrasewood open-source. The power of open source is the community it can attract and the contributions it can receive.

Initializing and Linking the Local Git Repository

I then initiated a local git repository within my project directory and linked it to the remote GitHub repository. This step is crucial for version control and collaboration.

cd ~/code/projects/phrasewood
git init
git remote add origin https://github.com/dimays/phrasewood.git

Fleshing out the Files

Before committing my work to the remote repository, I added some essential details to specific files.

.gitignore

This file specifies which files and directories should be excluded from version control in the remote repository. This helps keep the repository clean and secure.

For now we only have one file and two directories that we’d like to exclude:

1. .DS_Store: This is a hidden system file created by macOS in directories to store custom attributes and view settings for that folder, helping to remember how it should be displayed when viewed in the Finder. No need to include this one.
2. dist/: This will contain the files needed for distribution on PyPI, and need not be included in our source code repo.
3. phrasewood_env/: Similarly, this directory does not need to be included. It simply contains the Python installation and third-party dependencies, which will be installed with pip once this is distributed on PyPI.

.DS_Store
dist/
phrasewood_env/

LICENSE

Licensing is a complicated issue that I don’t pretend to know everything about—but ultimately I chose the MIT license to make Phrasewood accessible to all developers.

pyproject.toml

This file defines project metadata, build tool settings, and package dependencies in a standardized format.

Following this tutorial, and filling in details from this project, I define the build-system, project, and project.urls metadata fields:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "phrasewood"
version = "1.0.0"
authors = [
    { name="David Mays", email="maysidavid@gmail.com" },
]
description = "A robust Python library for creating text-based video games."
readme = "README.md"
requires-python = ">=3.9"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://github.com/dimays/phrasewood"
"Bug Tracker" = "https://github.com/dimays/phrasewood/issues"

README.md

This file will be a living document that directs my users on installation, usage, and how to find more documentation and information on Phrasewood.

For now, I’ll keep it simple:

# Phrasewood
A robust Python library for creating text-based video games.

**COMING SOON**

Learn more on my [devblog](https://medium.com/@maysidavid).

Pushing to the Remote Repository

With these details in place, I was ready to push my initial work to the remote repository.

cd ~/code/projects/phrasewood
git add .
git commit -m "initial commit"
git branch -M main
git push -u origin main

And just like that, the remote repository is complete, and my local repository is setup to track it!

This sets the stage for the actual development of Phrasewood, and I’m excited to take you along on this journey. Stay tuned for the next steps!

Until next time,
David