https://pantsbuild.org/ logo
Join Slack
Powered by
I rewrote our docs on 3rd-party dependencies. The ...
# general
h
I 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 uses
https://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
This 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.. 😉 )
Use 
module_mapping
 when the module is not standard
Perhaps, “.. 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.
➕ 1
i.e. 
My-distribution
 exposes the module `my_distribution`—so those dependencies may not be inferred.
The conclusion here is unclear what it refers to, as it seems contradictory (I know, but if I didn’t, this could be confusing)
👍 1
h
Is this better?
Pants handles dependencies with more precision than Python projects solely using workflows like 
virtualenv
or Poetry.
👀 1
c
How 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
scenario kind of covers what Poetry does, too.. it felt a bit the same..)
❤️ 1
➕ 1
h
Cool, thanks for the great feedback! Page updated
👍 1
c
More coming.. 😉
🙌 1
Warning: multiple targets for the same dependency
targets 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
We're also missing documenting 
--find-links
, which we do support
👍 1
c
Last note, is this really the case?
However, due to how the 
./pants dependencies
 goal works, it will only capture 3rdparty dependencies specified outside 
requirements.txt
because I see deps from my requirements.txt show up by 
./pants dependencies --type=3rdparty
h
Oh 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
Ah, yeah, that makes more sense 😄
Oh, 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.
👍 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 than 
requirements.txt
, set 
requirements_relpath=
The same applies for poetry, so may as well have one there as well (in case you jump to the relevant section and miss it)
👍 1
h
Oh, 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 
BUILD
tab for 
requirements.txt
?
🙌 1
c
Perfect!
❤️ 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
Agreed. 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
👍 1
🙌 1
Okay done! (minus 
--find-links
stuff) cc @witty-crayon-22786 and @ancient-vegetable-10556 if you have feedback on the lockfile section in particular: https://www.pantsbuild.org/v2.7/docs/third-party-dependencies-rewrite#lockfiles cc @happy-kitchen-89482, given that you wrote a lot of the original docs and thank you @curved-television-6568 🙌
w
thanks 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
Silly nit - the Title and slug should mention 
python
Looking at actual content
Pants handles dependencies with more precision than Python projects solely using workflows like requirements.txt or Poetry.
This could read as "Pants achieves X solely [by] 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.txt
, set 
requirements_relpath=
, e.g. 
requirements_relpath="reqs.txt"
." Should show a full example, otherwise this is unclear ("set what on what?")
👍 1
h
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?
1) Agreed 2) I think it will fit better when user lockfile uses the 
generate-lockfiles
goal too 3) I needed one central place to explain all the nuance of tool lockfiles so that linters page, 
test
page, and 
typeheck
page could all link to it. This seemed the best
c
Under “Tool lockfiles”, in the example for overriding the flake8 version, its listed as:
Copy code
[flake8]
version = "flake8==3.8.0"
Does it have to be with the project name included, or does it work with just 
version="3.8.0"
as well? I can see the benefit of allowing the name in there, in case you want to use a fork, or what not, but my first attempt would be without if I were not going for that..
h
yes 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 fork
That is exactly the reason
👍 1
h
Or there might be multiple requirements (such as plugins for the tool), I think that can be a list no?
c
Well then, I feel that to put that in a “version” field is a bit odd.. “requirement(s)” would perhaps be better..?
h
Or 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"]
that was a common gotcha that people would forgot to include 
pytest-cov
, and it's not as easy as:
Copy code
[pytest]
version = "pytest==6.4.3"
👍 1
h
Ah right, my mistake
h
Thanks @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
I didn't edit directly
👍 1
Did you apply to v2.8?
h
yeah, just updated all of 2.8 docs (this, typecheck, test, fmt, lint, Python linters page, project introspection)
🙌 1
Open in Slack
PreviousNext
Powered by