What do the different options for subtype enumerator in StringProperty do?

Question

bpy.props.StringProperty has [‘FILE_PATH’, ‘DIR_PATH’, ‘FILE_NAME’, ‘BYTE_STRING’, ‘PASSWORD’, ‘NONE’] as options, but nowhere are those documented.

It seams simple enough to guess what FILE_PATH, DIR_PATH, and FILE_NAME do, but what do they all do?
Are these actually documented somewhere?

Answer 1

bpy.props.StringProperty.subtype

FILE_PATH

Use for storing file paths. Adds a button to the UI property markup, that when used sets the string to the file path chosen. Option to make it a relative path.

DIR_PATH

Use for storing directory paths. Adds a button to the UI property markup, that when used sets the string to the directory path chosen.

FILE_NAME

AFAICT is for, as the name suggests storing a filename. Filenames cannot contain certain characters. It doesn't appear to in anyway auto-parse. The Paint Palettes addon uses the subtype for preset file names. The following method is used to parse out illegal / invalid chars.

def as_filename(name):  # could reuse for other presets
    for char in " !@#$%^&*(){}:\";'[]<>,.\\/?":
        name = name.replace(char, '_')
    return name.lower().strip()

BYTE_STRING

Stores the string as a utf-8 encoded byte string. Equivalent of "string".encode().

PASSWORD

Displays asterisks (*) when input is typed in the UI. Stores the string as entered.

NONE

Default. None of the above.

Run a script and see.

Like any code we can run and see, the worst thing that can happen is your computer explodes, starts a fire an burns down your city.

Here is a test script to set a string property of each subtype to the window manager, and display them in a panel (using the simple panel template code) as well as write their value to system console on change.

import bpy
from bpy.props import StringProperty

subtypes = ['FILE_PATH', 'DIR_PATH', 'FILE_NAME', 'BYTE_STRING', 'PASSWORD', 'NONE']

def print_value(subtype):
    def print_value(self, context):
        print(subtype, getattr(self, subtype))
    return print_value

for st in subtypes:
    setattr(bpy.types.WindowManager,
            st, 
            StringProperty(subtype=st, update=print_value(st)))


class HelloWorldPanel(bpy.types.Panel):
    """Creates a Panel in the Object properties window"""
    bl_label = "Hello World Panel"
    bl_idname = "OBJECT_PT_hello"
    bl_space_type = 'PROPERTIES'
    bl_region_type = 'WINDOW'
    bl_context = "object"

    def draw(self, context):
        wm = context.window_manager
        layout = self.layout
        for st in subtypes:
            layout.prop(wm, st)

def register():
    bpy.utils.register_class(HelloWorldPanel)

def unregister():
    bpy.utils.unregister_class(HelloWorldPanel)

if __name__ == "__main__":
    register()

Here is the result.

and the result of setting all to "xxxxxx" in the panel written to system console.

FILE_PATH xxxxxx
DIR_PATH xxxxxx
FILE_NAME xxxxxx
BYTE_STRING b'xxxxxx'
PASSWORD xxxxxx
NONE xxxxxx