Establish BackendFromEnv machinery

Author: b-long

bind/backend.go

@@ -0,0 +1,65 @@
+// Copyright 2026 The go-python Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package bind
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+// BackendEnvVar is the environment variable that selects which tool is used
+// to bind the generated cgo shim to CPython.
+const BackendEnvVar = "GOPY_BACKEND"
+
+// Backend names a CPython binding tool.
+type Backend string
+
+const (
+	BackendPyBindGen Backend = "pybindgen" // default
+	BackendCFFI      Backend = "cffi"
+	BackendPyBind11  Backend = "pybind11"
+	BackendNanobind  Backend = "nanobind"
+	BackendCAPI      Backend = "capi"
+	BackendCGO       Backend = "cgo"
+)
+
+// backends lists every known backend and whether gopy can generate it yet.
+var backends = []struct {
+	name        Backend
+	implemented bool
+}{
+	{BackendPyBindGen, true},
+	{BackendCFFI, false},
+	{BackendPyBind11, false},
+	{BackendNanobind, false},
+	{BackendCAPI, false},
+	{BackendCGO, false},
+}
+
+// BackendFromEnv returns the backend selected by GOPY_BACKEND.
+// An unset or empty variable selects pybindgen.
+func BackendFromEnv() (Backend, error) {
+	return parseBackend(os.Getenv(BackendEnvVar))
+}
+
+func parseBackend(v string) (Backend, error) {
+	v = strings.ToLower(strings.TrimSpace(v))
+	if v == "" {
+		return BackendPyBindGen, nil
+	}
+	names := make([]string, len(backends))
+	for i, b := range backends {
+		names[i] = string(b.name)
+		if string(b.name) != v {
+			continue
+		}
+		if !b.implemented {
+			return "", fmt.Errorf("gopy: %s=%q is not implemented yet", BackendEnvVar, v)
+		}
+		return b.name, nil
+	}
+	return "", fmt.Errorf("gopy: unknown %s=%q (valid values: %s)", BackendEnvVar, v, strings.Join(names, ", "))
+}

bind/backend_test.go

@@ -0,0 +1,46 @@
+// Copyright 2026 The go-python Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package bind
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParseBackend(t *testing.T) {
+	for _, tc := range []struct {
+		in      string
+		want    Backend
+		errPart string
+	}{
+		{in: "", want: BackendPyBindGen},
+		{in: "pybindgen", want: BackendPyBindGen},
+		{in: " PyBindGen ", want: BackendPyBindGen},
+		{in: "cffi", errPart: "not implemented yet"},
+		{in: "bogus", errPart: "unknown GOPY_BACKEND"},
+	} {
+		got, err := parseBackend(tc.in)
+		if tc.errPart != "" {
+			if err == nil || !strings.Contains(err.Error(), tc.errPart) {
+				t.Errorf("parseBackend(%q): got err=%v, want error containing %q", tc.in, err, tc.errPart)
+			}
+			continue
+		}
+		if err != nil || got != tc.want {
+			t.Errorf("parseBackend(%q) = %q, %v; want %q", tc.in, got, err, tc.want)
+		}
+	}
+}
+
+func TestBackendFromEnv(t *testing.T) {
+	t.Setenv(BackendEnvVar, "")
+	if got, err := BackendFromEnv(); err != nil || got != BackendPyBindGen {
+		t.Errorf("unset: got %q, %v", got, err)
+	}
+	t.Setenv(BackendEnvVar, "bogus")
+	if _, err := BackendFromEnv(); err == nil {
+		t.Error("bogus value: want error")
+	}
+}

gen.go

@@ -63,6 +63,9 @@ func genOutDir(odir string) (string, error) {
 // mode = gen, build, pkg, exe
 func genPkg(mode bind.BuildMode, cfg *BuildCfg) error {
 	var err error
+	if _, err = bind.BackendFromEnv(); err != nil {
+		return err
+	}
 	cfg.OutputDir, err = genOutDir(cfg.OutputDir)
 	if err != nil {
 		return err