1TWINE(1) twine TWINE(1)
2
6 twine - twine Documentation
7 This project follows the semantic versioning and pre-release versioning
9 schemes recommended by the Python Packaging Authority.
10
12 Features
13 • Add support for Python 3.10. (#827)
14
16 Features
17 • Show more helpful messages for invalid passwords. (#815)
18 • Allow the --skip-existing option to work with GCP Artifact Registry.
20 (#823)
21 Bugfixes
23 • Add a helpful error message when an upload fails due to missing a
24 trailing slash in the URL. (#812)
25 • Generalize --verbose suggestion when an upload fails. (#817)
27
29 Bugfixes
30 • Improve error message for unsupported metadata. (#755)
31 • Improve error message for a missing config file. (#770)
33 • Do not include md5_digest or blake2_256_digest if FIPS mode is en‐
35 abled on the host. This removes those fields from the metadata before
36 sending the metadata to the repository. (#776)
37
39 Bugfixes
40 • Fix a regression that was causing some namespace packages with dots
41 in them fail to upload to PyPI. (#745)
42
44 Features
45 • Prefer importlib.metadata for entry point handling. (#728)
46 • Rely on importlib_metadata 3.6 for nicer entry point processing. (‐
48 #732)
49 • Eliminate dependency on setuptools/pkg_resources and replace with
51 packaging and importlib_metadata. (#736)
52
54 Features
55 • Print files to be uploaded using upload --verbose (#670)
56 • Print configuration file location when using upload --verbose (#675)
58 • Print source and values of credentials when using upload --verbose (‐
60 #685)
61 • Add support for Python 3.9 (#708)
63 • Turn warnings into errors when using check --strict (#715)
65 Bugfixes
67 • Make password optional when using upload --client-cert (#678)
68 • Support more Nexus versions with upload --skip-existing (#693)
70 • Support Gitlab Enterprise with upload --skip-existing (#698)
72 • Show a better error message for malformed files (#714)
74 Improved Documentation
76 • Adopt PSF code of conduct (#680)
77 • Adopt towncrier for the changleog (#718)
79
81 Features
82 • Improve display of HTTP errors during upload (#666)
83 • Print packages and signatures to be uploaded when using --verbose op‐
85 tion (#652)
86 • Use red text when printing errors on the command line (#649)
88 • Require repository URL scheme to be http or https (#602)
90 • Add type annotations, checked with mypy, with PEP 561 support for
92 users of Twine's API (#231)
93 Bugfixes
95 • Update URL to .pypirc specification (#655)
96 • Don't raise an exception when Python version can't be parsed from
98 filename (#612)
99 • Fix inaccurate retry message during upload (#611)
101 • Clarify error messages for archive format (#601)
103
105 Bugfixes
106 • Restore --non-interactive as a flag not expecting an argument. (#548)
107
109 Features
110 • Add support for specifying --non-interactive as an environment vari‐
111 able. (#547)
112
114 Features
115 • When a client certificate is indicated, all password processing is
116 disabled. (#336)
117 • Add --non-interactive flag to abort upload rather than interactively
119 prompt if credentials are missing. (#489)
120 • Twine now unconditionally requires the keyring library and no longer
122 supports uninstalling keyring as a means to disable that functional‐
123 ity. Instead, use keyring --disable keyring functionality if neces‐
124 sary. (#524)
125 • Add Python 3.8 to classifiers. (#518)
127 Bugfixes
129 • More robust handling of server response in --skip-existing (#332)
130
132 Features
133 • Twine now requires Python 3.6 or later. Use pip 9 or pin to "twine<2"
134 to install twine on older Python versions. (#437)
135 Bugfixes
137 • Require requests 2.20 or later to avoid reported security vulnerabil‐
138 ities in earlier releases. (#491)
139
141 Features
142 • Improved output on check command: Prints a message when there are no
143 distributions given to check. Improved handling of errors in a dis‐
144 tribution's markup, avoiding messages flowing through to the next
145 distribution's errors. (#488)
146
148 Features
149 • Show Warehouse URL after uploading a package (#459)
150 • Better error handling and gpg2 fallback if gpg not available. (#456)
152 • Now provide a more meaningful error on redirect during upload. (#310)
154 Bugfixes
156 • Fail more gracefully when encountering bad metadata (#341)
157
159 Features
160 • Add disable_progress_bar option to disable tqdm. (#427)
161 • Allow defining an empty username and password in .pypirc. (#426)
163 • Support keyring.get_credential. (#419)
165 • Support keyring.get_username_and_password. (#418)
167 • Add Python 3.7 to classifiers. (#416)
169 Bugfixes
171 • Restore prompts while retaining support for suppressing prompts. (‐
172 #452)
173 • Avoid requests-toolbelt to 0.9.0 to prevent attempting to use openssl
175 when it isn't available. (#447)
176 • Use io.StringIO instead of StringIO. (#444)
178 • Only install pyblake2 if needed. (#441)
180 • Use modern Python language features. (#436)
182 • Specify python_requires in setup.py (#435)
184 • Use https URLs everywhere. (#432)
186 • Fix --skip-existing for Nexus Repos. (#428)
188 • Remove unnecessary usage of readme_render.markdown. (#421)
190 • Don't crash if there's no package description. (#412)
192 • Fix keyring support. (#408)
194 Misc
196 • Refactor tox env and travis config. (#439)
197
199 Bugfixes
200 • Fix regression with upload exit code (#404)
201
203 Features
204 • Add twine check command to check long description (#395)
205 • Drop support for Python 3.3 (#392)
207 • Empower --skip-existing for Artifactory repositories (#363)
209 Bugfixes
211 • Avoid MD5 when Python is compiled in FIPS mode (#367)
212
214 Features
215 • Remove PyPI as default register package index. (#320)
216 • Support Metadata 2.1 (PEP 566), including Markdown for description
218 fields. (#319)
219 Bugfixes
221 • Raise exception if attempting upload to deprecated legacy PyPI URLs.
222 (#322)
223 • Avoid uploading to PyPI when given alternate repository URL, and re‐
225 quire http:// or https:// in repository_url. (#269)
226 Misc
228 • Update PyPI URLs. (#318)
229 • Add new maintainer, release checklists. (#314)
231 • Add instructions on how to use keyring. (#277)
233
235 Features
236 • Link to changelog from README (#46)
237 • Reorganize & improve user & developer documentation. (#304)
239 • Revise docs predicting future of twine (#303)
241 • Add architecture overview to docs (#296)
243 • Add doc building instructions (#295)
245 • Declare support for Python 3.6 (#257)
247 • Improve progressbar (#256)
249 Bugfixes
251 • Degrade gracefully when keyring is unavailable (#315)
252 • Fix changelog formatting (#299)
254 • Fix syntax highlighting in README (#298)
256 • Fix Read the Docs, tox, Travis configuration (#297)
258 • Fix Travis CI and test configuration (#286)
260 • Print progress to stdout, not stderr (#268)
262 • Fix --repository[-url] help text (#265)
264 • Remove obsolete registration guidance (#200)
266
268 Bugfixes
269 • Blacklist known bad versions of Requests. (#253)
270
272 Bugfixes
273 • Twine sends less information about the user's system in the
274 User-Agent string. (#229)
275 • Fix --skip-existing when used to upload a package for the first time.
277 (#220)
278 • Fix precedence of --repository-url over --repository. (#206)
280 Misc
282 • Twine will now resolve passwords using the keyring if available. Mod‐
283 ule can be required with the keyring extra.
284 • Twine will use hashlib.blake2b on Python 3.6+ instead of pyblake2
286
288 Misc
289 • Check if a package exists if the URL is one of:
290 • https://pypi.python.org/pypi/
292 • https://upload.pypi.org/
294 • https://upload.pypi.io/
296 This helps people with https://upload.pypi.io still in their
298 .pypirc file.
299
301 Features
302 • Switch from upload.pypi.io to upload.pypi.org. (#201)
303 • Retrieve configuration from the environment as a default. (#144)
305 • Repository URL will default to TWINE_REPOSITORY
307 • Username will default to TWINE_USERNAME
309 • Password will default to TWINE_PASSWORD
311 • Allow the Repository URL to be provided on the command-line (--repos‐
313 itory-url) or via an environment variable (TWINE_REPOSITORY_URL). (‐
314 #166)
315 • Generate Blake2b 256 digests for packages if pyblake2 is installed.
317 Users can use python -m pip install twine[with-blake2] to have py‐
318 blake2 installed with Twine. (#171)
319 Misc
321 • Generate SHA256 digest for all packages by default.
322 • Stop testing on Python 2.6.
324 • Warn users if they receive a 500 error when uploading to
326 *pypi.python.org (#199)
327
329 Bugfixes
330 • Correct a packaging error.
331
333 Bugfixes
334 • Fix uploads to instances of pypiserver using --skip-existing. We were
335 not properly checking the return status code on the response after
336 attempting an upload. (#195)
337 Misc
339 • Avoid attempts to upload a package if we can find it on Legacy PyPI.
340
342 Bugfixes
343 • Fix issue where we were checking the existence of packages even if
344 the user didn't specify --skip-existing. (#189) (#191)
345
347 Bugfixes
348 • Clint was not specified in the wheel metadata as a dependency. (#187)
349
351 Features
352 • Support --cert and --client-cert command-line flags and config file
353 options for feature parity with pip. This allows users to verify con‐
354 nections to servers other than PyPI (e.g., local package reposito‐
355 ries) with different certificates. (#142)
356 • Add progress bar to uploads. (#152)
358 • Allow --skip-existing to work for 409 status codes. (#162)
360 • Implement retries when the CDN in front of PyPI gives us a 5xx error.
362 (#167)
363 • Switch Twine to upload to pypi.io instead of pypi.python.org. (#177)
365 Bugfixes
367 • Allow passwords to have %s in them. (#186)
368
370 Bugfixes
371 • Bump requests-toolbelt version to ensure we avoid ConnectionErrors (‐
372 #155)
373
375 Bugfixes
376 • Paths with hyphens in them break the Wheel regular expression. (#145)
377 • Exception while accessing the repository key (sic) when raising a re‐
379 direct exception. (#146)
380
382 Bugfixes
383 • Fix uploading signatures causing a 500 error after large file support
384 was added. (#137, #140)
385
387 Bugfixes
388 • Upload signatures with packages appropriately (#132)
389 As part of the refactor for the 1.6.0 release, we were using the
390 wrong name to find the signature file.
391 This also uncovered a bug where if you're using twine in a situa‐
393 tion where * is not expanded by your shell, we might also miss up‐
394 loading signatures to PyPI. Both were fixed as part of this.
395
397 Bugfixes
398 • Fix signing support for uploads (#130)
399
401 Features
402 • Allow the user to specify the location of their .pypirc (#97)
403 • Support registering new packages with twine register (#8)
405 • Add the --skip-existing flag to twine upload to allow users to skip
407 releases that already exist on PyPI. (#115)
408 • Upload wheels first to PyPI (#106)
410 • Large file support via the requests-toolbelt (#104)
412 Bugfixes
414 • Raise an exception on redirects (#92)
415 • Work around problems with Windows when using getpass.getpass (#116)
417 • Warnings triggered by pkginfo searching for PKG-INFO files should no
419 longer be user visible. (#114)
420 • Provide more helpful messages if .pypirc is out of date. (#111)
422
424 Features
425 • Support commands not named "gpg" for signing (#29)
426 Bugfixes
428 • Display information about the version of setuptools installed (#85)
429 • Support deprecated pypirc file format (#61)
431 Misc
433 • Add lower-limit to requests dependency
434
436 Features
437 • Switch to a git style dispatching for the commands to enable simpler
438 commands and programmatic invocation. (#6)
439 • Parse ~/.pypirc ourselves and use subprocess instead of the distu‐
441 tils.spawn module. (#13)
442 Bugfixes
444 • Expand globs and check for existence of dists to upload (#65)
445 • Fix issue uploading packages with _s in the name (#47)
447 • List registered commands in help text (#34)
449 • Use pkg_resources to load registered commands (#32)
451 • Prevent ResourceWarning from being shown (#28)
453 • Add support for uploading Windows installers (#26)
455
457 Features
458 • Additional functionality.
459
461 Features
462 • Basic functionality.
463 We are happy you have decided to contribute to Twine.
465 Please see the GitHub repository for code and more documentation, and
467 the official Python Packaging User Guide for user documentation. To
468 ask questions or get involved, you can join the Python Packaging Dis‐
469 course forum, #pypa or #pypa-dev on IRC, or the distutils-sig mailing
470 list.
471 Everyone interacting in the Twine project's codebases, issue trackers,
473 chat rooms, and mailing lists is expected to follow the PSF Code of
474 Conduct.
475
477 We use tox to run tests, check code style, and build the documentation.
478 To install tox, run:
479 python3 -m pip install tox
481 Clone the twine repository from GitHub, then run:
483 cd /path/to/your/local/twine
485 tox -e dev
486 This creates a virtual environment, so that twine and its dependencies
488 do not interfere with other packages installed on your machine. In the
489 virtual environment, twine is pointing at your local copy, so when you
490 make changes, you can easily see their effect.
491 The virtual environment also contains the tools for running tests and
493 checking code style, so you can run them on single files directly or in
494 your code editor. However, we still encourage using the tox commands
495 below on the whole codebase.
496 To use the virtual environment, run:
498 source venv/bin/activate
500 Building the documentation
502 Additions and edits to twine's documentation are welcome and appreci‐
503 ated.
504 To preview the docs while you're making changes, run:
506 tox -e watch-docs
508 Then open a web browser to http://127.0.0.1:8000.
510 When you're done making changes, lint and build the docs locally before
512 making a pull request. In your active virtual environment, run:
513 tox -e docs
515 The HTML of the docs will be written to docs/_build/html.
517 Code style
519 To automatically reformat your changes with isort and black, run:
520 tox -e format
522 To detect any remaining code smells with flake8, run:
524 tox -e lint
526 To perform strict type-checking using mypy, run:
528 tox -e types
530 Any errors from lint or types need to be fixed manually.
532 Additionally, we prefer that import statements be used for packages and
534 modules only, rather than individual classes or functions.
535 Testing
537 We use pytest for writing and running tests.
538 To run the tests in your virtual environment, run:
540 tox -e py
542 To pass options to pytest, e.g. the name of a test, run:
544 tox -e py -- tests/test_upload.py::test_exception_for_http_status
546 Twine is continuously tested against supported versions of Python using
548 GitHub Actions. To run the tests against a specific version, e.g.
549 Python 3.8, you will need it installed on your machine. Then, run:
550 tox -e py38
552 To run the "integration" tests of uploading to real package indexes,
554 run:
555 tox -e integration
557 To run the tests against all supported Python versions, check code
559 style, and build the documentation, run:
560 tox
562
564 1. Fork the GitHub repository.
565 2. Make a branch off of main and commit your changes to it.
567 3. Run the tests, check code style, and build the docs as described
569 above.
570 4. Optionally, add your name to the end of the AUTHORS file using the
572 format Name <email@domain.com> (url), where the (url) portion is op‐
573 tional.
574 5. Submit a pull request to the main branch on GitHub, referencing an
576 open issue.
577 6. Add a changelog entry.
579 Changelog entries
581 The docs/changelog.rst file is built by towncrier from files in the
582 changelog/ directory. To add an entry, create a file in that directory
583 named {number}.{type}.rst, where {number} is the pull request number,
584 and {type} is feature, bugfix, doc, removal, or misc.
585 For example, if your PR number is 1234 and it's fixing a bug, then you
587 would create changelog/1234.bugfix.rst. PRs can span multiple cate‐
588 gories by creating multiple files: if you added a feature and depre‐
589 cated/removed an old feature in PR #5678, you would create
590 changelog/5678.feature.rst and changelog/5678.removal.rst.
591 A changelog entry is meant for end users and should only contain de‐
593 tails relevant to them. In order to maintain a consistent style, please
594 keep the entry to the point, in sentence case, shorter than 80 charac‐
595 ters, and in an imperative tone. An entry should complete the sentence
596 "This change will ...". If one line is not enough, use a summary line
597 in an imperative tone, followed by a description of the change in one
598 or more paragraphs, each wrapped at 80 characters and separated by
599 blank lines.
600 You don't need to reference the pull request or issue number in a
602 changelog entry, since towncrier will add a link using the number in
603 the file name, and the pull request should reference an issue number.
604 Similarly, you don't need to add your name to the entry, since that
605 will be associated with the pull request.
606 Changelog entries are rendered using reStructuredText, but they should
608 only have minimal formatting (such as ``monospaced text``).
609
611 Twine is a command-line tool for interacting with PyPI securely over
612 HTTPS. Its three purposes are to be:
613 1. A user-facing tool for publishing on pypi.org
615 2. A user-facing tool for publishing on other Python package indexes
617 (e.g., devpi instances)
618 3. A useful API for other programs (e.g., zest.releaser) to call for
620 publishing on any Python package index
621 Currently, twine has two principle functions: uploading new packages
623 and registering new projects (register is no longer supported on PyPI,
624 and is in Twine for use with other package indexes).
625 Its command line arguments are parsed in twine/cli.py. The code for
627 registering new projects is in twine/commands/register.py, and the code
628 for uploading is in twine/commands/upload.py. The file twine/package.py
629 contains a single class, PackageFile, which hashes the project files
630 and extracts their metadata. The file twine/repository.py contains the
631 Repository class, whose methods control the URL the package is uploaded
632 to (which the user can specify either as a default, in the .pypirc
633 file, or pass on the command line), and the methods that upload the
634 package securely to a URL.
635 For more details, refer to the source documentation (currently a work
637 in progress):
638 twine package
640 Top-level module for Twine.
641 The contents of this package are not a public API. For more details,
643 see https://github.com/pypa/twine/issues/194 and
644 https://github.com/pypa/twine/issues/665.
645 twine.commands package
647 Module containing the logic for the twine sub-commands.
648 The contents of this package are not a public API. For more details,
650 see https://github.com/pypa/twine/issues/194 and
651 https://github.com/pypa/twine/issues/665.
652 twine.commands.check module
654 Module containing the logic for twine check.
655 class twine.commands.check._WarningStream
657 __init__() -> None
659 write(text: str) -> None
661 twine.commands.check._check_file(filename: str, render_warning_stream:
663 twine.commands.check._WarningStream) -> Tuple[List[str], bool]
664 Check given distribution.
665 twine.commands.check.check(dists: List[str], output_stream: IO[str] =
667 sys.stdout, strict: bool = False) -> bool
668 Check that a distribution will render correctly on PyPI and dis‐
669 play the results.
670 This is currently only validates long_description, but more
672 checks could be added; see
673 https://github.com/pypa/twine/projects/2.
674 Parameters
676 • dists -- The distribution files to check.
678 • output_stream -- The destination of the resulting out‐
680 put.
681 • strict -- If True, treat warnings as errors.
683 Returns
685 True if there are rendering errors, otherwise False.
686 twine.commands.check.main(args: List[str]) -> bool
688 Execute the check command.
689 Parameters
691 args -- The command-line arguments.
692 Returns
694 The exit status of the check command.
695 twine.commands.register module
697 Module containing the logic for twine register.
698 twine.commands.register.register(register_settings: twine.settings.Set‐
700 tings, package: str) -> None
701 Pre-register a package name with a repository before uploading a
702 distribution.
703 Pre-registration is not supported on PyPI, so the register com‐
705 mand is only necessary if you are using a different repository
706 that requires it.
707 Parameters
709 • register_settings -- The configured options relating to
711 repository registration.
712 • package -- The path of the distribution to use for
714 package metadata.
715 Raises
717 • twine.exceptions.TwineException -- The registration
719 failed due to a configuration error.
720 • requests.HTTPError -- The repository responded with an
722 error.
723 twine.commands.register.main(args: List[str]) -> None
725 Execute the register command.
726 Parameters
728 args -- The command-line arguments.
729 twine.commands.upload module
731 Module containing the logic for twine upload.
732 twine.commands.upload.skip_upload(response: requests.models.Response,
734 skip_existing: bool, package: twine.package.PackageFile) -> bool
735 Determine if a failed upload is an error or can be safely ig‐
736 nored.
737 Parameters
739 • response -- The response from attempting to upload
741 package to a repository.
742 • skip_existing -- If True, use the status and content of
744 response to determine if the package already exists on
745 the repository. If so, then a failed upload is safe to
746 ignore.
747 • package -- The package that was being uploaded.
749 Returns
751 True if a failed upload can be safely ignored, otherwise
752 False.
753 twine.commands.upload._make_package(filename: str, signatures:
755 Dict[str, str], upload_settings: twine.settings.Settings) ->
756 twine.package.PackageFile
757 Create and sign a package, based off of filename, signatures and
758 settings.
759 twine.commands.upload.upload(upload_settings: twine.settings.Settings,
761 dists: List[str]) -> None
762 Upload one or more distributions to a repository, and display
763 the progress.
764 If a package already exists on the repository, most repositories
766 will return an error response. However, if upload_set‐
767 tings.skip_existing is True, a message will be displayed and any
768 remaining distributions will be uploaded.
769 For known repositories (like PyPI), the web URLs of successfully
771 uploaded packages will be displayed.
772 Parameters
774 • upload_settings -- The configured options related to
776 uploading to a repository.
777 • dists -- The distribution files to upload to the repos‐
779 itory. This can also include .asc files; the GPG signa‐
780 tures will be added to the corresponding uploads.
781 Raises
783 • twine.exceptions.TwineException -- The upload failed
785 due to a configuration error.
786 • requests.HTTPError -- The repository responded with an
788 error.
789 twine.commands.upload.main(args: List[str]) -> None
791 Execute the upload command.
792 Parameters
794 args -- The command-line arguments.
795 twine.auth module
797 class twine.auth.CredentialInput
798 __init__(username: Optional[str] = None, password: Optional[str]
800 = None) -> None
801 class twine.auth.Resolver
803 __init__(config: Dict[str, Optional[str]], input:
805 twine.auth.CredentialInput) -> None
806 classmethod choose(interactive: bool) -> Type[twine.auth.Re‐
808 solver]
809 property username: Optional[str]
811 property password: Optional[str]
813 property system: Optional[str]
815 get_username_from_keyring() -> Optional[str]
817 get_password_from_keyring() -> Optional[str]
819 username_from_keyring_or_prompt() -> str
821 password_from_keyring_or_prompt() -> str
823 prompt(what: str, how: Callable[[...], str]) -> str
825 class twine.auth.Private
827 prompt(what: str, how: Optional[Callable[[...], str]] = None) ->
829 str
830 twine.cli module
832 twine.cli.list_dependencies_and_versions() -> List[Tuple[str, str]]
833 twine.cli.dep_versions() -> str
835 twine.cli.dispatch(argv: List[str]) -> Any
837 twine.exceptions module
839 Module containing exceptions raised by twine.
840 exception twine.exceptions.TwineException
842 Base class for all exceptions raised by twine.
843 exception twine.exceptions.RedirectDetected
845 A redirect was detected that the user needs to resolve.
846 In some cases, requests refuses to issue a new POST request af‐
848 ter a redirect. In order to prevent a confusing user experience,
849 we raise this exception to allow users to know the index they're
850 uploading to is redirecting them.
851 classmethod from_args(repository_url: str, redirect_url: str) ->
853 twine.exceptions.RedirectDetected
854 exception twine.exceptions.PackageNotFound
856 A package file was provided that could not be found on the file
857 system.
858 This is only used when attempting to register a package_file.
860 exception twine.exceptions.UploadToDeprecatedPyPIDetected
862 An upload attempt was detected to deprecated PyPI domains.
863 The sites pypi.python.org and testpypi.python.org are depre‐
865 cated.
866 classmethod from_args(target_url: str, default_url: str,
868 test_url: str) -> twine.exceptions.UploadToDeprecatedPyPIDe‐
869 tected
870 Return an UploadToDeprecatedPyPIDetected instance.
871 exception twine.exceptions.UnreachableRepositoryURLDetected
873 An upload attempt was detected to a URL without a protocol pre‐
874 fix.
875 All repository URLs must have a protocol (e.g., https://).
877 exception twine.exceptions.InvalidSigningConfiguration
879 Both the sign and identity parameters must be present.
880 exception twine.exceptions.InvalidSigningExecutable
882 Signing executable must be installed on system.
883 exception twine.exceptions.InvalidConfiguration
885 Raised when configuration is invalid.
886 exception twine.exceptions.InvalidDistribution
888 Raised when a distribution is invalid.
889 exception twine.exceptions.NonInteractive
891 Raised in non-interactive mode when credentials could not be
892 found.
893 exception twine.exceptions.InvalidPyPIUploadURL
895 Repository configuration tries to use PyPI with an incorrect
896 URL.
897 For example, https://pypi.org instead of
899 https://upload.pypi.org/legacy.
900 twine.package module
902 twine.package._safe_name(name: str) -> str
903 Convert an arbitrary string to a standard distribution name.
904 Any runs of non-alphanumeric/. characters are replaced with a
906 single '-'.
907 Copied from pkg_resources.safe_name for compatibility with ware‐
909 house. See https://github.com/pypa/twine/issues/743.
910 class twine.package.PackageFile
912 __init__(filename: str, comment: Optional[str], metadata:
914 pkginfo.distribution.Distribution, python_version: Op‐
915 tional[str], filetype: Optional[str]) -> None
916 classmethod from_filename(filename: str, comment: Optional[str])
918 -> twine.package.PackageFile
919 metadata_dictionary() -> Dict[str, Union[str, Sequence[str]]]
921 add_gpg_signature(signature_filepath: str, signature_filename:
923 str) -> None
924 sign(sign_with: str, identity: Optional[str]) -> None
926 classmethod run_gpg(gpg_args: Tuple[str, ...]) -> None
928 class twine.package.Hexdigest
930 Hexdigest(md5, sha2, blake2)
931 md5: Optional[str]
933 Alias for field number 0
934 sha2: Optional[str]
936 Alias for field number 1
937 blake2: Optional[str]
939 Alias for field number 2
940 static __new__(_cls, md5: Optional[str], sha2: Optional[str],
942 blake2: Optional[str])
943 _asdict()
945 Return a new dict which maps field names to their values.
946 _field_defaults = {}
948 _fields = ('md5', 'sha2', 'blake2')
950 classmethod _make(iterable)
952 Make a new Hexdigest object from a sequence or iterable
953 _replace(**kwds)
955 Return a new Hexdigest object replacing specified fields
956 with new values
957 class twine.package.HashManager
959 Manage our hashing objects for simplicity.
960 This will also allow us to better test this logic.
962 __init__(filename: str) -> None
964 Initialize our manager and hasher objects.
965 _md5_update(content: bytes) -> None
967 _md5_hexdigest() -> Optional[str]
969 _sha2_update(content: bytes) -> None
971 _sha2_hexdigest() -> Optional[str]
973 _blake_update(content: bytes) -> None
975 _blake_hexdigest() -> Optional[str]
977 hash() -> None
979 Hash the file contents.
980 hexdigest() -> twine.package.Hexdigest
982 Return the hexdigest for the file.
983 twine.repository module
985 class twine.repository.ProgressBar
986 update_to(n: int) -> None
988 Update the bar in the way compatible with requests-tool‐
989 belt.
990 This is identical to tqdm.update, except n will be the
992 current value - not the delta as tqdm expects.
993 class twine.repository.Repository
995 __init__(repository_url: str, username: Optional[str], password:
997 Optional[str], disable_progress_bar: bool = False) -> None
998 static _make_adapter_with_retries() -> re‐
1000 quests.adapters.HTTPAdapter
1001 static _make_user_agent_string() -> str
1003 close() -> None
1005 static _convert_data_to_list_of_tuples(data: Dict[str, Any]) ->
1007 List[Tuple[str, Any]]
1008 set_certificate_authority(cacert: Optional[str]) -> None
1010 set_client_certificate(clientcert: Optional[str]) -> None
1012 register(package: twine.package.PackageFile) -> requests.mod‐
1014 els.Response
1015 _upload(package: twine.package.PackageFile) -> requests.mod‐
1017 els.Response
1018 upload(package: twine.package.PackageFile, max_redirects: int =
1020 5) -> requests.models.Response
1021 package_is_uploaded(package: twine.package.PackageFile, by‐
1023 pass_cache: bool = False) -> bool
1024 release_urls(packages: List[twine.package.PackageFile]) ->
1026 Set[str]
1027 verify_package_integrity(package: twine.package.PackageFile) ->
1029 None
1030 twine.settings module
1032 Module containing logic for handling settings.
1033 class twine.settings.Settings
1035 Object that manages the configuration for Twine.
1036 This object can only be instantiated with keyword arguments.
1038 For example,
1040 Settings(True, username='fakeusername')
1042 Will raise a TypeError. Instead, you would want
1044 Settings(sign=True, username='fakeusername')
1046 __init__(*, sign: bool = False, sign_with: str = 'gpg', iden‐
1048 tity: Optional[str] = None, username: Optional[str] = None,
1049 password: Optional[str] = None, non_interactive: bool = False,
1050 comment: Optional[str] = None, config_file: str = utils.DE‐
1051 FAULT_CONFIG_FILE, skip_existing: bool = False, cacert: Op‐
1052 tional[str] = None, client_cert: Optional[str] = None, reposi‐
1053 tory_name: str = 'pypi', repository_url: Optional[str] = None,
1054 verbose: bool = False, disable_progress_bar: bool = False, **ig‐
1055 nored_kwargs: Any) -> None
1056 Initialize our settings instance.
1057 Parameters
1059 • sign -- Configure whether the package file
1061 should be signed.
1062 • sign_with -- The name of the executable used to
1064 sign the package with.
1065 • identity -- The GPG identity that should be used
1067 to sign the package file.
1068 • username -- The username used to authenticate to
1070 the repository (package index).
1071 • password -- The password used to authenticate to
1073 the repository (package index).
1074 • non_interactive -- Do not interactively prompt
1076 for username/password if the required creden‐
1077 tials are missing.
1078 • comment -- The comment to include with each dis‐
1080 tribution file.
1081 • config_file -- The path to the configuration
1083 file to use.
1084 • skip_existing -- Specify whether twine should
1086 continue uploading files if one of them already
1087 exists. This primarily supports PyPI. Other
1088 package indexes may not be supported.
1089 • cacert -- The path to the bundle of certificates
1091 used to verify the TLS connection to the package
1092 index.
1093 • client_cert -- The path to the client certifi‐
1095 cate used to perform authentication to the in‐
1096 dex. This must be a single file that contains
1097 both the private key and the PEM-encoded cer‐
1098 tificate.
1099 • repository_name -- The name of the repository
1101 (package index) to interact with. This should
1102 correspond to a section in the config file.
1103 • repository_url -- The URL of the repository
1105 (package index) to interact with. This will
1106 override the settings inferred from reposi‐
1107 tory_name.
1108 • verbose -- Show verbose output.
1110 • disable_progress_bar -- Disable the progress
1112 bar.
1113 property username: Optional[str]
1115 property password: Optional[str]
1117 _allow_noninteractive() -> ContextManager[None]
1119 Bypass NonInteractive error when client cert is present.
1120 property verbose: bool
1122 static register_argparse_arguments(parser: argparse.Argument‐
1124 Parser) -> None
1125 Register the arguments for argparse.
1126 classmethod from_argparse(args: argparse.Namespace) ->
1128 twine.settings.Settings
1129 Generate the Settings from parsed arguments.
1130 _handle_package_signing(sign: bool, sign_with: str, identity:
1132 Optional[str]) -> None
1133 _handle_repository_options(repository_name: str, repository_url:
1135 Optional[str]) -> None
1136 _handle_certificates(cacert: Optional[str], client_cert: Op‐
1138 tional[str]) -> None
1139 check_repository_url() -> None
1141 Verify we are not using legacy PyPI.
1142 Raises twine.exceptions.UploadToDeprecatedPyPIDetected --
1144 The configured repository URL is for legacy PyPI.
1145 create_repository() -> twine.repository.Repository
1147 Create a new repository for uploading.
1148 twine.utils module
1150 twine.utils.get_config(path: str) -> Dict[str, Dict[str, Op‐
1151 tional[str]]]
1152 Read repository configuration from a file (i.e. ~/.pypirc).
1153 Format: https://packaging.python.org/specifications/pypirc/
1155 If the default config file doesn't exist, return a default con‐
1157 figuration for pypyi and testpypi.
1158 twine.utils._validate_repository_url(repository_url: str) -> None
1160 Validate the given url for allowed schemes and components.
1161 twine.utils.get_repository_from_config(config_file: str, repository:
1163 str, repository_url: Optional[str] = None) -> Dict[str, Optional[str]]
1164 Get repository config command-line values or the .pypirc file.
1165 twine.utils.normalize_repository_url(url: str) -> str
1167 twine.utils.get_file_size(filename: str) -> str
1169 Return the size of a file in KB, or MB if >= 1024 KB.
1170 twine.utils.check_status_code(response: requests.models.Response, ver‐
1172 bose: bool) -> None
1173 Generate a helpful message based on the response from the repos‐
1174 itory.
1175 Raise a custom exception for recognized errors. Otherwise, print
1177 the response content (based on the verbose option) before
1178 re-raising the HTTPError.
1179 twine.utils.get_userpass_value(cli_value: Optional[str], config:
1181 Dict[str, Optional[str]], key: str, prompt_strategy: Op‐
1182 tional[Callable[[], str]] = None) -> Optional[str]
1183 Get a credential (e.g. a username or password) from the configu‐
1184 ration.
1185 Uses the following rules:
1187 1. If cli_value is specified, use that.
1189 2. If config[key] is specified, use that.
1191 3. If prompt_strategy is specified, use its return value.
1193 4. Otherwise return None
1195 Parameters
1197 • cli_value -- The value supplied from the command line.
1199 • config -- A dictionary of repository configuration val‐
1201 ues.
1202 • key -- The credential to look up in config, e.g. "user‐
1204 name" or "password".
1205 • prompt_strategy -- An argumentless function to get the
1207 value, e.g. from keyring or by prompting the user.
1208 Returns
1210 The credential value, i.e. the username or password.
1211 twine.utils.get_cacert(cli_value: Optional[str], config: Dict[str, Op‐
1213 tional[str]], *, key: str = 'ca_cert', prompt_strategy: Op‐
1214 tional[Callable[[], str]] = None) -> Optional[str]
1215 Get the CA bundle via get_userpass_value().
1216 twine.utils.get_clientcert(cli_value: Optional[str], config: Dict[str,
1218 Optional[str]], *, key: str = 'client_cert', prompt_strategy: Op‐
1219 tional[Callable[[], str]] = None) -> Optional[str]
1220 Get the client certificate via get_userpass_value().
1221 class twine.utils.EnvironmentDefault
1223 Get values from environment variable.
1224 __init__(env: str, required: bool = True, default: Optional[str]
1226 = None, **kwargs: Any) -> None
1227 class twine.utils.EnvironmentFlag
1229 Set boolean flag from environment variable.
1230 __init__(env: str, **kwargs: Any) -> None
1232 static bool_from_env(val: Optional[str]) -> bool
1234 Allow '0' and 'false' and 'no' to be False.
1235 twine.wheel module
1237 class twine.wheel.Wheel
1238 __init__(filename: str, metadata_version: Optional[str] = None)
1240 -> None
1241 property py_version: str
1243 static find_candidate_metadata_files(names: List[str]) ->
1245 List[List[str]]
1246 Filter files that may be METADATA files.
1247 read() -> bytes
1249 parse(data: bytes) -> None
1251 twine.wininst module
1253 class twine.wininst.WinInst
1254 __init__(filename: str, metadata_version: Optional[str] = None)
1256 -> None
1257 property py_version: str
1259 read() -> bytes
1261 Where Twine gets configuration and credentials
1263 A user can set the repository URL, username, and/or password via com‐
1264 mand line, .pypirc files, environment variables, and keyring.
1265
1267 A checklist for adding a new maintainer to the project.
1268 1. Add them as a Member in the GitHub repo settings.
1270 2. Get them Test PyPI and canon PyPI usernames and add them as a Main‐
1272 tainer on our Test PyPI project and canon PyPI.
1273
1275 A checklist for creating, testing, and distributing a new version.
1276 1. Choose a version number, and create a new branch
1278 VERSION=3.4.2
1280 git switch -c release-$VERSION
1282 2. Update docs/changelog.rst
1284 tox -e changelog -- --version $VERSION
1286 git commit -am "Update changelog for $VERSION"
1288 3. Open a pull request for review
1290 4. Merge the pull request, and ensure the GitHub Actions build passes
1292 5. Create a new git tag for the version
1294 git switch main
1296 git pull --ff-only upstream main
1298 git tag -m "Release v$VERSION" $VERSION
1300 6. Push to start the release, and watch it in GitHub Actions
1302 git push upstream $VERSION
1304 7. View the new release on PyPI
1306
1308 See our open issues.
1309 In the future, pip and twine may merge into a single tool; see ongoing
1311 discussion.
1312 Twine is a utility for publishing Python packages to PyPI and other
1314 repositories. It provides build system independent uploads of source
1315 and binary distribution artifacts for both new and existing projects.
1316
1318 The goal of Twine is to improve PyPI interaction by improving security
1319 and testability.
1320 The biggest reason to use Twine is that it securely authenticates you
1322 to PyPI over HTTPS using a verified connection, regardless of the un‐
1323 derlying Python version. Meanwhile, python setup.py upload will only
1324 work correctly and securely if your build system, Python version, and
1325 underlying operating system are configured properly.
1326 Secondly, Twine encourages you to build your distribution files. python
1328 setup.py upload only allows you to upload a package as a final step af‐
1329 ter building with distutils or setuptools, within the same command in‐
1330 vocation. This means that you cannot test the exact file you're going
1331 to upload to PyPI to ensure that it works before uploading it.
1332 Finally, Twine allows you to pre-sign your files and pass the .asc
1334 files into the command line invocation (twine upload mypro‐
1335 ject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc). This enables you to be
1336 assured that you're typing your gpg passphrase into gpg itself and not
1337 anything else, since you will be the one directly executing gpg --de‐
1338 tach-sign -a <filename>.
1339
1341 • Verified HTTPS connections
1342 • Uploading doesn't require executing setup.py
1344 • Uploading files that have already been created, allowing testing of
1346 distributions before release
1347 • Supports uploading any packaging format (including wheels)
1349
1351 pip install twine
1352
1354 1. Create some distributions in the normal way:
1355 python -m build
1357 2. Upload to Test PyPI and verify things look right:
1359 twine upload -r testpypi dist/*
1361 Twine will prompt for your username and password.
1363 3. Upload to PyPI:
1365 twine upload dist/*
1367 4. Done!
1369 NOTE:
1371 Like many other command line tools, Twine does not show any charac‐
1372 ters when you enter your password.
1373 If you're using Windows and trying to paste your username, password,
1375 or token in the Command Prompt or PowerShell, Ctrl-V and Shift+In‐
1376 sert won't work. Instead, you can use "Edit > Paste" from the window
1377 menu, or enable "Use Ctrl+Shift+C/V as Copy/Paste" in "Properties".
1378 This is a known issue with Python's getpass module.
1379 More documentation on using Twine to upload packages to PyPI is in the
1381 Python Packaging User Guide.
1382
1384 twine upload
1385 Uploads one or more distributions to a repository.
1386 System Message: ERROR/6 (/builddir/build/BUILD/twine-3.6.0/docs/in‐
1388 dex.rst:, line 116)
1389 Command ['twine', 'upload', '-h'] failed: [Errno 2] No such file
1390 or directory: 'twine'
1391 twine check
1393 Checks whether your distribution's long description will render cor‐
1394 rectly on PyPI.
1395 System Message: ERROR/6 (/builddir/build/BUILD/twine-3.6.0/docs/in‐
1397 dex.rst:, line 124)
1398 Command ['twine', 'check', '-h'] failed: [Errno 2] No such file
1399 or directory: 'twine'
1400 twine register
1402 Pre-register a name with a repository before uploading a distribution.
1403 WARNING:
1405 Pre-registration is not supported on PyPI, so the register command
1406 is only necessary if you are using a different repository that re‐
1407 quires it. See issue #1627 on Warehouse (the software running on
1408 PyPI) for more details.
1409 System Message: ERROR/6 (/builddir/build/BUILD/twine-3.6.0/docs/in‐
1411 dex.rst:, line 137)
1412 Command ['twine', 'register', '-h'] failed: [Errno 2] No such
1413 file or directory: 'twine'
1414
1416 Twine can read repository configuration from a .pypirc file, either in
1417 your home directory, or provided with the --config-file option. For de‐
1418 tails on writing and using .pypirc, see the specification in the Python
1419 Packaging User Guide.
1420 Environment Variables
1422 Twine also supports configuration via environment variables. Options
1423 passed on the command line will take precedence over options set via
1424 environment variables. Definition via environment variable is helpful
1425 in environments where it is not convenient to create a .pypirc file
1426 (for example, on a CI/build server).
1427 • TWINE_USERNAME - the username to use for authentication to the repos‐
1429 itory.
1430 • TWINE_PASSWORD - the password to use for authentication to the repos‐
1432 itory.
1433 • TWINE_REPOSITORY - the repository configuration, either defined as a
1435 section in .pypirc or provided as a full URL.
1436 • TWINE_REPOSITORY_URL - the repository URL to use.
1438 • TWINE_CERT - custom CA certificate to use for repositories with
1440 self-signed or untrusted certificates.
1441 • TWINE_NON_INTERACTIVE - Do not interactively prompt for user‐
1443 name/password if the required credentials are missing.
1444 Proxy Support
1446 Twine can be configured to use a proxy by setting environment vari‐
1447 ables. For example, to use a proxy for just the twine command, without
1448 export-ing it for other tools:
1449 HTTPS_PROXY=socks5://user:pass@host:port twine upload dist/*
1451 For more information, see the Requests documentation on proxies and
1453 SOCKS , and an in-depth article about proxy environment variables.
1454
1456 Instead of typing in your password every time you upload a distribu‐
1457 tion, Twine allows storing a username and password securely using
1458 keyring. Keyring is installed with Twine but for some systems (Linux
1459 mainly) may require additional installation steps.
1460 Once Twine is installed, use the keyring program to set a username and
1462 password to use for each repository to which you may upload.
1463 For example, to set a username and password for PyPI:
1465 keyring set https://upload.pypi.org/legacy/ your-username
1467 and enter the password when prompted.
1469 For a different repository, replace the URL with the relevant reposi‐
1471 tory URL. For example, for Test PyPI, use
1472 https://test.pypi.org/legacy/.
1473 The next time you run twine, it will prompt you for a username, and
1475 then get the appropriate password from Keyring.
1476 NOTE:
1478 If you are using Linux in a headless environment (such as on a
1479 server) you'll need to do some additional steps to ensure that
1480 Keyring can store secrets securely. See Using Keyring on headless
1481 systems.
1482 Disabling Keyring
1484 In most cases, simply not setting a password with keyring will allow
1485 Twine to fall back to prompting for a password. In some cases, the
1486 presence of Keyring will cause unexpected or undesirable prompts from
1487 the backing system. In these cases, it may be desirable to disable
1488 Keyring altogether. To disable Keyring, run:
1489 keyring --disable
1491 See Twine issue #338 for discussion and background.
1493
1495 Donald Stufft, Individual contributors
1496
1498 2021, Donald Stufft and individual contributors
14993.6 Nov 10, 2021 TWINE(1)