RFC: A better name for TaskResult

[RealOrangeOne]

The name of TaskResult was copied from Celery, which uses a similar name for the handle to a given task. This naming however could be confusing, as it in itself isn't the "result" of the task (that's at .result).

Therefore, is there a better and more descriptive name for this?

Yes, naming things is hard!

[mgax]

The model is currently DBTaskResult which I think has a couple of issues:

• DB is implied because it's part of the django_tasks_database app.
• Result is somewhat misleading, because the model doesn't only represent a task's result, but also its arguments, routing information and status.

To be honest I'd vote for the short and simple name Task.

[mgax]

I've just noticed there's already a django_tasks.task.Task class so naming the model Task would certainly cause confusion. Perhaps DBTask would not be too bad then :)

[RealOrangeOne]

DBTaskResult is the DB version of a TaskResult - it's the TaskResult name I don't like. Sticking a DB prefix on whatever we call it is a fine name IMO.

I agree calling it a "result" when it's not really a result is a little confusing. But oddly, Celery seems to do this just fine. RQ deals with this by not having an equivilent for Task, and calling the running item a Job. I know DLQ uses Task and Job for the config and running item. I like that model, but the 2 are used by some people interchangeably.

[hooverdc]

TaskInstance, as in you've enqueued an instance of that task?

[RealOrangeOne]

The issue with "instance" is that it already has a definition, and gets a bit confusing and odd to talk about. "A TaskInstance" and "A Task instance" sound identical. Not to mention "A TaskInstance instance" sounds a little heavy-handled

[hooverdc]

Ah, good points.

[jhthompson]

What about TaskRun? Since it seems like this class represents a single "run" of a particular "task"?

[hooverdc]

TaskExecution if you want to be wordier.

[jhthompson]

Could work too! I like the terseness of TaskRun, but that might just be me.

[hooverdc]

On a reread I like TaskRun more than my suggestion.

[jhthompson]

Made a PR for this change here: #101 to gauge interest!

[RealOrangeOne]

Perhaps the correct solution here is actually to flip it. Instead, rename TaskResult to Task, and find a better name for Task. It feels more natural to me to ask "Did that task run?" where "task" is the thing which ran, as opposed to the configuration for it.

Perhaps the task decorator returns a new type subclassing Task, as opposed to an instance of a Task, so "Task instance" becomes a sensible name again, and somewhat matches the behaviour of models.

[jhthompson]

I like this!

What about the @task decorator? Are we okay with the disconnect between the naming of that decorator now returning a TaskConfiguration instead of a Task?

We could do:

@configure_task
def do_the_thing()
    return None

or

@task_configuration
def do_the_thing()
    return None

But I think I would be fine with leaving it as @task, it's a lot cleaner.

[RealOrangeOne]

That would be a breaking change, but I suspect you're right that the naming should be consistent.

I'll have a think and a play later today on sensible namings and refactoring.

[RealOrangeOne]

I don't think "TaskDefinition" works, as you end up with "A definition of a TaskDefinition", which is a little heavy-handed.

My intention had been to be inspired by some other queue libraries. However, most either don't distinguish between the 2, use ambiguous words (eg "Task" and "Job"), or use similar names to what there is now 😅

[RealOrangeOne]

I suspect not distinguishing is the way to go. The "Task" is the definition, and it's an instance of it which is run. Changing the @task to be a class itself rather than an instance of Task might help cement that, and allows for much more customization in future.
I'm going to have a play around.

[jhthompson]

Yeah maybe not distinguishing is the way to go... Just out of curiosity after you mentioned it, I went through a bunch of other library/frameworks and tried to figure out what they called these things:

Library	"definition" / "configuration"	"instance"
celery	Task	Result
huey	Task	Result
laravel	Job	N/A
rq	any function / @job	Job
sidekiq	Job	N/A

[RealOrangeOne]

I've addressed one side of this in #103, but I'm still not completely happy with the naming.