Pyproject Extension

Tombi provides enhanced features for Python projects through pyproject.toml, with special support for uv workspace and source metadata.

Experimentally, we provide additional features when editing pyproject.toml files.

Supported Features

Completion

The extension provides path-aware completion in places where pyproject.toml usually references local files or member projects.

[tool.uv.workspace]
members = ["packages/api"] # <- directory suggestions

[tool.uv.sources]
my-lib = { path = "packages/my-lib" } # <- file/directory suggestions

[project]
readme = "README.md" # <- file suggestions
license = { file = "LICENSE" } # <- file suggestions
license-files = ["licenses/*.txt"] # <- file suggestions

[build-system]
backend-path = ["backend"] # <- directory/file suggestions

Supported path completion targets include:

• [tool.uv.workspace].members
• [tool.uv.workspace].exclude
• [tool.uv.sources].*.path
• build-system.backend-path
• project.readme
• project.license.file
• project.license-files

Hover

For dependency entries, Tombi enriches hover content with package metadata.

[project]
dependencies = [
  "requests>=2.0", # <- package name and summary from PyPI
]

[tool.uv.sources]
my-lib = { workspace = true } # <- package name and description from the local member

Behavior:

• workspace and local path dependencies show metadata from the referenced member pyproject.toml
• registry dependencies can show package metadata fetched from PyPI
• in offline mode, remote PyPI lookups are skipped and only local workspace/path metadata is used

Inlay Hints

The extension can show inline hints for workspace-managed dependency versions in pyproject.toml.

These hints make it easier to confirm which shared dependency version is being applied from the workspace without manually tracing the workspace configuration.

Go to Definition

For example, suppose you have a pyproject.toml like the one below:

Go to package definition from dependencies

[project]
name = "albatross"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["bird-feeder", "tqdm>=4,<5"]

[tool.uv.sources]
bird-feeder = { workspace = true }

In this case, when your cursor is on workspace, executing "Go to Definition" will navigate you to the corresponding workspace-member entry in the workspace's pyproject.toml.

When your cursor is on the source key itself, such as bird-feeder, "Go to Definition" navigates to the member package's pyproject.toml and lands on its project.name value.

Go to Declaration

[project]
name = "albatross"
version = "0.1.0"
dependencies = ["bird-feeder", "tqdm>=4,<5"]

[tool.uv.sources]
bird-feeder = { workspace = true }

In this case, when your cursor is on workspace, executing "Go to Declaration" will navigate you to the workspace definition in the workspace's pyproject.toml file.

Go to Declaration also works when the cursor is placed on the dependency string itself (for example "bird-feeder"). If the package comes from tool.uv.sources with workspace = true, the command jumps to the member entry in the workspace pyproject.toml, letting you inspect which pattern pulled the project into the workspace.

Navigation List

The table below describes the intended accessor-by-accessor split between Go to Definition, Go to Declaration, and Find References.

For dependency strings, Go to Definition follows a compact rule:

• stay on the current string when this file itself is the source of truth for the PyPI dependency
• jump to the workspace dependency entry when the version is inherited from the workspace
• jump to the target package's project.name when the dependency resolves to a workspace member or local source

When Go to Definition returns the current location for a definition-site accessor, Tombi is intentionally signaling that there is no more specific definition target. In editors such as VS Code, this allows editor.gotoLocation.alternativeDefinitionCommand to take over and open the configured fallback, typically References.

Code Actions

When editing member pyproject.toml files, additional refactor actions help you converge on workspace-managed dependencies.

Use Workspace Dependency

If the workspace already pins the dependency, select "Use Workspace Dependency" to strip the version requirement (and keep extras) so the member follows the workspace definition.

Before

After

The action also works inside [project.optional-dependencies.*] groups.

Add to Workspace and Use Workspace Dependency

When the workspace has not registered the dependency yet, this action adds the current versioned requirement to the workspace's [project.dependencies] array and rewrites the member entry to use the shared dependency.

Before

After

Update Dependency to Latest Version

Refresh the selected dependency requirement to the latest published version. Use this when a dependency string is already present and you want Tombi to rewrite the pinned requirement without changing the surrounding dependency group structure.

Document Links

The extension annotates key project metadata with document links so you can jump to the right file or website in one click:

• entries in [tool.uv.workspace.members] and matches found via globs open the associated member project's pyproject.toml
• sources declared under [tool.uv.sources] with workspace = true expose links to both the member pyproject.toml and the workspace root pyproject.toml
• dependency arrays in [project.dependencies], [project.optional-dependencies.*], and [dependency-groups.*] link to local workspace packages when available, or fall back to the package page on PyPI