cmdoptions.py 28 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009
  1. """
  2. shared options and groups
  3. The principle here is to define options once, but *not* instantiate them
  4. globally. One reason being that options with action='append' can carry state
  5. between parses. pip parses general options twice internally, and shouldn't
  6. pass on state. To be consistent, all options will follow this design.
  7. """
  8. # The following comment should be removed at some point in the future.
  9. # mypy: strict-optional=False
  10. import os
  11. import textwrap
  12. import warnings
  13. from functools import partial
  14. from optparse import SUPPRESS_HELP, Option, OptionGroup, OptionParser, Values
  15. from textwrap import dedent
  16. from typing import Any, Callable, Dict, Optional, Tuple
  17. from pip._vendor.packaging.utils import canonicalize_name
  18. from pip._internal.cli.parser import ConfigOptionParser
  19. from pip._internal.cli.progress_bars import BAR_TYPES
  20. from pip._internal.exceptions import CommandError
  21. from pip._internal.locations import USER_CACHE_DIR, get_src_prefix
  22. from pip._internal.models.format_control import FormatControl
  23. from pip._internal.models.index import PyPI
  24. from pip._internal.models.target_python import TargetPython
  25. from pip._internal.utils.hashes import STRONG_HASHES
  26. from pip._internal.utils.misc import strtobool
  27. def raise_option_error(parser: OptionParser, option: Option, msg: str) -> None:
  28. """
  29. Raise an option parsing error using parser.error().
  30. Args:
  31. parser: an OptionParser instance.
  32. option: an Option instance.
  33. msg: the error text.
  34. """
  35. msg = f"{option} error: {msg}"
  36. msg = textwrap.fill(" ".join(msg.split()))
  37. parser.error(msg)
  38. def make_option_group(group: Dict[str, Any], parser: ConfigOptionParser) -> OptionGroup:
  39. """
  40. Return an OptionGroup object
  41. group -- assumed to be dict with 'name' and 'options' keys
  42. parser -- an optparse Parser
  43. """
  44. option_group = OptionGroup(parser, group["name"])
  45. for option in group["options"]:
  46. option_group.add_option(option())
  47. return option_group
  48. def check_install_build_global(
  49. options: Values, check_options: Optional[Values] = None
  50. ) -> None:
  51. """Disable wheels if per-setup.py call options are set.
  52. :param options: The OptionParser options to update.
  53. :param check_options: The options to check, if not supplied defaults to
  54. options.
  55. """
  56. if check_options is None:
  57. check_options = options
  58. def getname(n: str) -> Optional[Any]:
  59. return getattr(check_options, n, None)
  60. names = ["build_options", "global_options", "install_options"]
  61. if any(map(getname, names)):
  62. control = options.format_control
  63. control.disallow_binaries()
  64. warnings.warn(
  65. "Disabling all use of wheels due to the use of --build-option "
  66. "/ --global-option / --install-option.",
  67. stacklevel=2,
  68. )
  69. def check_dist_restriction(options: Values, check_target: bool = False) -> None:
  70. """Function for determining if custom platform options are allowed.
  71. :param options: The OptionParser options.
  72. :param check_target: Whether or not to check if --target is being used.
  73. """
  74. dist_restriction_set = any(
  75. [
  76. options.python_version,
  77. options.platforms,
  78. options.abis,
  79. options.implementation,
  80. ]
  81. )
  82. binary_only = FormatControl(set(), {":all:"})
  83. sdist_dependencies_allowed = (
  84. options.format_control != binary_only and not options.ignore_dependencies
  85. )
  86. # Installations or downloads using dist restrictions must not combine
  87. # source distributions and dist-specific wheels, as they are not
  88. # guaranteed to be locally compatible.
  89. if dist_restriction_set and sdist_dependencies_allowed:
  90. raise CommandError(
  91. "When restricting platform and interpreter constraints using "
  92. "--python-version, --platform, --abi, or --implementation, "
  93. "either --no-deps must be set, or --only-binary=:all: must be "
  94. "set and --no-binary must not be set (or must be set to "
  95. ":none:)."
  96. )
  97. if check_target:
  98. if dist_restriction_set and not options.target_dir:
  99. raise CommandError(
  100. "Can not use any platform or abi specific options unless "
  101. "installing via '--target'"
  102. )
  103. def _path_option_check(option: Option, opt: str, value: str) -> str:
  104. return os.path.expanduser(value)
  105. def _package_name_option_check(option: Option, opt: str, value: str) -> str:
  106. return canonicalize_name(value)
  107. class PipOption(Option):
  108. TYPES = Option.TYPES + ("path", "package_name")
  109. TYPE_CHECKER = Option.TYPE_CHECKER.copy()
  110. TYPE_CHECKER["package_name"] = _package_name_option_check
  111. TYPE_CHECKER["path"] = _path_option_check
  112. ###########
  113. # options #
  114. ###########
  115. help_: Callable[..., Option] = partial(
  116. Option,
  117. "-h",
  118. "--help",
  119. dest="help",
  120. action="help",
  121. help="Show help.",
  122. )
  123. isolated_mode: Callable[..., Option] = partial(
  124. Option,
  125. "--isolated",
  126. dest="isolated_mode",
  127. action="store_true",
  128. default=False,
  129. help=(
  130. "Run pip in an isolated mode, ignoring environment variables and user "
  131. "configuration."
  132. ),
  133. )
  134. require_virtualenv: Callable[..., Option] = partial(
  135. Option,
  136. # Run only if inside a virtualenv, bail if not.
  137. "--require-virtualenv",
  138. "--require-venv",
  139. dest="require_venv",
  140. action="store_true",
  141. default=False,
  142. help=SUPPRESS_HELP,
  143. )
  144. verbose: Callable[..., Option] = partial(
  145. Option,
  146. "-v",
  147. "--verbose",
  148. dest="verbose",
  149. action="count",
  150. default=0,
  151. help="Give more output. Option is additive, and can be used up to 3 times.",
  152. )
  153. no_color: Callable[..., Option] = partial(
  154. Option,
  155. "--no-color",
  156. dest="no_color",
  157. action="store_true",
  158. default=False,
  159. help="Suppress colored output.",
  160. )
  161. version: Callable[..., Option] = partial(
  162. Option,
  163. "-V",
  164. "--version",
  165. dest="version",
  166. action="store_true",
  167. help="Show version and exit.",
  168. )
  169. quiet: Callable[..., Option] = partial(
  170. Option,
  171. "-q",
  172. "--quiet",
  173. dest="quiet",
  174. action="count",
  175. default=0,
  176. help=(
  177. "Give less output. Option is additive, and can be used up to 3"
  178. " times (corresponding to WARNING, ERROR, and CRITICAL logging"
  179. " levels)."
  180. ),
  181. )
  182. progress_bar: Callable[..., Option] = partial(
  183. Option,
  184. "--progress-bar",
  185. dest="progress_bar",
  186. type="choice",
  187. choices=list(BAR_TYPES.keys()),
  188. default="on",
  189. help=(
  190. "Specify type of progress to be displayed ["
  191. + "|".join(BAR_TYPES.keys())
  192. + "] (default: %default)"
  193. ),
  194. )
  195. log: Callable[..., Option] = partial(
  196. PipOption,
  197. "--log",
  198. "--log-file",
  199. "--local-log",
  200. dest="log",
  201. metavar="path",
  202. type="path",
  203. help="Path to a verbose appending log.",
  204. )
  205. no_input: Callable[..., Option] = partial(
  206. Option,
  207. # Don't ask for input
  208. "--no-input",
  209. dest="no_input",
  210. action="store_true",
  211. default=False,
  212. help="Disable prompting for input.",
  213. )
  214. proxy: Callable[..., Option] = partial(
  215. Option,
  216. "--proxy",
  217. dest="proxy",
  218. type="str",
  219. default="",
  220. help="Specify a proxy in the form [user:passwd@]proxy.server:port.",
  221. )
  222. retries: Callable[..., Option] = partial(
  223. Option,
  224. "--retries",
  225. dest="retries",
  226. type="int",
  227. default=5,
  228. help="Maximum number of retries each connection should attempt "
  229. "(default %default times).",
  230. )
  231. timeout: Callable[..., Option] = partial(
  232. Option,
  233. "--timeout",
  234. "--default-timeout",
  235. metavar="sec",
  236. dest="timeout",
  237. type="float",
  238. default=15,
  239. help="Set the socket timeout (default %default seconds).",
  240. )
  241. def exists_action() -> Option:
  242. return Option(
  243. # Option when path already exist
  244. "--exists-action",
  245. dest="exists_action",
  246. type="choice",
  247. choices=["s", "i", "w", "b", "a"],
  248. default=[],
  249. action="append",
  250. metavar="action",
  251. help="Default action when a path already exists: "
  252. "(s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort.",
  253. )
  254. cert: Callable[..., Option] = partial(
  255. PipOption,
  256. "--cert",
  257. dest="cert",
  258. type="path",
  259. metavar="path",
  260. help=(
  261. "Path to PEM-encoded CA certificate bundle. "
  262. "If provided, overrides the default. "
  263. "See 'SSL Certificate Verification' in pip documentation "
  264. "for more information."
  265. ),
  266. )
  267. client_cert: Callable[..., Option] = partial(
  268. PipOption,
  269. "--client-cert",
  270. dest="client_cert",
  271. type="path",
  272. default=None,
  273. metavar="path",
  274. help="Path to SSL client certificate, a single file containing the "
  275. "private key and the certificate in PEM format.",
  276. )
  277. index_url: Callable[..., Option] = partial(
  278. Option,
  279. "-i",
  280. "--index-url",
  281. "--pypi-url",
  282. dest="index_url",
  283. metavar="URL",
  284. default=PyPI.simple_url,
  285. help="Base URL of the Python Package Index (default %default). "
  286. "This should point to a repository compliant with PEP 503 "
  287. "(the simple repository API) or a local directory laid out "
  288. "in the same format.",
  289. )
  290. def extra_index_url() -> Option:
  291. return Option(
  292. "--extra-index-url",
  293. dest="extra_index_urls",
  294. metavar="URL",
  295. action="append",
  296. default=[],
  297. help="Extra URLs of package indexes to use in addition to "
  298. "--index-url. Should follow the same rules as "
  299. "--index-url.",
  300. )
  301. no_index: Callable[..., Option] = partial(
  302. Option,
  303. "--no-index",
  304. dest="no_index",
  305. action="store_true",
  306. default=False,
  307. help="Ignore package index (only looking at --find-links URLs instead).",
  308. )
  309. def find_links() -> Option:
  310. return Option(
  311. "-f",
  312. "--find-links",
  313. dest="find_links",
  314. action="append",
  315. default=[],
  316. metavar="url",
  317. help="If a URL or path to an html file, then parse for links to "
  318. "archives such as sdist (.tar.gz) or wheel (.whl) files. "
  319. "If a local path or file:// URL that's a directory, "
  320. "then look for archives in the directory listing. "
  321. "Links to VCS project URLs are not supported.",
  322. )
  323. def trusted_host() -> Option:
  324. return Option(
  325. "--trusted-host",
  326. dest="trusted_hosts",
  327. action="append",
  328. metavar="HOSTNAME",
  329. default=[],
  330. help="Mark this host or host:port pair as trusted, even though it "
  331. "does not have valid or any HTTPS.",
  332. )
  333. def constraints() -> Option:
  334. return Option(
  335. "-c",
  336. "--constraint",
  337. dest="constraints",
  338. action="append",
  339. default=[],
  340. metavar="file",
  341. help="Constrain versions using the given constraints file. "
  342. "This option can be used multiple times.",
  343. )
  344. def requirements() -> Option:
  345. return Option(
  346. "-r",
  347. "--requirement",
  348. dest="requirements",
  349. action="append",
  350. default=[],
  351. metavar="file",
  352. help="Install from the given requirements file. "
  353. "This option can be used multiple times.",
  354. )
  355. def editable() -> Option:
  356. return Option(
  357. "-e",
  358. "--editable",
  359. dest="editables",
  360. action="append",
  361. default=[],
  362. metavar="path/url",
  363. help=(
  364. "Install a project in editable mode (i.e. setuptools "
  365. '"develop mode") from a local project path or a VCS url.'
  366. ),
  367. )
  368. def _handle_src(option: Option, opt_str: str, value: str, parser: OptionParser) -> None:
  369. value = os.path.abspath(value)
  370. setattr(parser.values, option.dest, value)
  371. src: Callable[..., Option] = partial(
  372. PipOption,
  373. "--src",
  374. "--source",
  375. "--source-dir",
  376. "--source-directory",
  377. dest="src_dir",
  378. type="path",
  379. metavar="dir",
  380. default=get_src_prefix(),
  381. action="callback",
  382. callback=_handle_src,
  383. help="Directory to check out editable projects into. "
  384. 'The default in a virtualenv is "<venv path>/src". '
  385. 'The default for global installs is "<current dir>/src".',
  386. )
  387. def _get_format_control(values: Values, option: Option) -> Any:
  388. """Get a format_control object."""
  389. return getattr(values, option.dest)
  390. def _handle_no_binary(
  391. option: Option, opt_str: str, value: str, parser: OptionParser
  392. ) -> None:
  393. existing = _get_format_control(parser.values, option)
  394. FormatControl.handle_mutual_excludes(
  395. value,
  396. existing.no_binary,
  397. existing.only_binary,
  398. )
  399. def _handle_only_binary(
  400. option: Option, opt_str: str, value: str, parser: OptionParser
  401. ) -> None:
  402. existing = _get_format_control(parser.values, option)
  403. FormatControl.handle_mutual_excludes(
  404. value,
  405. existing.only_binary,
  406. existing.no_binary,
  407. )
  408. def no_binary() -> Option:
  409. format_control = FormatControl(set(), set())
  410. return Option(
  411. "--no-binary",
  412. dest="format_control",
  413. action="callback",
  414. callback=_handle_no_binary,
  415. type="str",
  416. default=format_control,
  417. help="Do not use binary packages. Can be supplied multiple times, and "
  418. 'each time adds to the existing value. Accepts either ":all:" to '
  419. 'disable all binary packages, ":none:" to empty the set (notice '
  420. "the colons), or one or more package names with commas between "
  421. "them (no colons). Note that some packages are tricky to compile "
  422. "and may fail to install when this option is used on them.",
  423. )
  424. def only_binary() -> Option:
  425. format_control = FormatControl(set(), set())
  426. return Option(
  427. "--only-binary",
  428. dest="format_control",
  429. action="callback",
  430. callback=_handle_only_binary,
  431. type="str",
  432. default=format_control,
  433. help="Do not use source packages. Can be supplied multiple times, and "
  434. 'each time adds to the existing value. Accepts either ":all:" to '
  435. 'disable all source packages, ":none:" to empty the set, or one '
  436. "or more package names with commas between them. Packages "
  437. "without binary distributions will fail to install when this "
  438. "option is used on them.",
  439. )
  440. platforms: Callable[..., Option] = partial(
  441. Option,
  442. "--platform",
  443. dest="platforms",
  444. metavar="platform",
  445. action="append",
  446. default=None,
  447. help=(
  448. "Only use wheels compatible with <platform>. Defaults to the "
  449. "platform of the running system. Use this option multiple times to "
  450. "specify multiple platforms supported by the target interpreter."
  451. ),
  452. )
  453. # This was made a separate function for unit-testing purposes.
  454. def _convert_python_version(value: str) -> Tuple[Tuple[int, ...], Optional[str]]:
  455. """
  456. Convert a version string like "3", "37", or "3.7.3" into a tuple of ints.
  457. :return: A 2-tuple (version_info, error_msg), where `error_msg` is
  458. non-None if and only if there was a parsing error.
  459. """
  460. if not value:
  461. # The empty string is the same as not providing a value.
  462. return (None, None)
  463. parts = value.split(".")
  464. if len(parts) > 3:
  465. return ((), "at most three version parts are allowed")
  466. if len(parts) == 1:
  467. # Then we are in the case of "3" or "37".
  468. value = parts[0]
  469. if len(value) > 1:
  470. parts = [value[0], value[1:]]
  471. try:
  472. version_info = tuple(int(part) for part in parts)
  473. except ValueError:
  474. return ((), "each version part must be an integer")
  475. return (version_info, None)
  476. def _handle_python_version(
  477. option: Option, opt_str: str, value: str, parser: OptionParser
  478. ) -> None:
  479. """
  480. Handle a provided --python-version value.
  481. """
  482. version_info, error_msg = _convert_python_version(value)
  483. if error_msg is not None:
  484. msg = "invalid --python-version value: {!r}: {}".format(
  485. value,
  486. error_msg,
  487. )
  488. raise_option_error(parser, option=option, msg=msg)
  489. parser.values.python_version = version_info
  490. python_version: Callable[..., Option] = partial(
  491. Option,
  492. "--python-version",
  493. dest="python_version",
  494. metavar="python_version",
  495. action="callback",
  496. callback=_handle_python_version,
  497. type="str",
  498. default=None,
  499. help=dedent(
  500. """\
  501. The Python interpreter version to use for wheel and "Requires-Python"
  502. compatibility checks. Defaults to a version derived from the running
  503. interpreter. The version can be specified using up to three dot-separated
  504. integers (e.g. "3" for 3.0.0, "3.7" for 3.7.0, or "3.7.3"). A major-minor
  505. version can also be given as a string without dots (e.g. "37" for 3.7.0).
  506. """
  507. ),
  508. )
  509. implementation: Callable[..., Option] = partial(
  510. Option,
  511. "--implementation",
  512. dest="implementation",
  513. metavar="implementation",
  514. default=None,
  515. help=(
  516. "Only use wheels compatible with Python "
  517. "implementation <implementation>, e.g. 'pp', 'jy', 'cp', "
  518. " or 'ip'. If not specified, then the current "
  519. "interpreter implementation is used. Use 'py' to force "
  520. "implementation-agnostic wheels."
  521. ),
  522. )
  523. abis: Callable[..., Option] = partial(
  524. Option,
  525. "--abi",
  526. dest="abis",
  527. metavar="abi",
  528. action="append",
  529. default=None,
  530. help=(
  531. "Only use wheels compatible with Python abi <abi>, e.g. 'pypy_41'. "
  532. "If not specified, then the current interpreter abi tag is used. "
  533. "Use this option multiple times to specify multiple abis supported "
  534. "by the target interpreter. Generally you will need to specify "
  535. "--implementation, --platform, and --python-version when using this "
  536. "option."
  537. ),
  538. )
  539. def add_target_python_options(cmd_opts: OptionGroup) -> None:
  540. cmd_opts.add_option(platforms())
  541. cmd_opts.add_option(python_version())
  542. cmd_opts.add_option(implementation())
  543. cmd_opts.add_option(abis())
  544. def make_target_python(options: Values) -> TargetPython:
  545. target_python = TargetPython(
  546. platforms=options.platforms,
  547. py_version_info=options.python_version,
  548. abis=options.abis,
  549. implementation=options.implementation,
  550. )
  551. return target_python
  552. def prefer_binary() -> Option:
  553. return Option(
  554. "--prefer-binary",
  555. dest="prefer_binary",
  556. action="store_true",
  557. default=False,
  558. help="Prefer older binary packages over newer source packages.",
  559. )
  560. cache_dir: Callable[..., Option] = partial(
  561. PipOption,
  562. "--cache-dir",
  563. dest="cache_dir",
  564. default=USER_CACHE_DIR,
  565. metavar="dir",
  566. type="path",
  567. help="Store the cache data in <dir>.",
  568. )
  569. def _handle_no_cache_dir(
  570. option: Option, opt: str, value: str, parser: OptionParser
  571. ) -> None:
  572. """
  573. Process a value provided for the --no-cache-dir option.
  574. This is an optparse.Option callback for the --no-cache-dir option.
  575. """
  576. # The value argument will be None if --no-cache-dir is passed via the
  577. # command-line, since the option doesn't accept arguments. However,
  578. # the value can be non-None if the option is triggered e.g. by an
  579. # environment variable, like PIP_NO_CACHE_DIR=true.
  580. if value is not None:
  581. # Then parse the string value to get argument error-checking.
  582. try:
  583. strtobool(value)
  584. except ValueError as exc:
  585. raise_option_error(parser, option=option, msg=str(exc))
  586. # Originally, setting PIP_NO_CACHE_DIR to a value that strtobool()
  587. # converted to 0 (like "false" or "no") caused cache_dir to be disabled
  588. # rather than enabled (logic would say the latter). Thus, we disable
  589. # the cache directory not just on values that parse to True, but (for
  590. # backwards compatibility reasons) also on values that parse to False.
  591. # In other words, always set it to False if the option is provided in
  592. # some (valid) form.
  593. parser.values.cache_dir = False
  594. no_cache: Callable[..., Option] = partial(
  595. Option,
  596. "--no-cache-dir",
  597. dest="cache_dir",
  598. action="callback",
  599. callback=_handle_no_cache_dir,
  600. help="Disable the cache.",
  601. )
  602. no_deps: Callable[..., Option] = partial(
  603. Option,
  604. "--no-deps",
  605. "--no-dependencies",
  606. dest="ignore_dependencies",
  607. action="store_true",
  608. default=False,
  609. help="Don't install package dependencies.",
  610. )
  611. build_dir: Callable[..., Option] = partial(
  612. PipOption,
  613. "-b",
  614. "--build",
  615. "--build-dir",
  616. "--build-directory",
  617. dest="build_dir",
  618. type="path",
  619. metavar="dir",
  620. help=SUPPRESS_HELP,
  621. )
  622. ignore_requires_python: Callable[..., Option] = partial(
  623. Option,
  624. "--ignore-requires-python",
  625. dest="ignore_requires_python",
  626. action="store_true",
  627. help="Ignore the Requires-Python information.",
  628. )
  629. no_build_isolation: Callable[..., Option] = partial(
  630. Option,
  631. "--no-build-isolation",
  632. dest="build_isolation",
  633. action="store_false",
  634. default=True,
  635. help="Disable isolation when building a modern source distribution. "
  636. "Build dependencies specified by PEP 518 must be already installed "
  637. "if this option is used.",
  638. )
  639. def _handle_no_use_pep517(
  640. option: Option, opt: str, value: str, parser: OptionParser
  641. ) -> None:
  642. """
  643. Process a value provided for the --no-use-pep517 option.
  644. This is an optparse.Option callback for the no_use_pep517 option.
  645. """
  646. # Since --no-use-pep517 doesn't accept arguments, the value argument
  647. # will be None if --no-use-pep517 is passed via the command-line.
  648. # However, the value can be non-None if the option is triggered e.g.
  649. # by an environment variable, for example "PIP_NO_USE_PEP517=true".
  650. if value is not None:
  651. msg = """A value was passed for --no-use-pep517,
  652. probably using either the PIP_NO_USE_PEP517 environment variable
  653. or the "no-use-pep517" config file option. Use an appropriate value
  654. of the PIP_USE_PEP517 environment variable or the "use-pep517"
  655. config file option instead.
  656. """
  657. raise_option_error(parser, option=option, msg=msg)
  658. # Otherwise, --no-use-pep517 was passed via the command-line.
  659. parser.values.use_pep517 = False
  660. use_pep517: Any = partial(
  661. Option,
  662. "--use-pep517",
  663. dest="use_pep517",
  664. action="store_true",
  665. default=None,
  666. help="Use PEP 517 for building source distributions "
  667. "(use --no-use-pep517 to force legacy behaviour).",
  668. )
  669. no_use_pep517: Any = partial(
  670. Option,
  671. "--no-use-pep517",
  672. dest="use_pep517",
  673. action="callback",
  674. callback=_handle_no_use_pep517,
  675. default=None,
  676. help=SUPPRESS_HELP,
  677. )
  678. install_options: Callable[..., Option] = partial(
  679. Option,
  680. "--install-option",
  681. dest="install_options",
  682. action="append",
  683. metavar="options",
  684. help="Extra arguments to be supplied to the setup.py install "
  685. 'command (use like --install-option="--install-scripts=/usr/local/'
  686. 'bin"). Use multiple --install-option options to pass multiple '
  687. "options to setup.py install. If you are using an option with a "
  688. "directory path, be sure to use absolute path.",
  689. )
  690. build_options: Callable[..., Option] = partial(
  691. Option,
  692. "--build-option",
  693. dest="build_options",
  694. metavar="options",
  695. action="append",
  696. help="Extra arguments to be supplied to 'setup.py bdist_wheel'.",
  697. )
  698. global_options: Callable[..., Option] = partial(
  699. Option,
  700. "--global-option",
  701. dest="global_options",
  702. action="append",
  703. metavar="options",
  704. help="Extra global options to be supplied to the setup.py "
  705. "call before the install or bdist_wheel command.",
  706. )
  707. no_clean: Callable[..., Option] = partial(
  708. Option,
  709. "--no-clean",
  710. action="store_true",
  711. default=False,
  712. help="Don't clean up build directories.",
  713. )
  714. pre: Callable[..., Option] = partial(
  715. Option,
  716. "--pre",
  717. action="store_true",
  718. default=False,
  719. help="Include pre-release and development versions. By default, "
  720. "pip only finds stable versions.",
  721. )
  722. disable_pip_version_check: Callable[..., Option] = partial(
  723. Option,
  724. "--disable-pip-version-check",
  725. dest="disable_pip_version_check",
  726. action="store_true",
  727. default=False,
  728. help="Don't periodically check PyPI to determine whether a new version "
  729. "of pip is available for download. Implied with --no-index.",
  730. )
  731. def _handle_merge_hash(
  732. option: Option, opt_str: str, value: str, parser: OptionParser
  733. ) -> None:
  734. """Given a value spelled "algo:digest", append the digest to a list
  735. pointed to in a dict by the algo name."""
  736. if not parser.values.hashes:
  737. parser.values.hashes = {}
  738. try:
  739. algo, digest = value.split(":", 1)
  740. except ValueError:
  741. parser.error(
  742. "Arguments to {} must be a hash name " # noqa
  743. "followed by a value, like --hash=sha256:"
  744. "abcde...".format(opt_str)
  745. )
  746. if algo not in STRONG_HASHES:
  747. parser.error(
  748. "Allowed hash algorithms for {} are {}.".format( # noqa
  749. opt_str, ", ".join(STRONG_HASHES)
  750. )
  751. )
  752. parser.values.hashes.setdefault(algo, []).append(digest)
  753. hash: Callable[..., Option] = partial(
  754. Option,
  755. "--hash",
  756. # Hash values eventually end up in InstallRequirement.hashes due to
  757. # __dict__ copying in process_line().
  758. dest="hashes",
  759. action="callback",
  760. callback=_handle_merge_hash,
  761. type="string",
  762. help="Verify that the package's archive matches this "
  763. "hash before installing. Example: --hash=sha256:abcdef...",
  764. )
  765. require_hashes: Callable[..., Option] = partial(
  766. Option,
  767. "--require-hashes",
  768. dest="require_hashes",
  769. action="store_true",
  770. default=False,
  771. help="Require a hash to check each requirement against, for "
  772. "repeatable installs. This option is implied when any package in a "
  773. "requirements file has a --hash option.",
  774. )
  775. list_path: Callable[..., Option] = partial(
  776. PipOption,
  777. "--path",
  778. dest="path",
  779. type="path",
  780. action="append",
  781. help="Restrict to the specified installation path for listing "
  782. "packages (can be used multiple times).",
  783. )
  784. def check_list_path_option(options: Values) -> None:
  785. if options.path and (options.user or options.local):
  786. raise CommandError("Cannot combine '--path' with '--user' or '--local'")
  787. list_exclude: Callable[..., Option] = partial(
  788. PipOption,
  789. "--exclude",
  790. dest="excludes",
  791. action="append",
  792. metavar="package",
  793. type="package_name",
  794. help="Exclude specified package from the output",
  795. )
  796. no_python_version_warning: Callable[..., Option] = partial(
  797. Option,
  798. "--no-python-version-warning",
  799. dest="no_python_version_warning",
  800. action="store_true",
  801. default=False,
  802. help="Silence deprecation warnings for upcoming unsupported Pythons.",
  803. )
  804. use_new_feature: Callable[..., Option] = partial(
  805. Option,
  806. "--use-feature",
  807. dest="features_enabled",
  808. metavar="feature",
  809. action="append",
  810. default=[],
  811. choices=["2020-resolver", "fast-deps", "in-tree-build"],
  812. help="Enable new functionality, that may be backward incompatible.",
  813. )
  814. use_deprecated_feature: Callable[..., Option] = partial(
  815. Option,
  816. "--use-deprecated",
  817. dest="deprecated_features_enabled",
  818. metavar="feature",
  819. action="append",
  820. default=[],
  821. choices=["legacy-resolver"],
  822. help=("Enable deprecated functionality, that will be removed in the future."),
  823. )
  824. ##########
  825. # groups #
  826. ##########
  827. general_group: Dict[str, Any] = {
  828. "name": "General Options",
  829. "options": [
  830. help_,
  831. isolated_mode,
  832. require_virtualenv,
  833. verbose,
  834. version,
  835. quiet,
  836. log,
  837. no_input,
  838. proxy,
  839. retries,
  840. timeout,
  841. exists_action,
  842. trusted_host,
  843. cert,
  844. client_cert,
  845. cache_dir,
  846. no_cache,
  847. disable_pip_version_check,
  848. no_color,
  849. no_python_version_warning,
  850. use_new_feature,
  851. use_deprecated_feature,
  852. ],
  853. }
  854. index_group: Dict[str, Any] = {
  855. "name": "Package Index Options",
  856. "options": [
  857. index_url,
  858. extra_index_url,
  859. no_index,
  860. find_links,
  861. ],
  862. }