codegen

README

(codegen)= (crosscode)=

Code generation

Code generation is essential to Pulumi's ability to support both a variety of programming languages and a variety of cloud providers. This package defines the core components of Pulumi's code generation functionality (known as Pulumi CrossCode). At a high level, code generation is used to manage three categories of output: SDKs, programs, and documentation. At a lower level, these all make use of a number of shared concepts such as schema and Pulumi Configuration Language (PCL).

:::{toctree} :maxdepth: 1 :titlesonly:

/pkg/codegen/sdks.md /pkg/codegen/programs.md /pkg/codegen/schema/README /pkg/codegen/pcl/README :::

Documentation

Index

• func CleanDir(dirPath string, exclusions StringSet) error
• func ExpandShortEnumName(name string) string
• func FilterExamples(description string, lang string) string
• func GenGitAttributesFile() []byte
• func IsNOptionalInput(t schema.Type) bool
• func IsProvideDefaultsFuncRequired(t schema.Type) bool
• func IsWireDiscriminatableUnionType(u *schema.UnionType) bool
• func MapInnerType(t schema.Type, f func(schema.Type) schema.Type) schema.Type
• func MapOptionalType(t schema.Type, f func(schema.Type) schema.Type) schema.Type
• func OptionalType(p *schema.Property) schema.Type
• func PackageReferences(pkg *schema.Package) []schema.PackageReference
• func PkgEquals(p1, p2 schema.PackageReference) bool
• func PlainType(t schema.Type) schema.Type
• func PushOptionalIntoInput(t schema.Type) schema.Type
• func RequiredType(p *schema.Property) schema.Type
• func ResolvedType(t schema.Type) schema.Type
• func SimplifyInputUnion(t schema.Type) schema.Type
• func UnwrapType(t schema.Type) schema.Type
• func VisitType(schemaType schema.Type, visitor func(t schema.Type))
• func VisitTypeClosure(properties []*schema.Property, visitor func(t schema.Type))
• type DocLanguageHelper
• type Fs
  • func (fs Fs) Add(path string, contents []byte)
• type Set
  • func (s Set) Add(v any)
  • func (s Set) Delete(v any)
  • func (s Set) Has(v any) bool
• type StringSet
  • func NewStringSet(values ...string) StringSet
  • func (ss StringSet) Add(s string)
  • func (ss StringSet) Any() bool
  • func (ss StringSet) Contains(subset StringSet) bool
  • func (ss StringSet) Delete(s string)
  • func (ss StringSet) Except(s string) StringSet
  • func (ss StringSet) Has(s string) bool
  • func (ss StringSet) SortedValues() []string
  • func (ss StringSet) Subtract(other StringSet) StringSet
  • func (ss StringSet) Union(other StringSet) StringSet

Functions

func CleanDir

func CleanDir(dirPath string, exclusions StringSet) error

CleanDir removes all existing files from a directory except those in the exclusions list. Note: The exclusions currently don't function recursively, so you cannot exclude a single file in a subdirectory, only entire subdirectories. This function will need improvements to be able to target that use-case.

func ExpandShortEnumName

func ExpandShortEnumName(name string) string

func FilterExamples

func FilterExamples(description string, lang string) string

FilterExamples filters the code snippets in a schema docstring to include only those that target the given language.

func GenGitAttributesFile

func GenGitAttributesFile() []byte

A .gitattributes file allows us to mark filepath patterns as containing generated content. This enables git tools to treat these files differently, for example GitHub will show these files as collapsed by default.

func IsNOptionalInput

func IsNOptionalInput(t schema.Type) bool

func IsProvideDefaultsFuncRequired

func IsProvideDefaultsFuncRequired(t schema.Type) bool

If a helper function needs to be invoked to provide default values for a plain type. The provided map cannot be reused.

func IsWireDiscriminatableUnionType

func IsWireDiscriminatableUnionType(u *schema.UnionType) bool

IsWireDiscriminatableUnionType checks whether u is wire discriminatable when known: given a fully-known protobuf wire value and the union's type information, the member the value belongs to can always be determined.

The union's members are flattened through optional, input, token, and nested union wrappers; the union is discriminatable when at most one member admits null and no wire value is comatchable with two members: no value belongs to both. Types are compared by their wire shape (bool, number, string, list, dict, asset, archive, resource reference); asset, archive, and resource-reference values carry signature keys that separate them from plain dicts, and resource references of different types are separated by the type embedded in their URNs. Within a shape:

• int and number share the number shape, since all wire numbers arrive as float64.
• Enums reduce to their sets of literal values: two members of one primitive shape are disjoint only when both are literal-bounded with disjoint sets.
• Lists never separate and neither do two maps: their empty values are indistinguishable. A map and an object are disjoint only when some required property of the object cannot co-match the map's element type.
• Two objects share a value exactly when each one's required properties are all declared by the other and every property required by either side admits a common value — recursively by type, with a constant property narrowed to a single-valued enum so its bound distributes through unions and optionals. This assumes closed objects: a value carries only the properties its member declares. The union's declared Discriminator is not trusted; only this structural evidence counts. A common value is finite, so co-matchability is a least fixpoint: recursion through cyclic object graphs reports false on revisits, which makes required-recursive object pairs — types with no finite values at all — vacuously disjoint.

Must match sdk/python/lib/pulumi/_types.py's _wire_matches.

func MapInnerType

func MapInnerType(t schema.Type, f func(schema.Type) schema.Type) schema.Type

MapInnerType applies f to the first non-wrapper type in t. MapInnerType does not mutate it's input, and t should not either.

func MapOptionalType

func MapOptionalType(t schema.Type, f func(schema.Type) schema.Type) schema.Type

Applies f to the first non-optional type in t. If t is Optional{v} then returns Optional{f(v)}, otherwise f(t) is returned

func OptionalType

func OptionalType(p *schema.Property) schema.Type

OptionalType wraps the Property's type in an OptionalType if it is not already optional.

func PackageReferences

func PackageReferences(pkg *schema.Package) []schema.PackageReference

PackageReferences returns a list of packages that are referenced by the given package.

func PkgEquals

func PkgEquals(p1, p2 schema.PackageReference) bool

Check if two packages are the same.

func PlainType

func PlainType(t schema.Type) schema.Type

PlainType deeply removes any InputTypes from t, with the exception of argument structs. Use ResolvedType to unwrap argument structs as well.

func PushOptionalIntoInput

func PushOptionalIntoInput(t schema.Type) schema.Type

PushOptionalIntoInput rewrites Optional(Input(T)) to Input(Optional(T))

func RequiredType

func RequiredType(p *schema.Property) schema.Type

RequiredType unwraps the OptionalType enclosing the Property's type, if any.

func ResolvedType

func ResolvedType(t schema.Type) schema.Type

ResolvedType deeply removes any InputTypes from t.

func SimplifyInputUnion

func SimplifyInputUnion(t schema.Type) schema.Type

func UnwrapType

func UnwrapType(t schema.Type) schema.Type

UnwrapType removes any outer OptionalTypes and InputTypes from t.

func VisitType

func VisitType(schemaType schema.Type, visitor func(t schema.Type))

func VisitTypeClosure

func VisitTypeClosure(properties []*schema.Property, visitor func(t schema.Type))

Types

type DocLanguageHelper

type DocLanguageHelper interface {
	// GetModuleName returns the in-language name of the module.
	//
	// For example, lets get the hypothetical name of the module for the "pkg:module/nestedMod:Type" token in python:
	//
	//	var python python_codegen.DocLanguageHelper
	//	python.GetModuleName(pkgRef, pkgRef.TokenToModule("pkg:module/nestedMod:Type")) // "module.nestedmod"
	GetModuleName(pkg schema.PackageReference, modName string) string

	GetPropertyName(p *schema.Property) (string, error)
	GetEnumName(e *schema.Enum, typeName string) (string, error)
	// GetTypeName gets the name of a type in the language of the DocLanguageHelper.
	//
	// relativeToModule describes the module that is consuming the type
	// name. Typically, GetTypeName will output an unqualified name if typ is native
	// to relativeToModule. Otherwise GetTypeName may return a qualified name.
	// relativeToModule should always be a module returned from pkg.TokenToModule. It
	// should not be language specialized.
	//
	// For example, lets get the name of a hypothetical python property type:
	//
	//	var pkg *schema.Package = getOurPackage(/* Schema{
	//		Name: "pkg",
	//		Resource: []{
	//			{
	//				Token: "pkg:myModule:Resource",
	//				Properties: []{
	//					{
	//						Type: Object{Name: "pkg:myModule:TheType"},
	//						Name: "theType",
	//					},
	//				},
	//			},
	//		},
	//	} */)
	//	var res *schema.Resource = pkg.Resources[i]
	//	var prop *schema.Property := res.Properties[j]
	//
	//	var python python_codegen.DocLanguageHelper
	//
	//	unqualifiedName := python.GetTypeName(pkg, prop.Type, false, pkg.TokenToModule(res.Token))
	//	fmt.Println(unqualifiedName) // Prints "TheType".
	//
	//	qualifiedName := python.GetTypeName(pkg, prop.Type, false, "")
	//	fmt.Println(qualifiedName) // Prints "my_module.TheType"
	GetTypeName(pkg schema.PackageReference, t schema.Type, input bool, relativeToModule string) string
	// GetResourceName returns the name of the resource.
	//
	// Implements should prefer a short name if possible: "MyResource" over "Pulumi.MyPackage.MyModule.MyResource".
	GetResourceName(r *schema.Resource) string
	GetFunctionName(f *schema.Function) string

	// GetResourceFunctionResultName returns the name of the result type when a static resource function is used to lookup
	// an existing resource.
	GetResourceFunctionResultName(modName string, f *schema.Function) string

	// Methods
	GetMethodName(m *schema.Method) string
	GetMethodResultName(pkg schema.PackageReference, modName string, r *schema.Resource, m *schema.Method) string

	// ResolveDocRef renders a single `{{% ref %}}` shortcode target as a name in the target
	// language (e.g. PascalCase types in Go, snake_case properties in Python). Callers typically
	// use this as the resolver callback passed to schema.PackageReference.InterpretPulumiRefs.
	//
	// selfRef identifies the entity whose documentation is being rendered. Property refs that
	// belong to that entity are emitted unqualified (e.g. `prop` rather than `Self.prop`). Pass
	// the zero `schema.DocRef{}` if there is no enclosing entity.
	//
	// The boolean return mirrors `schema.PulumiRefResolver`: false means the ref could not be
	// resolved and the caller should fall back to a default rendering. The error return is for
	// setup failures (e.g. Go's package-context map cannot be built); successful resolution to
	// "ref not found" returns `("", false, nil)`.
	ResolveDocRef(pkg schema.PackageReference, selfRef, ref schema.DocRef) (string, bool, error)

	// Doc links
	GetDocLinkForResourceType(pkg *schema.Package, moduleName, typeName string) string
	GetDocLinkForPulumiType(pkg *schema.Package, typeName string) string
	GetDocLinkForResourceInputOrOutputType(pkg *schema.Package, moduleName, typeName string, input bool) string
	GetDocLinkForFunctionInputOrOutputType(pkg *schema.Package, moduleName, typeName string, input bool) string
}

DocLanguageHelper is an interface for extracting language-specific information from a Pulumi schema. See the implementation for this interface under each of the language code generators.

type Fs

type Fs map[string][]byte

A simple in memory file system.

func (Fs) Add

func (fs Fs) Add(path string, contents []byte)

Add a new file to the Fs.

Panic if the file is a duplicate.

type Set

type Set map[any]struct{}

func (Set) Add

func (s Set) Add(v any)

func (Set) Delete

func (s Set) Delete(v any)

func (Set) Has

func (s Set) Has(v any) bool

type StringSet

type StringSet map[string]struct{}

func NewStringSet

func NewStringSet(values ...string) StringSet

func (StringSet) Add

func (ss StringSet) Add(s string)

func (StringSet) Any

func (ss StringSet) Any() bool

func (StringSet) Contains

func (ss StringSet) Contains(subset StringSet) bool

Contains returns true if all elements of the subset are also present in the current set. It also returns true if subset is empty.

func (StringSet) Delete

func (ss StringSet) Delete(s string)

func (StringSet) Except

func (ss StringSet) Except(s string) StringSet

StringSet.Except returns the string set setminus s.

func (StringSet) Has

func (ss StringSet) Has(s string) bool

func (StringSet) SortedValues

func (ss StringSet) SortedValues() []string

func (StringSet) Subtract

func (ss StringSet) Subtract(other StringSet) StringSet

Subtract returns a new string set with all elements of the current set that are not present in the other set.

func (StringSet) Union

func (ss StringSet) Union(other StringSet) StringSet