#general
Title
h
hundreds-father-404
09/22/2021, 6:45 AMI rewrote our docs on 3rd-party dependencies. The original didn't explain Pants's conceptual model very well, whereas now it all builds off of this main idea:
Pants handles dependencies with more precision than Python projects solely using workflows like requirements.txt or Poetry. Whereas normally you have a single virtual environment, Pants understands precisely which third-party dependencies each file in your project useshttps://www.pantsbuild.org/v2.7/docs/third-party-dependencies-rewrite. Feedback welcomed!
❤️ 4
https://www.pantsbuild.org/v2.7/docs/python-third-party-dependencies for the original. This rewrite isn't published yet
c
curved-television-6568
09/22/2021, 7:10 AMThis opening text:
Pants handles dependencies with more precision than Python projects using workflows like requirements.txt …Leads me to believe that Pants does not use requirements.txt at all, and as such, it is confusing when I later read about using requirements.txt files to teach Pants my universe of dependencies. Perhaps make it clear(er) that using requirements.txt is an optional method of telling about my dep universe.
👍 1
Or, that Pants can build on top of that of normal requirements.txt or Poetry dependencies use case, to further the fine grained precision with which Pants assembles each environment, depending on what is required.. (my formulation is not the best, but I’m sure you understand what I’m trying to say.. 😉 )
UsePerhaps, “.. when the module name is not standard”, as it is the naming of the module, not the module itself, that is considered here. I understand the heading is rather long already.when the module is not standardmodule_mapping
➕ 1
i.e.The conclusion here is unclear what it refers to, as it seems contradictory (I know, but if I didn’t, this could be confusing)exposes the module `my_distribution`—so those dependencies may not be inferred.My-distribution
👍 1
h
hundreds-father-404
09/22/2021, 7:16 AMIs this better?
Pants handles dependencies with more precision than Python projects solely using workflows likeor Poetry.virtualenv
👀 1
c
curved-television-6568
09/22/2021, 7:24 AMHow about:
Pants handles dependencies with more precision than Python projects solely using workflows requirements.txt or Poetry.actually, just adding the word “solely” in the original sentence, makes it a lot better. No need to get rid of requirements.txt there (as I see the
virtualenv❤️ 1
➕ 1
h
hundreds-father-404
09/22/2021, 7:25 AMCool, thanks for the great feedback! Page updated
👍 1
c
curved-television-6568
09/22/2021, 7:26 AMMore coming.. 😉
🙌 1
Warning: multiple targets for the same dependencytargets here feels like implementation detail, and hides what we want to say. How about:
Warning: multiple versions of the same dependency
➕ 1
In the text, I think targets is fine, as it is directly followed with what we mean…
👍 1
Ah, cheese chop, as there is a section on “Custom repositories”, it mentions adding/replacing the index url for python repos, but it doesn’t mention anything about credentials… Is it supported, or if not, could be good to mention that, too. (as this was a question that came up recently.)
➕ 1
h
hundreds-father-404
09/22/2021, 7:32 AMWe're also missing documenting
--find-links👍 1
c
curved-television-6568
09/22/2021, 7:34 AMLast note, is this really the case?
However, due to how thegoal works, it will only capture 3rdparty dependencies specified outside./pants dependenciesrequirements.txt
because I see deps from my requirements.txt show up by
./pants dependencies --type=3rdpartyh
hundreds-father-404
09/22/2021, 7:36 AMOh the sentence reads weirdly. Should be:
Unless the dependency was specified in requirements.txt, Pants will only capture it if it is actually used by your code.
👍 1
c
curved-television-6568
09/22/2021, 7:36 AMAh, yeah, that makes more sense 😄
Oh, I missed this in the first read through, the
Shell👍 1
When trying to grok these concepts, it is sections as those, I’ve read and read again, to get to grips with the ins and outs.
The peek output doesn’t really translate to BUILD syntax that fluently..
If the file uses a different name thanThe same applies for poetry, so may as well have one there as well (in case you jump to the relevant section and miss it), setrequirements.txtrequirements_relpath=
👍 1
h
hundreds-father-404
09/22/2021, 7:47 AMOh, I missed this in the first read through, the Shell tab, cool as it is, is also very low tech (absolutely worth mentioning), however, I feel that the “this macro, when expanded is equivalent to these targets (in BUILD file syntax)” are more helpful.Oh great point! Reload the page. What do you think about having both the macro call and "this is equivalent to" in the
BUILDrequirements.txt🙌 1
c
curved-television-6568
09/22/2021, 7:49 AMPerfect!
❤️ 1
In the note on how to generate lock files, I think it could warrant a little excursion into the available options, to save the reader some time, for instance using poetry export, there’s --without-hashes that is needed, and you might want to include --dev to also get your dev deps in the constraints file.
➕ 1
h
hundreds-father-404
09/22/2021, 7:59 AMAgreed. I can't wait for that section to go away once pants generates user lockfiles...and it's going to be a bit weird that we generate tool lockfiles but not user lockfiles
💯 1
@curved-television-6568 check out the table at https://www.pantsbuild.org/v2.7/docs/third-party-dependencies-rewrite#user-lockfile
👍 1
🙌 1
Okay done! (minus
--find-linksw
witty-crayon-22786
09/22/2021, 8:42 PMthanks a lot! will look today.
looks really great: thanks.
i have a vague sense that the “Tool Lockfiles” aspect doesn’t belong on that page though… because the page itself is about user’s requirements, in general?
but it does overlap in that the supported syntax for requirements strings is the same.
h
happy-kitchen-89482
09/22/2021, 10:27 PMSilly nit - the Title and slug should mention
pythonLooking at actual content
Pants handles dependencies with more precision than Python projects solely using workflows like requirements.txt or Poetry.How about just
Pants handles dependencies with more precision than traditional Python workflows.Mentioning requirements.txt and Poetry is just confusing, since we can use both
👍 2
I suggest:
Copy code
With traditional Python workflows you typically have a single heavyweight virtual environment that includes a large set of dependencies, whether or not you actually need them for your current task. But Pants understands exactly which dependencies every file in your repo needs, and can efficiently use just that subset of dependencies."For Pants to know which dependencies each file uses, it must first know which specific dependencies are in your "universe"." - you don't really define what "universe" means here.
👍 1
"If the file uses a different name than
requirements.txtrequirements_relpath=requirements_relpath="reqs.txt"👍 1
h
hundreds-father-404
09/23/2021, 5:20 AMi have a vague sense that the “Tool Lockfiles” aspect doesn’t belong on that page though… because the page itself is about user’s requirements, in general?1) Agreed 2) I think it will fit better when user lockfile uses the
generate-lockfilestesttypeheckc
curved-television-6568
09/23/2021, 7:40 AMUnder “Tool lockfiles”, in the example for overriding the flake8 version, its listed as:
Copy code
[flake8]
version = "flake8==3.8.0"version="3.8.0"h
hundreds-father-404
09/24/2021, 5:00 PMyes it must use be a normal requirement
I can see the benefit of allowing the name in there, in case you want to use a forkThat is exactly the reason
👍 1
h
happy-kitchen-89482
09/24/2021, 6:29 PMOr there might be multiple requirements (such as plugins for the tool), I think that can be a list no?
c
curved-television-6568
09/24/2021, 6:32 PMWell then, I feel that to put that in a “version” field is a bit odd.. “requirement(s)” would perhaps be better..?
h
hundreds-father-404
09/24/2021, 6:35 PMOr there might be multiple requirements (such as plugins for the tool), I think that can be a list no?That's the extra_requirements option --
. “requirement(s)” would perhaps be better..?We used to use this. The reason we split it out is that it's common for Pants to have default extra_requirements, like pytest-cov for Pytest. It's impossible to override a single element from the default, you have to replace the whole list if you want to change its value. So let's say you want a new Pytest version but are fine with default pytest-cov. Then you would have to do this
Copy code
[pytest]
requirements = ["pytest==6.4.3", "pytest-cov>=5"]pytest-cov Copy code
[pytest]
version = "pytest==6.4.3"👍 1
h
happy-kitchen-89482
09/24/2021, 6:41 PMAh right, my mistake
h
hundreds-father-404
09/24/2021, 7:28 PMThanks @happy-kitchen-89482 for the feedback! Applied to https://www.pantsbuild.org/v2.7/docs/python-third-party-dependencies
Had you directly edited anything btw? I copied over the -rewrite page to be the normal one, so if so, your edits likely went to the wrong page
h
happy-kitchen-89482
09/24/2021, 8:08 PMI didn't edit directly
👍 1
Did you apply to v2.8?
h
hundreds-father-404
09/24/2021, 8:09 PMyeah, just updated all of 2.8 docs (this, typecheck, test, fmt, lint, Python linters page, project introspection)
🙌 1