Improve error handling for `args` in `Thread` to prevent confusion with iterable arguments that are not a `list` or `tuple` (such as a `string`)

[MattiHayes]

Feature or enhancement

Proposal:

Improve error handling for args in Thread to prevent confusion with iterable arguments that are not a list or tuple

Hey! This isn’t a major change, just something I noticed recently while working with threading.Thread.

If you accidentally pass a string into the args parameter , it leads to confusing runtime errors that could be caught earlier.

Example

import threading

def greet(name):
    print(f"Hello, {name}!")

# Common mistake: passing a string instead of a tuple
t = threading.Thread(target=greet, args="World")
t.start()

Will produce:

TypeError: greet() takes 1 positional argument but 5 were given

But the following code

import threading

def greet(name):
    print(f"Hello, {name}!")

# Common mistake: passing a string instead of a tuple
t = threading.Thread(target=greet, args=1)
t.start()

Will produce this error message

TypeError: __main__.greet() argument after * must be an iterable, not int

Suggested Improvement

Add an explicit check in threading.Thread.__init__ to verify that:

1. args is an iterable, and
2. it's not a string or bytes-like object.

I was thinking something like

if isinstance(args, (str, bytes)) or not hasattr(args, '__iter__'):
    raise TypeError(f"'args' must be a non-string iterable like tuple or list, not {type(args).__name__}")

I think this could help improve clarity and catch beginner mistakes while also being backward-compatible with existing valid usage.

Contribution

I’d be happy to submit a pull request for this change, along with a test case. Please let me know if this enhancement would be welcome—or if it makes sense to consider adding similar checks for other Thread constructor parameters.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-131540: Improve type checking error for args in threading.Thread objects #131582

[ZeroIntensity]

I think it makes sense to add a check for __iter__, but changing bytes or str here would technically be a breaking change. Something like this is currently valid:

def whatever(a, b, c):
    ...

thread = Thread(target=whatever, args="abc")  # splats to ("a", "b", "c")
thread.start()  # whatever("a", "b", "c")

But I'm not sure if people are actually doing this in practice.

[MattiHayes]

Hi thanks for pointing that out!

Yeah, I see now that this would technically be a breaking change. I’m not sure how often people are actually doing that in practice—or whether they should be—since the docs mention that args should be a tuple or a list.

Would it make sense to raise a warning when a string object is passed? That way, it wouldn’t break existing code immediately, but it would give users better context and maybe nudge them toward the intended usage.

I'm happy to change anything if there is a better approach.