Smart Sales Starter Files

Start a processing a BI pipeline by reading raw data into pandas DataFrames (a two dimensional representation much like an Excel sheet).

---

WORKFLOW 1. Set Up Your Machine (DONE in P1)

Proper setup is critical. Follow earlier instructions to set up your machine.

---

WORKFLOW 2. Set Up Your Project (DONE in P1)

We used these one-time commands when first starting the project.

uv python pin 3.12
uv venv
uv sync --extra dev --extra docs --upgrade
uv run pre-commit install
uv run python --version

Windows (PowerShell):

.\.venv\Scripts\activate

macOS / Linux / WSL:

source .venv/bin/activate

---

WORKFLOW 3. Daily Workflow

As we progress, we'll use this daily workflow often.

3.1 Git Pull from GitHub

Always start with git pull to check for any changes made to the GitHub repo.

git pull

3.2 Run Checks as You Work

If we need additional packages, we first add them to pyproject.toml. Add pre-commit to pyproject.toml if you haven't already.

1. Update dependencies (for security and compatibility).
2. Clean unused cached packages to free space.
3. Use git add . to stage all changes.
4. Run ruff and fix minor issues.
5. Update pre-commit periodically.
6. Run pre-commit quality checks on all code files (twice if needed, the first pass may fix things).
7. Run tests.

In VS Code, open your repository, then open a terminal (Terminal / New Terminal) and run the following commands one at a time to check the code.

uv sync --extra dev --extra docs --upgrade
uv cache clean
git add .
uvx ruff check --fix
uvx pre-commit autoupdate
uv run pre-commit run --all-files
git add .
uv run pytest

NOTE: The second git add . ensures any automatic fixes made by Ruff or pre-commit are included before testing or committing.

3.3 Build Project Documentation

Make sure you have current doc dependencies, then build your docs, fix any errors, and serve them locally to test.

uv run mkdocs build --strict
uv run mkdocs serve

• After running the serve command, the local URL of the docs will be provided. To open the site, press CTRL and click the provided link (at the same time) to view the documentation. On a Mac, use CMD and click.
• Press CTRL c (at the same time) to stop the hosting process.

3.4 Execute

This project includes demo code. Run the data_prep module to confirm everything is working.

In VS Code terminal, run:

uv run python -m analytics_project.data_prep

---

3.5 Git add-commit-push to GitHub

Anytime we make working changes to code is a good time to git add-commit-push to GitHub.

1. Stage your changes with git add.
2. Commit your changes with a useful message in quotes.
3. Push your work to GitHub.

git add .
git commit -m "describe your change in quotes"
git push -u origin main

This will trigger the GitHub Actions workflow and publish your documentation via GitHub Pages.

3.6 Modify and Debug

With a working version safe in GitHub, start making changes to the code.

Before starting a new session, remember to do a git pull and keep your tools updated.

Each time forward progress is made, remember to git add-commit-push.