Skip to content

Commit 0223076

Browse files
authored
Merge branch 'main' into yarn-v2-immutable-install
2 parents 5177a9b + ef03520 commit 0223076

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+218
-91
lines changed

docs/docs/using-pants/project-introspection.mdx

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,72 @@ To include the original target itself, use `--closed`:
127127
helloworld/main.py:lib
128128
```
129129

130+
## Export dependency graph
131+
132+
Both `dependencies` and `dependents` goals have the `--format` option allowing you to export data in multiple formats.
133+
Exporting information about the dependencies and dependents in JSON format will produce the
134+
[adjacency list](https://en.wikipedia.org/wiki/Adjacency_list) of your dependency graph:
135+
136+
```bash
137+
$ pants dependencies --format=json \
138+
helloworld/greet/greeting.py \
139+
helloworld/translator/translator_test.py
140+
141+
{
142+
"helloworld/greet/greeting.py:lib": [
143+
"//:reqs#setuptools",
144+
"//:reqs#types-setuptools",
145+
"helloworld/greet:translations",
146+
"helloworld/translator/translator.py:lib"
147+
],
148+
"helloworld/translator/translator_test.py:tests": [
149+
"//:reqs#pytest",
150+
"helloworld/translator/translator.py:lib"
151+
]
152+
}
153+
```
154+
155+
This has various applications, and you could analyze, visualize, and process the data further. Sometimes, a fairly
156+
straightforward `jq` query would suffice, but for anything more complex, it may make sense to write a small program
157+
to process the exported graph. For instance, you could:
158+
159+
* find tests with most transitive dependencies
160+
161+
```bash
162+
$ pants dependencies --filter-target-type=python_test --format=json :: \
163+
| jq -r 'to_entries[] | "\(.key)\t\(.value | length)"' \
164+
| sort -k2 -n
165+
```
166+
167+
* find resources that only a few other targets depend on
168+
169+
```bash
170+
$ pants dependents --filter-target-type=resource --format=json :: \
171+
| jq -r 'to_entries[] | select(.value | length < 2)'
172+
```
173+
174+
* find files within the `src/` directory that transitively lead to the most tests
175+
176+
```python
177+
# depgraph.py
178+
import json
179+
180+
with open("data.json") as fh:
181+
data = json.load(fh)
182+
183+
for source, dependents in data.items():
184+
print(source, len([d for d in dependents if d.startswith("tests/")]))
185+
```
186+
187+
```bash
188+
$ pants dependents --transitive --format=json src:: > data.json
189+
$ python3 depgraph.py | sort -k2 -n
190+
```
191+
192+
For more sophisticated graph querying, you may want to look into graph libraries such as [`networkx`](https://networkx.org/).
193+
In a larger repository, it may make sense to track the health of the dependency graph and use the output
194+
of the graph export to identify parts of your codebase that would benefit from refactoring.
195+
130196
## `filedeps` - find which files a target owns
131197

132198
`filedeps` outputs all of the files belonging to a target, based on its `sources` field.

src/python/pants/backend/awslambda/python/target_types.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ class PythonAWSLambda(_AWSLambdaBaseTarget):
191191
f"""
192192
A self-contained Python function suitable for uploading to AWS Lambda.
193193
194-
See {doc_url('awslambda-python')}.
194+
See {doc_url('docs/python/integrations/aws-lambda')}.
195195
"""
196196
)
197197

@@ -207,7 +207,7 @@ class PythonAWSLambdaLayer(_AWSLambdaBaseTarget):
207207
f"""
208208
A Python layer suitable for uploading to AWS Lambda.
209209
210-
See {doc_url('awslambda-python')}.
210+
See {doc_url('docs/python/integrations/aws-lambda')}.
211211
"""
212212
)
213213

src/python/pants/backend/codegen/protobuf/python/python_protobuf_subsystem.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ class PythonProtobufSubsystem(Subsystem):
3535
f"""
3636
Options related to the Protobuf Python backend.
3737
38-
See {doc_url('protobuf-python')}.
38+
See {doc_url('docs/python/integrations/protobuf-and-grpc')}.
3939
"""
4040
)
4141

src/python/pants/backend/codegen/protobuf/target_types.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,8 @@ class ProtobufSourceTarget(Target):
6666
A single Protobuf file used to generate various languages.
6767
6868
See language-specific docs:
69-
Python: {doc_url('protobuf-python')}
70-
Go: {doc_url('protobuf-go')}
69+
Python: {doc_url('docs/python/integrations/protobuf-and-grpc')}
70+
Go: {doc_url('docs/go/integrations/protobuf')}
7171
"""
7272
)
7373

src/python/pants/backend/codegen/thrift/target_types.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ class ThriftSourceTarget(Target):
7272
A single Thrift file used to generate various languages.
7373
7474
See language-specific docs:
75-
Python: {doc_url('thrift-python')}
75+
Python: {doc_url('docs/python/integrations/thrift')}
7676
"""
7777
)
7878

src/python/pants/backend/codegen/utils.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ def find_python_runtime_library_or_raise_error(
5454
No `python_requirement` target was found with the module `{runtime_library_module}`
5555
in your project{for_resolve_str}, so the Python code generated from the target
5656
{codegen_address} will not work properly. See
57-
{doc_url('python-third-party-dependencies')} for how to add a requirement, such as
57+
{doc_url('docs/python/overview/third-party-dependencies')} for how to add a requirement, such as
5858
adding to requirements.txt. Usually you will want to use the
5959
`{recommended_requirement_name}` project at {recommended_requirement_url}.
6060

src/python/pants/backend/docker/target_types.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ class DockerImageTagsField(StringSequenceField):
149149
150150
{_interpolation_help.format(kind="tag")}
151151
152-
See {doc_url('tagging-docker-images')}.
152+
See {doc_url('docs/docker/tagging-docker-images')}.
153153
"""
154154
)
155155

src/python/pants/backend/google_cloud_function/python/target_types.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ class PythonGoogleCloudFunction(Target):
125125
f"""
126126
A self-contained Python function suitable for uploading to Google Cloud Function.
127127
128-
See {doc_url('google-cloud-function-python')}.
128+
See {doc_url('docs/python/integrations/google-cloud-functions')}.
129129
"""
130130
)
131131

src/python/pants/backend/python/dependency_inference/rules.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -346,7 +346,7 @@ async def _handle_unowned_imports(
346346
347347
If you do not expect an import to be inferrable, add `# pants: no-infer-dep` to the
348348
import line. Otherwise, see
349-
{doc_url('troubleshooting#import-errors-and-missing-dependencies')} for common problems.
349+
{doc_url('docs/using-pants/troubleshooting-common-issues#import-errors-and-missing-dependencies')} for common problems.
350350
"""
351351
)
352352
if unowned_dependency_behavior is UnownedDependencyUsage.LogWarning:

src/python/pants/backend/python/goals/pytest_runner.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ async def validate_pytest_cov_included(_pytest: PyTest):
243243
`{_pytest.install_from_resolve}` used to install pytest is missing
244244
`pytest-cov`, which is needed to collect coverage data.
245245
246-
See {doc_url("python-test-goal#pytest-version-and-plugins")} for details
246+
See {doc_url("docs/python/goals/test#pytest-version-and-plugins")} for details
247247
on how to set up a custom resolve for use by pytest.
248248
"""
249249
)

0 commit comments

Comments
 (0)