Python Package Minimal File Structure for llpkg

[PengPengPeng717]

Python Package Minimal File Structure for llpkg

📁 Directory Structure

py/
└── {package_name}/                    # Python package directory
    ├── llpkg.cfg                      # Package configuration
    ├── llpyg.cfg                      # Python binding configuration
    ├── go.mod                         # Go module definition
    ├── go.sum                         # Go dependency lock
    └── {package_name}.go              # Go binding code

📋 Required Files

1. llpkg.cfg - Package Configuration

Purpose: Defines the basic package information including type, upstream source, and Python-specific settings.

Required Fields:

• type: Must be "python"
• upstream.installer.name: Package manager (e.g., "pip")
• upstream.package.name: Python package name
• upstream.package.version: Package version
• llpyg.mod_name: Go module path
• llpyg.output_dir: Output directory for generated files
• llpyg.mod_depth: Module depth for Go bindings

Example:

{
  "type": "python",
  "upstream": {
    "installer": {
      "name": "pip"
    },
    "package": {
      "name": "tqdm",
      "version": "4.66.3"
    }
  },
  "llpyg": {
    "output_dir": "./test",
    "mod_name": "github.com/PengPengPeng717/llpkg/py/tqdm",
    "mod_depth": 1
  }
}

2. llpyg.cfg - Python Binding Configuration

Purpose: Configures how Python modules are bound to Go code.

Required Fields:

• name: Python module name
• libName: Library name for Go bindings
• modules: List of Python modules to bind

Example:

{
  "name": "tqdm",
  "libName": "tqdm",
  "modules": [
    "tqdm"
  ]
}

3. go.mod - Go Module Definition

Purpose: Defines the Go module path and dependencies.

Required Fields:

• module: Go module path (must match llpkg.cfg mod_name)
• go: Go version requirement
• require: Dependencies (typically github.com/goplus/lib)

Example:

module github.com/PengPengPeng717/llpkg/py/tqdm

go 1.24.5

require github.com/goplus/lib v0.3.0

4. go.sum - Go Dependency Lock

Purpose: Locks dependency versions to ensure consistent builds.

Content: Automatically generated by Go module system.

Example:

github.com/goplus/lib v0.3.0 h1:example_hash_here
github.com/goplus/lib v0.3.0/go.mod h1:example_hash_here

5. {package_name}.go - Go Binding Code

Purpose: Contains the main Go bindings for Python functions and constants.

Required Elements:

• Package declaration
• Import statements (including github.com/goplus/lib/py)
• Function declarations with //go:linkname directives
• Constant definitions
• LLGoPackage constant

Example:

package tqdm

import (
	"github.com/goplus/lib/py"
	_ "unsafe"
)

const LLGoPackage = "py.tqdm"

//go:linkname TqdmPandas py.tqdm_pandas
func TqdmPandas(tclass *py.Object) *py.Object

//go:linkname Tqdm py.tqdm
func Tqdm(iterable *py.Object, desc *py.Object, total *py.Object, leave *py.Object, file *py.Object, ncols *py.Object, mininterval *py.Object, maxinterval *py.Object, miniters *py.Object, ascii *py.Object, disable *py.Object, unit *py.Object, unit_scale *py.Object, dynamic_ncols *py.Object, smoothing *py.Object, bar_format *py.Object, initial *py.Object, position *py.Object, postfix *py.Object, unit_divisor *py.Object, write_bytes *py.Object, lock_args *py.Object, nrows *py.Object, colour *py.Object, delay *py.Object, gui *py.Object, **kwargs) *py.Object

🔗 File Relationships

llpkg.cfg (Package Info) 
    ↓
llpyg.cfg (Python Module Binding)
    ↓
go.mod (Go Module Definition)
    ↓
go.sum (Dependency Lock)
    ↓
{package}.go (Go Bindings)
    ↓
llpkgstore install/generate

📊 File Summary

File	Purpose	Required
llpkg.cfg	Package configuration	✅
llpyg.cfg	Python binding config	✅
go.mod	Go module definition	✅
go.sum	Dependency lock	✅
{package}.go	Go binding code	✅

Total Required Files: 5

📝 Example: Complete tqdm Package

py/tqdm/
├── llpkg.cfg          # Package configuration
├── llpyg.cfg          # Python binding configuration  
├── go.mod             # Go module definition
├── go.sum             # Go dependency lock
└── tqdm.go            # Go binding code

This structure provides the minimal required files for a Python package in the llpkg ecosystem, enabling seamless integration between Python libraries and Go applications.