[4/5] Introduce OperationDefinition

[dandavison]

This is PR 4/5 in a stack.

Introduces nexusrpc.OperationDefinition with non-nullable fields. This is the internal counterpart of the user-facing syntactic sugar nexusrpc.Operation.

It also performs a number of variable renames to avoid confusion between the two classes. This PR is pure refactoring without user-facing consequences.

[cretz]

Is there a user-facing use case for this or set_operation? I see we expose this call at the module level to users. I think we'd expect them to operate on a service definition and only we would be the ones translating and setting attributes.

[dandavison]

The only known user of this library at the moment is Temporal (i.e. us, in another role). Temporal are adding additional decorators analogous to sync_operation.

Temporal use set_operation here to "officially" attach the nexusrpc.Operation to the user's operation handler method
https://github.com/temporalio/sdk-python/blob/nexusrpc-update/temporalio/nexus/_decorators.py#L120.

It seems to me that set_operation is an API that the library must expose, for this reason.

Their nexus caller uses get_operation in two situations, both in the situation where their caller invokes an operation by referring directly to the operation handler method (as opposed to the operation definition in the service definition):

1. They need to obtain the operation name used to address the operation (i.e., perhaps the name override from the decorator): https://github.com/temporalio/sdk-python/blob/nexusrpc-update/temporalio/worker/_interceptor.py#L328
2. They also use it to get the output type from the operation https://github.com/temporalio/sdk-python/blob/nexusrpc-update/temporalio/worker/_interceptor.py#L309-L310

[cretz]

It seems to me that set_operation is an API that the library must expose, for this reason.

Hrmm, can end users' (and Temporal's) custom decorators not use the Nexus decorators themselves to mark this?

Their nexus caller uses get_operation in two situations, both in the situation where their caller invokes an operation by referring directly to the operation handler method (as opposed to the operation definition in the service definition)

Hrmm, arguably you should be able to obtain the service definition from the parent of the operation handler method in use. As a user that might want to write something that accepts either an operation contract or an operation handler, can I get the service definition that is on if I need/want it? Can Temporal do the same? Or maybe there's a static call on OperationDefinition to obtain just the operation if they don't care about which service it is on?

Also, why might a user want the nexusrpc.Operation (sugar for the definition) instead of the definition?

[dandavison]

I think these are good questions. Let's merge this as-is since it's forward progress and is ntot changing the public API?

[cretz]

Can we add it to your list so we make sure we don't forget about it? Having these get/set functions as public API at the top-level Nexus module is a bit surprising (not to mention they seem to be the only non-decorator module functions we have in public Nexus API).

[dandavison]

Added to list