aio-libs / aio-libs/aiobotocore

Move to a src/ layout

Aberta
#1,685 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
1.4k
Forks
209
Merge médio
4d 15h
PRs com merge (30d)
16

Descrição

## Summary

Move the package from a flat layout (`aiobotocore/` at the repo root) to a `src/` layout
(`src/aiobotocore/`).

This is deliberately **not** bundled with the "test the dists" work, because renaming the
package directory touches every path in the repo and would conflict with anything in flight.
Filing it so the reasoning isn't lost.

## Why

With a flat layout, `aiobotocore/` and `tests/` live in the same directory, so a single
`sys.path` entry controls both. That single entry is over-subscribed:

* Tests must be able to import `tests.mock_server` — `conftest.py` forces the multiprocessing
`spawn` start method, and the child process unpickles `AIOServer` by its qualified name
`tests.mock_server.AIOServer`, inheriting the parent's `sys.path`.
* The suite must **not** be able to import `aiobotocore` from the checkout, or CI silently
tests the source tree instead of the wheel it just installed.

Both are served by the same directory, so the two requirements are in direct conflict.
Measured, running the suite out of an unpacked sdist with the wheel installed:

| rootdir on `sys.path`? | installed wheel wins | moto-server tests |
|-|-|-|
| no (`--import-mode=importlib`, no `pythonpath`) | pass | fail — `ModuleNotFoundError: No module named 'tests'` |
| yes | fail — checkout shadows the wheel | pass |

The current workaround is in `tests/conftest.py`: **append** (never insert) the rootdir to
`sys.path`, so `spawn` children can import `tests` while `site-packages` still precedes the
source tree. It works, but it is an ordering convention. Any future `sys.path.insert(0, ...)`,
or a plugin that prepends the rootdir, silently flips CI back to testing the checkout — and
the failure is invisible, because everything still passes.

A `src/` layout removes the conflict instead of balancing it: the rootdir would hold `tests/`
but no importable `aiobotocore`, so putting it on `sys.path` is simply safe. This is PyPA's
stated rationale for the layout:

> if an import package exists in the current working directory with the same name as an
> installed import package, the variant from the current working directory will be used

— https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/

urllib3, cryptography, pip, attrs, black, flask, poetry and trio all use `src/` for this reason.

## What it takes

Mechanical, one commit:

- [ ] `git mv aiobotocore src/aiobotocore`
- [ ] `[tool.hatch.version] path` → `src/aiobotocore/__init__.py`
- [ ] `[tool.hatch.build.targets.wheel] packages` → `["src/aiobotocore"]`
- [ ] `[tool.hatch.build.targets.sdist] include` → `/src` instead of `/aiobotocore`
- [ ] `[tool.coverage.paths]` → `src/aiobotocore/` as the canonical prefix
- [ ] drop `--import-mode=importlib` from `addopts` and the `sys.path.append` block in
`tests/conftest.py` (both exist only to work around the flat layout)
- [ ] `.git-blame-ignore-revs` entry so `git blame` stays useful
- [ ] sweep `docs/`, `plugins/aiobotocore-bot/skills/`, `.github/*-prompt.md` for
`aiobotocore/` path references

No behavior change, no user-visible change — the wheel contents are identical either way.

## When

After the current batch of PRs lands, to avoid mass conflicts.

Guia de contribuição

Abrir o guia de contribuição

Direção de pesquisa

Start with pyproject.toml, tests/conftest.py, and the repository paths listed in the checklist; inspect the Hatch, coverage, pytest, and documentation path settings before moving aiobotocore/ to src/aiobotocore/. Sweep the named docs, plugin, and prompt paths, then verify the installed wheel and test imports retain the expected behavior.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
build-system, testing
Tipo de issue
Refatoração
Dificuldade
4/5
Tempo estimado
3-5 dias
Status de atividade
Pouca atividade
Clareza
Claramente especificada
Facilidade para iniciantes
58/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.