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: Optional[str] = None, password: Optional[str]
844 = None) -> None
845 class twine.auth.Resolver
847 __init__(config: Dict[str, Optional[str]], input:
849 CredentialInput) -> None
850 classmethod choose(interactive: bool) -> Type[Resolver]
852 property username: Optional[str]
854 property password: Optional[str]
856 property system: Optional[str]
858 get_username_from_keyring() -> Optional[str]
860 get_password_from_keyring() -> Optional[str]
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: Optional[Callable[[...], str]] = 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: Optional[str], metadata: Dis‐
958 tribution, python_version: Optional[str], filetype: Op‐
959 tional[str]) -> None
960 classmethod from_filename(filename: str, comment: Optional[str])
962 -> PackageFile
963 metadata_dictionary() -> Dict[str, Union[str, Sequence[str]]]
965 Merge multiple sources of metadata into a single dictio‐
966 nary.
967 Includes values from filename, PKG-INFO, hashers, and
969 signature.
970 add_gpg_signature(signature_filepath: str, signature_filename:
972 str) -> None
973 sign(sign_with: str, identity: Optional[str]) -> None
975 classmethod run_gpg(gpg_args: Tuple[str, ...]) -> None
977 class twine.package.Hexdigest
979 Hexdigest(md5, sha2, blake2)
980 md5: Optional[str]
982 Alias for field number 0
983 sha2: Optional[str]
985 Alias for field number 1
986 blake2: Optional[str]
988 Alias for field number 2
989 static __new__(_cls, md5: Optional[str], sha2: Optional[str],
991 blake2: Optional[str])
992 Create new instance of Hexdigest(md5, sha2, blake2)
993 _asdict()
995 Return a new dict which maps field names to their values.
996 _field_defaults = {}
998 _fields = ('md5', 'sha2', 'blake2')
1000 classmethod _make(iterable)
1002 Make a new Hexdigest object from a sequence or iterable
1003 _replace(**kwds)
1005 Return a new Hexdigest object replacing specified fields
1006 with new values
1007 class twine.package.HashManager
1009 Manage our hashing objects for simplicity.
1010 This will also allow us to better test this logic.
1012 __init__(filename: str) -> None
1014 Initialize our manager and hasher objects.
1015 _md5_update(content: bytes) -> None
1017 _md5_hexdigest() -> Optional[str]
1019 _sha2_update(content: bytes) -> None
1021 _sha2_hexdigest() -> Optional[str]
1023 _blake_update(content: bytes) -> None
1025 _blake_hexdigest() -> Optional[str]
1027 hash() -> None
1029 Hash the file contents.
1030 hexdigest() -> Hexdigest
1032 Return the hexdigest for the file.
1033 twine.repository module
1035 class twine.repository.Repository
1036 __init__(repository_url: str, username: Optional[str], password:
1038 Optional[str], disable_progress_bar: bool = False) -> None
1039 static _make_adapter_with_retries() -> HTTPAdapter
1041 static _make_user_agent_string() -> str
1043 close() -> None
1045 static _convert_data_to_list_of_tuples(data: Dict[str, Any]) ->
1047 List[Tuple[str, Any]]
1048 set_certificate_authority(cacert: Optional[str]) -> None
1050 set_client_certificate(clientcert: Optional[str]) -> None
1052 register(package: PackageFile) -> Response
1054 _upload(package: PackageFile) -> Response
1056 upload(package: PackageFile, max_redirects: int = 5) -> Response
1058 package_is_uploaded(package: PackageFile, bypass_cache: bool =
1060 False) -> bool
1061 release_urls(packages: List[PackageFile]) -> Set[str]
1063 verify_package_integrity(package: PackageFile) -> None
1065 twine.settings module
1067 Module containing logic for handling settings.
1068 class twine.settings.Settings
1070 Object that manages the configuration for Twine.
1071 This object can only be instantiated with keyword arguments.
1073 For example,
1075 Settings(True, username='fakeusername')
1077 Will raise a TypeError. Instead, you would want
1079 Settings(sign=True, username='fakeusername')
1081 __init__(*, sign: bool = False, sign_with: str = 'gpg', iden‐
1083 tity: Optional[str] = None, username: Optional[str] = None,
1084 password: Optional[str] = None, non_interactive: bool = False,
1085 comment: Optional[str] = None, config_file: str = utils.DE‐
1086 FAULT_CONFIG_FILE, skip_existing: bool = False, cacert: Op‐
1087 tional[str] = None, client_cert: Optional[str] = None, reposi‐
1088 tory_name: str = 'pypi', repository_url: Optional[str] = None,
1089 verbose: bool = False, disable_progress_bar: bool = False, **ig‐
1090 nored_kwargs: Any) -> None
1091 Initialize our settings instance.
1092 Parameters
1094 • sign -- Configure whether the package file
1096 should be signed.
1097 • sign_with -- The name of the executable used to
1099 sign the package with.
1100 • identity -- The GPG identity that should be used
1102 to sign the package file.
1103 • username -- The username used to authenticate to
1105 the repository (package index).
1106 • password -- The password used to authenticate to
1108 the repository (package index).
1109 • non_interactive -- Do not interactively prompt
1111 for username/password if the required creden‐
1112 tials are missing.
1113 • comment -- The comment to include with each dis‐
1115 tribution file.
1116 • config_file -- The path to the configuration
1118 file to use.
1119 • skip_existing -- Specify whether twine should
1121 continue uploading files if one of them already
1122 exists. This primarily supports PyPI. Other
1123 package indexes may not be supported.
1124 • cacert -- The path to the bundle of certificates
1126 used to verify the TLS connection to the package
1127 index.
1128 • client_cert -- The path to the client certifi‐
1130 cate used to perform authentication to the in‐
1131 dex. This must be a single file that contains
1132 both the private key and the PEM-encoded cer‐
1133 tificate.
1134 • repository_name -- The name of the repository
1136 (package index) to interact with. This should
1137 correspond to a section in the config file.
1138 • repository_url -- The URL of the repository
1140 (package index) to interact with. This will
1141 override the settings inferred from reposi‐
1142 tory_name.
1143 • verbose -- Show verbose output.
1145 • disable_progress_bar -- Disable the progress
1147 bar.
1148 property username: Optional[str]
1150 property password: Optional[str]
1152 _allow_noninteractive() -> AbstractContextManager[None]
1154 Bypass NonInteractive error when client cert is present.
1155 property verbose: bool
1157 static register_argparse_arguments(parser: ArgumentParser) ->
1159 None
1160 Register the arguments for argparse.
1161 classmethod from_argparse(args: Namespace) -> Settings
1163 Generate the Settings from parsed arguments.
1164 _handle_package_signing(sign: bool, sign_with: str, identity:
1166 Optional[str]) -> None
1167 _handle_repository_options(repository_name: str, repository_url:
1169 Optional[str]) -> None
1170 _handle_certificates(cacert: Optional[str], client_cert: Op‐
1172 tional[str]) -> None
1173 check_repository_url() -> None
1175 Verify we are not using legacy PyPI.
1176 Raises twine.exceptions.UploadToDeprecatedPyPIDetected --
1178 The configured repository URL is for legacy PyPI.
1179 create_repository() -> Repository
1181 Create a new repository for uploading.
1182 twine.utils module
1184 twine.utils.get_config(path: str) -> Dict[str, Dict[str, Op‐
1185 tional[str]]]
1186 Read repository configuration from a file (i.e. ~/.pypirc).
1187 Format: https://packaging.python.org/specifications/pypirc/
1189 If the default config file doesn't exist, return a default con‐
1191 figuration for pypyi and testpypi.
1192 twine.utils._validate_repository_url(repository_url: str) -> None
1194 Validate the given url for allowed schemes and components.
1195 twine.utils.get_repository_from_config(config_file: str, repository:
1197 str, repository_url: Optional[str] = None) -> Dict[str, Optional[str]]
1198 Get repository config command-line values or the .pypirc file.
1199 twine.utils.normalize_repository_url(url: str) -> str
1201 twine.utils.get_file_size(filename: str) -> str
1203 Return the size of a file in KB, or MB if >= 1024 KB.
1204 twine.utils.check_status_code(response: Response, verbose: bool) ->
1206 None
1207 Generate a helpful message based on the response from the repos‐
1208 itory.
1209 Raise a custom exception for recognized errors. Otherwise, print
1211 the response content (based on the verbose option) before
1212 re-raising the HTTPError.
1213 twine.utils.get_userpass_value(cli_value: Optional[str], config:
1215 Dict[str, Optional[str]], key: str, prompt_strategy: Op‐
1216 tional[Callable[[], str]] = None) -> Optional[str]
1217 Get a credential (e.g. a username or password) from the configu‐
1218 ration.
1219 Uses the following rules:
1221 1. If cli_value is specified, use that.
1223 2. If config[key] is specified, use that.
1225 3. If prompt_strategy is specified, use its return value.
1227 4. Otherwise return None
1229 Parameters
1231 • cli_value -- The value supplied from the command line.
1233 • config -- A dictionary of repository configuration val‐
1235 ues.
1236 • key -- The credential to look up in config, e.g. "user‐
1238 name" or "password".
1239 • prompt_strategy -- An argumentless function to get the
1241 value, e.g. from keyring or by prompting the user.
1242 Returns
1244 The credential value, i.e. the username or password.
1245 twine.utils.get_cacert(cli_value: Optional[str], config: Dict[str, Op‐
1247 tional[str]], *, key: str = 'ca_cert', prompt_strategy: Op‐
1248 tional[Callable[[], str]] = None) -> Optional[str]
1249 Get the CA bundle via get_userpass_value().
1250 twine.utils.get_clientcert(cli_value: Optional[str], config: Dict[str,
1252 Optional[str]], *, key: str = 'client_cert', prompt_strategy: Op‐
1253 tional[Callable[[], str]] = None) -> Optional[str]
1254 Get the client certificate via get_userpass_value().
1255 class twine.utils.EnvironmentDefault
1257 Get values from environment variable.
1258 __init__(env: str, required: bool = True, default: Optional[str]
1260 = None, **kwargs: Any) -> None
1261 class twine.utils.EnvironmentFlag
1263 Set boolean flag from environment variable.
1264 __init__(env: str, **kwargs: Any) -> None
1266 static bool_from_env(val: Optional[str]) -> bool
1268 Allow '0' and 'false' and 'no' to be False.
1269 twine.wheel module
1271 class twine.wheel.Wheel
1272 __init__(filename: str, metadata_version: Optional[str] = None)
1274 -> None
1275 property py_version: str
1277 static find_candidate_metadata_files(names: List[str]) ->
1279 List[List[str]]
1280 Filter files that may be METADATA files.
1281 read() -> bytes
1283 parse(data: bytes) -> None
1285 twine.wininst module
1287 class twine.wininst.WinInst
1288 __init__(filename: str, metadata_version: Optional[str] = None)
1290 -> None
1291 property py_version: str
1293 read() -> bytes
1295 Where Twine gets configuration and credentials
1297 A user can set the repository URL, username, and/or password via com‐
1298 mand line, .pypirc files, environment variables, and keyring.
1299
1301 A checklist for adding a new maintainer to the project.
1302 1. Add them as a Member in the GitHub repo settings.
1304 2. Get them Test PyPI and canon PyPI usernames and add them as a Main‐
1306 tainer on our Test PyPI project and canon PyPI.
1307
1309 A checklist for creating, testing, and distributing a new version.
1310 1. Choose a version number, and create a new branch
1312 VERSION=3.4.2
1314 git switch -c release-$VERSION
1316 2. Update docs/changelog.rst
1318 tox -e changelog -- --version $VERSION
1320 git commit -am "Update changelog for $VERSION"
1322 3. Open a pull request for review
1324 4. Merge the pull request, and ensure the GitHub Actions build passes
1326 5. Create a new git tag for the version
1328 git switch main
1330 git pull --ff-only upstream main
1332 git tag -m "Release v$VERSION" $VERSION
1334 6. Push to start the release, and watch it in GitHub Actions
1336 git push upstream $VERSION
1338 7. View the new release on PyPI
1340
1342 See our open issues.
1343 In the future, pip and twine may merge into a single tool; see ongoing
1345 discussion.
1346 Twine is a utility for publishing Python packages to PyPI and other
1348 repositories. It provides build system independent uploads of source
1349 and binary distribution artifacts for both new and existing projects.
1350
1352 The goal of Twine is to improve PyPI interaction by improving security
1353 and testability.
1354 The biggest reason to use Twine is that it securely authenticates you
1356 to PyPI over HTTPS using a verified connection, regardless of the un‐
1357 derlying Python version. Meanwhile, python setup.py upload will only
1358 work correctly and securely if your build system, Python version, and
1359 underlying operating system are configured properly.
1360 Secondly, Twine encourages you to build your distribution files. python
1362 setup.py upload only allows you to upload a package as a final step af‐
1363 ter building with distutils or setuptools, within the same command in‐
1364 vocation. This means that you cannot test the exact file you're going
1365 to upload to PyPI to ensure that it works before uploading it.
1366 Finally, Twine allows you to pre-sign your files and pass the .asc
1368 files into the command line invocation (twine upload mypro‐
1369 ject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc). This enables you to be
1370 assured that you're typing your gpg passphrase into gpg itself and not
1371 anything else, since you will be the one directly executing gpg --de‐
1372 tach-sign -a <filename>.
1373
1375 • Verified HTTPS connections
1376 • Uploading doesn't require executing setup.py
1378 • Uploading files that have already been created, allowing testing of
1380 distributions before release
1381 • Supports uploading any packaging format (including wheels)
1383
1385 pip install twine
1386
1388 1. Create some distributions in the normal way:
1389 python -m build
1391 2. Upload to Test PyPI and verify things look right:
1393 twine upload -r testpypi dist/*
1395 Twine will prompt for your username and password.
1397 3. Upload to PyPI:
1399 twine upload dist/*
1401 4. Done!
1403 NOTE:
1405 Like many other command line tools, Twine does not show any charac‐
1406 ters when you enter your password.
1407 If you're using Windows and trying to paste your username, password,
1409 or token in the Command Prompt or PowerShell, Ctrl-V and Shift+In‐
1410 sert won't work. Instead, you can use "Edit > Paste" from the window
1411 menu, or enable "Use Ctrl+Shift+C/V as Copy/Paste" in "Properties".
1412 This is a known issue with Python's getpass module.
1413 More documentation on using Twine to upload packages to PyPI is in the
1415 Python Packaging User Guide.
1416
1418 twine upload
1419 Uploads one or more distributions to a repository.
1420 System Message: ERROR/6 (/builddir/build/BUILD/twine-4.0.1/docs/in‐
1422 dex.rst:, line 116)
1423 Command ['twine', 'upload', '-h'] failed: [Errno 2] No such file
1424 or directory: 'twine'
1425 twine check
1427 Checks whether your distribution's long description will render cor‐
1428 rectly on PyPI.
1429 System Message: ERROR/6 (/builddir/build/BUILD/twine-4.0.1/docs/in‐
1431 dex.rst:, line 124)
1432 Command ['twine', 'check', '-h'] failed: [Errno 2] No such file
1433 or directory: 'twine'
1434 twine register
1436 Pre-register a name with a repository before uploading a distribution.
1437 WARNING:
1439 Pre-registration is not supported on PyPI, so the register command
1440 is only necessary if you are using a different repository that re‐
1441 quires it. See issue #1627 on Warehouse (the software running on
1442 PyPI) for more details.
1443 System Message: ERROR/6 (/builddir/build/BUILD/twine-4.0.1/docs/in‐
1445 dex.rst:, line 137)
1446 Command ['twine', 'register', '-h'] failed: [Errno 2] No such
1447 file or directory: 'twine'
1448
1450 Twine can read repository configuration from a .pypirc file, either in
1451 your home directory, or provided with the --config-file option. For de‐
1452 tails on writing and using .pypirc, see the specification in the Python
1453 Packaging User Guide.
1454 Environment Variables
1456 Twine also supports configuration via environment variables. Options
1457 passed on the command line will take precedence over options set via
1458 environment variables. Definition via environment variable is helpful
1459 in environments where it is not convenient to create a .pypirc file
1460 (for example, on a CI/build server).
1461 • TWINE_USERNAME - the username to use for authentication to the repos‐
1463 itory.
1464 • TWINE_PASSWORD - the password to use for authentication to the repos‐
1466 itory.
1467 • TWINE_REPOSITORY - the repository configuration, either defined as a
1469 section in .pypirc or provided as a full URL.
1470 • TWINE_REPOSITORY_URL - the repository URL to use.
1472 • TWINE_CERT - custom CA certificate to use for repositories with
1474 self-signed or untrusted certificates.
1475 • TWINE_NON_INTERACTIVE - Do not interactively prompt for user‐
1477 name/password if the required credentials are missing.
1478 Proxy Support
1480 Twine can be configured to use a proxy by setting environment vari‐
1481 ables. For example, to use a proxy for just the twine command, without
1482 export-ing it for other tools:
1483 HTTPS_PROXY=socks5://user:pass@host:port twine upload dist/*
1485 For more information, see the Requests documentation on proxies and
1487 SOCKS , and an in-depth article about proxy environment variables.
1488
1490 Instead of typing in your password every time you upload a distribu‐
1491 tion, Twine allows storing a username and password securely using
1492 keyring. Keyring is installed with Twine but for some systems (Linux
1493 mainly) may require additional installation steps.
1494 Once Twine is installed, use the keyring program to set a username and
1496 password to use for each repository to which you may upload.
1497 For example, to set a username and password for PyPI:
1499 keyring set https://upload.pypi.org/legacy/ your-username
1501 and enter the password when prompted.
1503 For a different repository, replace the URL with the relevant reposi‐
1505 tory URL. For example, for Test PyPI, use
1506 https://test.pypi.org/legacy/.
1507 The next time you run twine, it will prompt you for a username, and
1509 then get the appropriate password from Keyring.
1510 NOTE:
1512 If you are using Linux in a headless environment (such as on a
1513 server) you'll need to do some additional steps to ensure that
1514 Keyring can store secrets securely. See Using Keyring on headless
1515 systems.
1516 Disabling Keyring
1518 In most cases, simply not setting a password with keyring will allow
1519 Twine to fall back to prompting for a password. In some cases, the
1520 presence of Keyring will cause unexpected or undesirable prompts from
1521 the backing system. In these cases, it may be desirable to disable
1522 Keyring altogether. To disable Keyring, run:
1523 keyring --disable
1525 See Twine issue #338 for discussion and background.
1527
1529 Donald Stufft, Individual contributors
1530
1532 2022, Donald Stufft and individual contributors
15334.0 Jul 22, 2022 TWINE(1)