Skip to content

WIP #148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

WIP #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d3080ad
wire namespace cloud.
n-g May 26, 2025
1485dc4
remove ci pants
n-g May 26, 2025
a4b9ddb
Try array syntax
n-g May 26, 2025
059170e
Update README.
n-g May 26, 2025
159a3ae
also run on arm
n-g May 26, 2025
151896f
Arm runners from matrix
n-g May 26, 2025
c86b21d
split artifact logs per runner
n-g May 26, 2025
b2fc7c0
Set up arm and amd examples.
n-g May 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 43 additions & 31 deletions .github/workflows/pants.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,48 +5,59 @@

name: Pants

on: [push, pull_request]
on: [push, workflow_dispatch]

jobs:
org-check:
name: Check GitHub Organization
if: ${{ github.repository_owner == 'pantsbuild' }}
runs-on: ubuntu-24.04
steps:
- name: Noop
run: "true"
build:
name: Perform CI Checks
needs: org-check
runs-on: ubuntu-24.04
strategy:
matrix:
runner:
# Replace with your profile label https://namespace.so/docs/features/faster-github-actions#using-runner-profiles
- namespace-profile-amd64-with-caching
- namespace-profile-arm64-with-caching
python-version: [3.9]
setup:
- manual
- init-pants-action
fail-fast: false
runs-on: ${{ matrix.runner }}
steps:
- uses: actions/checkout@v4

- name: Set up remote cache
run: |
nsc pants cache setup --pants-toml=pants.cache.toml

- name: Set up local cache
uses: namespacelabs/nscloud-cache-action@v1
with:
path: |
~/.cache/pants/named_caches
~/.cache/pants/lmdb_store
~/.cache/nce

- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}

- name: Limit LMDB memory usage
if: runner.arch == 'ARM64'
run: echo "PANTS_LOCAL_STORE_PROCESSES_MAX_SIZE_BYTES=536870912" >> $GITHUB_ENV

- 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/
if: matrix.setup == 'init-pants-action'
with:
# v0 makes it easy to bust the cache if needed
# just increase the integer to start with a fresh cache
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') }}
# If you're not using a fine-grained remote caching service (see https://www.pantsbuild.org/docs/remote-caching),
# then you may also want to preserve the local Pants cache (lmdb_store). However this must invalidate for
# changes to any file that can affect the build, so may not be practical in larger repos.
# A remote cache service integrates with Pants's fine-grained invalidation and avoids these problems.
cache-lmdb-store: 'true' # defaults to 'false'
# 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://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.
pants-ci-config: "['pants.toml', 'pants.ci.toml', 'pants.cache.toml']"

- name: Install Pants manually
if: matrix.setup == 'manual'
run: |
curl --proto '=https' --tlsv1.2 -fsSL https://static.pantsbuild.org/setup/get-pants.sh | bash
echo "PANTS_CONFIG_FILES=['pants.toml','pants.ci.toml','pants.cache.toml']" >> $GITHUB_ENV

- name: Check BUILD files
run: |
pants tailor --check update-build-files --check ::
Expand All @@ -61,9 +72,10 @@ jobs:
# We also smoke test that our release process will work by running `package`.
pants package ::
pants run helloworld/:pex_binary
- name: Upload pants log
uses: actions/upload-artifact@v4

- name: Breakpoint
uses: namespacelabs/breakpoint-action@v0
if: failure()
with:
name: pants-log
path: .pants.d/workdir/pants.log
if: always() # We want the log even on failures.
duration: 15m
authorized-users: edganiukov,hugosantos,n-g,htr,nichtverstehen,gmichelo
189 changes: 4 additions & 185 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,188 +1,7 @@
# example-python
An example repository to demonstrate Python support in Pants.
# pantbuild-example-python

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
[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` launcher binary, which will bootstrap the
version of Pants configured for this repo if necessary.

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
in `pants.toml`).

# Goals

Pants commands are called _goals_. You can get a list of goals with

```
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
`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).
In the latter case, Pants locates target metadata for the source files as needed.

## File specifications

Invoking goals on files is straightforward, e.g.,

```
pants test helloworld/greet/greeting_test.py
```

You can use globs:

```
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
```

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'
```

You can run on all changed files:

```
pants --changed-since=HEAD lint
```

You can run on all changed files, and any of their "dependents":

```
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
```

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::
```
An example repository to demonstrate Python support in Pants with remote caching in Namespace.

## Globbing semantics

When you glob over files or targets, Pants knows to ignore ones that aren't relevant to the requested goal.
For example, if you run the `test` goal over a set of files that includes non-test files, Pants will just ignore
those, rather than error. So you can safely do things like

```
pants test ::
```

To run all tests.

# Example Goals

Try these out in this repo!

## List targets

```
pants list :: # All targets.
pants list 'helloworld/**/*.py' # Just targets containing Python code.
```

## Run linters and formatters

```
pants lint ::
pants fmt helloworld/greet::
```

## Run MyPy

```
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.
```

## 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: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
```

## 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.
```

## Build a wheel / generate `setup.py`

This will build both a `.whl` bdist and a `.tar.gz` sdist.

```
pants package helloworld/translator:dist
```

## Count lines of code

```
pants count-loc '**/*'
```

## Generate or update a lockfile containing the dependencies

```
pants generate-lockfiles --resolve=python-default
```


## Create virtualenv for IDE integration
See [pantsbuild.org](https://www.pantsbuild.org/docs) for much more detailed documentation.

```
pants export --resolve=python-default
```
This example is based on [pantsbuild/example-python](https://github.com/pantsbuild/example-python).