gopy

README

GoPy

GoPy provides various utilities for working with PyPi packages in Go.

See the module documentation for usage.

Documentation

Index

• func IsValidIdentifier(name string) bool
• func IsValidModuleName(name string) bool
• func IsValidPackageName(name string, flatLayout bool) bool
• type FindPackagesOptions
• type PackageDiscoveryResult
  • func FindPackages(ctx context.Context, root string, opts *FindPackagesOptions) (*PackageDiscoveryResult, error)
• type PackageLayout

Functions

func IsValidIdentifier

func IsValidIdentifier(name string) bool

IsValidIdentifier checks if a string is a valid Python identifier.

func IsValidModuleName

func IsValidModuleName(name string) bool

IsValidModuleName reports whether name is a valid Python module name.

func IsValidPackageName

func IsValidPackageName(name string, flatLayout bool) bool

IsValidPackageName reports whether name is a valid Python package name.

When flatLayout is true, it applies stricter validation to the root package, allowing PEP 561 stub packages (ending in "-stubs") but requiring all other root packages to be valid Python identifiers.

All package components must be valid Python identifiers, except for PEP 561 stub packages at the root level.

Types

type FindPackagesOptions

type FindPackagesOptions struct {
	Exclude []string // Glob patterns of packages to exclude from discovery.
	Include []string // Glob patterns of packages to include in discovery (default: all).
}

FindPackagesOptions contains configuration for package discovery

type PackageDiscoveryResult

type PackageDiscoveryResult struct {
	Packages   map[string]string // Map of relative paths and package names.
	Modules    map[string]string // Map of relative paths and module names.
	Layout     PackageLayout
	Name       string // Suggested project name.
	UsesPEP420 bool   // Whether PEP 420 namespace packages were detected.
}

PackageDiscoveryResult contains the results of package discovery

func FindPackages

func FindPackages(ctx context.Context, root string, opts *FindPackagesOptions) (*PackageDiscoveryResult, error)

FindPackages discovers Python packages and modules in a directory tree, analyzing project structure to determine the appropriate layout pattern.

The function examines the directory structure starting from root and identifies Python packages (directories containing __init__.py or namespace packages per PEP 420) and standalone modules (.py files). It supports both src-layout (packages under src/) and flat-layout (packages at root level) project structures.

For src-layout projects, FindPackages searches within the src/ subdirectory. For flat-layout projects, it applies conservative exclusion patterns to avoid including common non-package directories like tests, docs, and build artifacts.

The discovery process respects the provided options:

• Include patterns specify which packages to include (defaults to "*" for all)
• Exclude patterns specify which packages to exclude from discovery
• Patterns support shell-style wildcards via filepath.Match

FindPackages returns a PackageDiscoveryResult containing:

• Packages: map of relative file paths to Python package names
• Modules: map of relative file paths to Python module names
• Layout: detected project layout (SrcLayout, FlatLayout, or UnknownLayout)
• Name: suggested project name derived from discovered packages/modules
• UsesPEP420: whether PEP 420 namespace packages were detected

For flat-layout projects with multiple top-level packages or modules, FindPackages returns an error to prevent accidental inclusion of unrelated code.

Example usage:

opts := FindPackagesOptions{
  Exclude: []string{"tests", "docs"},
  Include: []string{"mypackage*"},
}
result, err := FindPackages(ctx, "/path/to/project", opts)
if err != nil {
  // handle error
}
fmt.Printf("Found %d packages using %v layout\n", len(result.Packages), result.Layout)

type PackageLayout

type PackageLayout int

PackageLayout represents the different Python project layouts.

const (
	UnknownLayout PackageLayout = iota
	SrcLayout
	FlatLayout
	SingleModule
)