Document how third parties use our undocumented/unsupported APIs

[di]

In #659 it was pointed out that some third parties use twine's undocumented/unsupported APIs and that certain changes and refactoring should not be made as it might break their usage.

@sigmavirus24 said:

I've worked hard to keep things stable until someone had the time to build the real API.

In the interest of maintaining that stability, I think we should attempt to document how various third-parties are currently using this unsupported API, so we can continue to support them until there is a supported API available, and so that contributors are aware what can and cannot be changed.

List of externally used methods

twine.cli.dispatch

• zest.releaser
  • from twine.cli import dispatch as twine_dispatch
• oscrypto
  • import twine.cli
• bork
  • from twine.cli import dispatch as twine_dispatch

twine.utils.DEFAULT_REPOSITORY, twine.utils.TEST_REPOSITORY

• hatch
  • from twine.utils import DEFAULT_REPOSITORY, TEST_REPOSITORY

[sigmavirus24]

buildout uses twine iirc

[sigmavirus24]

I think https://github.com/wbond/oscrypto/blob/master/dev/release.py insists on never using a CLI and always importing unsupported interfaces in all of their projects (this being one example)

[di]

Looks like oscrypto is using twine.cli.dispatch as well, I've added it above.

I couldn't find any reference to twine in buildout: https://github.com/buildout/buildout/search?q=twine

[sigmavirus24]

oscrypto was just the project I recalled. I think all of wbond's projects use the same infrastructure/project skeleton

[bhrutledge]

I added hatch to the list.

[sigmavirus24]

I'm not seeing it in the issue @bhrutledge

[bhrutledge]

@sigmavirus24 It's in the description of this issue, under "Other uses"

[di]

Besides DEFAULT_REPOSITORY/TEST_REPOSITORY, it looks like hatch is just using one of the entry points we've explicitly defined:

twine/setup.cfg

Lines 50 to 54 in 895ac8a

	[options.entry_points]
	twine.registered_commands =
	check = twine.commands.check:main
	upload = twine.commands.upload:main
	register = twine.commands.register:main

Do we consider that to be an unsupported use of an internal API?

[sigmavirus24]

Those entry points are for us to use so I'd hope they're not using them directly. Also https://github.com/ofek/hatch/blob/666fc1a1b383cf9c882720bbb90a5cdf4d7b8110/hatch/commands/release.py#L114-L115 is shelling out from within python so I don't consider that a problem. python -m twine is a valid way of invoking the tool

[di]

I'm confused. Invoking twine like python -m twine upload invokes the entrypoint main in twine.commands.upload. Hatch is using that entrypoint, if it wasn't defined in twine/setup.cfg calling python -m twine upload would fail.

Edit: I see what you're saying now.

[duckinator]

bork uses from twine.cli import dispatch as twine_dispatch, same as zest.releaser.

[di]

Thanks! Added.