Merge branch 'main' into csb/up-2.24.0

Author: cburroughs

.github/workflows/pants.yaml

@@ -1,7 +1,7 @@
 # Copyright 2020 Pants project contributors.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-# See https://pants.readme.io/docs/using-pants-in-ci for tips on how to set up your CI with Pants.
+# See https://www.pantsbuild.org/stable/docs/using-pants/using-pants-in-ci for tips on how to set up your CI with Pants.
 
 name: Pants
 
@@ -23,15 +23,17 @@ jobs:
       matrix:
         python-version: [3.9]
     steps:
-    - uses: actions/checkout@v3
-    - uses: pantsbuild/actions/init-pants@v2
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - uses: pantsbuild/actions/init-pants@v8
       # This action bootstraps pants and manages 2-3 GHA caches.
       # See: github.com/pantsbuild/actions/tree/main/init-pants/
       with:
-        pants-python-version: ${{ matrix.python-version }}
-        # cache0 makes it easy to bust the cache if needed
+        # v0 makes it easy to bust the cache if needed
         # just increase the integer to start with a fresh cache
-        gha-cache-key: cache0-py${{ matrix.python-version }}
+        gha-cache-key: v0
         # The Python backend uses named_caches for Pip/PEX state,
         # so it is appropriate to invalidate on lockfile changes.
         named-caches-hash: ${{ hashFiles('python-default.lock') }}
@@ -43,25 +45,25 @@ jobs:
         # Note that named_caches and lmdb_store falls back to partial restore keys which
         # may give a useful partial result that will save time over completely clean state,
         # but will cause the cache entry to grow without bound over time.
-        # See https://pants.readme.io/docs/using-pants-in-ci for tips on how to periodically clean it up.
+        # See https://www.pantsbuild.org/stable/docs/using-pants/using-pants-in-ci for tips on how to periodically clean it up.
         # Alternatively you change gha-cache-key to ignore old caches.
     - name: Check BUILD files
-      run:  |
-        ./pants tailor --check update-build-files --check ::
+      run: |
+        pants tailor --check update-build-files --check ::
     - name: Lint and typecheck
-      run: | 
-        ./pants lint check ::
+      run: |
+        pants lint check ::
     - name: Test
       run: |
-        ./pants test ::
+        pants test ::
     - name: Package / Run
       run: |
         # We also smoke test that our release process will work by running `package`.
-        ./pants package ::
-        ./pants run helloworld/main.py
+        pants package ::
+        pants run helloworld/:pex_binary
     - name: Upload pants log
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: pants-log
-        path: .pants.d/pants.log
+        path: .pants.d/workdir/pants.log
       if: always()  # We want the log even on failures.

README.md

@@ -3,34 +3,36 @@ An example repository to demonstrate Python support in Pants.
 
 See [pantsbuild.org](https://www.pantsbuild.org/docs) for much more detailed documentation.
 
-This is only one possible way of laying out your project with Pants. See 
+This is only one possible way of laying out your project with Pants. See
 [pantsbuild.org/docs/source-roots#examples](https://www.pantsbuild.org/docs/source-roots#examples) for some other
 example layouts.
 
 # Running Pants
 
-You run Pants goals using the `./pants` wrapper script, which will bootstrap the
-configured version of Pants if necessary.
+You run Pants goals using the `pants` launcher binary, which will bootstrap the
+version of Pants configured for this repo if necessary.
 
-> :question: Running with Apple Silicon and/or MacOS? You will want to make changes to the `search_path` and
-`interpreter_constraints` values in `pants.toml` before running `./pants` - there is guidance in `pants.toml`
+See [here](https://www.pantsbuild.org/docs/installation) for how to install the `pants` binary.
+
+> :question: Running with Apple Silicon and/or macOS? You will want to make changes to the `search_path` and
+`interpreter_constraints` values in `pants.toml` before running `pants` - there is guidance in `pants.toml`
 for those settings.
 
-Use `./pants --version` to see the version of Pants configured for the repo (which you can also find
+Use `pants --version` to see the version of Pants configured for the repo (which you can also find
 in `pants.toml`).
 
 # Goals
 
 Pants commands are called _goals_. You can get a list of goals with
 
 ```
-./pants help goals
+pants help goals
 ```
 
 # Targets
 
-Targets are a way of setting metadata for some part of your code, such as timeouts for tests and 
-entry points for binaries. Targets have types like `python_source`, `resources`, and 
+Targets are a way of setting metadata for some part of your code, such as timeouts for tests and
+entry points for binaries. Targets have types like `python_source`, `resources`, and
 `pex_binary`. They are defined in `BUILD` files.
 
 Pants goals can be invoked on targets or directly on source files (which is often more intuitive and convenient).
@@ -41,52 +43,52 @@ In the latter case, Pants locates target metadata for the source files as needed
 Invoking goals on files is straightforward, e.g.,
 
 ```
-./pants test helloworld/greet/greeting_test.py
+pants test helloworld/greet/greeting_test.py
 ```
 
 You can use globs:
 
 ```
-./pants lint helloworld/greet/*.py
+pants lint helloworld/greet/*.py
 ```
 
 But note that these will be expanded by your shell, so this is equivalent to having used
 
 ```
-./pants lint helloworld/greet/__init__.py helloworld/greet/greeting.py helloworld/greet/greeting_test.py
+pants lint helloworld/greet/__init__.py helloworld/greet/greeting.py helloworld/greet/greeting_test.py
 ```
 
 If you want Pants itself to expand the globs (which is sometimes necessary), you must quote them in the shell:
 
 ```
-./pants lint 'helloworld/greet/*.py'
+pants lint 'helloworld/greet/*.py'
 ```
 
 You can run on all changed files:
 
 ```
-./pants --changed-since=HEAD lint
+pants --changed-since=HEAD lint
 ```
 
-You can run on all changed files, and any of their "dependees":
+You can run on all changed files, and any of their "dependents":
 
 ```
-./pants --changed-since=HEAD --changed-dependees=transitive test
+pants --changed-since=HEAD --changed-dependents=transitive test
 ```
 
 ## Target specifications
 
 Targets are referenced on the command line using their address, of the form `path/to/dir:name`, e.g.,
 
 ```
-./pants lint helloworld/greet:lib
+pants lint helloworld/greet:lib
 ```
 
 You can glob over all targets in a directory with a single trailing `:`, or over all targets in a directory
 and all its subdirectories with a double trailing `::`, e.g.,
 
 ```
-./pants lint helloworld::
+pants lint helloworld::
 ```
 
 ## Globbing semantics
@@ -96,7 +98,7 @@ For example, if you run the `test` goal over a set of files that includes non-te
 those, rather than error. So you can safely do things like
 
 ```
-./pants test ::
+pants test ::
 ```
 
 To run all tests.
@@ -108,67 +110,79 @@ Try these out in this repo!
 ## List targets
 
 ```
-./pants list ::  # All targets.
-./pants list 'helloworld/**/*.py'  # Just targets containing Python code.
+pants list ::  # All targets.
+pants list 'helloworld/**/*.py'  # Just targets containing Python code.
 ```
 
 ## Run linters and formatters
 
 ```
-./pants lint ::
-./pants fmt helloworld/greet::
+pants lint ::
+pants fmt helloworld/greet::
 ```
 
 ## Run MyPy
 
 ```
-./pants check ::
+pants check ::
 ```
 
 ## Run tests
 
 ```
-./pants test ::  # Run all tests in the repo.
-./pants test --output=all ::  # Run all tests in the repo and view pytest output even for tests that passed (you can set this permanently in pants.toml).
-./pants test helloworld/translator:tests  # Run all the tests in this target.
-./pants test helloworld/translator/translator_test.py  # Run just the tests in this file.
-./pants test helloworld/translator/translator_test.py -- -k test_unknown_phrase  # Run just this one test by passing through pytest args.
+pants test ::  # Run all tests in the repo.
+pants test --output=all ::  # Run all tests in the repo and view pytest output even for tests that passed (you can set this permanently in pants.toml).
+pants test helloworld/translator:tests  # Run all the tests in this target.
+pants test helloworld/translator/translator_test.py  # Run just the tests in this file.
+pants test helloworld/translator/translator_test.py -- -k test_unknown_phrase  # Run just this one test by passing through pytest args.
 ```
 
 ## Create a PEX binary
 
+The `package` goal requires specifying a target which can be packaged. In this case, the there is a `pex_binary` target with the name `pex_binary` in the `helloworld/BUILD` file.
+
 ```
-./pants package helloworld/main.py
+pants package helloworld:pex_binary
 ```
 
+The pex file is output to `dist/helloworld/pex_binary.pex` and can be executed directly.
+
 ## Run a binary directly
 
 ```
-./pants run helloworld/main.py
+pants run helloworld/main.py
 ```
 
 ## Open a REPL
 
 ```
-./pants repl helloworld/greet:lib  # The REPL will have all relevant code and dependencies on its sys.path.
-./pants repl --shell=ipython helloworld/greet:lib --no-pantsd  # To use IPython, you must disable Pantsd for now.
+pants repl helloworld/greet:lib  # The REPL will have all relevant code and dependencies on its sys.path.
+pants repl --shell=ipython helloworld/greet:lib --no-pantsd  # To use IPython, you must disable Pantsd for now.
 ```
 
 ## Build a wheel / generate `setup.py`
 
 This will build both a `.whl` bdist and a `.tar.gz` sdist.
 
 ```
-./pants package helloworld/translator:dist
+pants package helloworld/translator:dist
 ```
 
 ## Count lines of code
 
 ```
-./pants count-loc '**/*'
+pants count-loc '**/*'
 ```
+
+## Generate or update a lockfile containing the dependencies
+
+```
+pants generate-lockfiles --resolve=python-default
+```
+
+
 ## Create virtualenv for IDE integration
 
 ```
-./pants export ::
+pants export --resolve=python-default
 ```