threading module is missing basic/introductory usage example

[matkoniecz]

Documentation

threading module is missing basic/introductory usage example

documentation start from some general notes which may have its place there and jump into "This module defines the following functions: threading.active_count()"

Would it be maybe possible to have an example of basic standard usage? For "my Python script is CPU-limited, I want to use more than one core"

the closest that I found is https://docs.python.org/3/library/threading.html#threading.Thread.run that does not really explain at all how it is actually supposed to be used even for a toy example

(I will probably find tutorial somewhere, maybe chatgpt/deepseek will produce something but I would love to have an official example that I can assume to be a good idea rather than finding something that seems to work)

Linked PRs

• gh-124210: Add introduction to threading docs #127046
• [3.14] gh-124210: Add introduction to threading docs (GH-127046) #134090
• [3.13] gh-124210: Add introduction to threading docs (GH-127046) #134091

[matkoniecz]

I am not claiming that it is a good code (I was in fact looking in docs as I have no clear idea how ideal/typical code is expected to look like) but following seems to work and sort-of-demonstrates threading (admittedly, this one does not demonstrate that GIL was worked around but I am going to trust docs that it will work also for CPU-heavy things):

import threading
import time

class SingleScan():
    def __init__(self, link):
        self.link = link

    def crawl(self):
        print("CRAWL STARTED for", self.link)
        time.sleep(3)
        print("CRAWL ENDED for", self.link)

s = SingleScan("https://example.com")
t1 = threading.Thread(target = s.crawl)
t1.start()

s = SingleScan("http://example.com")
t2 = threading.Thread(target = s.crawl)
t2.start()

(yes, code above is likely terrible, that is why I tried checking official docs first)

BTW, I was initially confused as I had s.crawl() and it was sequential but without obvious failures :)

[gaogaotiantian]

my Python script is CPU-limited, I want to use more than one core

You can't :(. At least for now.

If you read the docs, it's actually mentioned in the very early section in "CPython implementation detail".

I'm not a docs expert, but I think people have different opinions of docs. I'm not against examples in docs but I think most of the time Python docs gives examples immediately after the documented methods. What you are looking for might be a "tutorial" about how to use threading module - which is something that Python tries to cover for many aspects (https://docs.python.org/3/howto/index.html).

[matkoniecz]

oh right, in such case https://docs.python.org/3/library/multiprocessing.html#module-multiprocessing should be used which actually has a basic example

still, it would be nice for threading to have something comparable

[ZeroIntensity]

Would you like to submit a PR for that?

[matkoniecz]

Sadly, I am not able as I have no idea what is the proper way to code this. Unless something like #124210 (comment) is actually a good example.

[ZeroIntensity]

It's a working example, but maybe we want something that has args and kwargs with it.

[donBarbos]

what about next example:

import threading
import time

def crawl(link, delay=3):
    print(f"crawl started for {link}")
    time.sleep(delay)
    print(f"crawl ended for {link}")

links = [
    "https://example.com",
    "https://another-example.com",
    "https://yet-another-example.com"
]

# Start threads for each link
threads = []
for link in links:
    # Using `args` to pass positional arguments and `kwargs` for keyword arguments
    t = threading.Thread(target=crawl, args=(link,), kwargs={"delay": 2})
    threads.append(t)
    t.start()

# Wait for all threads to finish
for t in threads:
    t.join()

[ZeroIntensity]

I like it :)

[hridyasadanand]

Hi! I’m Hridya, a first-year BTech student learning Python. I’d love to work on this issue as part of my GSoC preparation. Can I take it?

[ZeroIntensity]

There's already a PR up, but reviewing PRs is a great way to contribute as well.