Bail

from ArtisanPlugin.Scripting import BailApi

The bail is the loop soldered or fused to the top of a pendant so a chain can pass through it. Artisan builds it as a tapered arch swept along a ring profile - wider where it meets the pendant, narrower at the top - and can add a torus O-ring hanging from it.

Create

ids = BailApi.Create(plane = ..., diameterTop = 3, diameterBottom = 1, distance = 5,
                     withORing = False, name = None, profile = None,
                     topWidth = 4, topHeight = 1.4, bottomWidth = 1, bottomHeight = 1,
                     topProfile = None, bottomProfile = None,
                     startingOnTop = 0.5, startingOnBottom = 0.5, curveTension = 1,
                     oRingThickness = 1, oRingDiameter = 2, oRingOverlap = 1,
                     oRingRotation = 0, element = None)                  # -> [ids]

Parameter	Default	Meaning
plane	active CPlane	Placement plane. If omitted or invalid, the active view’s construction plane is used, then Plane.WorldXY
diameterTop	3	Diameter at the top of the arch, mm
diameterBottom	1	Diameter where the bail meets the pendant, mm
distance	5	Height of the bail, mm
topWidth / topHeight	4 / 1.4	Wire cross-section at the top, mm. This, not the diameters, is what drives the weight
bottomWidth / bottomHeight	1 / 1	Wire cross-section at the bottom, mm
profile	saved/default	A RING_PROFILE asset name (or "id:<n>") for both the top and the bottom
topProfile / bottomProfile	—	The same, for one end only. These override profile
startingOnTop / startingOnBottom	0.5	Where the side curves leave the top loop and reach the bottom one
curveTension	1	Tension of the side curves
withORing	False	True also builds the torus O-ring. False builds none
oRingThickness / oRingDiameter / oRingOverlap	1 / 2 / 1	O-ring size, mm
oRingRotation	0	O-ring rotation, degrees
name	"Bail"	Name stored on the component, shown in the Outliner
element	—	A saved Bail element (for example the factory BL001) to start from

Millimetres follow the house 0-keeps-default convention: 0 means “use the tool’s default, or my saved defaults”. The three curve-shape arguments and oRingRotation, where 0 is a meaningful value, keep their default when omitted.

Create returns the ids of the created breps: one for the bail itself, plus a second for the O-ring when there is one. The breps are added as Artisan brep objects on the metal layer, so the bail is weighed with the piece, and they get the document’s metal material. They are gathered into a single group that carries the serialised parameters in user data. That group is what makes the component editable afterwards.

Where the starting values come from

1. With element: the preset replaces the whole starting model. A profile you pass replaces both of its profiles. withORing = False keeps the preset’s own O-ring choice, and True forces one.
2. Without element: the ring-profile asset is resolved first. Your saved bail defaults replace the model, but only when you pass no profile at all (profile, topProfile or bottomProfile). If you ask for a profile, pass the other dimensions you care about alongside it.
3. Every explicit argument is then applied on top.

This is a licensed mutation, so it needs a valid licence, and it fails with “No active document.” when there is none. If the geometry cannot be computed with the given numbers, it raises “Bail computation failed with the given parameters.” and nothing is added. Wrap the call in a Transaction to get one-step undo.

Edit

A bail stays editable after creation: SmartComponentApi finds it from any of its pieces and edits its parameters by path, keeping the same ids:

from ArtisanPlugin.Scripting import BailApi, SmartComponentApi, Transaction

with Transaction.Begin("Heavier bail"):
    ids = BailApi.Create(element = "BL001", withORing = True)
    bail = SmartComponentApi.Find(ids[0])
    bail.SetParameters('{"DiameterTop": 3.5, "TopProfile": {"Width": 4.5}}')

Through MCP, use create_bail to create and edit_object to edit, for example {"top_profile.width": 4.5}.