Normalize Callable naming convention

[vasinov]

Multiple Griptape classes have Callable properties. We use the following naming convention for them:

1. _func. For example SnowflakeSqlDriver.connection_func.
2. _fn. For example, LocalVectorStoreDriver.relatedness_fn.
3. Method-like. For example, BasePromptDriver.prompt_stack_to_string.

The team decided to normalize all callable properties to follow the _fn naming convention.

[collindutter]

After revisiting the naming conventions, we decided against using the _fn suffix, as it felt unpythonic and inconsistent with naming conventions for other field types. For instance, we don't use _str for string fields, so there's no need to treat callables differently.

For callable fields and methods, the following guidelines should be used:

1. Action Functions: Functions that perform an action should be named using a verb or verb phrase that clearly describes what the function does.

   • SnowflakeSqlDriver.connection_func → SnowflakeSqlDriver.create_connection
   • LocalVectorStoreDriver.relatedness_fn → LocalVectorStoreDriver.calculate_relatedness
   • BasePromptDriver.prompt_stack_to_string → BasePromptDriver.convert_prompt_stack_to_string

2. Boolean Functions: Functions that return a boolean should be prefixed with predicates such as is_, has_, or can_ to indicate a state or condition.

3. Event Handlers: Functions that react to events should be prefixed with on_. These functions typically don’t return a value but are triggered in response to an event. If a function transforms an event or returns a value based on it, it should follow the first rule (e.g., process_event).

Keep in mind that these are guidelines, not strict rules, and can be adjusted based on context.

[collindutter]

Some team members have noted that these naming conventions may be more appropriate for class methods than class fields. For example, create_connection could be misinterpreted as a boolean that indicates whether a connection should be created.

To avoid this confusion, we are standardizing class field naming to be noun-based. Below are some of the conventions I landed on in #1275.

*_factory: Used for functions that create a new instance of an object.
*_provider: Used for functions that supply a value. These functions may create new instances, as long as the value represents the same resource or value.
*_formatter: Formats an object or value, typically into a string or another representation.
*_callback: Used for functions that react to or handle a specific event or condition.
*_handler: Used for functions responsible for actively managing or processing an event or task.
*_calculator: Used for functions that compute or derive a specific value.
Again, these aren't hard-and-fast rules, but hopefully they provide a clear framework to guide future naming decisions.

[collindutter]

And finally, after even more discussion we've settled on a variation of the initial proposal:

• Action Functions: Functions that perform an action should be named using a verb or verb phrase that clearly describes what the function does.

  • SnowflakeSqlDriver.connection_func → SnowflakeSqlDriver.create_connection
  • LocalVectorStoreDriver.relatedness_fn → LocalVectorStoreDriver.calculate_relatedness
  • BasePromptDriver.prompt_stack_to_string → BasePromptDriver.convert_prompt_stack_to_string

• Boolean Functions: Functions that return a boolean should be prefixed with predicates such as is_, has_, or can_, indicating a state or condition.

• Callbacks/Hooks: Functions that execute during specific events should be prefixed with on_. This naming convention avoids assumptions about the function's behavior, emphasizing that it reacts to an event.

This article comes closest to summarizing these ideas.

Addressing Previous Points:

• Verbs sound like booleans: While it's true that verbs can resemble boolean names, our extensive use of type hints should minimize ambiguity. Additionally, we can improve our boolean function names over time.
• What happened to nouns?: Attempting to force noun-based names for functions (e.g., "factory" or "provider") felt clunky and could be confusing for users unfamiliar with these terms. A consistent verb-based naming convention, with a few exceptions, is simpler and clearer.