Skip to content

Give a strategy for broken references in `usethis-python-module-layou… #1372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nathanjmcdougall merged 1 commit into from
Mar 11, 2026
Merged

Give a strategy for broken references in `usethis-python-module-layou… #1372

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion .agents/skills/usethis-python-module-layout-modify/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,29 @@ description: Modify the Python module layout (create, move, rename, or delete mo
compatibility: usethis, Python
license: MIT
metadata:
version: "1.0"
version: "1.1"
---

# Modifying the module layout for Python projects

## Strategy for broken references

Whenever:

- creating a new module and moving code into it from another module
- moving an existing module to a different location
- renaming an existing module

There is the possibility of breaking references (e.g. import statements). Make sure to check for these and fix any.

### Preserving backwards compatibility

usethis adheres to a convention where modules starting with an underscore (e.g. `usethis._internal`) are considered internal (including all their submodules) and are not part of the public API. As such, it is not necessary to maintain backwards compatibility for these modules.

For example, if we had `src/usethis/_a.py` and were splitting it into new submodules `usethis/_a/b.py` and `usethis/_a/c.py`, we would not need to maintain backwards compatibility for `usethis._a` (e.g. by keeping an `__init__.py` file with imports of the new submodules).

However, in other cases, backwards compatibility should be maintained.

## Updating Import Linter Contracts

Make sure to adhere to the Import Linter checks using the `usethis-qa-import-linter` skill.