1TWINE(1) twine TWINE(1)
2
6 twine - twine Documentation
7 This project follows the semantic versioning and pre-release versioning
9 schemes recommended by the Python Packaging Authority.
10
12 Features
13 • Add --verbose logging for querying keyring credentials. (#849)
14 • Log all upload responses with --verbose. (#859)
16 • Show more helpful error message for invalid metadata. (#861)
18 Bugfixes
20 • Require a recent version of urllib3. (#858)
21
23 Improved Documentation
24 • Fix broken link to packaging tutorial. (#844)
25
27 Features
28 • Add support for core metadata version 2.2, defined in PEP 643. (#833)
29
31 Features
32 • Add support for Python 3.10. (#827)
33
35 Features
36 • Show more helpful messages for invalid passwords. (#815)
37 • Allow the --skip-existing option to work with GCP Artifact Registry.
39 (#823)
40 Bugfixes
42 • Add a helpful error message when an upload fails due to missing a
43 trailing slash in the URL. (#812)
44 • Generalize --verbose suggestion when an upload fails. (#817)
46
48 Bugfixes
49 • Improve error message for unsupported metadata. (#755)
50 • Improve error message for a missing config file. (#770)
52 • Do not include md5_digest or blake2_256_digest if FIPS mode is en‐
54 abled on the host. This removes those fields from the metadata before
55 sending the metadata to the repository. (#776)
56
58 Bugfixes
59 • Fix a regression that was causing some namespace packages with dots
60 in them fail to upload to PyPI. (#745)
61
63 Features
64 • Prefer importlib.metadata for entry point handling. (#728)
65 • Rely on importlib_metadata 3.6 for nicer entry point processing. (‐
67 #732)
68 • Eliminate dependency on setuptools/pkg_resources and replace with
70 packaging and importlib_metadata. (#736)
71
73 Features
74 • Print files to be uploaded using upload --verbose (#670)
75 • Print configuration file location when using upload --verbose (#675)
77 • Print source and values of credentials when using upload --verbose (‐
79 #685)
80 • Add support for Python 3.9 (#708)
82 • Turn warnings into errors when using check --strict (#715)
84 Bugfixes
86 • Make password optional when using upload --client-cert (#678)
87 • Support more Nexus versions with upload --skip-existing (#693)
89 • Support Gitlab Enterprise with upload --skip-existing (#698)
91 • Show a better error message for malformed files (#714)
93 Improved Documentation
95 • Adopt PSF code of conduct (#680)
96 • Adopt towncrier for the changleog (#718)
98
100 Features
101 • Improve display of HTTP errors during upload (#666)
102 • Print packages and signatures to be uploaded when using --verbose op‐
104 tion (#652)
105 • Use red text when printing errors on the command line (#649)
107 • Require repository URL scheme to be http or https (#602)
109 • Add type annotations, checked with mypy, with PEP 561 support for
111 users of Twine's API (#231)
112 Bugfixes
114 • Update URL to .pypirc specification (#655)
115 • Don't raise an exception when Python version can't be parsed from
117 filename (#612)
118 • Fix inaccurate retry message during upload (#611)
120 • Clarify error messages for archive format (#601)
122
124 Bugfixes
125 • Restore --non-interactive as a flag not expecting an argument. (#548)
126
128 Features
129 • Add support for specifying --non-interactive as an environment vari‐
130 able. (#547)
131
133 Features
134 • When a client certificate is indicated, all password processing is
135 disabled. (#336)
136 • Add --non-interactive flag to abort upload rather than interactively
138 prompt if credentials are missing. (#489)
139 • Twine now unconditionally requires the keyring library and no longer
141 supports uninstalling keyring as a means to disable that functional‐
142 ity. Instead, use keyring --disable keyring functionality if neces‐
143 sary. (#524)
144 • Add Python 3.8 to classifiers. (#518)
146 Bugfixes
148 • More robust handling of server response in --skip-existing (#332)
149
151 Features
152 • Twine now requires Python 3.6 or later. Use pip 9 or pin to "twine<2"
153 to install twine on older Python versions. (#437)
154 Bugfixes
156 • Require requests 2.20 or later to avoid reported security vulnerabil‐
157 ities in earlier releases. (#491)
158
160 Features
161 • Improved output on check command: Prints a message when there are no
162 distributions given to check. Improved handling of errors in a dis‐
163 tribution's markup, avoiding messages flowing through to the next
164 distribution's errors. (#488)
165
167 Features
168 • Show Warehouse URL after uploading a package (#459)
169 • Better error handling and gpg2 fallback if gpg not available. (#456)
171 • Now provide a more meaningful error on redirect during upload. (#310)
173 Bugfixes
175 • Fail more gracefully when encountering bad metadata (#341)
176
178 Features
179 • Add disable_progress_bar option to disable tqdm. (#427)
180 • Allow defining an empty username and password in .pypirc. (#426)
182 • Support keyring.get_credential. (#419)
184 • Support keyring.get_username_and_password. (#418)
186 • Add Python 3.7 to classifiers. (#416)
188 Bugfixes
190 • Restore prompts while retaining support for suppressing prompts. (‐
191 #452)
192 • Avoid requests-toolbelt to 0.9.0 to prevent attempting to use openssl
194 when it isn't available. (#447)
195 • Use io.StringIO instead of StringIO. (#444)
197 • Only install pyblake2 if needed. (#441)
199 • Use modern Python language features. (#436)
201 • Specify python_requires in setup.py (#435)
203 • Use https URLs everywhere. (#432)
205 • Fix --skip-existing for Nexus Repos. (#428)
207 • Remove unnecessary usage of readme_render.markdown. (#421)
209 • Don't crash if there's no package description. (#412)
211 • Fix keyring support. (#408)
213 Misc
215 • Refactor tox env and travis config. (#439)
216
218 Bugfixes
219 • Fix regression with upload exit code (#404)
220
222 Features
223 • Add twine check command to check long description (#395)
224 • Drop support for Python 3.3 (#392)
226 • Empower --skip-existing for Artifactory repositories (#363)
228 Bugfixes
230 • Avoid MD5 when Python is compiled in FIPS mode (#367)
231
233 Features
234 • Remove PyPI as default register package index. (#320)
235 • Support Metadata 2.1 (PEP 566), including Markdown for description
237 fields. (#319)
238 Bugfixes
240 • Raise exception if attempting upload to deprecated legacy PyPI URLs.
241 (#322)
242 • Avoid uploading to PyPI when given alternate repository URL, and re‐
244 quire http:// or https:// in repository_url. (#269)
245 Misc
247 • Update PyPI URLs. (#318)
248 • Add new maintainer, release checklists. (#314)
250 • Add instructions on how to use keyring. (#277)
252
254 Features
255 • Link to changelog from README (#46)
256 • Reorganize & improve user & developer documentation. (#304)
258 • Revise docs predicting future of twine (#303)
260 • Add architecture overview to docs (#296)
262 • Add doc building instructions (#295)
264 • Declare support for Python 3.6 (#257)
266 • Improve progressbar (#256)
268 Bugfixes
270 • Degrade gracefully when keyring is unavailable (#315)
271 • Fix changelog formatting (#299)
273 • Fix syntax highlighting in README (#298)
275 • Fix Read the Docs, tox, Travis configuration (#297)
277 • Fix Travis CI and test configuration (#286)
279 • Print progress to stdout, not stderr (#268)
281 • Fix --repository[-url] help text (#265)
283 • Remove obsolete registration guidance (#200)
285
287 Bugfixes
288 • Blacklist known bad versions of Requests. (#253)
289
291 Bugfixes
292 • Twine sends less information about the user's system in the
293 User-Agent string. (#229)
294 • Fix --skip-existing when used to upload a package for the first time.
296 (#220)
297 • Fix precedence of --repository-url over --repository. (#206)
299 Misc
301 • Twine will now resolve passwords using the keyring if available. Mod‐
302 ule can be required with the keyring extra.
303 • Twine will use hashlib.blake2b on Python 3.6+ instead of pyblake2
305
307 Misc
308 • Check if a package exists if the URL is one of:
309 • https://pypi.python.org/pypi/
311 • https://upload.pypi.org/
313 • https://upload.pypi.io/
315 This helps people with https://upload.pypi.io still in their
317 .pypirc file.
318
320 Features
321 • Switch from upload.pypi.io to upload.pypi.org. (#201)
322 • Retrieve configuration from the environment as a default. (#144)
324 • Repository URL will default to TWINE_REPOSITORY
326 • Username will default to TWINE_USERNAME
328 • Password will default to TWINE_PASSWORD
330 • Allow the Repository URL to be provided on the command-line (--repos‐
332 itory-url) or via an environment variable (TWINE_REPOSITORY_URL). (‐
333 #166)
334 • Generate Blake2b 256 digests for packages if pyblake2 is installed.
336 Users can use python -m pip install twine[with-blake2] to have py‐
337 blake2 installed with Twine. (#171)
338 Misc
340 • Generate SHA256 digest for all packages by default.
341 • Stop testing on Python 2.6.
343 • Warn users if they receive a 500 error when uploading to
345 *pypi.python.org (#199)
346
348 Bugfixes
349 • Correct a packaging error.
350
352 Bugfixes
353 • Fix uploads to instances of pypiserver using --skip-existing. We were
354 not properly checking the return status code on the response after
355 attempting an upload. (#195)
356 Misc
358 • Avoid attempts to upload a package if we can find it on Legacy PyPI.
359
361 Bugfixes
362 • Fix issue where we were checking the existence of packages even if
363 the user didn't specify --skip-existing. (#189) (#191)
364
366 Bugfixes
367 • Clint was not specified in the wheel metadata as a dependency. (#187)
368
370 Features
371 • Support --cert and --client-cert command-line flags and config file
372 options for feature parity with pip. This allows users to verify con‐
373 nections to servers other than PyPI (e.g., local package reposito‐
374 ries) with different certificates. (#142)
375 • Add progress bar to uploads. (#152)
377 • Allow --skip-existing to work for 409 status codes. (#162)
379 • Implement retries when the CDN in front of PyPI gives us a 5xx error.
381 (#167)
382 • Switch Twine to upload to pypi.io instead of pypi.python.org. (#177)
384 Bugfixes
386 • Allow passwords to have %s in them. (#186)
387
389 Bugfixes
390 • Bump requests-toolbelt version to ensure we avoid ConnectionErrors (‐
391 #155)
392
394 Bugfixes
395 • Paths with hyphens in them break the Wheel regular expression. (#145)
396 • Exception while accessing the repository key (sic) when raising a re‐
398 direct exception. (#146)
399
401 Bugfixes
402 • Fix uploading signatures causing a 500 error after large file support
403 was added. (#137, #140)
404
406 Bugfixes
407 • Upload signatures with packages appropriately (#132)
408 As part of the refactor for the 1.6.0 release, we were using the
409 wrong name to find the signature file.
410 This also uncovered a bug where if you're using twine in a situa‐
412 tion where * is not expanded by your shell, we might also miss up‐
413 loading signatures to PyPI. Both were fixed as part of this.
414
416 Bugfixes
417 • Fix signing support for uploads (#130)
418
420 Features
421 • Allow the user to specify the location of their .pypirc (#97)
422 • Support registering new packages with twine register (#8)
424 • Add the --skip-existing flag to twine upload to allow users to skip
426 releases that already exist on PyPI. (#115)
427 • Upload wheels first to PyPI (#106)
429 • Large file support via the requests-toolbelt (#104)
431 Bugfixes
433 • Raise an exception on redirects (#92)
434 • Work around problems with Windows when using getpass.getpass (#116)
436 • Warnings triggered by pkginfo searching for PKG-INFO files should no
438 longer be user visible. (#114)
439 • Provide more helpful messages if .pypirc is out of date. (#111)
441
443 Features
444 • Support commands not named "gpg" for signing (#29)
445 Bugfixes
447 • Display information about the version of setuptools installed (#85)
448 • Support deprecated pypirc file format (#61)
450 Misc
452 • Add lower-limit to requests dependency
453
455 Features
456 • Switch to a git style dispatching for the commands to enable simpler
457 commands and programmatic invocation. (#6)
458 • Parse ~/.pypirc ourselves and use subprocess instead of the distu‐
460 tils.spawn module. (#13)
461 Bugfixes
463 • Expand globs and check for existence of dists to upload (#65)
464 • Fix issue uploading packages with _s in the name (#47)
466 • List registered commands in help text (#34)
468 • Use pkg_resources to load registered commands (#32)
470 • Prevent ResourceWarning from being shown (#28)
472 • Add support for uploading Windows installers (#26)
474
476 Features
477 • Additional functionality.
478
480 Features
481 • Basic functionality.
482 We are happy you have decided to contribute to Twine.
484 Please see the GitHub repository for code and more documentation, and
486 the official Python Packaging User Guide for user documentation. To
487 ask questions or get involved, you can join the Python Packaging Dis‐
488 course forum, #pypa or #pypa-dev on IRC, or the distutils-sig mailing
489 list.
490 Everyone interacting in the Twine project's codebases, issue trackers,
492 chat rooms, and mailing lists is expected to follow the PSF Code of
493 Conduct.
494
496 We use tox to run tests, check code style, and build the documentation.
497 To install tox, run:
498 python3 -m pip install tox
500 Clone the twine repository from GitHub, then run:
502 cd /path/to/your/local/twine
504 tox -e dev
505 This creates a virtual environment, so that twine and its dependencies
507 do not interfere with other packages installed on your machine. In the
508 virtual environment, twine is pointing at your local copy, so when you
509 make changes, you can easily see their effect.
510 The virtual environment also contains the tools for running tests and
512 checking code style, so you can run them on single files directly or in
513 your code editor. However, we still encourage using the tox commands
514 below on the whole codebase.
515 To use the virtual environment, run:
517 source venv/bin/activate
519 Building the documentation
521 Additions and edits to twine's documentation are welcome and appreci‐
522 ated.
523 To preview the docs while you're making changes, run:
525 tox -e watch-docs
527 Then open a web browser to http://127.0.0.1:8000.
529 When you're done making changes, lint and build the docs locally before
531 making a pull request. In your active virtual environment, run:
532 tox -e docs
534 The HTML of the docs will be written to docs/_build/html.
536 Code style
538 To automatically reformat your changes with isort and black, run:
539 tox -e format
541 To detect any remaining code smells with flake8, run:
543 tox -e lint
545 To perform strict type-checking using mypy, run:
547 tox -e types
549 Any errors from lint or types need to be fixed manually.
551 Additionally, we prefer that import statements be used for packages and
553 modules only, rather than individual classes or functions.
554 Testing
556 We use pytest for writing and running tests.
557 To run the tests in your virtual environment, run:
559 tox -e py
561 To pass options to pytest, e.g. the name of a test, run:
563 tox -e py -- tests/test_upload.py::test_exception_for_http_status
565 Twine is continuously tested against supported versions of Python using
567 GitHub Actions. To run the tests against a specific version, e.g.
568 Python 3.8, you will need it installed on your machine. Then, run:
569 tox -e py38
571 To run the "integration" tests of uploading to real package indexes,
573 run:
574 tox -e integration
576 To run the tests against all supported Python versions, check code
578 style, and build the documentation, run:
579 tox
581
583 1. Fork the GitHub repository.
584 2. Make a branch off of main and commit your changes to it.
586 3. Run the tests, check code style, and build the docs as described
588 above.
589 4. Optionally, add your name to the end of the AUTHORS file using the
591 format Name <email@domain.com> (url), where the (url) portion is op‐
592 tional.
593 5. Submit a pull request to the main branch on GitHub, referencing an
595 open issue.
596 6. Add a changelog entry.
598 Changelog entries
600 The docs/changelog.rst file is built by towncrier from files in the
601 changelog/ directory. To add an entry, create a file in that directory
602 named {number}.{type}.rst, where {number} is the pull request number,
603 and {type} is feature, bugfix, doc, removal, or misc.
604 For example, if your PR number is 1234 and it's fixing a bug, then you
606 would create changelog/1234.bugfix.rst. PRs can span multiple cate‐
607 gories by creating multiple files: if you added a feature and depre‐
608 cated/removed an old feature in PR #5678, you would create
609 changelog/5678.feature.rst and changelog/5678.removal.rst.
610 A changelog entry is meant for end users and should only contain de‐
612 tails relevant to them. In order to maintain a consistent style, please
613 keep the entry to the point, in sentence case, shorter than 80 charac‐
614 ters, and in an imperative tone. An entry should complete the sentence
615 "This change will ...". If one line is not enough, use a summary line
616 in an imperative tone, followed by a description of the change in one
617 or more paragraphs, each wrapped at 80 characters and separated by
618 blank lines.
619 You don't need to reference the pull request or issue number in a
621 changelog entry, since towncrier will add a link using the number in
622 the file name, and the pull request should reference an issue number.
623 Similarly, you don't need to add your name to the entry, since that
624 will be associated with the pull request.
625 Changelog entries are rendered using reStructuredText, but they should
627 only have minimal formatting (such as ``monospaced text``).
628
630 Twine is a command-line tool for interacting with PyPI securely over
631 HTTPS. Its three purposes are to be:
632 1. A user-facing tool for publishing on pypi.org
634 2. A user-facing tool for publishing on other Python package indexes
636 (e.g., devpi instances)
637 3. A useful API for other programs (e.g., zest.releaser) to call for
639 publishing on any Python package index
640 Currently, twine has two principle functions: uploading new packages
642 and registering new projects (register is no longer supported on PyPI,
643 and is in Twine for use with other package indexes).
644 Its command line arguments are parsed in twine/cli.py. The code for
646 registering new projects is in twine/commands/register.py, and the code
647 for uploading is in twine/commands/upload.py. The file twine/package.py
648 contains a single class, PackageFile, which hashes the project files
649 and extracts their metadata. The file twine/repository.py contains the
650 Repository class, whose methods control the URL the package is uploaded
651 to (which the user can specify either as a default, in the .pypirc
652 file, or pass on the command line), and the methods that upload the
653 package securely to a URL.
654 For more details, refer to the source documentation (currently a work
656 in progress):
657 twine package
659 Top-level module for Twine.
660 The contents of this package are not a public API. For more details,
662 see https://github.com/pypa/twine/issues/194 and
663 https://github.com/pypa/twine/issues/665.
664 twine.commands package
666 Module containing the logic for the twine sub-commands.
667 The contents of this package are not a public API. For more details,
669 see https://github.com/pypa/twine/issues/194 and
670 https://github.com/pypa/twine/issues/665.
671 twine.commands.check module
673 Module containing the logic for twine check.
674 class twine.commands.check._WarningStream
676 __init__() -> None
678 write(text: str) -> None
680 twine.commands.check._check_file(filename: str, render_warning_stream:
682 twine.commands.check._WarningStream) -> Tuple[List[str], bool]
683 Check given distribution.
684 twine.commands.check.check(dists: List[str], output_stream: IO[str] =
686 sys.stdout, strict: bool = False) -> bool
687 Check that a distribution will render correctly on PyPI and dis‐
688 play the results.
689 This is currently only validates long_description, but more
691 checks could be added; see
692 https://github.com/pypa/twine/projects/2.
693 Parameters
695 • dists -- The distribution files to check.
697 • output_stream -- The destination of the resulting out‐
699 put.
700 • strict -- If True, treat warnings as errors.
702 Returns
704 True if there are rendering errors, otherwise False.
705 twine.commands.check.main(args: List[str]) -> bool
707 Execute the check command.
708 Parameters
710 args -- The command-line arguments.
711 Returns
713 The exit status of the check command.
714 twine.commands.register module
716 Module containing the logic for twine register.
717 twine.commands.register.register(register_settings: twine.settings.Set‐
719 tings, package: str) -> None
720 Pre-register a package name with a repository before uploading a
721 distribution.
722 Pre-registration is not supported on PyPI, so the register com‐
724 mand is only necessary if you are using a different repository
725 that requires it.
726 Parameters
728 • register_settings -- The configured options relating to
730 repository registration.
731 • package -- The path of the distribution to use for
733 package metadata.
734 Raises
736 • twine.exceptions.TwineException -- The registration
738 failed due to a configuration error.
739 • requests.HTTPError -- The repository responded with an
741 error.
742 twine.commands.register.main(args: List[str]) -> None
744 Execute the register command.
745 Parameters
747 args -- The command-line arguments.
748 twine.commands.upload module
750 Module containing the logic for twine upload.
751 twine.commands.upload.skip_upload(response: requests.models.Response,
753 skip_existing: bool, package: twine.package.PackageFile) -> bool
754 Determine if a failed upload is an error or can be safely ig‐
755 nored.
756 Parameters
758 • response -- The response from attempting to upload
760 package to a repository.
761 • skip_existing -- If True, use the status and content of
763 response to determine if the package already exists on
764 the repository. If so, then a failed upload is safe to
765 ignore.
766 • package -- The package that was being uploaded.
768 Returns
770 True if a failed upload can be safely ignored, otherwise
771 False.
772 twine.commands.upload._make_package(filename: str, signatures:
774 Dict[str, str], upload_settings: twine.settings.Settings) ->
775 twine.package.PackageFile
776 Create and sign a package, based off of filename, signatures and
777 settings.
778 twine.commands.upload.upload(upload_settings: twine.settings.Settings,
780 dists: List[str]) -> None
781 Upload one or more distributions to a repository, and display
782 the progress.
783 If a package already exists on the repository, most repositories
785 will return an error response. However, if upload_set‐
786 tings.skip_existing is True, a message will be displayed and any
787 remaining distributions will be uploaded.
788 For known repositories (like PyPI), the web URLs of successfully
790 uploaded packages will be displayed.
791 Parameters
793 • upload_settings -- The configured options related to
795 uploading to a repository.
796 • dists -- The distribution files to upload to the repos‐
798 itory. This can also include .asc files; the GPG signa‐
799 tures will be added to the corresponding uploads.
800 Raises
802 • twine.exceptions.TwineException -- The upload failed
804 due to a configuration error.
805 • requests.HTTPError -- The repository responded with an
807 error.
808 twine.commands.upload.main(args: List[str]) -> None
810 Execute the upload command.
811 Parameters
813 args -- The command-line arguments.
814 twine.auth module
816 class twine.auth.CredentialInput
817 __init__(username: Optional[str] = None, password: Optional[str]
819 = None) -> None
820 class twine.auth.Resolver
822 __init__(config: Dict[str, Optional[str]], input:
824 twine.auth.CredentialInput) -> None
825 classmethod choose(interactive: bool) -> Type[twine.auth.Re‐
827 solver]
828 property username: Optional[str]
830 property password: Optional[str]
832 property system: Optional[str]
834 get_username_from_keyring() -> Optional[str]
836 get_password_from_keyring() -> Optional[str]
838 username_from_keyring_or_prompt() -> str
840 password_from_keyring_or_prompt() -> str
842 prompt(what: str, how: Callable[[...], str]) -> str
844 class twine.auth.Private
846 prompt(what: str, how: Optional[Callable[[...], str]] = None) ->
848 str
849 twine.cli module
851 twine.cli.list_dependencies_and_versions() -> List[Tuple[str, str]]
852 twine.cli.dep_versions() -> str
854 twine.cli.dispatch(argv: List[str]) -> Any
856 twine.exceptions module
858 Module containing exceptions raised by twine.
859 exception twine.exceptions.TwineException
861 Base class for all exceptions raised by twine.
862 exception twine.exceptions.RedirectDetected
864 A redirect was detected that the user needs to resolve.
865 In some cases, requests refuses to issue a new POST request af‐
867 ter a redirect. In order to prevent a confusing user experience,
868 we raise this exception to allow users to know the index they're
869 uploading to is redirecting them.
870 classmethod from_args(repository_url: str, redirect_url: str) ->
872 twine.exceptions.RedirectDetected
873 exception twine.exceptions.PackageNotFound
875 A package file was provided that could not be found on the file
876 system.
877 This is only used when attempting to register a package_file.
879 exception twine.exceptions.UploadToDeprecatedPyPIDetected
881 An upload attempt was detected to deprecated PyPI domains.
882 The sites pypi.python.org and testpypi.python.org are depre‐
884 cated.
885 classmethod from_args(target_url: str, default_url: str,
887 test_url: str) -> twine.exceptions.UploadToDeprecatedPyPIDe‐
888 tected
889 Return an UploadToDeprecatedPyPIDetected instance.
890 exception twine.exceptions.UnreachableRepositoryURLDetected
892 An upload attempt was detected to a URL without a protocol pre‐
893 fix.
894 All repository URLs must have a protocol (e.g., https://).
896 exception twine.exceptions.InvalidSigningConfiguration
898 Both the sign and identity parameters must be present.
899 exception twine.exceptions.InvalidSigningExecutable
901 Signing executable must be installed on system.
902 exception twine.exceptions.InvalidConfiguration
904 Raised when configuration is invalid.
905 exception twine.exceptions.InvalidDistribution
907 Raised when a distribution is invalid.
908 exception twine.exceptions.NonInteractive
910 Raised in non-interactive mode when credentials could not be
911 found.
912 exception twine.exceptions.InvalidPyPIUploadURL
914 Repository configuration tries to use PyPI with an incorrect
915 URL.
916 For example, https://pypi.org instead of
918 https://upload.pypi.org/legacy.
919 twine.package module
921 twine.package._safe_name(name: str) -> str
922 Convert an arbitrary string to a standard distribution name.
923 Any runs of non-alphanumeric/. characters are replaced with a
925 single '-'.
926 Copied from pkg_resources.safe_name for compatibility with ware‐
928 house. See https://github.com/pypa/twine/issues/743.
929 class twine.package.PackageFile
931 __init__(filename: str, comment: Optional[str], metadata:
933 pkginfo.distribution.Distribution, python_version: Op‐
934 tional[str], filetype: Optional[str]) -> None
935 classmethod from_filename(filename: str, comment: Optional[str])
937 -> twine.package.PackageFile
938 metadata_dictionary() -> Dict[str, Union[str, Sequence[str]]]
940 Merge multiple sources of metadata into a single dictio‐
941 nary.
942 Includes values from filename, PKG-INFO, hashers, and
944 signature.
945 add_gpg_signature(signature_filepath: str, signature_filename:
947 str) -> None
948 sign(sign_with: str, identity: Optional[str]) -> None
950 classmethod run_gpg(gpg_args: Tuple[str, ...]) -> None
952 class twine.package.Hexdigest
954 Hexdigest(md5, sha2, blake2)
955 md5: Optional[str]
957 Alias for field number 0
958 sha2: Optional[str]
960 Alias for field number 1
961 blake2: Optional[str]
963 Alias for field number 2
964 static __new__(_cls, md5: Optional[str], sha2: Optional[str],
966 blake2: Optional[str])
967 Create new instance of Hexdigest(md5, sha2, blake2)
968 _asdict()
970 Return a new dict which maps field names to their values.
971 _field_defaults = {}
973 _fields = ('md5', 'sha2', 'blake2')
975 classmethod _make(iterable)
977 Make a new Hexdigest object from a sequence or iterable
978 _replace(**kwds)
980 Return a new Hexdigest object replacing specified fields
981 with new values
982 class twine.package.HashManager
984 Manage our hashing objects for simplicity.
985 This will also allow us to better test this logic.
987 __init__(filename: str) -> None
989 Initialize our manager and hasher objects.
990 _md5_update(content: bytes) -> None
992 _md5_hexdigest() -> Optional[str]
994 _sha2_update(content: bytes) -> None
996 _sha2_hexdigest() -> Optional[str]
998 _blake_update(content: bytes) -> None
1000 _blake_hexdigest() -> Optional[str]
1002 hash() -> None
1004 Hash the file contents.
1005 hexdigest() -> twine.package.Hexdigest
1007 Return the hexdigest for the file.
1008 twine.repository module
1010 class twine.repository.ProgressBar
1011 update_to(n: int) -> None
1013 Update the bar in the way compatible with requests-tool‐
1014 belt.
1015 This is identical to tqdm.update, except n will be the
1017 current value - not the delta as tqdm expects.
1018 class twine.repository.Repository
1020 __init__(repository_url: str, username: Optional[str], password:
1022 Optional[str], disable_progress_bar: bool = False) -> None
1023 static _make_adapter_with_retries() -> re‐
1025 quests.adapters.HTTPAdapter
1026 static _make_user_agent_string() -> str
1028 close() -> None
1030 static _convert_data_to_list_of_tuples(data: Dict[str, Any]) ->
1032 List[Tuple[str, Any]]
1033 set_certificate_authority(cacert: Optional[str]) -> None
1035 set_client_certificate(clientcert: Optional[str]) -> None
1037 register(package: twine.package.PackageFile) -> requests.mod‐
1039 els.Response
1040 _upload(package: twine.package.PackageFile) -> requests.mod‐
1042 els.Response
1043 upload(package: twine.package.PackageFile, max_redirects: int =
1045 5) -> requests.models.Response
1046 package_is_uploaded(package: twine.package.PackageFile, by‐
1048 pass_cache: bool = False) -> bool
1049 release_urls(packages: List[twine.package.PackageFile]) ->
1051 Set[str]
1052 verify_package_integrity(package: twine.package.PackageFile) ->
1054 None
1055 twine.settings module
1057 Module containing logic for handling settings.
1058 class twine.settings.Settings
1060 Object that manages the configuration for Twine.
1061 This object can only be instantiated with keyword arguments.
1063 For example,
1065 Settings(True, username='fakeusername')
1067 Will raise a TypeError. Instead, you would want
1069 Settings(sign=True, username='fakeusername')
1071 __init__(*, sign: bool = False, sign_with: str = 'gpg', iden‐
1073 tity: Optional[str] = None, username: Optional[str] = None,
1074 password: Optional[str] = None, non_interactive: bool = False,
1075 comment: Optional[str] = None, config_file: str = utils.DE‐
1076 FAULT_CONFIG_FILE, skip_existing: bool = False, cacert: Op‐
1077 tional[str] = None, client_cert: Optional[str] = None, reposi‐
1078 tory_name: str = 'pypi', repository_url: Optional[str] = None,
1079 verbose: bool = False, disable_progress_bar: bool = False, **ig‐
1080 nored_kwargs: Any) -> None
1081 Initialize our settings instance.
1082 Parameters
1084 • sign -- Configure whether the package file
1086 should be signed.
1087 • sign_with -- The name of the executable used to
1089 sign the package with.
1090 • identity -- The GPG identity that should be used
1092 to sign the package file.
1093 • username -- The username used to authenticate to
1095 the repository (package index).
1096 • password -- The password used to authenticate to
1098 the repository (package index).
1099 • non_interactive -- Do not interactively prompt
1101 for username/password if the required creden‐
1102 tials are missing.
1103 • comment -- The comment to include with each dis‐
1105 tribution file.
1106 • config_file -- The path to the configuration
1108 file to use.
1109 • skip_existing -- Specify whether twine should
1111 continue uploading files if one of them already
1112 exists. This primarily supports PyPI. Other
1113 package indexes may not be supported.
1114 • cacert -- The path to the bundle of certificates
1116 used to verify the TLS connection to the package
1117 index.
1118 • client_cert -- The path to the client certifi‐
1120 cate used to perform authentication to the in‐
1121 dex. This must be a single file that contains
1122 both the private key and the PEM-encoded cer‐
1123 tificate.
1124 • repository_name -- The name of the repository
1126 (package index) to interact with. This should
1127 correspond to a section in the config file.
1128 • repository_url -- The URL of the repository
1130 (package index) to interact with. This will
1131 override the settings inferred from reposi‐
1132 tory_name.
1133 • verbose -- Show verbose output.
1135 • disable_progress_bar -- Disable the progress
1137 bar.
1138 property username: Optional[str]
1140 property password: Optional[str]
1142 _allow_noninteractive() -> ContextManager[None]
1144 Bypass NonInteractive error when client cert is present.
1145 property verbose: bool
1147 static register_argparse_arguments(parser: argparse.Argument‐
1149 Parser) -> None
1150 Register the arguments for argparse.
1151 classmethod from_argparse(args: argparse.Namespace) ->
1153 twine.settings.Settings
1154 Generate the Settings from parsed arguments.
1155 _handle_package_signing(sign: bool, sign_with: str, identity:
1157 Optional[str]) -> None
1158 _handle_repository_options(repository_name: str, repository_url:
1160 Optional[str]) -> None
1161 _handle_certificates(cacert: Optional[str], client_cert: Op‐
1163 tional[str]) -> None
1164 check_repository_url() -> None
1166 Verify we are not using legacy PyPI.
1167 Raises twine.exceptions.UploadToDeprecatedPyPIDetected --
1169 The configured repository URL is for legacy PyPI.
1170 create_repository() -> twine.repository.Repository
1172 Create a new repository for uploading.
1173 twine.utils module
1175 twine.utils.get_config(path: str) -> Dict[str, Dict[str, Op‐
1176 tional[str]]]
1177 Read repository configuration from a file (i.e. ~/.pypirc).
1178 Format: https://packaging.python.org/specifications/pypirc/
1180 If the default config file doesn't exist, return a default con‐
1182 figuration for pypyi and testpypi.
1183 twine.utils._validate_repository_url(repository_url: str) -> None
1185 Validate the given url for allowed schemes and components.
1186 twine.utils.get_repository_from_config(config_file: str, repository:
1188 str, repository_url: Optional[str] = None) -> Dict[str, Optional[str]]
1189 Get repository config command-line values or the .pypirc file.
1190 twine.utils.normalize_repository_url(url: str) -> str
1192 twine.utils.get_file_size(filename: str) -> str
1194 Return the size of a file in KB, or MB if >= 1024 KB.
1195 twine.utils.check_status_code(response: requests.models.Response, ver‐
1197 bose: bool) -> None
1198 Generate a helpful message based on the response from the repos‐
1199 itory.
1200 Raise a custom exception for recognized errors. Otherwise, print
1202 the response content (based on the verbose option) before
1203 re-raising the HTTPError.
1204 twine.utils.get_userpass_value(cli_value: Optional[str], config:
1206 Dict[str, Optional[str]], key: str, prompt_strategy: Op‐
1207 tional[Callable[[], str]] = None) -> Optional[str]
1208 Get a credential (e.g. a username or password) from the configu‐
1209 ration.
1210 Uses the following rules:
1212 1. If cli_value is specified, use that.
1214 2. If config[key] is specified, use that.
1216 3. If prompt_strategy is specified, use its return value.
1218 4. Otherwise return None
1220 Parameters
1222 • cli_value -- The value supplied from the command line.
1224 • config -- A dictionary of repository configuration val‐
1226 ues.
1227 • key -- The credential to look up in config, e.g. "user‐
1229 name" or "password".
1230 • prompt_strategy -- An argumentless function to get the
1232 value, e.g. from keyring or by prompting the user.
1233 Returns
1235 The credential value, i.e. the username or password.
1236 twine.utils.get_cacert(cli_value: Optional[str], config: Dict[str, Op‐
1238 tional[str]], *, key: str = 'ca_cert', prompt_strategy: Op‐
1239 tional[Callable[[], str]] = None) -> Optional[str]
1240 Get the CA bundle via get_userpass_value().
1241 twine.utils.get_clientcert(cli_value: Optional[str], config: Dict[str,
1243 Optional[str]], *, key: str = 'client_cert', prompt_strategy: Op‐
1244 tional[Callable[[], str]] = None) -> Optional[str]
1245 Get the client certificate via get_userpass_value().
1246 class twine.utils.EnvironmentDefault
1248 Get values from environment variable.
1249 __init__(env: str, required: bool = True, default: Optional[str]
1251 = None, **kwargs: Any) -> None
1252 class twine.utils.EnvironmentFlag
1254 Set boolean flag from environment variable.
1255 __init__(env: str, **kwargs: Any) -> None
1257 static bool_from_env(val: Optional[str]) -> bool
1259 Allow '0' and 'false' and 'no' to be False.
1260 twine.wheel module
1262 class twine.wheel.Wheel
1263 __init__(filename: str, metadata_version: Optional[str] = None)
1265 -> None
1266 property py_version: str
1268 static find_candidate_metadata_files(names: List[str]) ->
1270 List[List[str]]
1271 Filter files that may be METADATA files.
1272 read() -> bytes
1274 parse(data: bytes) -> None
1276 twine.wininst module
1278 class twine.wininst.WinInst
1279 __init__(filename: str, metadata_version: Optional[str] = None)
1281 -> None
1282 property py_version: str
1284 read() -> bytes
1286 Where Twine gets configuration and credentials
1288 A user can set the repository URL, username, and/or password via com‐
1289 mand line, .pypirc files, environment variables, and keyring.
1290
1292 A checklist for adding a new maintainer to the project.
1293 1. Add them as a Member in the GitHub repo settings.
1295 2. Get them Test PyPI and canon PyPI usernames and add them as a Main‐
1297 tainer on our Test PyPI project and canon PyPI.
1298
1300 A checklist for creating, testing, and distributing a new version.
1301 1. Choose a version number, and create a new branch
1303 VERSION=3.4.2
1305 git switch -c release-$VERSION
1307 2. Update docs/changelog.rst
1309 tox -e changelog -- --version $VERSION
1311 git commit -am "Update changelog for $VERSION"
1313 3. Open a pull request for review
1315 4. Merge the pull request, and ensure the GitHub Actions build passes
1317 5. Create a new git tag for the version
1319 git switch main
1321 git pull --ff-only upstream main
1323 git tag -m "Release v$VERSION" $VERSION
1325 6. Push to start the release, and watch it in GitHub Actions
1327 git push upstream $VERSION
1329 7. View the new release on PyPI
1331
1333 See our open issues.
1334 In the future, pip and twine may merge into a single tool; see ongoing
1336 discussion.
1337 Twine is a utility for publishing Python packages to PyPI and other
1339 repositories. It provides build system independent uploads of source
1340 and binary distribution artifacts for both new and existing projects.
1341
1343 The goal of Twine is to improve PyPI interaction by improving security
1344 and testability.
1345 The biggest reason to use Twine is that it securely authenticates you
1347 to PyPI over HTTPS using a verified connection, regardless of the un‐
1348 derlying Python version. Meanwhile, python setup.py upload will only
1349 work correctly and securely if your build system, Python version, and
1350 underlying operating system are configured properly.
1351 Secondly, Twine encourages you to build your distribution files. python
1353 setup.py upload only allows you to upload a package as a final step af‐
1354 ter building with distutils or setuptools, within the same command in‐
1355 vocation. This means that you cannot test the exact file you're going
1356 to upload to PyPI to ensure that it works before uploading it.
1357 Finally, Twine allows you to pre-sign your files and pass the .asc
1359 files into the command line invocation (twine upload mypro‐
1360 ject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc). This enables you to be
1361 assured that you're typing your gpg passphrase into gpg itself and not
1362 anything else, since you will be the one directly executing gpg --de‐
1363 tach-sign -a <filename>.
1364
1366 • Verified HTTPS connections
1367 • Uploading doesn't require executing setup.py
1369 • Uploading files that have already been created, allowing testing of
1371 distributions before release
1372 • Supports uploading any packaging format (including wheels)
1374
1376 pip install twine
1377
1379 1. Create some distributions in the normal way:
1380 python -m build
1382 2. Upload to Test PyPI and verify things look right:
1384 twine upload -r testpypi dist/*
1386 Twine will prompt for your username and password.
1388 3. Upload to PyPI:
1390 twine upload dist/*
1392 4. Done!
1394 NOTE:
1396 Like many other command line tools, Twine does not show any charac‐
1397 ters when you enter your password.
1398 If you're using Windows and trying to paste your username, password,
1400 or token in the Command Prompt or PowerShell, Ctrl-V and Shift+In‐
1401 sert won't work. Instead, you can use "Edit > Paste" from the window
1402 menu, or enable "Use Ctrl+Shift+C/V as Copy/Paste" in "Properties".
1403 This is a known issue with Python's getpass module.
1404 More documentation on using Twine to upload packages to PyPI is in the
1406 Python Packaging User Guide.
1407
1409 twine upload
1410 Uploads one or more distributions to a repository.
1411 System Message: ERROR/6 (/builddir/build/BUILD/twine-3.8.0/docs/in‐
1413 dex.rst:, line 116)
1414 Command ['twine', 'upload', '-h'] failed: [Errno 2] No such file
1415 or directory: 'twine'
1416 twine check
1418 Checks whether your distribution's long description will render cor‐
1419 rectly on PyPI.
1420 System Message: ERROR/6 (/builddir/build/BUILD/twine-3.8.0/docs/in‐
1422 dex.rst:, line 124)
1423 Command ['twine', 'check', '-h'] failed: [Errno 2] No such file
1424 or directory: 'twine'
1425 twine register
1427 Pre-register a name with a repository before uploading a distribution.
1428 WARNING:
1430 Pre-registration is not supported on PyPI, so the register command
1431 is only necessary if you are using a different repository that re‐
1432 quires it. See issue #1627 on Warehouse (the software running on
1433 PyPI) for more details.
1434 System Message: ERROR/6 (/builddir/build/BUILD/twine-3.8.0/docs/in‐
1436 dex.rst:, line 137)
1437 Command ['twine', 'register', '-h'] failed: [Errno 2] No such
1438 file or directory: 'twine'
1439
1441 Twine can read repository configuration from a .pypirc file, either in
1442 your home directory, or provided with the --config-file option. For de‐
1443 tails on writing and using .pypirc, see the specification in the Python
1444 Packaging User Guide.
1445 Environment Variables
1447 Twine also supports configuration via environment variables. Options
1448 passed on the command line will take precedence over options set via
1449 environment variables. Definition via environment variable is helpful
1450 in environments where it is not convenient to create a .pypirc file
1451 (for example, on a CI/build server).
1452 • TWINE_USERNAME - the username to use for authentication to the repos‐
1454 itory.
1455 • TWINE_PASSWORD - the password to use for authentication to the repos‐
1457 itory.
1458 • TWINE_REPOSITORY - the repository configuration, either defined as a
1460 section in .pypirc or provided as a full URL.
1461 • TWINE_REPOSITORY_URL - the repository URL to use.
1463 • TWINE_CERT - custom CA certificate to use for repositories with
1465 self-signed or untrusted certificates.
1466 • TWINE_NON_INTERACTIVE - Do not interactively prompt for user‐
1468 name/password if the required credentials are missing.
1469 Proxy Support
1471 Twine can be configured to use a proxy by setting environment vari‐
1472 ables. For example, to use a proxy for just the twine command, without
1473 export-ing it for other tools:
1474 HTTPS_PROXY=socks5://user:pass@host:port twine upload dist/*
1476 For more information, see the Requests documentation on proxies and
1478 SOCKS , and an in-depth article about proxy environment variables.
1479
1481 Instead of typing in your password every time you upload a distribu‐
1482 tion, Twine allows storing a username and password securely using
1483 keyring. Keyring is installed with Twine but for some systems (Linux
1484 mainly) may require additional installation steps.
1485 Once Twine is installed, use the keyring program to set a username and
1487 password to use for each repository to which you may upload.
1488 For example, to set a username and password for PyPI:
1490 keyring set https://upload.pypi.org/legacy/ your-username
1492 and enter the password when prompted.
1494 For a different repository, replace the URL with the relevant reposi‐
1496 tory URL. For example, for Test PyPI, use
1497 https://test.pypi.org/legacy/.
1498 The next time you run twine, it will prompt you for a username, and
1500 then get the appropriate password from Keyring.
1501 NOTE:
1503 If you are using Linux in a headless environment (such as on a
1504 server) you'll need to do some additional steps to ensure that
1505 Keyring can store secrets securely. See Using Keyring on headless
1506 systems.
1507 Disabling Keyring
1509 In most cases, simply not setting a password with keyring will allow
1510 Twine to fall back to prompting for a password. In some cases, the
1511 presence of Keyring will cause unexpected or undesirable prompts from
1512 the backing system. In these cases, it may be desirable to disable
1513 Keyring altogether. To disable Keyring, run:
1514 keyring --disable
1516 See Twine issue #338 for discussion and background.
1518
1520 Donald Stufft, Individual contributors
1521
1523 2022, Donald Stufft and individual contributors
15243.8 Feb 24, 2022 TWINE(1)