bpy.ops.object.align( align_mode='OPT_4' ) throws: keyword "align_mode" unrecognized

Question

I'm not sure how to correctly specify what is written in the blender API documentation. I'm coding:

bpy.ops.object.align( align_mode='OPT_4' )

but get the console error message:

TypeError: Converting py args to operator properties: : keyword "align_mode" unrecognized

The API documentation explains the "align_mode":

bpy.ops.object.align(bb_quality=True, align_mode='OPT_2', relative_to='OPT_4', align_axis={})
Align objects
Parameters
        bb_quality (boolean, (optional)) – High Quality, Enables high quality calculation of the bounding box for perfect results on complex shape meshes with rotation/scale (Slow)
    align_mode (enum in ['OPT_1', 'OPT_2', 'OPT_3'], (optional)) – Align Mode, Side of object to use for alignment

    relative_to (enum in ['OPT_1', 'OPT_2', 'OPT_3', 'OPT_4'], (optional)) –

    Relative To, Reference location to align to

        OPT_1 Scene Origin, Use the scene origin as the position for the selected objects to align to.

        OPT_2 3D Cursor, Use the 3D cursor as the position for the selected objects to align to.

        OPT_3 Selection, Use the selected objects as the position for the selected objects to align to.

        OPT_4 Active, Use the active object as the position for the selected objects to align to.

    align_axis (enum set in {'X', 'Y', 'Z'}, (optional)) – Align, Align to axis

My script (for context):

import bpy
replace imported Mesh Text (selected) with real (editable) Text aligned to old that gets deleted
oldObjects = bpy.context.selected_objects
bpy.ops.object.select_all( action='DESELECT' ) # Deselect all objects
for oldObj in oldObjects:
    bpy.ops.object.select_all( action='DESELECT' ) # Deselect all objects
    bpy.ops.object.text_add(enter_editmode=False, align='WORLD', location=oldObj.location, scale=(1, 1, 1))
# Delete last 4 letters from template "Text" to leave a single Letter "T"
bpy.ops.object.editmode_toggle()
bpy.ops.font.delete(type='PREVIOUS_OR_SELECTION')
bpy.ops.font.delete(type='PREVIOUS_OR_SELECTION')
bpy.ops.font.delete(type='PREVIOUS_OR_SELECTION')
bpy.ops.object.editmode_toggle()

# align new letter to old mesh
print( oldObj.name + str( oldObj.location ) )
oldObj.select_set(True)
bpy.ops.object.align( align_mode='OPT_4' )

# delete oldObj
bpy.ops.object.select_all( action='DESELECT' ) # Deselect all objects
oldObj.select_set(True)
bpy.ops.object.delete()

and yes I know I could replace the align() with:

bpy.ops.object.text_add(enter_editmode=False, align='WORLD', location=oldObj.location, rotation=oldObj.rotation_euler )

but I want to understand better how understand blender API documentation.

Answer 1

To track down the cause of the error shown :.

• Could be a version issue, the docs linked are for current, matching those available circa 2.91

• If you are using an older version, consult the appropriate version docs, or consult the python console.

   >>> bpy.ops.object.align(
  align()
   bpy.ops.object.align(
           bb_quality=True,
  
           align_mode='OPT_2',
           relative_to='OPT_4',
           align_axis=set()
           )
   Align Objects
  

and to quickly see the valid values of any argument, crunch in an invalid one as shown above with align_mode='FOO'.

>>> bpy.ops.object.align(align_mode='OPT_4')
Traceback (most recent call last):
  File "<blender_console>", line 1, in <module>
  File "/home/batfinger/blender/vers/blender-2.91.2-linux64/2.91/scripts/modules/bpy/ops.py", line 132, in __call__
    ret = _op_call(self.idname_py(), None, kw)
TypeError: Converting py args to operator properties:  enum "FOO" not found in ('OPT_1', 'OPT_2', 'OPT_3')
&gt;&gt;&gt; bpy.ops.object.align(align_mode='OPT_4')
Traceback (most recent call last):
  File &quot;&lt;blender_console&gt;&quot;, line 1, in &lt;module&gt;

File "/home/batfinger/blender/vers/blender-2.91.2-linux64/2.91/scripts/modules/bpy/ops.py", line 132, in call
    ret = _op_call(self.idname_py(), None, kw)
TypeError: Converting py args to operator properties:  enum "OPT_4" not found in ('OPT_1', 'OPT_2', 'OPT_3')

• It could be the case some addon you have enabled has overridden the default operator.

• As displayed above this will be evident by typing bpy.ops.object.align( to autocomplete, into python console to display the operator docstring

With API calls (ie no operators).

As is the case for most operators can be replaced with API calls.

eg Here I've simply placed a text object, each sharing the data (single letter "T") at global location of each of the selected objects, before removing. Changing transform based on whatever the desired align operator properties would be little to no hassle.

import bpy
from bpy import context
# font
font = bpy.data.curves.new("Foo", 'FONT')
font.body = "T"
for ob in context.selected_objects:
    text = bpy.data.objects.new("Text", font)
    text.matrix_world = ob.matrix_world
    context.collection.objects.link(text)
    bpy.data.objects.remove(ob)