This guide is for contributors or anyone interested in the technical implementation of the Habit Tracker CLI. It details the project's structure, development setup, and testing procedures.

The project is organized using a standard src layout to ensure a clean separation between the installable source code and other project files like tests and configuration. This design promotes modularity and testability.

• src/habit/: The core Python package containing all application logic.
• tests/: A separate, top-level directory for all tests, ensuring they are not included in the final distribution.
• Configuration Files: Root-level files (pyproject.toml, setup.py, etc.) manage the project's installation, dependencies, and script entry points.

• pyproject.toml / setup.py

  • Role: Defines the project for packaging with tools like pip and setuptools. It specifies metadata, dependencies, and, most importantly, registers the habit command as a script entry point that points to habit.cli:cli.

• src/habit/

  • Role: The main, installable Python package.
  • __init__.py: Marks the directory as a Python package.
  • cli.py: The user interface layer. It uses click to define all commands and options for the habit script. It contains no business logic itself.
  • models.py: The data layer. Defines the database schema using SQLAlchemy.
  • habit_manager.py: The business logic layer for data manipulation (CRUD operations).
  • analysis.py: The business logic layer for data analysis (streaks, scores, summaries).
  • fixtures.py: A data generation module used exclusively for the demo environment.

• tests/

  • Role: Contains all application tests, completely separate from the source code.
  • conftest.py: A special pytest file defining shared test fixtures, primarily the in-memory test database setup.
  • test_*.py: Individual test modules for habit_manager and analysis functions.

Follow these steps to set up a local development environment. This process uses an "editable" install, which means changes you make to the source code will be immediately effective without needing to reinstall.

1. Clone the Repository

git clone https://github.com/Sydefix/habit-tracker.git
cd habit-tracker

2. Create and Activate a Virtual Environment

# On macOS / Linux
python3 -m venv venv
source venv/bin/activate

# On Windows
python -m venv venv
.\venv\Scripts\activate

3. Install in Editable Mode

From the project's root directory, run the following command. This will install the habit package itself, along with all its dependencies (click, sqlalchemy) and make the habit command available in your terminal.

pip install -e .

The -e flag stands for "editable," linking the installed package directly to your source code in the src directory.

4. Verify the Installation

Check that the habit command is working correctly:

habit --help

You should see the main help message with a list of available commands (add, demo, analyze, etc.). Your development environment is now ready.

The project uses the pytest framework. Tests are designed to run against a clean, in-memory SQLite database for speed and isolation.

To run the entire test suite, navigate to the project's root directory and simply run:

pytest

This command will automatically discover and run all tests in the tests/ directory. It is essential to run the tests after making any changes to ensure that no existing functionality has been broken.

• Please follow the existing code style to maintain consistency.
• Ensure all tests pass by running pytest before submitting changes.
• If adding new features, please include corresponding tests.
• Submit changes via GitHub Pull Requests.