[Python] Creating git subtree repo that can import Python files as from "fake" namespace

tl;dr: What are the minimal changes needed to make a standalone folder work in Python runtime, and get modules resolved in VS Code, as though it's part of a parent module namespace?

I have a git repo I develop on with a structure like:

~/proj/
├── xxx/
├── src/
│ └── proj/
│ ├── yyy/
│ ├── foo/
│ │ ├── docs/
│ │ └── bar/
│ └── zzz/
└── tests/


I have an intern who is not allowed to clone proj repo, because it has sensitive files. I want the intern to work on and run code in the foo directory.

So, I broke foo out into a git subtree hosted in its own repo. That repo is cloned into a directory ~/foo-repo.

~/foo-repo/
├── docs/
└── bar/


I added a custom pyproject.toml file to the root of this repo so that the intern can uv sync and get a .venv with all the necessary packages.

At this point I cannot run python bar/jim.py (in the venv) because that file imports other files that have import proj.foo.bar, and this repo knows nothing about proj.

So, I added this to the pyproject.toml in the foo repo:

[build-system]
requires = ["setuptools>=69", "wheel"]
build-backend = "setuptools.build_meta"

# Map the repo root to the import package `proj.foo`
[tool.setuptools]
include-package-data = true

[tool.setuptools.package-dir]
"proj.foo" = "."

[tool.setuptools.packages.find]
namespaces = true
include = ["proj.foo*"]
where = ["."]


After that (and fresh uv sync) I'm able to run the files…but pyright in VS Code is not able to resolve import proj.foo or sub modules.

• I don't want to move files within the foo project to have src/proj/foo directories, because that's not the right hierarchy within the proj repo.
• I don't want to have to create dummy stub files in this repo.
• I want the files in this repo to be built/installed editable, so that changes to the files during development take effect without needing to rebuild or reinstall.

What are the minimal changes I can make to this repo so that the Python runtime and VS Code fully understand that files immediately under ~/foo-repo/ represent proj.foo namespace?

Using Python 3.11 and uv.

Continue reading...