Kunumi Python Styler (K-Style)

A Visual Studio Code extension designed to scaffold and enforce consistent style, linting, and documentation standards across Python projects at Kunumi.
It provides automated configuration for tools such as Ruff, Vale, and Black, and can generate ready-to-use project structures for FastAPI or minimal Python setups.

1. Overview

K-Style standardizes Python projects by automating:

Style and lint configuration (.ruff.toml, .vale.ini, .gitignore).
Optional GitHub Actions for CI linting.
Pre-configured FastAPI scaffolding.
English or Portuguese documentation enforcement.
Line-length and Python version consistency across teams.

This ensures that every new repository starts aligned with Kunumi’s code quality standards.

2. Installation

2.1 From the Visual Studio Code Marketplace

Open Visual Studio Code.
Go to the Extensions view (Ctrl+Shift+X).
Search for "Kunumi Python Styler".
Click Install.

Or install it directly via terminal:

code --install-extension K-Arthur.kunumi-python-styler

3. Usage

3.1 Scaffolding a new project

Open an empty or existing Python project folder in VS Code.
Open the Command Palette (Ctrl+Shift+P).
Search for and run:
```
Python Styler: Scaffold style config
```
The extension will guide you through the setup process.

You will be asked to configure:

Project type (FastAPI or Minimal)
Documentation language (en or pt-BR)
Python version (detected automatically)
Line length (88, 100, or 120)
Whether to include CI linting (Yes or No)

Once confirmed, the extension will create:

.ruff.toml
.vale.ini
.gitignore
Optionally .github/workflows/lint.yml
FastAPI base structure (if selected)

4. FastAPI Template

If FastAPI is selected during scaffolding, the extension creates:

app/
├── api/
├── core/
├── models/
├── services/
├── tests/
└── main.py
pyproject.toml
README.md

The generated project includes a basic main.py:

from fastapi import FastAPI

app = FastAPI(title="My API")

@app.get("/")
def read_root():
    return {"message": "Hello from FastAPI template!"}

To run locally:

uvicorn app.main:app --reload

5. Style and Linting

5.1 Ruff

Used for linting, import sorting, and style enforcement.

Run checks manually:

ruff check .
ruff format .

5.2 Vale

Ensures that all comments and documentation are written in the configured language.

Run Vale:

vale .

6. Optional GitHub Actions (CI)

If enabled during scaffolding, the extension creates a .github/workflows/lint.yml file.
This workflow automatically runs Ruff and Vale checks on every pull request and push to main or master.

Example workflow content:

name: Lint & Style Checks

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.13'
      - run: pip install ruff vale fastapi uvicorn
      - run: ruff check .
      - run: ruff format --check .
      - run: vale .

7. Commands Available

Command	Description
`Python Styler: Scaffold style config`	Initializes project structure and configuration files.
`Python Styler: Run lint & docs check`	Executes Ruff and Vale over the current workspace.
`Python Styler: Fix formatting`	Automatically formats all Python files.
`Python Styler: Check documentation language`	Detects non-English or non-Portuguese docstrings/comments.

8. Recommended Dependencies

To use all features, install the following tools globally or in your virtual environment:

pip install ruff vale fastapi uvicorn

Optional (for development):

pip install pre-commit black isort

9. Project Configuration Files

File	Purpose
`.ruff.toml`	Configures line length, target Python version, linting rules, and ignores.
`.vale.ini`	Defines documentation style and vocabulary language.
`.gitignore`	Excludes virtual environments, caches, and common Python artifacts.
`.github/workflows/lint.yml`	CI pipeline for automated lint and style checks.

10. Troubleshooting

“Command not found” → Ensure the extension is installed and enabled.
Ruff or Vale not found → Verify that both tools are installed in your Python environment.
No workspace detected → Open a folder or project in VS Code before running the scaffold command.

11. Contributing

Clone this repository.
Install dependencies:
```
npm install
```
Build the extension:
```
npm run compile
```
Package it for testing:
```
vsce package
```

Install locally:

code --install-extension kunumi-python-styler-<version>.vsix

Before submitting changes, ensure:

TypeScript passes compilation (tsc -p ./).
No unnecessary files are included in .vscodeignore.
All new features are documented.