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 Bugfixes
13 • Improve logging when keyring fails. (#890)
14 • Reconfgure root logger to show all log messages. (#896)
16
18 Features
19 • Drop support for Python 3.6. (#869)
20 • Use Rich to add color to upload output. (#851)
22 • Use Rich to add color to check output. (#874)
24 • Use Rich instead of tqdm for upload progress bar. (#877)
26 Bugfixes
28 • Remove Twine's dependencies from the User-Agent header when upload‐
29 ing. (#871)
30 • Improve detection of disabled BLAKE2 hashing due to FIPS mode. (#879)
32 • Restore warning for missing long_description. (#887)
34
36 Features
37 • Add --verbose logging for querying keyring credentials. (#849)
38 • Log all upload responses with --verbose. (#859)
40 • Show more helpful error message for invalid metadata. (#861)
42 Bugfixes
44 • Require a recent version of urllib3. (#858)
45
47 Improved Documentation
48 • Fix broken link to packaging tutorial. (#844)
49
51 Features
52 • Add support for core metadata version 2.2, defined in PEP 643. (#833)
53
55 Features
56 • Add support for Python 3.10. (#827)
57
59 Features
60 • Show more helpful messages for invalid passwords. (#815)
61 • Allow the --skip-existing option to work with GCP Artifact Registry.
63 (#823)
64 Bugfixes
66 • Add a helpful error message when an upload fails due to missing a
67 trailing slash in the URL. (#812)
68 • Generalize --verbose suggestion when an upload fails. (#817)
70
72 Bugfixes
73 • Improve error message for unsupported metadata. (#755)
74 • Improve error message for a missing config file. (#770)
76 • Do not include md5_digest or blake2_256_digest if FIPS mode is en‐
78 abled on the host. This removes those fields from the metadata before
79 sending the metadata to the repository. (#776)
80
82 Bugfixes
83 • Fix a regression that was causing some namespace packages with dots
84 in them fail to upload to PyPI. (#745)
85
87 Features
88 • Prefer importlib.metadata for entry point handling. (#728)
89 • Rely on importlib_metadata 3.6 for nicer entry point processing. (‐
91 #732)
92 • Eliminate dependency on setuptools/pkg_resources and replace with
94 packaging and importlib_metadata. (#736)
95
97 Features
98 • Print files to be uploaded using upload --verbose (#670)
99 • Print configuration file location when using upload --verbose (#675)
101 • Print source and values of credentials when using upload --verbose (‐
103 #685)
104 • Add support for Python 3.9 (#708)
106 • Turn warnings into errors when using check --strict (#715)
108 Bugfixes
110 • Make password optional when using upload --client-cert (#678)
111 • Support more Nexus versions with upload --skip-existing (#693)
113 • Support Gitlab Enterprise with upload --skip-existing (#698)
115 • Show a better error message for malformed files (#714)
117 Improved Documentation
119 • Adopt PSF code of conduct (#680)
120 • Adopt towncrier for the changleog (#718)
122
124 Features
125 • Improve display of HTTP errors during upload (#666)
126 • Print packages and signatures to be uploaded when using --verbose op‐
128 tion (#652)
129 • Use red text when printing errors on the command line (#649)
131 • Require repository URL scheme to be http or https (#602)
133 • Add type annotations, checked with mypy, with PEP 561 support for
135 users of Twine's API (#231)
136 Bugfixes
138 • Update URL to .pypirc specification (#655)
139 • Don't raise an exception when Python version can't be parsed from
141 filename (#612)
142 • Fix inaccurate retry message during upload (#611)
144 • Clarify error messages for archive format (#601)
146
148 Bugfixes
149 • Restore --non-interactive as a flag not expecting an argument. (#548)
150
152 Features
153 • Add support for specifying --non-interactive as an environment vari‐
154 able. (#547)
155
157 Features
158 • When a client certificate is indicated, all password processing is
159 disabled. (#336)
160 • Add --non-interactive flag to abort upload rather than interactively
162 prompt if credentials are missing. (#489)
163 • Twine now unconditionally requires the keyring library and no longer
165 supports uninstalling keyring as a means to disable that functional‐
166 ity. Instead, use keyring --disable keyring functionality if neces‐
167 sary. (#524)
168 • Add Python 3.8 to classifiers. (#518)
170 Bugfixes
172 • More robust handling of server response in --skip-existing (#332)
173
175 Features
176 • Twine now requires Python 3.6 or later. Use pip 9 or pin to "twine<2"
177 to install twine on older Python versions. (#437)
178 Bugfixes
180 • Require requests 2.20 or later to avoid reported security vulnerabil‐
181 ities in earlier releases. (#491)
182
184 Features
185 • Improved output on check command: Prints a message when there are no
186 distributions given to check. Improved handling of errors in a dis‐
187 tribution's markup, avoiding messages flowing through to the next
188 distribution's errors. (#488)
189
191 Features
192 • Show Warehouse URL after uploading a package (#459)
193 • Better error handling and gpg2 fallback if gpg not available. (#456)
195 • Now provide a more meaningful error on redirect during upload. (#310)
197 Bugfixes
199 • Fail more gracefully when encountering bad metadata (#341)
200
202 Features
203 • Add disable_progress_bar option to disable tqdm. (#427)
204 • Allow defining an empty username and password in .pypirc. (#426)
206 • Support keyring.get_credential. (#419)
208 • Support keyring.get_username_and_password. (#418)
210 • Add Python 3.7 to classifiers. (#416)
212 Bugfixes
214 • Restore prompts while retaining support for suppressing prompts. (‐
215 #452)
216 • Avoid requests-toolbelt to 0.9.0 to prevent attempting to use openssl
218 when it isn't available. (#447)
219 • Use io.StringIO instead of StringIO. (#444)
221 • Only install pyblake2 if needed. (#441)
223 • Use modern Python language features. (#436)
225 • Specify python_requires in setup.py (#435)
227 • Use https URLs everywhere. (#432)
229 • Fix --skip-existing for Nexus Repos. (#428)
231 • Remove unnecessary usage of readme_render.markdown. (#421)
233 • Don't crash if there's no package description. (#412)
235 • Fix keyring support. (#408)
237 Misc
239 • Refactor tox env and travis config. (#439)
240
242 Bugfixes
243 • Fix regression with upload exit code (#404)
244
246 Features
247 • Add twine check command to check long description (#395)
248 • Drop support for Python 3.3 (#392)
250 • Empower --skip-existing for Artifactory repositories (#363)
252 Bugfixes
254 • Avoid MD5 when Python is compiled in FIPS mode (#367)
255
257 Features
258 • Remove PyPI as default register package index. (#320)
259 • Support Metadata 2.1 (PEP 566), including Markdown for description
261 fields. (#319)
262 Bugfixes
264 • Raise exception if attempting upload to deprecated legacy PyPI URLs.
265 (#322)
266 • Avoid uploading to PyPI when given alternate repository URL, and re‐
268 quire http:// or https:// in repository_url. (#269)
269 Misc
271 • Update PyPI URLs. (#318)
272 • Add new maintainer, release checklists. (#314)
274 • Add instructions on how to use keyring. (#277)
276
278 Features
279 • Link to changelog from README (#46)
280 • Reorganize & improve user & developer documentation. (#304)
282 • Revise docs predicting future of twine (#303)
284 • Add architecture overview to docs (#296)
286 • Add doc building instructions (#295)
288 • Declare support for Python 3.6 (#257)
290 • Improve progressbar (#256)
292 Bugfixes
294 • Degrade gracefully when keyring is unavailable (#315)
295 • Fix changelog formatting (#299)
297 • Fix syntax highlighting in README (#298)
299 • Fix Read the Docs, tox, Travis configuration (#297)
301 • Fix Travis CI and test configuration (#286)
303 • Print progress to stdout, not stderr (#268)
305 • Fix --repository[-url] help text (#265)
307 • Remove obsolete registration guidance (#200)
309
311 Bugfixes
312 • Blacklist known bad versions of Requests. (#253)
313
315 Bugfixes
316 • Twine sends less information about the user's system in the
317 User-Agent string. (#229)
318 • Fix --skip-existing when used to upload a package for the first time.
320 (#220)
321 • Fix precedence of --repository-url over --repository. (#206)
323 Misc
325 • Twine will now resolve passwords using the keyring if available. Mod‐
326 ule can be required with the keyring extra.
327 • Twine will use hashlib.blake2b on Python 3.6+ instead of pyblake2
329
331 Misc
332 • Check if a package exists if the URL is one of:
333 • https://pypi.python.org/pypi/
335 • https://upload.pypi.org/
337 • https://upload.pypi.io/
339 This helps people with https://upload.pypi.io still in their
341 .pypirc file.
342
344 Features
345 • Switch from upload.pypi.io to upload.pypi.org. (#201)
346 • Retrieve configuration from the environment as a default. (#144)
348 • Repository URL will default to TWINE_REPOSITORY
350 • Username will default to TWINE_USERNAME
352 • Password will default to TWINE_PASSWORD
354 • Allow the Repository URL to be provided on the command-line (--repos‐
356 itory-url) or via an environment variable (TWINE_REPOSITORY_URL). (‐
357 #166)
358 • Generate Blake2b 256 digests for packages if pyblake2 is installed.
360 Users can use python -m pip install twine[with-blake2] to have py‐
361 blake2 installed with Twine. (#171)
362 Misc
364 • Generate SHA256 digest for all packages by default.
365 • Stop testing on Python 2.6.
367 • Warn users if they receive a 500 error when uploading to
369 *pypi.python.org (#199)
370
372 Bugfixes
373 • Correct a packaging error.
374
376 Bugfixes
377 • Fix uploads to instances of pypiserver using --skip-existing. We were
378 not properly checking the return status code on the response after
379 attempting an upload. (#195)
380 Misc
382 • Avoid attempts to upload a package if we can find it on Legacy PyPI.
383
385 Bugfixes
386 • Fix issue where we were checking the existence of packages even if
387 the user didn't specify --skip-existing. (#189) (#191)
388
390 Bugfixes
391 • Clint was not specified in the wheel metadata as a dependency. (#187)
392
394 Features
395 • Support --cert and --client-cert command-line flags and config file
396 options for feature parity with pip. This allows users to verify con‐
397 nections to servers other than PyPI (e.g., local package reposito‐
398 ries) with different certificates. (#142)
399 • Add progress bar to uploads. (#152)
401 • Allow --skip-existing to work for 409 status codes. (#162)
403 • Implement retries when the CDN in front of PyPI gives us a 5xx error.
405 (#167)
406 • Switch Twine to upload to pypi.io instead of pypi.python.org. (#177)
408 Bugfixes
410 • Allow passwords to have %s in them. (#186)
411
413 Bugfixes
414 • Bump requests-toolbelt version to ensure we avoid ConnectionErrors (‐
415 #155)
416
418 Bugfixes
419 • Paths with hyphens in them break the Wheel regular expression. (#145)
420 • Exception while accessing the repository key (sic) when raising a re‐
422 direct exception. (#146)
423
425 Bugfixes
426 • Fix uploading signatures causing a 500 error after large file support
427 was added. (#137, #140)
428
430 Bugfixes
431 • Upload signatures with packages appropriately (#132)
432 As part of the refactor for the 1.6.0 release, we were using the
433 wrong name to find the signature file.
434 This also uncovered a bug where if you're using twine in a situa‐
436 tion where * is not expanded by your shell, we might also miss up‐
437 loading signatures to PyPI. Both were fixed as part of this.
438
440 Bugfixes
441 • Fix signing support for uploads (#130)
442
444 Features
445 • Allow the user to specify the location of their .pypirc (#97)
446 • Support registering new packages with twine register (#8)
448 • Add the --skip-existing flag to twine upload to allow users to skip
450 releases that already exist on PyPI. (#115)
451 • Upload wheels first to PyPI (#106)
453 • Large file support via the requests-toolbelt (#104)
455 Bugfixes
457 • Raise an exception on redirects (#92)
458 • Work around problems with Windows when using getpass.getpass (#116)
460 • Warnings triggered by pkginfo searching for PKG-INFO files should no
462 longer be user visible. (#114)
463 • Provide more helpful messages if .pypirc is out of date. (#111)
465
467 Features
468 • Support commands not named "gpg" for signing (#29)
469 Bugfixes
471 • Display information about the version of setuptools installed (#85)
472 • Support deprecated pypirc file format (#61)
474 Misc
476 • Add lower-limit to requests dependency
477
479 Features
480 • Switch to a git style dispatching for the commands to enable simpler
481 commands and programmatic invocation. (#6)
482 • Parse ~/.pypirc ourselves and use subprocess instead of the distu‐
484 tils.spawn module. (#13)
485 Bugfixes
487 • Expand globs and check for existence of dists to upload (#65)
488 • Fix issue uploading packages with _s in the name (#47)
490 • List registered commands in help text (#34)
492 • Use pkg_resources to load registered commands (#32)
494 • Prevent ResourceWarning from being shown (#28)
496 • Add support for uploading Windows installers (#26)
498
500 Features
501 • Additional functionality.
502
504 Features
505 • Basic functionality.
506 We are happy you have decided to contribute to Twine.
508 Please see the GitHub repository for code and more documentation, and
510 the official Python Packaging User Guide for user documentation. To
511 ask questions or get involved, you can join the Python Packaging Dis‐
512 course forum, #pypa or #pypa-dev on IRC, or the distutils-sig mailing
513 list.
514 Everyone interacting in the Twine project's codebases, issue trackers,
516 chat rooms, and mailing lists is expected to follow the PSF Code of
517 Conduct.
518
520 We use tox to run tests, check code style, and build the documentation.
521 To install tox, run:
522 python3 -m pip install tox
524 Clone the twine repository from GitHub, then run:
526 cd /path/to/your/local/twine
528 tox -e dev
529 This creates a virtual environment, so that twine and its dependencies
531 do not interfere with other packages installed on your machine. In the
532 virtual environment, twine is pointing at your local copy, so when you
533 make changes, you can easily see their effect.
534 The virtual environment also contains the tools for running tests and
536 checking code style, so you can run them on single files directly or in
537 your code editor. However, we still encourage using the tox commands
538 below on the whole codebase.
539 To use the virtual environment, run:
541 source venv/bin/activate
543 Building the documentation
545 Additions and edits to twine's documentation are welcome and appreci‐
546 ated.
547 To preview the docs while you're making changes, run:
549 tox -e watch-docs
551 Then open a web browser to http://127.0.0.1:8000.
553 When you're done making changes, lint and build the docs locally before
555 making a pull request. In your active virtual environment, run:
556 tox -e docs
558 The HTML of the docs will be written to docs/_build/html.
560 Code style
562 To automatically reformat your changes with isort and black, run:
563 tox -e format
565 To detect any remaining code smells with flake8, run:
567 tox -e lint
569 To perform strict type-checking using mypy, run:
571 tox -e types
573 Any errors from lint or types need to be fixed manually.
575 Additionally, we prefer that import statements be used for packages and
577 modules only, rather than individual classes or functions.
578 Testing
580 We use pytest for writing and running tests.
581 To run the tests in your virtual environment, run:
583 tox -e py
585 To pass options to pytest, e.g. the name of a test, run:
587 tox -e py -- tests/test_upload.py::test_exception_for_http_status
589 Twine is continuously tested against supported versions of Python using
591 GitHub Actions. To run the tests against a specific version, e.g.
592 Python 3.8, you will need it installed on your machine. Then, run:
593 tox -e py38
595 To run the "integration" tests of uploading to real package indexes,
597 run:
598 tox -e integration
600 To run the tests against all supported Python versions, check code
602 style, and build the documentation, run:
603 tox
605
607 1. Fork the GitHub repository.
608 2. Make a branch off of main and commit your changes to it.
610 3. Run the tests, check code style, and build the docs as described
612 above.
613 4. Optionally, add your name to the end of the AUTHORS file using the
615 format Name <email@domain.com> (url), where the (url) portion is op‐
616 tional.
617 5. Submit a pull request to the main branch on GitHub, referencing an
619 open issue.
620 6. Add a changelog entry.
622 Changelog entries
624 The docs/changelog.rst file is built by towncrier from files in the
625 changelog/ directory. To add an entry, create a file in that directory
626 named {number}.{type}.rst, where {number} is the pull request number,
627 and {type} is feature, bugfix, doc, removal, or misc.
628 For example, if your PR number is 1234 and it's fixing a bug, then you
630 would create changelog/1234.bugfix.rst. PRs can span multiple cate‐
631 gories by creating multiple files: if you added a feature and depre‐
632 cated/removed an old feature in PR #5678, you would create
633 changelog/5678.feature.rst and changelog/5678.removal.rst.
634 A changelog entry is meant for end users and should only contain de‐
636 tails relevant to them. In order to maintain a consistent style, please
637 keep the entry to the point, in sentence case, shorter than 80 charac‐
638 ters, and in an imperative tone. An entry should complete the sentence
639 "This change will ...". If one line is not enough, use a summary line
640 in an imperative tone, followed by a description of the change in one
641 or more paragraphs, each wrapped at 80 characters and separated by
642 blank lines.
643 You don't need to reference the pull request or issue number in a
645 changelog entry, since towncrier will add a link using the number in
646 the file name, and the pull request should reference an issue number.
647 Similarly, you don't need to add your name to the entry, since that
648 will be associated with the pull request.
649 Changelog entries are rendered using reStructuredText, but they should
651 only have minimal formatting (such as ``monospaced text``).
652
654 Twine is a command-line tool for interacting with PyPI securely over
655 HTTPS. Its three purposes are to be:
656 1. A user-facing tool for publishing on pypi.org
658 2. A user-facing tool for publishing on other Python package indexes
660 (e.g., devpi instances)
661 3. A useful API for other programs (e.g., zest.releaser) to call for
663 publishing on any Python package index
664 Currently, twine has two principle functions: uploading new packages
666 and registering new projects (register is no longer supported on PyPI,
667 and is in Twine for use with other package indexes).
668 Its command line arguments are parsed in twine/cli.py. The code for
670 registering new projects is in twine/commands/register.py, and the code
671 for uploading is in twine/commands/upload.py. The file twine/package.py
672 contains a single class, PackageFile, which hashes the project files
673 and extracts their metadata. The file twine/repository.py contains the
674 Repository class, whose methods control the URL the package is uploaded
675 to (which the user can specify either as a default, in the .pypirc
676 file, or pass on the command line), and the methods that upload the
677 package securely to a URL.
678 For more details, refer to the source documentation (currently a work
680 in progress):
681 twine package
683 Top-level module for Twine.
684 The contents of this package are not a public API. For more details,
686 see https://github.com/pypa/twine/issues/194 and
687 https://github.com/pypa/twine/issues/665.
688 twine.commands package
690 Module containing the logic for the twine sub-commands.
691 The contents of this package are not a public API. For more details,
693 see https://github.com/pypa/twine/issues/194 and
694 https://github.com/pypa/twine/issues/665.
695 twine.commands.check module
697 Module containing the logic for twine check.
698 class twine.commands.check._WarningStream
700 write(text: str) -> int
702 Write string to file.
703 Returns the number of characters written, which is always
705 equal to the length of the string.
706 twine.commands.check._check_file(filename: str, render_warning_stream:
708 _WarningStream) -> Tuple[List[str], bool]
709 Check given distribution.
710 twine.commands.check.check(dists: List[str], strict: bool = False) ->
712 bool
713 Check that a distribution will render correctly on PyPI and dis‐
714 play the results.
715 This is currently only validates long_description, but more
717 checks could be added; see
718 https://github.com/pypa/twine/projects/2.
719 Parameters
721 • dists -- The distribution files to check.
723 • output_stream -- The destination of the resulting out‐
725 put.
726 • strict -- If True, treat warnings as errors.
728 Returns
730 True if there are rendering errors, otherwise False.
731 twine.commands.check.main(args: List[str]) -> bool
733 Execute the check command.
734 Parameters
736 args -- The command-line arguments.
737 Returns
739 The exit status of the check command.
740 twine.commands.register module
742 Module containing the logic for twine register.
743 twine.commands.register.register(register_settings: Settings, package:
745 str) -> None
746 Pre-register a package name with a repository before uploading a
747 distribution.
748 Pre-registration is not supported on PyPI, so the register com‐
750 mand is only necessary if you are using a different repository
751 that requires it.
752 Parameters
754 • register_settings -- The configured options relating to
756 repository registration.
757 • package -- The path of the distribution to use for
759 package metadata.
760 Raises
762 • twine.exceptions.TwineException -- The registration
764 failed due to a configuration error.
765 • requests.HTTPError -- The repository responded with an
767 error.
768 twine.commands.register.main(args: List[str]) -> None
770 Execute the register command.
771 Parameters
773 args -- The command-line arguments.
774 twine.commands.upload module
776 Module containing the logic for twine upload.
777 twine.commands.upload.skip_upload(response: Response, skip_existing:
779 bool, package: PackageFile) -> bool
780 Determine if a failed upload is an error or can be safely ig‐
781 nored.
782 Parameters
784 • response -- The response from attempting to upload
786 package to a repository.
787 • skip_existing -- If True, use the status and content of
789 response to determine if the package already exists on
790 the repository. If so, then a failed upload is safe to
791 ignore.
792 • package -- The package that was being uploaded.
794 Returns
796 True if a failed upload can be safely ignored, otherwise
797 False.
798 twine.commands.upload._make_package(filename: str, signatures:
800 Dict[str, str], upload_settings: Settings) -> PackageFile
801 Create and sign a package, based off of filename, signatures and
802 settings.
803 twine.commands.upload.upload(upload_settings: Settings, dists:
805 List[str]) -> None
806 Upload one or more distributions to a repository, and display
807 the progress.
808 If a package already exists on the repository, most repositories
810 will return an error response. However, if upload_set‐
811 tings.skip_existing is True, a message will be displayed and any
812 remaining distributions will be uploaded.
813 For known repositories (like PyPI), the web URLs of successfully
815 uploaded packages will be displayed.
816 Parameters
818 • upload_settings -- The configured options related to
820 uploading to a repository.
821 • dists -- The distribution files to upload to the repos‐
823 itory. This can also include .asc files; the GPG signa‐
824 tures will be added to the corresponding uploads.
825 Raises
827 • twine.exceptions.TwineException -- The upload failed
829 due to a configuration error.
830 • requests.HTTPError -- The repository responded with an
832 error.
833 twine.commands.upload.main(args: List[str]) -> None
835 Execute the upload command.
836 Parameters
838 args -- The command-line arguments.
839 twine.auth module
841 class twine.auth.CredentialInput
842 __init__(username: str | None = None, password: str | None =
844 None) -> None
845 class twine.auth.Resolver
847 __init__(config: Dict[str, str | None], input: CredentialInput)
849 -> None
850 classmethod choose(interactive: bool) -> Type[Resolver]
852 property username: str | None
854 property password: str | None
856 property system: str | None
858 get_username_from_keyring() -> str | None
860 get_password_from_keyring() -> str | None
862 username_from_keyring_or_prompt() -> str
864 password_from_keyring_or_prompt() -> str
866 prompt(what: str, how: Callable[[...], str]) -> str
868 class twine.auth.Private
870 prompt(what: str, how: Callable[[...], str] | None = None) ->
872 str
873 twine.cli module
875 twine.cli.configure_output() -> None
876 twine.cli.list_dependencies_and_versions() -> List[Tuple[str, str]]
878 twine.cli.dep_versions() -> str
880 twine.cli.dispatch(argv: List[str]) -> Any
882 twine.exceptions module
884 Module containing exceptions raised by twine.
885 exception twine.exceptions.TwineException
887 Base class for all exceptions raised by twine.
888 exception twine.exceptions.RedirectDetected
890 A redirect was detected that the user needs to resolve.
891 In some cases, requests refuses to issue a new POST request af‐
893 ter a redirect. In order to prevent a confusing user experience,
894 we raise this exception to allow users to know the index they're
895 uploading to is redirecting them.
896 classmethod from_args(repository_url: str, redirect_url: str) ->
898 RedirectDetected
899 exception twine.exceptions.PackageNotFound
901 A package file was provided that could not be found on the file
902 system.
903 This is only used when attempting to register a package_file.
905 exception twine.exceptions.UploadToDeprecatedPyPIDetected
907 An upload attempt was detected to deprecated PyPI domains.
908 The sites pypi.python.org and testpypi.python.org are depre‐
910 cated.
911 classmethod from_args(target_url: str, default_url: str,
913 test_url: str) -> UploadToDeprecatedPyPIDetected
914 Return an UploadToDeprecatedPyPIDetected instance.
915 exception twine.exceptions.UnreachableRepositoryURLDetected
917 An upload attempt was detected to a URL without a protocol pre‐
918 fix.
919 All repository URLs must have a protocol (e.g., https://).
921 exception twine.exceptions.InvalidSigningConfiguration
923 Both the sign and identity parameters must be present.
924 exception twine.exceptions.InvalidSigningExecutable
926 Signing executable must be installed on system.
927 exception twine.exceptions.InvalidConfiguration
929 Raised when configuration is invalid.
930 exception twine.exceptions.InvalidDistribution
932 Raised when a distribution is invalid.
933 exception twine.exceptions.NonInteractive
935 Raised in non-interactive mode when credentials could not be
936 found.
937 exception twine.exceptions.InvalidPyPIUploadURL
939 Repository configuration tries to use PyPI with an incorrect
940 URL.
941 For example, https://pypi.org instead of
943 https://upload.pypi.org/legacy.
944 twine.package module
946 twine.package._safe_name(name: str) -> str
947 Convert an arbitrary string to a standard distribution name.
948 Any runs of non-alphanumeric/. characters are replaced with a
950 single '-'.
951 Copied from pkg_resources.safe_name for compatibility with ware‐
953 house. See https://github.com/pypa/twine/issues/743.
954 class twine.package.PackageFile
956 __init__(filename: str, comment: str | None, metadata: Distribu‐
958 tion, python_version: str | None, filetype: str | None) -> None
959 classmethod from_filename(filename: str, comment: str | None) ->
961 PackageFile
962 metadata_dictionary() -> Dict[str, str | Sequence[str]]
964 Merge multiple sources of metadata into a single dictio‐
965 nary.
966 Includes values from filename, PKG-INFO, hashers, and
968 signature.
969 add_gpg_signature(signature_filepath: str, signature_filename:
971 str) -> None
972 sign(sign_with: str, identity: str | None) -> None
974 classmethod run_gpg(gpg_args: Tuple[str, ...]) -> None
976 class twine.package.Hexdigest
978 Hexdigest(md5, sha2, blake2)
979 md5: str | None
981 Alias for field number 0
982 sha2: str | None
984 Alias for field number 1
985 blake2: str | None
987 Alias for field number 2
988 static __new__(_cls, md5: str | None, sha2: str | None, blake2:
990 str | None)
991 Create new instance of Hexdigest(md5, sha2, blake2)
992 _asdict()
994 Return a new dict which maps field names to their values.
995 _field_defaults = {}
997 _fields = ('md5', 'sha2', 'blake2')
999 classmethod _make(iterable)
1001 Make a new Hexdigest object from a sequence or iterable
1002 _replace(**kwds)
1004 Return a new Hexdigest object replacing specified fields
1005 with new values
1006 class twine.package.HashManager
1008 Manage our hashing objects for simplicity.
1009 This will also allow us to better test this logic.
1011 __init__(filename: str) -> None
1013 Initialize our manager and hasher objects.
1014 _md5_update(content: bytes) -> None
1016 _md5_hexdigest() -> str | None
1018 _sha2_update(content: bytes) -> None
1020 _sha2_hexdigest() -> str | None
1022 _blake_update(content: bytes) -> None
1024 _blake_hexdigest() -> str | None
1026 hash() -> None
1028 Hash the file contents.
1029 hexdigest() -> Hexdigest
1031 Return the hexdigest for the file.
1032 twine.repository module
1034 class twine.repository.Repository
1035 __init__(repository_url: str, username: str | None, password:
1037 str | None, disable_progress_bar: bool = False) -> None
1038 static _make_adapter_with_retries() -> HTTPAdapter
1040 static _make_user_agent_string() -> str
1042 close() -> None
1044 static _convert_data_to_list_of_tuples(data: Dict[str, Any]) ->
1046 List[Tuple[str, Any]]
1047 set_certificate_authority(cacert: str | None) -> None
1049 set_client_certificate(clientcert: str | None) -> None
1051 register(package: PackageFile) -> Response
1053 _upload(package: PackageFile) -> Response
1055 upload(package: PackageFile, max_redirects: int = 5) -> Response
1057 package_is_uploaded(package: PackageFile, bypass_cache: bool =
1059 False) -> bool
1060 release_urls(packages: List[PackageFile]) -> Set[str]
1062 verify_package_integrity(package: PackageFile) -> None
1064 twine.settings module
1066 Module containing logic for handling settings.
1067 class twine.settings.Settings
1069 Object that manages the configuration for Twine.
1070 This object can only be instantiated with keyword arguments.
1072 For example,
1074 Settings(True, username='fakeusername')
1076 Will raise a TypeError. Instead, you would want
1078 Settings(sign=True, username='fakeusername')
1080 __init__(*, sign: bool = False, sign_with: str = 'gpg', iden‐
1082 tity: str | None = None, username: str | None = None, password:
1083 str | None = None, non_interactive: bool = False, comment: str |
1084 None = None, config_file: str = utils.DEFAULT_CONFIG_FILE,
1085 skip_existing: bool = False, cacert: str | None = None,
1086 client_cert: str | None = None, repository_name: str = 'pypi',
1087 repository_url: str | None = None, verbose: bool = False, dis‐
1088 able_progress_bar: bool = False, **ignored_kwargs: Any) -> None
1089 Initialize our settings instance.
1090 Parameters
1092 • sign -- Configure whether the package file
1094 should be signed.
1095 • sign_with -- The name of the executable used to
1097 sign the package with.
1098 • identity -- The GPG identity that should be used
1100 to sign the package file.
1101 • username -- The username used to authenticate to
1103 the repository (package index).
1104 • password -- The password used to authenticate to
1106 the repository (package index).
1107 • non_interactive -- Do not interactively prompt
1109 for username/password if the required creden‐
1110 tials are missing.
1111 • comment -- The comment to include with each dis‐
1113 tribution file.
1114 • config_file -- The path to the configuration
1116 file to use.
1117 • skip_existing -- Specify whether twine should
1119 continue uploading files if one of them already
1120 exists. This primarily supports PyPI. Other
1121 package indexes may not be supported.
1122 • cacert -- The path to the bundle of certificates
1124 used to verify the TLS connection to the package
1125 index.
1126 • client_cert -- The path to the client certifi‐
1128 cate used to perform authentication to the in‐
1129 dex. This must be a single file that contains
1130 both the private key and the PEM-encoded cer‐
1131 tificate.
1132 • repository_name -- The name of the repository
1134 (package index) to interact with. This should
1135 correspond to a section in the config file.
1136 • repository_url -- The URL of the repository
1138 (package index) to interact with. This will
1139 override the settings inferred from reposi‐
1140 tory_name.
1141 • verbose -- Show verbose output.
1143 • disable_progress_bar -- Disable the progress
1145 bar.
1146 property username: str | None
1148 property password: str | None
1150 _allow_noninteractive() -> AbstractContextManager[None]
1152 Bypass NonInteractive error when client cert is present.
1153 property verbose: bool
1155 static register_argparse_arguments(parser: ArgumentParser) ->
1157 None
1158 Register the arguments for argparse.
1159 classmethod from_argparse(args: Namespace) -> Settings
1161 Generate the Settings from parsed arguments.
1162 _handle_package_signing(sign: bool, sign_with: str, identity:
1164 str | None) -> None
1165 _handle_repository_options(repository_name: str, repository_url:
1167 str | None) -> None
1168 _handle_certificates(cacert: str | None, client_cert: str |
1170 None) -> None
1171 check_repository_url() -> None
1173 Verify we are not using legacy PyPI.
1174 Raises twine.exceptions.UploadToDeprecatedPyPIDetected --
1176 The configured repository URL is for legacy PyPI.
1177 create_repository() -> Repository
1179 Create a new repository for uploading.
1180 twine.utils module
1182 twine.utils.get_config(path: str) -> Dict[str, Dict[str, str | None]]
1183 Read repository configuration from a file (i.e. ~/.pypirc).
1184 Format: https://packaging.python.org/specifications/pypirc/
1186 If the default config file doesn't exist, return a default con‐
1188 figuration for pypyi and testpypi.
1189 twine.utils._validate_repository_url(repository_url: str) -> None
1191 Validate the given url for allowed schemes and components.
1192 twine.utils.get_repository_from_config(config_file: str, repository:
1194 str, repository_url: str | None = None) -> Dict[str, str | None]
1195 Get repository config command-line values or the .pypirc file.
1196 twine.utils.normalize_repository_url(url: str) -> str
1198 twine.utils.get_file_size(filename: str) -> str
1200 Return the size of a file in KB, or MB if >= 1024 KB.
1201 twine.utils.check_status_code(response: Response, verbose: bool) ->
1203 None
1204 Generate a helpful message based on the response from the repos‐
1205 itory.
1206 Raise a custom exception for recognized errors. Otherwise, print
1208 the response content (based on the verbose option) before
1209 re-raising the HTTPError.
1210 twine.utils.get_userpass_value(cli_value: str | None, config: Dict[str,
1212 str | None], key: str, prompt_strategy: Callable[[], str] | None =
1213 None) -> str | None
1214 Get a credential (e.g. a username or password) from the configu‐
1215 ration.
1216 Uses the following rules:
1218 1. If cli_value is specified, use that.
1220 2. If config[key] is specified, use that.
1222 3. If prompt_strategy is specified, use its return value.
1224 4. Otherwise return None
1226 Parameters
1228 • cli_value -- The value supplied from the command line.
1230 • config -- A dictionary of repository configuration val‐
1232 ues.
1233 • key -- The credential to look up in config, e.g. "user‐
1235 name" or "password".
1236 • prompt_strategy -- An argumentless function to get the
1238 value, e.g. from keyring or by prompting the user.
1239 Returns
1241 The credential value, i.e. the username or password.
1242 twine.utils.get_cacert(cli_value: str | None, config: Dict[str, str |
1244 None], *, key: str = 'ca_cert', prompt_strategy: Callable[[], str] |
1245 None = None) -> str | None
1246 Get the CA bundle via get_userpass_value().
1247 twine.utils.get_clientcert(cli_value: str | None, config: Dict[str, str
1249 | None], *, key: str = 'client_cert', prompt_strategy: Callable[[],
1250 str] | None = None) -> str | None
1251 Get the client certificate via get_userpass_value().
1252 class twine.utils.EnvironmentDefault
1254 Get values from environment variable.
1255 __init__(env: str, required: bool = True, default: str | None =
1257 None, **kwargs: Any) -> None
1258 class twine.utils.EnvironmentFlag
1260 Set boolean flag from environment variable.
1261 __init__(env: str, **kwargs: Any) -> None
1263 static bool_from_env(val: str | None) -> bool
1265 Allow '0' and 'false' and 'no' to be False.
1266 twine.wheel module
1268 class twine.wheel.Wheel
1269 __init__(filename: str, metadata_version: str | None = None) ->
1271 None
1272 property py_version: str
1274 static find_candidate_metadata_files(names: List[str]) ->
1276 List[List[str]]
1277 Filter files that may be METADATA files.
1278 read() -> bytes
1280 parse(data: bytes) -> None
1282 twine.wininst module
1284 class twine.wininst.WinInst
1285 __init__(filename: str, metadata_version: str | None = None) ->
1287 None
1288 property py_version: str
1290 read() -> bytes
1292 Where Twine gets configuration and credentials
1294 A user can set the repository URL, username, and/or password via com‐
1295 mand line, .pypirc files, environment variables, and keyring.
1296
1298 A checklist for adding a new maintainer to the project.
1299 1. Add them as a Member in the GitHub repo settings.
1301 2. Get them Test PyPI and canon PyPI usernames and add them as a Main‐
1303 tainer on our Test PyPI project and canon PyPI.
1304
1306 A checklist for creating, testing, and distributing a new version.
1307 1. Choose a version number, and create a new branch
1309 VERSION=3.4.2
1311 git switch -c release-$VERSION
1313 2. Update docs/changelog.rst
1315 tox -e changelog -- --version $VERSION
1317 git commit -am "Update changelog for $VERSION"
1319 3. Open a pull request for review
1321 4. Merge the pull request, and ensure the GitHub Actions build passes
1323 5. Create a new git tag for the version
1325 git switch main
1327 git pull --ff-only upstream main
1329 git tag -m "Release v$VERSION" $VERSION
1331 6. Push to start the release, and watch it in GitHub Actions
1333 git push upstream $VERSION
1335 7. View the new release on PyPI
1337
1339 See our open issues.
1340 In the future, pip and twine may merge into a single tool; see ongoing
1342 discussion.
1343 Twine is a utility for publishing Python packages to PyPI and other
1345 repositories. It provides build system independent uploads of source
1346 and binary distribution artifacts for both new and existing projects.
1347
1349 The goal of Twine is to improve PyPI interaction by improving security
1350 and testability.
1351 The biggest reason to use Twine is that it securely authenticates you
1353 to PyPI over HTTPS using a verified connection, regardless of the un‐
1354 derlying Python version. Meanwhile, python setup.py upload will only
1355 work correctly and securely if your build system, Python version, and
1356 underlying operating system are configured properly.
1357 Secondly, Twine encourages you to build your distribution files. python
1359 setup.py upload only allows you to upload a package as a final step af‐
1360 ter building with distutils or setuptools, within the same command in‐
1361 vocation. This means that you cannot test the exact file you're going
1362 to upload to PyPI to ensure that it works before uploading it.
1363 Finally, Twine allows you to pre-sign your files and pass the .asc
1365 files into the command line invocation (twine upload mypro‐
1366 ject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc). This enables you to be
1367 assured that you're typing your gpg passphrase into gpg itself and not
1368 anything else, since you will be the one directly executing gpg --de‐
1369 tach-sign -a <filename>.
1370
1372 • Verified HTTPS connections
1373 • Uploading doesn't require executing setup.py
1375 • Uploading files that have already been created, allowing testing of
1377 distributions before release
1378 • Supports uploading any packaging format (including wheels)
1380
1382 pip install twine
1383
1385 1. Create some distributions in the normal way:
1386 python -m build
1388 2. Upload to Test PyPI and verify things look right:
1390 twine upload -r testpypi dist/*
1392 Twine will prompt for your username and password.
1394 3. Upload to PyPI:
1396 twine upload dist/*
1398 4. Done!
1400 NOTE:
1402 Like many other command line tools, Twine does not show any charac‐
1403 ters when you enter your password.
1404 If you're using Windows and trying to paste your username, password,
1406 or token in the Command Prompt or PowerShell, Ctrl-V and Shift+In‐
1407 sert won't work. Instead, you can use "Edit > Paste" from the window
1408 menu, or enable "Use Ctrl+Shift+C/V as Copy/Paste" in "Properties".
1409 This is a known issue with Python's getpass module.
1410 More documentation on using Twine to upload packages to PyPI is in the
1412 Python Packaging User Guide.
1413
1415 twine upload
1416 Uploads one or more distributions to a repository.
1417 System Message: ERROR/6 (/builddir/build/BUILD/twine-4.0.1/docs/in‐
1419 dex.rst:, line 116)
1420 Command ['twine', 'upload', '-h'] failed: [Errno 2] No such file
1421 or directory: 'twine'
1422 twine check
1424 Checks whether your distribution's long description will render cor‐
1425 rectly on PyPI.
1426 System Message: ERROR/6 (/builddir/build/BUILD/twine-4.0.1/docs/in‐
1428 dex.rst:, line 124)
1429 Command ['twine', 'check', '-h'] failed: [Errno 2] No such file
1430 or directory: 'twine'
1431 twine register
1433 Pre-register a name with a repository before uploading a distribution.
1434 WARNING:
1436 Pre-registration is not supported on PyPI, so the register command
1437 is only necessary if you are using a different repository that re‐
1438 quires it. See issue #1627 on Warehouse (the software running on
1439 PyPI) for more details.
1440 System Message: ERROR/6 (/builddir/build/BUILD/twine-4.0.1/docs/in‐
1442 dex.rst:, line 137)
1443 Command ['twine', 'register', '-h'] failed: [Errno 2] No such
1444 file or directory: 'twine'
1445
1447 Twine can read repository configuration from a .pypirc file, either in
1448 your home directory, or provided with the --config-file option. For de‐
1449 tails on writing and using .pypirc, see the specification in the Python
1450 Packaging User Guide.
1451 Environment Variables
1453 Twine also supports configuration via environment variables. Options
1454 passed on the command line will take precedence over options set via
1455 environment variables. Definition via environment variable is helpful
1456 in environments where it is not convenient to create a .pypirc file
1457 (for example, on a CI/build server).
1458 • TWINE_USERNAME - the username to use for authentication to the repos‐
1460 itory.
1461 • TWINE_PASSWORD - the password to use for authentication to the repos‐
1463 itory.
1464 • TWINE_REPOSITORY - the repository configuration, either defined as a
1466 section in .pypirc or provided as a full URL.
1467 • TWINE_REPOSITORY_URL - the repository URL to use.
1469 • TWINE_CERT - custom CA certificate to use for repositories with
1471 self-signed or untrusted certificates.
1472 • TWINE_NON_INTERACTIVE - Do not interactively prompt for user‐
1474 name/password if the required credentials are missing.
1475 Proxy Support
1477 Twine can be configured to use a proxy by setting environment vari‐
1478 ables. For example, to use a proxy for just the twine command, without
1479 export-ing it for other tools:
1480 HTTPS_PROXY=socks5://user:pass@host:port twine upload dist/*
1482 For more information, see the Requests documentation on proxies and
1484 SOCKS , and an in-depth article about proxy environment variables.
1485
1487 Instead of typing in your password every time you upload a distribu‐
1488 tion, Twine allows storing a username and password securely using
1489 keyring. Keyring is installed with Twine but for some systems (Linux
1490 mainly) may require additional installation steps.
1491 Once Twine is installed, use the keyring program to set a username and
1493 password to use for each repository to which you may upload.
1494 For example, to set a username and password for PyPI:
1496 keyring set https://upload.pypi.org/legacy/ your-username
1498 and enter the password when prompted.
1500 For a different repository, replace the URL with the relevant reposi‐
1502 tory URL. For example, for Test PyPI, use
1503 https://test.pypi.org/legacy/.
1504 The next time you run twine, it will prompt you for a username, and
1506 then get the appropriate password from Keyring.
1507 NOTE:
1509 If you are using Linux in a headless environment (such as on a
1510 server) you'll need to do some additional steps to ensure that
1511 Keyring can store secrets securely. See Using Keyring on headless
1512 systems.
1513 Disabling Keyring
1515 In most cases, simply not setting a password with keyring will allow
1516 Twine to fall back to prompting for a password. In some cases, the
1517 presence of Keyring will cause unexpected or undesirable prompts from
1518 the backing system. In these cases, it may be desirable to disable
1519 Keyring altogether. To disable Keyring, run:
1520 keyring --disable
1522 See Twine issue #338 for discussion and background.
1524
1526 Donald Stufft, Individual contributors
1527
1529 2023, Donald Stufft and individual contributors
15304.0 Jul 21, 2023 TWINE(1)