twine
twine copied to clipboard
Expand reference and user documentation
-
[ ]
.pypirc
- link to the comprehensive documentation at https://docs.python.org/3/distutils/packageindex.html#pypirc and say, for instance, your.pypirc
file needs a[pypi]
section, and per #118, the documentation should discuss how you can choose to use.pypirc
to store the URL of a repo even if you don't want to store credentials. -
[x] #277 is where we are specifically figuring out what documentation to add about
keyring
usage, which figures into pypa/python-packaging-user-guide#297 for the Python Packaging User Guide. I want to both make sure that we have, or link to, comprehensive.pypirc
guidance, AND encourage folks to usekeyring
instead. -
[ ] improve
twine -h
/twine --help
invocation (right now you have to invoke astwine upload -h
and thetwine -h upload
error message is misleading) -
[x] improve command help/usage annotations for
twine upload
to explain that you should uploaddist/*
-
[x] address pypa/python-packaging-user-guide#145 and this Twitter conversation by adding a "use Test PyPI" line to the Usage section of the
README
-
[ ] add "when to use this versus when to use flit/zest.releaser" to
README
-
[ ] OS-specific troubleshooting tips, e.g., https://github.com/pypa/twine/issues/274#issuecomment-337340465 troubleshooting tip for Mac users running with SIP enabled
-
[x] a maintainer checklist for making new releases (see #306)
-
[ ] improve command help/usage annotations/
README
fortwine upload
to add instructions for adding a detached GPG signature & uploading it
In particular, when it said...
% twine upload dist/*
KeyError: Missing 'pypi' section from the configuration file
...at first run, I had no idea what config file it expected. My first guess was a .twinerc, but now I'm leaning toward .pypirc. Apparently, twine needs a [pypi]
section in it, which mine lacks despite lots of previous packaging work. Thus, let's be sure to document what it expects in the file.
Also:
$ twine --help
usage: twine [-h] [--version] command
positional arguments:
command
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
This not helpful. :smile:
https://twine.readthedocs.org is also empty :(
I only learnt from finding #160 that twine register
exists... it's not mentioned on the homepage which passes for docs.
I'm very glad it does, as it provides exactly what I needed
Also confusing is this:
$ ⮀twine upload --help
usage: twine upload [-h] [-r REPOSITORY] [-s] [--sign-with SIGN_WITH]
[-i IDENTITY] [-u USERNAME] [-p PASSWORD] [-c COMMENT]
[--config-file CONFIG_FILE] [--skip-existing]
dist [dist ...]
positional arguments:
dist The distribution files to upload to the repository,
may additionally contain a .asc file to include an
existing signature with the file upload
vs
$ ⮀twine register --help
usage: twine register [-h] [-r REPOSITORY] [-u USERNAME] [-p PASSWORD]
[-c COMMENT] [--config-file CONFIG_FILE]
package
positional arguments:
package File from which we read the package metadata
So upload
needs the dist/*
files path as the dist
arg. I wasn't sure what I was supposed to pass to the register
command as a package
though.
I tried passing the setup.py
but that was an error. In the end I tried passing the dist/*
path and that worked (despite that it was a wildcard and not a 'file' name)... I guess maybe the mypackage.egg-info
path would be accepted too?
Again some basic docs would help.
hmm, the egg-info doesn't seem usable:
$ ⮀twine register --config-file=./.pypirc mypackage.egg-info
Registering package to https://pypi.python.org/pypi
ValueError: Unknown distribution format: 'mypackage.egg-info'
and
$ ⮀twine register --config-file=./.pypirc mypackage.egg-info/PKG-INFO
Registering package to https://pypi.python.org/pypi
ValueError: Unknown distribution format: 'PKG-INFO'
...if it only accepts the same dist/*
path as the upload
command maybe the command help description should be the same
I notice that this issue is not part of any milestone. Is there no plan to improve/create documentation?
If there were no plan to do so this issue wouldn't be open. There is no milestone because we aren't going to stall a release on a vague issue
Sent from my Android device with K-9 Mail. Please excuse my brevity.
will there still be a ~/.pypirc for future versions, especially for pip publish
?
For anyone arriving here and looking for changelog, it's in the docs folder, see https://github.com/pypa/twine/blob/master/docs/changelog.rst
Also, there is little documentation at https://packaging.python.org/distributing/?highlight=twine#upload-your-distributions but AFAIK no reference documentation, that this ticket is about.
I'd love reviews of #292 which is the beginning of scratching the surface on this issue.
A little bit of reference documentation is in #295 and #296 in case people would like to review that.
I'm a newish Twine maintainer. Thanks for the suggestions for improvement!
A status update:
In July 2017, uploading to pypi.python.org stopped, and now package maintainers can only upload to the new PyPI, pypi.org. Warehouse, the codebase behind the new PyPI, is available as a pre-production site at https://pypi.org, and I'm one of the people working on it. We're making steady progress on the developer roadmap thanks to funding from Mozilla's Open Source Support Program, and it's on its way to fully replacing the legacy PyPI site, I believe, this year. We're currently seeking feedback from package maintainers, including via several IRC livechats/office hours this week, about what does or doesn't work for you in the new interface, and in the next few weeks we'll be doing so with the wider Python developer community.
I'm working on releasing Twine 1.10.0 in the next few days.
We've improved Twine user (and developer) documentation a lot in the past couple months -- see http://twine.readthedocs.io/ which now works, including the changelog. And the Python Packaging User Guide has a lot more material than it used to about .pypirc
files and about packaging and uploading with Twine more generally -- see https://packaging.python.org/tutorials/distributing-packages/?highlight=pypirc , https://packaging.python.org/guides/migrating-to-pypi-org/?highlight=pypirc , and https://packaging.python.org/guides/using-testpypi/?highlight=pypirc .
Clearly we need more reference documentation and user help docs, on Twine behavior, .pypirc
(although perhaps a comprehensive .pypirc
guide should live at https://packaging.python.org ), and Twine internals. I'd welcome issues and pull requests.
I'm editing the original post at the top of this thread with a TODO list.
I'm working on some relevant improvements in #320. I'm working towards getting 1.10.1 out in the next few days and would strongly welcome doc improvements to get into that release!
Re: .pypirc
and keyring, I added some research and possible next steps to https://github.com/pypa/packaging.python.org/issues/297#issuecomment-576409783. See also https://github.com/pypa/twine/issues/118, https://github.com/pypa/twine/pull/340, https://github.com/pypa/twine/issues/216, and https://github.com/pypa/twine/issues/324.
I'm tempted to break this issue up into discrete, actionable issues.
I'd be happy to see the individual tasks broken out into discrete issues with some kind of docs tag/label.
Indeed, this issue is something of a laundry list with an unbounded scope, which is part of why it's been around forever. Closing in favor of creating discrete requests (as needed).
Jason, do you mind if we reopen till someone has time to break these out into individual issues? Maybe @bhrutledge?