main,bind: extended gopy:name control, auto PEP8 naming, and property docstring support

This commit provides an option to automatically rename functions, methods, and properties to PEP-style snake_case when generating code.

Author: justinfx

_examples/rename/rename.go

@@ -5,15 +5,37 @@
 // package rename tests changing the names of methods and functions
 package rename
 
-// gopy:name say_hi
+// gopy:name say_hi_fn
+// Comment follows the tag and function should be renamed
+// to say_hi_fn
 func SayHi() string {
 	return "hi"
 }
 
+// I should be renamed to auto_renamed_func, when generated
+// with -rename flag
+func AutoRenamedFunc() {
+
+}
+
+// MyStruct has two fields
 type MyStruct struct {
+	// I should be renamed to auto_renamed_property
+	// when generated with -rename flag
+	AutoRenamedProperty string
+
+	// I should be renamed to custom_name with the custom option
+	AutoRenamedProperty2 string `gopy:"custom_name"`
 }
 
+// A method that says something
 // gopy:name say_something
-func (s *MyStruct) SaySomething() (something string) {
+func (s *MyStruct) SaySomethingFunc() (something string) {
 	return "something"
 }
+
+// I should be renamed to auto_renamed_meth, when generated
+// with -rename flag
+func (s *MyStruct) AutoRenamedMeth() {
+
+}

_examples/rename/test.py

@@ -7,7 +7,19 @@
 
 import rename
 
-print(rename.say_hi())
-print(rename.MyStruct().say_something())
+print("say_hi_fn():", rename.say_hi_fn())
+print("MyStruct().say_something():", rename.MyStruct().say_something())
+
+# Just make sure the symbols exist
+rename.auto_renamed_func()
+struct = rename.MyStruct()
+struct.auto_renamed_meth()
+_ = struct.auto_renamed_property
+struct.auto_renamed_property = "foo"
+_ = struct.custom_name
+struct.custom_name = "foo"
+
+print("MyStruct.auto_renamed_property.__doc__:", rename.MyStruct.auto_renamed_property.__doc__.strip())
+print("MyStruct.custom_name.__doc__:", rename.MyStruct.custom_name.__doc__.strip())
 
 print("OK")

bind/bind.go

@@ -26,6 +26,8 @@ type BindCfg struct {
 	VM string
 	// package prefix used when generating python import statements
 	PkgPrefix string
+	// rename Go exported symbols to python PEP snake_case
+	RenameCase bool
 }
 
 // ErrorList is a list of errors

bind/gen_func.go

@@ -83,7 +83,12 @@ func (g *pyGen) genFuncSig(sym *symbol, fsym *Func) bool {
 		return false
 	}
 
-	gname, gdoc, err := extractPythonName(fsym.GoName(), fsym.Doc())
+	gname := fsym.GoName()
+	if g.cfg.RenameCase {
+		gname = toSnakeCase(gname)
+	}
+
+	gname, gdoc, err := extractPythonName(gname, fsym.Doc())
 	if err != nil {
 		return false
 	}

bind/gen_struct.go

@@ -183,11 +183,25 @@ func (g *pyGen) genStructMemberGetter(s *Struct, i int, f types.Object) {
 		return
 	}
 
+	gname := f.Name()
+	if g.cfg.RenameCase {
+		gname = toSnakeCase(gname)
+	}
+
+	if newName, err := extractPythonNameFieldTag(gname, s.Struct().Tag(i)); err == nil {
+		gname = newName
+	}
+
 	cgoFn := fmt.Sprintf("%s_%s_Get", s.ID(), f.Name())
 
 	g.pywrap.Printf("@property\n")
-	g.pywrap.Printf("def %[1]s(self):\n", f.Name())
+	g.pywrap.Printf("def %[1]s(self):\n", gname)
 	g.pywrap.Indent()
+	if gdoc := g.pkg.getDoc(s.Obj().Name(), f); gdoc != "" {
+		g.pywrap.Printf(`"""`)
+		g.pywrap.Printf(gdoc)
+		g.pywrap.Println(`"""`)
+	}
 	if ret.hasHandle() {
 		cvnm := ret.pyPkgId(g.pkg.pkg)
 		g.pywrap.Printf("return %s(handle=_%s.%s(self.handle))\n", cvnm, pkgname, cgoFn)
@@ -224,10 +238,19 @@ func (g *pyGen) genStructMemberSetter(s *Struct, i int, f types.Object) {
 		return
 	}
 
+	gname := f.Name()
+	if g.cfg.RenameCase {
+		gname = toSnakeCase(gname)
+	}
+
+	if newName, err := extractPythonNameFieldTag(gname, s.Struct().Tag(i)); err == nil {
+		gname = newName
+	}
+
 	cgoFn := fmt.Sprintf("%s_%s_Set", s.ID(), f.Name())
 
-	g.pywrap.Printf("@%s.setter\n", f.Name())
-	g.pywrap.Printf("def %[1]s(self, value):\n", f.Name())
+	g.pywrap.Printf("@%s.setter\n", gname)
+	g.pywrap.Printf("def %[1]s(self, value):\n", gname)
 	g.pywrap.Indent()
 	g.pywrap.Printf("if isinstance(value, go.GoClass):\n")
 	g.pywrap.Indent()

bind/gen_varconst.go

@@ -36,6 +36,9 @@ func (g *pyGen) genVarGetter(v *Var) {
 	gopkg := g.pkg.Name()
 	pkgname := g.cfg.Name
 	cgoFn := v.Name() // plain name is the getter
+	if g.cfg.RenameCase {
+		cgoFn = toSnakeCase(cgoFn)
+	}
 	qCgoFn := gopkg + "_" + cgoFn
 	qFn := "_" + pkgname + "." + qCgoFn
 	qVn := gopkg + "." + v.Name()
@@ -76,6 +79,9 @@ func (g *pyGen) genVarSetter(v *Var) {
 	gopkg := g.pkg.Name()
 	pkgname := g.cfg.Name
 	cgoFn := fmt.Sprintf("Set_%s", v.Name())
+	if g.cfg.RenameCase {
+		cgoFn = toSnakeCase(cgoFn)
+	}
 	qCgoFn := gopkg + "_" + cgoFn
 	qFn := "_" + pkgname + "." + qCgoFn
 	qVn := gopkg + "." + v.Name()

bind/package.go

@@ -6,6 +6,7 @@ package bind
 
 import (
 	"fmt"
+	"go/ast"
 	"go/doc"
 	"go/types"
 	"path/filepath"
@@ -109,7 +110,7 @@ func (p *Package) AddPyImport(ipath string, extra bool) {
 // parent is the name of the containing scope ("" for global scope)
 func (p *Package) getDoc(parent string, o types.Object) string {
 	n := o.Name()
-	switch o.(type) {
+	switch tp := o.(type) {
 	case *types.Const:
 		for _, c := range p.doc.Consts {
 			for _, cn := range c.Names {
@@ -120,6 +121,38 @@ func (p *Package) getDoc(parent string, o types.Object) string {
 		}
 
 	case *types.Var:
+		if tp.IsField() && parent != "" {
+			// Find the package-scoped struct
+			for _, typ := range p.doc.Types {
+				_ = typ
+				if typ.Name != parent {
+					continue
+				}
+				// Name matches package-scoped struct.
+				// Make sure it is a struct type.
+				for _, spec := range typ.Decl.Specs {
+					typSpec, ok := spec.(*ast.TypeSpec)
+					if !ok {
+						continue
+					}
+					structSpec, ok := typSpec.Type.(*ast.StructType)
+					if !ok {
+						continue
+					}
+					// We have the package-scoped struct matching the parent name.
+					// Find the matching field.
+					for _, field := range structSpec.Fields.List {
+						for _, fieldName := range field.Names {
+							if fieldName.Name == tp.Name() {
+								return field.Doc.Text()
+							}
+						}
+					}
+				}
+
+			}
+		}
+		// Otherwise just check the captured vars
 		for _, v := range p.doc.Vars {
 			for _, vn := range v.Names {
 				if n == vn {

bind/utils.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"reflect"
 	"regexp"
 	"strconv"
 	"strings"
@@ -197,19 +198,78 @@ func getGoVersion(version string) (int64, int64, error) {
 	return major, minor, nil
 }
 
+var (
+	rxValidPythonName = regexp.MustCompile(`^[\pL_][\pL_\pN]+$`)
+)
+
 func extractPythonName(gname, gdoc string) (string, string, error) {
-	const PythonName = "\ngopy:name "
-	i := strings.Index(gdoc, PythonName)
+	const (
+		PythonName   = "gopy:name "
+		NLPythonName = "\n" + PythonName
+	)
+	i := -1
+	var tag string
+	// Check for either a doc string that starts with our tag,
+	// or as the first token of a newline
+	if strings.HasPrefix(gdoc, PythonName) {
+		i = 0
+		tag = PythonName
+	} else {
+		i = strings.Index(gdoc, NLPythonName)
+		tag = NLPythonName
+	}
 	if i < 0 {
 		return gname, gdoc, nil
 	}
-	s := gdoc[i+len(PythonName):]
+	s := gdoc[i+len(tag):]
 	if end := strings.Index(s, "\n"); end > 0 {
-		validIdPattern := regexp.MustCompile(`^[\pL_][\pL_\pN]+$`)
-		if !validIdPattern.MatchString(s[:end]) {
+		if !isValidPythonName(s[:end]) {
 			return "", "", fmt.Errorf("gopy: invalid identifier: %s", s[:end])
 		}
 		return s[:end], gdoc[:i] + s[end:], nil
 	}
 	return gname, gdoc, nil
 }
+
+// extractPythonNameFieldTag parses a struct field tag and returns
+// a new python name. If the tag is not defined then the original
+// name is returned.
+// If the tag name is specified but is an invalid python identifier,
+// then an error is returned.
+func extractPythonNameFieldTag(gname, tag string) (string, error) {
+	const tagKey = "gopy"
+	if tag == "" {
+		return gname, nil
+	}
+	tagVal := reflect.StructTag(tag).Get(tagKey)
+	if tagVal == "" {
+		return gname, nil
+	}
+	if !isValidPythonName(tagVal) {
+		return "", fmt.Errorf("gopy: invalid identifier for struct field tag: %s", tagVal)
+	}
+	return tagVal, nil
+}
+
+// isValidPythonName returns true if the string is a valid
+// python identifier name
+func isValidPythonName(name string) bool {
+	if name == "" {
+		return false
+	}
+	return rxValidPythonName.MatchString(name)
+}
+
+var (
+	rxMatchFirstCap = regexp.MustCompile("([A-Z])([A-Z][a-z])")
+	rxMatchAllCap   = regexp.MustCompile("([a-z0-9])([A-Z])")
+)
+
+// toSnakeCase converts the provided string to snake_case.
+// Based on https://gist.github.com/stoewer/fbe273b711e6a06315d19552dd4d33e6
+func toSnakeCase(input string) string {
+	output := rxMatchFirstCap.ReplaceAllString(input, "${1}_${2}")
+	output = rxMatchAllCap.ReplaceAllString(output, "${1}_${2}")
+	output = strings.ReplaceAll(output, "-", "_")
+	return strings.ToLower(output)
+}

cmd_build.go

@@ -40,6 +40,7 @@ ex:
 	cmd.Flag.String("main", "", "code string to run in the go main() function in the cgo library")
 	cmd.Flag.String("package-prefix", ".", "custom package prefix used when generating import "+
 		"statements for generated package")
+	cmd.Flag.Bool("rename", false, "rename Go symbols to python PEP snake_case")
 	cmd.Flag.Bool("symbols", true, "include symbols in output")
 	cmd.Flag.Bool("no-warn", false, "suppress warning messages, which may be expected")
 	cmd.Flag.Bool("no-make", false, "do not generate a Makefile, e.g., when called from Makefile")
@@ -59,6 +60,7 @@ func gopyRunCmdBuild(cmdr *commander.Command, args []string) error {
 	cfg.Main = cmdr.Flag.Lookup("main").Value.Get().(string)
 	cfg.VM = cmdr.Flag.Lookup("vm").Value.Get().(string)
 	cfg.PkgPrefix = cmdr.Flag.Lookup("package-prefix").Value.Get().(string)
+	cfg.RenameCase = cmdr.Flag.Lookup("rename").Value.Get().(bool)
 	cfg.Symbols = cmdr.Flag.Lookup("symbols").Value.Get().(bool)
 	cfg.NoWarn = cmdr.Flag.Lookup("no-warn").Value.Get().(bool)
 	cfg.NoMake = cmdr.Flag.Lookup("no-make").Value.Get().(bool)

cmd_exe.go

@@ -47,6 +47,7 @@ ex:
 		"-- defaults to GoPyMainRun() but typically should be overriden")
 	cmd.Flag.String("package-prefix", ".", "custom package prefix used when generating import "+
 		"statements for generated package")
+	cmd.Flag.Bool("rename", false, "rename Go symbols to python PEP snake_case")
 	cmd.Flag.Bool("symbols", true, "include symbols in output")
 	cmd.Flag.String("exclude", "", "comma-separated list of package names to exclude")
 	cmd.Flag.String("user", "", "username on https://www.pypa.io/en/latest/ for package name suffix")
@@ -74,6 +75,7 @@ func gopyRunCmdExe(cmdr *commander.Command, args []string) error {
 	cfg.Main = cmdr.Flag.Lookup("main").Value.Get().(string)
 	cfg.VM = cmdr.Flag.Lookup("vm").Value.Get().(string)
 	cfg.PkgPrefix = cmdr.Flag.Lookup("package-prefix").Value.Get().(string)
+	cfg.RenameCase = cmdr.Flag.Lookup("rename").Value.Get().(bool)
 	cfg.Symbols = cmdr.Flag.Lookup("symbols").Value.Get().(bool)
 	cfg.NoWarn = cmdr.Flag.Lookup("no-warn").Value.Get().(bool)
 	cfg.NoMake = cmdr.Flag.Lookup("no-make").Value.Get().(bool)