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)

[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