Skip to content

Latest commit

 

History

History
76 lines (52 loc) · 6.29 KB

help.md

File metadata and controls

76 lines (52 loc) · 6.29 KB
Raw

Helper Resources 💭

Tools Used

There are a number of tools used more widely in the JavaScript / TypeScript ecosystem that can enable better development in Python projects.

Tool Description Project Usage Starter Links
🐾 .husky Husky improves your workflow by running scripts when certain events are triggered by Git. Each file within .husky/ is a shell script that behaves like a hook. Useful when certain actions should run automatically when a commit occurs or a pull from remote is initiated. This may include re-installing the package with pip, etc. Code Quality with Husky and Hooks
⚠️ .pre-commit-config.yaml Pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. Useful when certain actions should run automatically when a commit is initiated. This may include linting, formatting, testing, etc. Getting Started with Python Pre-commit Hooks
🖋 .commitlint.config.js and .czrc Commitlint is a tool to check if your commit messages meet the conventional commit format. Useful when commit messages should follow a certain format. This may include following the Conventional Commits specification. Implement Good Commit Message Conventions in Your Development Workflow
📑 mkdocs MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Useful when documentation should be generated from Markdown files. This project uses the material theme Documenting a Python package with mkdocs-material
🧱 pnpm pnpm is another package manager for Node, an alternative to npm. Similar to npm, pnpm creates a pnpm-lock.yamlfile to keep track of the exact version of all packages in the dependency tree. Useful for quick project initialization and getting all tools setup with single commands. Also useful to setup custom scripts within package.json PNPM

Tools Deep-Dives & Setup

Listed below are more details as well as setup instructions (ordered) to get the template up and running.

Node

It is recommended to use nvm to setup node: Download the installer, Configure your shell environment with certain variables, Verify your installation.

It is recommended to install an LTS Version of Node, which would install node and npm (The node package manager)

nvm install --lts

Pnpm

Once node and npm are available through nvm:

npm i -g pnpm

Initialize a project with pnpm i or pnpm install. Once this command is run, a pnpm-lock.yaml file will be created. This file will be used to install all dependencies across all projects in the system. This includes husky, commitlint, etc.

pnpm stores all dependencies across all projects in hard links at a single location on a computer. This makes it more space efficient compared to npm, which uses flat node modules per project that can tank the size of the project. Once pnpm is installed once globally with -g flag, it will be available across any project in that system.

Anaconda

It is recommended to use Anaconda to setup Python. Download the installer, Configure your shell environment with certain variables, Verify your installation. Visit Managing Conda Environments for more information on how to create and manage environments.

Linting

Linting is a process of running a program that will analyse code for potential errors. This project uses ruff as the primary linter. It is recommended to install the Ruff VSCode Extension

Tests & Coverage

Tests are a way to ensure that the code is working as expected. This project uses pytest for testing. It is recommended to install the pytest extension for vscode. Coverage is a way to measure how much of the code is being tested. This project uses coverage for coverage.

Project Workflow

The following workflow is recommended to be followed when working on a project:

  • Use the dotlas python package cookiecutter to create the project template
  • Follow the setup instructions within the project template's README (such as pnpm and conda setup)
  • Make any changes to the codebase
  • Linting warnings will show up directly on vscode if the recommended extensions are installed (they will also reference the linting configuration within pyproject.toml)
  • Format your code with pnpm format
    • This will use the black formatter to make your python code more readable, and use isort to sort the import statements across your files
    • black formatter can also be configured to run on save instead
  • You can optionally run tests you have created using pnpm test
  • Stage the files (git add)
  • Run pnpm commit to launch a prompt for commit messages, and rerun commits using pnpm commit --retry