🔵 Run and Check
This mirrors professional practice: run and check code as you work.
Step 1. Run Code
Run Python scripts as needed for your project. Exact commands should be listed in the project README.md. The command should look something like this, but the package name might be different than datafun to match your project:
shell
uv run python -m datafun.app
Step 2. (As Needed) Add / Update Dependencies
As we work on the code, we may find we need additional dependencies listed in pyproject.toml. For example, after generating results we may add matplotlib to visualize charts. Edit pyproject.toml and add packages to the dependencies section as needed. You may occasionally need to clean the cache (delete downloaded dependency files stored locally). Then re-run the uv sync command as shown below:
```shell uv cache clean
uv python install uv lock --upgrade uv sync ```
When working on a project, open the project repository folder in VS Code. In general, all terminal commands should be executed in the root project folder.
Step 3. Run Checks and Tests (as available)
Run the following commands in a VS Code terminal to:
- Format all project Python files using Ruff.
- Check and fix all project Python files (automatically "lint" or fix basic issues).
- Optional: Run pytest if you have working tests in the tests/ folder.
shell
uv run ruff format .
uv run ruff check . --fix
uv run ty check
uv run python -m pytest
Step 4. Build Documentation
Make sure the documentation dependencies in pyproject.toml are installed. Then build the project docs, fix any errors, and serve them locally to test.
shell
uv run python -m zensical build
uv run python -m zensical serve
- After running the serve command, a local URL for the documentation will be displayed.
- To open the site, press Ctrl and click the provided link (at the same time) to view the documentation. Use Cmd and click on Mac.
- To stop the server, click in the terminal, and press Ctrl c to terminate the local hosting process.
Why we include python -m
In a command like this: uv run python -m zensical build, the python -m is sometimes optional. The longer form is safer for heterogeneous environments. It:
- explicitly uses the Python interpreter selected by uv
- avoids relying on a separate console-script wrapper
- behaves consistently across Windows, macOS, and Linux
- is officially supported by the Zensical package
- provides one standard command form for all users and machines wherever possible
Professional Reminders
- Use the VS Code menu to turn on Auto Save (File / Auto Save), or remember to save your changes as you work.
- Comment out code as needed to get a version that runs without errors.
- If you encounter errors, use debugging tools, strategically placed logging statements, or print() calls to reveal where execution is occurring and what values are stored in variables.