Local tool namespace in pyproject.toml?

Packaging Standards
1

PEP 518 defines the tool table and recommends as a namespace under tool:

We need some mechanism to allocate names within the tool.* namespace, to make sure that different projects don’t attempt to use the same sub-table and collide. Our rule is that a project can use the subtable tool.$NAME if, and only if, they own the entry for $NAME in the Cheeseshop/PyPI.

This is all well and good for public tools released on PyPI, but what if a repo has some local tools they want to drive from the pyproject.toml file? We want to avoid name collisions by things that could existing or maybe already do so names like tool.local.* are out of the question.

To me, the obvious next best thing is to prefix a local tool with an underscore, so for example in a project I’m working on, I’d include a section like:

[tool._workspace]
make_a_local_choice = true

What do other folks do? Can we or should we codify leading underscores in tool names as reserved for local tools?

4 Likes
2

The underscore convention seems reasonable to me.

1 Like
3

Without giving it much thought… wouldn’t the project’s own name work?

[project]
name = "foo-bar"

[tool.foo-bar]
make_a_local_choice = true
4

Yes, but (and I should have mentioned this) it’s a local tool I use in several repos/projects so tying it to one such name isn’t appropriate.

1 Like
5

Oh… Then maybe whatever name that is not a valid (canonical) name for distribution package should be safe, right?

6

That’s a good point - according to the standard, project names must start and end with a letter or number. So a key in the tool namespace that starts or ends with an underscore can never be claimed, and is therefore safe to use (or at least, “safe” in the sense that no published tool will claim it, you’ll still have to manage ownership between your own local tools yourself).

3 Likes
7

This is all well and good for public tools released on PyPI, but what if a repo has some local tools they want to drive from the pyproject.toml file? We want to avoid name collisions by things that could existing or maybe already do so names like tool.local.* are out of the question.

If you’re using a local tool and it has a meaningful name, that name may
already conflict with PyPI. If you’re using the local tool in multiple
repos, how do you install it? Via an internal index? Via pip install
git+https://git.server/toolrepo or similar? If it is a standalone
single-file script, does it even have a name? :smiley:

Once at a certain point, you’ve already accepted the risk of having a
naming conflict with someone else’s program (to the point where
“solving” this would involve everyone registering dummy projects on PyPI
for every standalone script in their dotfiles, and then nobody is going
to be happy), and the simple solution to that is to simply commit to not
needing that PyPI tool, or else eventually renaming your own tool if it
proves to be an inconvenience.

Name conflicts don’t matter unless you anticipate the need to use both
projects. Assuming that any project may eventually, one day, come to
need any two tools is a safe default, most particularly because the
author of one tool is not able to predict what external users of the
tool do; hence if two popular tools on PyPI both use the same tool.xxx
namespace, it is the users of the tools who suffer the consequences,
and who cannot fix it by fixing the tools to read different config
sections, as the users are not the maintainers of said tools.

That concern doesn’t apply here, so, conflict away? If you have issues
down the line, make tweaks to your own tool and be happy. The underscore
trick is convenient if it works, but I wouldn’t overthink it