### Initialize Please Project Configuration

Source: https://github.com/thought-machine/please/blob/master/docs/quickstart.html

Run this command in the root directory of your project to create the `.plzconfig` file. This configuration file holds various settings for the Please build system. While it has many options, the default settings are usually sufficient to get started.

```bash
plz init
```

--------------------------------

### Navigate to Getting Started Go Codelab Directory

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/plz_query.md

This command changes the current directory to the 'getting_started_go' codelab within the cloned `please-codelabs` repository. This is a prerequisite for running the subsequent examples.

```bash
cd please-codelabs/getting_started_go

```

--------------------------------

### Configuring go_repo() with Alias and Install List

Source: https://github.com/thought-machine/please/blob/master/docs/milestones/17.0.0.html

This example demonstrates how to use the `name` and `install` arguments within the `go_repo()` rule. This allows for custom aliases and specifies particular packages to be installed from the module, providing more granular control and simplifying dependency references.

```Please
go_repo(
    name = "testify",
    install = ["assert", "require"],
    module = "github.com/stretchr/testify",
    version = "v1.8.0",
)
```

--------------------------------

### Basic Go Library and Test Setup with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Defines a Go library and its associated test using Please's build system. The `go_library` rule compiles the main source files, while `go_test` specifies the test sources and dependencies. This setup is fundamental for any Go project managed by Please.

```python
go_library(
    name = "greetings",
    srcs = ["greetings.go"],
    visibility = ["//src/..."],
)

go_test(
    name = "greetings_test",
    srcs = ["greetings_test.go"],
    deps = [":greetings"],
    external = True,
)
```

--------------------------------

### Example 'make' Build Commands for Protobuf and Compilation

Source: https://github.com/thought-machine/please/blob/master/README.md

This snippet presents a simplified 'make' command example for installing protobuf and compiling Go source files. It highlights the dependencies and commands used in a traditional make environment, contrasting with the Please build system.

```make
protobuf:
    go install google.golang.org/protobuf

webserver: protobuf
    go tool compile --pack foo.go -o foo.a

pages: ???

```

--------------------------------

### Initialize Please Language Server Protocol

Source: https://github.com/thought-machine/please/blob/master/docs/quickstart.html

This command starts the Please Language Server Protocol (LPS) binary. This LPS server provides features like auto-completion, hover information, go-to-definition, and diagnostics for Please build files. It is designed to integrate with editors that support the Language Server Protocol, such as VS Code.

```bash
plz tool lps
```

--------------------------------

### Resolving and Adding Third-Party Go Dependencies with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Demonstrates how to add third-party Go dependencies to a Please project. It uses the `plz run ///go//tools:please_go -- get` command to resolve dependencies and then manually adds them to the `third_party/go/BUILD` file using `go_repo` rules. This allows for explicit versioning and management of external libraries.

```text
$ plz run ///go//tools:please_go -- get github.com/stretchr/testify@v1.8.2
go_repo(module="github.com/objx", version="v0.5.0")
go_repo(module="gopkg.in/yaml.v3", version="v3.0.1")
go_repo(module="gopkg.in/check.v1", version="v0.0.0-20161208181325-20d25e280405")
go_repo(module="github.com/stretchr/testify", version="v1.8.2")
go_repo(module="github.com/davecgh/go-spew", version="v1.1.1")
go_repo(module="github.com/pmezard/go-difflib", version="v1.0.0")
```

```python
# We give direct modules a name and install list so we can reference them nicely
go_repo(
    name = "testify",
    module = "github.com/stretchr/testify", 
    version="v1.8.2",
    # We add the subset of packages we actually depend on here
    install = [
        "assert",
        "require",
    ]
)

# Indirect modules are referenced internally, so we don't have to name them if we don't want to. They can still be 
# referenced by the following build label naming convention: ///third_party/go/github.com_owner_repo//package.
#
# NB: Any slashes in the module name will be replaced by _ 
go_repo(module="github.com/davecgh/go-spew", version="v1.1.1")
go_repo(module="github.com/pmezard/go-difflib", version="v1.0.0")
go_repo(module="github.com/stretchr/objx", version="v0.5.0")
go_repo(module="gopkg.in/yaml.v3", version="v3.0.1")
go_repo(module="gopkg.in/check.v1", version="v0.0.0-20161208181325-20d25e280405")
```

--------------------------------

### Configure Go Toolchain with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Sets up the Go toolchain for Please projects. It includes options for a managed toolchain using `go_toolchain()` rule or using the Go executable from the system PATH. For system PATH usage with Go 1.20+, the standard library must be installed separately.

```python
go_toolchain(
    name = "toolchain",
    version = "1.20",
)

```

```ini
[Plugin "go"]
Target = //plugins:go
ImportPath = github.com/example/module
GoTool = //third_party/go:toolchain|go

```

```ini
[Build]
Path = /usr/local/go/bin:/usr/local/bin:/usr/bin:/bin

```

```shell
$ GODEBUG="installgoroot=all" go install std

```

--------------------------------

### Initialize Go Project with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Initializes a new Go project using Please and sets up the Go module. This involves creating project directories, initializing Please, and setting up the Go module name.

```shell
mkdir getting_started_go && cd getting_started_go
$ plz init 
$ plz init plugin go
$ go mod init github.com/example/module 

```

--------------------------------

### Install Go Module Dependencies (gRPC Example)

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_module.md

This set of rules demonstrates how to install various Go module dependencies, such as 'golang.org/x/sys', 'golang.org/x/net', 'golang.org/x/text', and 'golang.org/x/crypto'. Each rule specifies the module, version, and which parts to install.

```python
go_module(
    name = "xsys",
    module = "golang.org/x/sys",
    install = ["..."],
    version = "v0.0.0-20210415045647-66c3f260301c",
)
```

```python
go_module(
    name = "net",
    install = ["..."],
    module = "golang.org/x/net",
    version = "136a25c244d3019482a795d728110278d6ba09a4",
    deps = [
        ":crypto",
        ":text",
    ],
)
```

```python
go_module(
    name = "text",
    install = [
        "secure/…",
        "unicode/…",
        "transform",
        "encoding/…",
    ],
    module = "golang.org/x/text",
    version = "v0.3.5",
)
```

```python
go_module(
    name = "crypto",
    install = [
        "ssh/terminal",
        "cast5",
    ],
    module = "golang.org/x/crypto",
    version = "7b85b097bf7527677d54d3220065e966a0e3b613",
)
```

--------------------------------

### Initialize a New Plugin

Source: https://github.com/thought-machine/please/blob/master/docs/plugins.html

Quickly get started with creating a new plugin for Please by initializing it for Go, Python, or Java. This command sets up the basic structure for your plugin.

```bash
plz init plugin [go|python|java]
```

--------------------------------

### Build and Run a Python Binary with PEX

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Demonstrates how to build a Python application into a self-executable PEX file using `python_binary()` and then run it. PEX files bundle all Python code and dependencies into a single distributable file.

```shell
$ plz build //src:main
Build finished; total time 50ms, incrementality 100.0%. Outputs:
//src:main:
  plz-out/bin/src/main.pex

$ plz-out/bin/src/main.pex
Bonjour, world!
```

--------------------------------

### Python Hello World Program

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

A simple Python script that prints 'Hello, world!' to the console. This serves as a basic example for creating an executable Python program.

```python
print('Hello, world!')
```

--------------------------------

### Clone Please Codelabs Repository

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/plz_query.md

This command clones the `please-codelabs` repository, which is used for the examples in this tutorial. Ensure you have Git installed and configured.

```bash
git clone https://github.com/thought-machine/please-codelabs

```

--------------------------------

### Initialize Python Project with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Initializes a new project and enables the Python plugin for Please. This sets up the necessary configuration files and directory structure for Python development.

```bash
mkdir getting_started_python && cd getting_started_python
plz init --no_prompt
plz init plugin python
```

--------------------------------

### Initialize Please Plugin for Build Rules

Source: https://github.com/thought-machine/please/blob/master/docs/quickstart.html

After initializing the project configuration, this command can be used to add language-specific build rules by pulling in a plugin. Replace `[plugin]` with the desired plugin name (e.g., `python`, `java`). Refer to the Please documentation for available plugins and more information on their usage.

```bash
plz init plugin [plugin]
```

--------------------------------

### Build a Go Binary with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Defines a Go binary target using the `go_binary` rule in a `BUILD` file. This rule compiles the specified source files into an executable binary. It requires source files to be listed in `srcs`.

```go
package main

import "fmt"

func main(){
	fmt.Println("Hello, world!")
}
```

```python
go_binary(
  name = "main",
  srcs = ["main.go"],
)
```

--------------------------------

### Initialize Project with Please and Go Plugin

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_module.md

This sequence of shell commands initializes a new Go project with Please and installs the Go plugin. It's a starting point for managing Go dependencies within the Please build system.

```shell
$ mkdir go_module && cd go_module
$ go mod init example_module
$ plz init --no_prompt
$ plz init plugin go
```

--------------------------------

### Create and Run a Go Test with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Defines a Go test target using the `go_test` rule and includes it in a `BUILD` file alongside a `go_library`. The `go_test` rule compiles and runs specified Go test source files. Dependencies on libraries are specified using the `deps` argument.

```go
package greetings

import "testing"

func TestGreeting(t *testing.T) {
    if Greeting() == "" {
        panic("Greeting failed to produce a result")
    }
}
```

```python
go_library(
    name = "greetings",
    srcs = ["greetings.go"],
    visibility = ["//src/..."],
)

go_test(
    name = "greetings_test",
    srcs = ["greetings_test.go"],
    # Here we have used the shorthand `:greetings` label format. This format can be used to refer to a rule in the same
    # package and is shorthand for `//src/greetings:greetings`.
    deps = [":greetings"],
)
```

--------------------------------

### Configuring Go Test Dependencies in Please Build File

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Updates the `BUILD` file to include the third-party `testify` dependency for the `greetings_test` target. The `deps` list now includes `//third_party/go:testify`, linking the test executable to the assertion library defined elsewhere in the build configuration.

```python
go_library(
    name = "greetings",
    srcs = ["greetings.go"],
    visibility = ["//src/..."],
)

go_test(
    name = "greetings_test",
    srcs = ["greetings_test.go"],
    deps = [
        ":greetings",
        # Could use a subrepo label i.e. ///third_party/go/github.com_stretchr_testify//assert instead if we want
        "//third_party/go:testify",
    ],
    external = True,
)
```

--------------------------------

### Create a Python Unit Test

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Illustrates how to write a Python unit test using the `unittest` module. This test verifies the functionality of a function within the `greetings` module by asserting its return value.

```python
import unittest
from src.greetings import greetings

class GreetingTest(unittest.TestCase):

    def test_greeting(self):
        self.assertTrue(greetings.greeting())
```

--------------------------------

### Go Cross-Compilation Setup

Source: https://github.com/thought-machine/please/blob/master/docs/cross_compiling.html

This shows how to configure Go cross-compilation with Please. Using the go_toolchain() plugin simplifies the process, making cross-compilation work automatically. If not using go_toolchain, the Go standard library must be installed for the target architecture on the host machine.

```BUILD
# Using go_toolchain() for automatic cross-compilation support
go_toolchain(name = "go_toolchain")

go_binary(name = "my_go_app",
    src = "main.go",
    go_toolchain = ":go_toolchain",
)

# If not using go_toolchain, ensure std lib is installed:
# GOOS="linux" GOARCH="386" go install -i std

```

--------------------------------

### Please Configuration for Go Plugin

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/go_intro.md

Configures the Please build system to use the Go plugin and automatically makes Go build rules available in BUILD files. It also sets the target for the Go plugin and the import path for Go modules.

```ini
[parse]
preloadsubincludes = ///go//build_defs:go ; Makes the Go rules available automatically in BUILD files

[Plugin "go"]
Target = //plugins:go

```

```ini
[Plugin "go"]
Target = //plugins:go
ImportPath = github.com/example/module ; Should match the module name in go.mod

```

--------------------------------

### Set Up Shell Completion for Please

Source: https://github.com/thought-machine/please/blob/master/docs/quickstart.html

This command generates a shell completion script for Please, which can be sourced to enable tab completion for Please subcommands, flags, and build labels. It is recommended to add this to your `.bashrc` or `.zshrc` file for persistent shell completion. The `<()` syntax is a process substitution that allows the output of the command to be treated as a file.

```bash
source <(plz --completion_script)
```

--------------------------------

### Install Please on Linux/macOS/FreeBSD

Source: https://github.com/thought-machine/please/blob/master/docs/faq.html

Installs Please on Linux, macOS, or FreeBSD by downloading and executing an installation script. Ensure you have curl installed. Further language-specific dependencies (like a JDK for Java) might be needed.

```bash
curl https://get.please.build | bash
```

--------------------------------

### Python Main Script Example

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

A simple Python script that imports a function from another module (`src.greetings`) and prints a formatted string. This script serves as the entry point for a `python_binary` target.

```python
from src.greetings import greetings

print(greetings.greeting() + ", world!")
```

--------------------------------

### Configure Please PATH for Python

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Demonstrates how to configure the Please build system's PATH environment variable to include the Python installation directory. This is necessary if Python is not in the default Please PATH.

```ini
[build]
path = $YOUR_PYTHON_INSTALL_HERE:/usr/local/bin:/usr/bin:/bin
```

--------------------------------

### Go Example: Please Cache Operations

Source: https://context7.com/thought-machine/please/llms.txt

This Go program demonstrates how to interact with the Please caching system. It covers creating a build state, initializing the cache, storing and retrieving artifacts, and cleaning cache entries.

```go
package main

import (
    "github.com/thought-machine/please/src/cache"
    "github.com/thought-machine/please/src/core"
)

func main() {
    // Create build state with configuration
    config := core.DefaultConfiguration()
    config.Cache.Dir = "~/.cache/please"
    config.Cache.HTTPURL = "https://cache.example.com"
    config.Cache.Workers = 4

    state := core.NewBuildState(config)

    // Initialize cache from configuration
    c := cache.NewCache(state)
    defer c.Shutdown()

    // Create a build target
    target := core.NewBuildTarget(core.NewBuildLabel("pkg", "target"))
    target.AddOutput("output.txt")

    // Generate cache key from target inputs
    key := []byte("content-hash-key")
    files := []string{"output.txt"}

    // Store artifacts in cache
    c.Store(target, key, files)

    // Retrieve artifacts from cache
    found := c.Retrieve(target, key, files)
    if found {
        println("Cache hit - artifacts restored")
    } else {
        println("Cache miss - need to build")
    }

    // Clean specific target from cache
    c.Clean(target)

    // Clean all cache entries
    c.CleanAll()
}

```

--------------------------------

### BUILD File Syntax Example: Go Library and Tests

Source: https://context7.com/thought-machine/please/llms.txt

This snippet illustrates a typical BUILD file defining a Go library target (`go_library`) with its source files and dependencies, along with a corresponding Go test target (`go_test`). It showcases common attributes like `name`, `srcs`, `visibility`, and `deps`.

```python
# BUILD file example: src/core/BUILD

# Include additional build definitions
subinclude("//build_defs:benchmark")

# Define a Go library target
go_library(
    name = "core",
    srcs = glob(
        ["*.go"],
        exclude = ["*_test.go"],
    ),
    visibility = ["PUBLIC"],
    deps = [
        "///third_party/go/github.com_google_shlex//:shlex",
        "///third_party/go/github.com_zeebo_blake3//:blake3",
        "//src/cli",
        "//src/cli/logging",
        "//src/fs",
        "//src/metrics",
    ],
)

# Define tests for the library
go_test(
    name = "core_test",
    srcs = glob(["*_test.go"]),
    data = ["test_data"],
    deps = [
        ":core",
        "///third_party/go/github.com_stretchr_testify//assert",
        "//src/cli",
    ],
)

```

--------------------------------

### Migrate Go module rule from go_get to go_module

Source: https://github.com/thought-machine/please/blob/master/docs/milestones/16.0.0.html

This snippet shows the migration from the deprecated `go_get()` rule to the new `go_module()` rule in Please v16. `go_module()` offers better compatibility with Go's module fingerprinting introduced in Go 1.15. The key change is how packages are specified: `go_get` uses the `get` parameter with a package path, while `go_module` uses the `module` parameter for the module name and `install` for specific packages within that module.

```go
go_get(
    name = "some_module_foo",
    get = "example.com/some/module/foo/.",
    revision = "v1.0.0",
)
```

```go
go_module(
    name = "some_module_foo",
    module = "example.com/some/module",
    version = "v1.0.0",
    install = ["foo/."],
)
```

--------------------------------

### Initialize Project and Go Plugin

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/k8s.md

Initializes a new project, sets up Go modules, and configures the Go plugin for use with Please. This involves creating a Go toolchain and configuring plugin settings in the Please configuration.

```shell
$ plz init 
go mod init github.com/example/module
$ plz init plugin go
```

--------------------------------

### Install Please Build System via Bash

Source: https://github.com/thought-machine/please/blob/master/README.md

This snippet shows the command to install the Please build system directly from a curl script. It's a quick method for getting the tool onto your system. It assumes a Unix-like environment where curl is available.

```bash
curl -s https://get.please.build | bash
```

--------------------------------

### Define Go Toolchain and Plugin Configuration (Python/INI)

Source: https://context7.com/thought-machine/please/llms.txt

This snippet shows how to define language-specific build rules and toolchain integration using plugins. It includes a Python example for defining a Go toolchain and a commented-out INI example for configuring the plugin in `.plzconfig`.

```Python
# plugins/BUILD - Define plugin targets

go_toolchain(
    name = "go",
    version = "1.24.0",
)

```

```INI
# .plzconfig - Configure plugin
# [Plugin "go"]
# Target = //plugins:go
# ImportPath = github.com/example/project
# GoTool = go

```

--------------------------------

### Please Configuration System (.plzconfig) Example

Source: https://context7.com/thought-machine/please/llms.txt

This INI-style configuration file demonstrates how to set project-wide build settings, language toolchains, caching behavior, and remote execution options in Please. It covers sections like `[please]`, `[build]`, `[cache]`, and language-specific configurations.

```ini
# .plzconfig - Main configuration file

[please]
version = 16.0.0
selfupdate = true
numthreads = 8

[build]
path = /usr/local/bin:/usr/bin:/bin
config = opt
timeout = 600
fallbackconfig = dbg

[buildconfig]
opt = --gc_flags="-c 3"
dbg = --gc_flags="-c 1" --strip=false

[parse]
preloadsubincludes = ///go//build_defs:go

[cache]
dir = ~/.cache/please
httpurl = https://cache.example.com
workers = 8

[Plugin "go"]
Target = //plugins:go
ImportPath = github.com/thought-machine/please
GoTool = go

[python]
moduledir = third_party.python
defaultinterpreter = python3.11

[cpp]
defaultoptcppflags = --std=c++17 -O3
defaultdbgcppflags = --std=c++17 -g

[java]
sourcelevel = 11
targetlevel = 11

[display]
systemstats = true
updatetitle = true

[test]
timeout = 300
defaultcontainer = docker://ubuntu:22.04

[metrics]
prometheusgatewayurl = http://localhost:9091

```

--------------------------------

### Python Greeting Module

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

A Python module that defines a function to return a random greeting. This demonstrates how to create a reusable Python library component.

```python
import random

def greeting():
    return random.choice(["Hello", "Bonjour", "Marhabaan"])

```

--------------------------------

### Install Go Plugin using `plz init`

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/using_plugins.md

Installs the Go language plugin into the current Please project. This command automatically configures the necessary files, including `.plzconfig` and the `plugins/BUILD` file, and creates a `plugins` directory.

```bash
plz init plugin go
tree -a
. 
├── pleasew
├── plugins
│   └── BUILD
├── .plzconfig
└── plz-out
    └── log
        └── build.log

4 directories, 4 files
```

--------------------------------

### Build Target and Label Management in Go

Source: https://context7.com/thought-machine/please/llms.txt

Demonstrates how to create, manipulate, and query build labels in Go using the `core` package. This includes creating labels from strings, handling errors, generating short forms, checking for subpackage expansion, and working with subrepository labels.

```go
package main

import (
    "fmt"
    "github.com/thought-machine/please/src/core"
)

func main() {
    // Create a build label for //src/core:core target
    label := core.NewBuildLabel("src/core", "core")
    fmt.Println(label.String()) // Output: //src/core:core

    // Create label with error handling
    label2, err := core.TryNewBuildLabel("test/pkg", "mytest")
    if err != nil {
        panic(err)
    }

    // Get short form relative to another label
    contextLabel := core.NewBuildLabel("test/pkg", "other")
    shortForm := label2.ShortString(contextLabel) // Returns: :mytest

    // Check if label represents all subpackages
    allLabel := core.BuildLabel{PackageName: "src", Name: "..."}
    if allLabel.IsAllSubpackages() {
        fmt.Println("Matches all subpackages in src/")
    }

    // Work with subrepo labels
    subrepoLabel := core.BuildLabel{
        PackageName: "plugin/path",
        Name:        "target",
        Subrepo:     "third_party",
    }
    fmt.Println(subrepoLabel.String()) // Output: ///third_party//plugin/path:target
}
```

--------------------------------

### C Build Targets Example

Source: https://github.com/thought-machine/please/blob/master/docs/basics.html

Defines a C library, a binary that depends on the library, and a test for the library. This showcases the typical Please build rule setup for C projects.

```c
c_library(
    name = 'my_library',
    srcs = ['file1.c', 'file2.c'],
    hdrs = ['file1.h'],
)

c_binary(
    name = 'my_binary',
    srcs = ['main.c'],
    deps = [':my_library'],
)

c_test(
    name = 'my_library_test',
    srcs = ['my_library_test.c'],
    deps = [':my_library'],
)
```

--------------------------------

### Example of go_module() for Cyclic Dependencies

Source: https://github.com/thought-machine/please/blob/master/docs/milestones/17.0.0.html

This code snippet demonstrates the workaround for cyclic dependencies using `go_module()` by downloading the module and compiling it in parts. It highlights the complexity involved in managing such dependencies with the existing rule.

```Please
go_mod_download(
    name = "go-opentelemetry_download",
    module = "go.opentelemetry.io/otel",
    version = "v1.11.1",
)
go_module(
    name = "go-opentelemetry",
    download = ":go-opentelemetry_download",
    install = [
        ".",
        "baggage",
        "internal",
        "internal/baggage",
        "internal/attribute",
        "internal/global",
        "propagation",
        "semconv/internal",
        "semconv/v1.10.0",
    ],
    module = "go.opentelemetry.io/otel",
    deps = [
        ":go-opentelemetry_trace",
        ":logr",
        ":stdr",
    ],
)
# split off due to go-opentelemetry's circular dependency with go-opentelemetry.trace
go_module(
    name = "go-opentelemetry_1",
    download = ":go-opentelemetry_download",
    install = [
        "attribute",
        "codes",
    ],
    module = "go.opentelemetry.io/otel",
)
```

--------------------------------

### Initialize a Please Repository

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/using_plugins.md

Initializes a new project as a Please repository. This command creates essential configuration files and the `pleasew` wrapper script, setting up the basic structure for using Please in a project.

```bash
plz init
tree -a
. 
├── pleasew
└── .plzconfig

1 directory, 2 files
```

--------------------------------

### Run All Python Tests

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Command to execute all defined Python tests within the specified directory structure. Please aggregates results from all test targets, supporting cross-language testing.

```shell
$ plz test //src/...
//src/greetings:greetings_test 1 test run in 3ms; 1 passed
1 test target and 1 test run in 3ms; 1 passed. Total time 90ms.
```

--------------------------------

### Define a Python Library and Test Target

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Defines a `python_library` for reusable code and a `python_test` for testing that library. The `python_test` rule depends on the `python_library`, and uses shorthand for same-package dependencies.

```python
python_library(
    name = "greetings",
    srcs = ["greetings.py"],
    visibility = ["//src/..."],
)

python_test(
    name = "greetings_test",
    srcs = ["greetings_test.py"],
    # Here we have used the shorthand ":greetings" label format. This format can be used to refer to a rule in the same
    # package and is shorthand for `//src/greetings:greetings`.
    deps = [":greetings"],
)
```

--------------------------------

### Update Python Library with NumPy Dependency

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Modifies a `python_library` to include NumPy as a dependency. This allows the library's code to import and use NumPy functionalities, such as random choices for greetings.

```python
python_library(
    name = "greetings",
    srcs = ["greetings.py"],
    visibility = ["//src/..."],
    deps = ["//third_party/python:numpy"],
)

python_test(
    name = "greetings_test",
    srcs = ["greetings_test.py"],
    deps = [":greetings"],
)
```

--------------------------------

### BUILD File Syntax Example: Filegroup and Genrule

Source: https://context7.com/thought-machine/please/llms.txt

This snippet demonstrates defining a `filegroup` for version information and a `genrule` for executing shell commands, such as code generation. It highlights custom build steps and dynamic target creation using Python loops.

```python
# Define a filegroup for version information
filegroup(
    name = "version",
    srcs = ["VERSION"],
    visibility = ["PUBLIC"],
)

# Custom genrule for code generation
genrule(
    name = "bootstrap",
    srcs = ["bootstrap.sh"],
    outs = ["bootstrap.sh"],
    binary = True,
    cmd = "sed 's/EXCLUDES=\"\"/EXCLUDES=\"%s\"/' $SRC > \"$OUT\"" % CONFIG.get("EXCLUDETEST", ""),
)

# Use loops for dynamic target generation
pages = []
for page in glob(include = ["*.md"]):
    pages += markdown_page(
        name = page.removesuffix(".md"),
        srcs = [page],
        visibility = ["//website/"],
    )

```

--------------------------------

### Configure Python Module Path

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Configuration for the `python` plugin in `.plzconfig` to set the `ModuleDir`. This ensures that third-party modules like NumPy are imported correctly based on their location in the project structure.

```ini
[plugin "python"]
ModuleDir = third_party.python
```

--------------------------------

### Create Executable Python Binary with Please

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Defines a Python binary target using Please. This rule specifies the main Python file to be executed, allowing it to be built and run as an application.

```python
python_binary(
  name = "main",
  main = "main.py",
)
```

--------------------------------

### Please Configuration for Python Plugin

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Configuration snippet for the Please build system, specifically enabling and setting up the Python plugin. It defines build targets and preload paths for Python definitions.

```ini
[parse]
preloadsubincludes = ///python//build_defs:python

[Plugin "python"]
Target = //plugins:python
```

--------------------------------

### Define a Python Binary Target

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

Shows how to define a `python_binary` target in a BUILD file. This rule specifies the main script and any dependencies required for the executable. Dependencies are declared using build labels.

```python
python_binary(
    name = "main",
    main = "main.py",
    # NB: if the package and rule name are the same, you may omit the name i.e. this could be just //src/greetings
    deps = ["//src/greetings:greetings"],
)
```

--------------------------------

### Configure Go Toolchain and Plugin

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/k8s.md

Sets up the Go toolchain and configures the Go plugin within the Please build system. This involves defining a toolchain in a BUILD file and specifying plugin configurations in the configuration file.

```python
go_toolchain(
    name = "toolchain",
    version = "1.20",
)
```

--------------------------------

### Python Functionality Using NumPy

Source: https://github.com/thought-machine/please/blob/master/docs/codelabs/python_intro.md

A Python function that utilizes the NumPy library to select a random greeting from a list. This demonstrates how to integrate third-party libraries into your Python code within the Please build system.

```python
from numpy import random

def greeting():
    return random.choice(["Hello", "Bonjour", "Marhabaan"])
```