<commit_before># threading-extensions
Some useful, well-tested extensions of threading.Thread

# StoppableThread
Thread with internal stop event.  To properly work, the `run` method or `target` function MUST check for changes in the stop event.  If using `target`, the stop event will be passed in as the last argument.

Example using `run`:

    class DoSomethingThread(StoppableThread):
        def run(self):
            while not self._stop.is_set():
                do_something()
                # use this in place of time.sleep b/c wait is interrupted by stop events
                # and will immediately exit
                self._stop.wait(10)
    
    dt = DoSomethingThread()
    dt.start()
    assert(dt.is_alive() is True)
    assert(dt.stopped is False)
    dt.stop()
    assert(dt.is_alive() is False)
    assert(dt.stopped is True)

Example using `target`, `args` and `kwargs`:

    def infinite_running_target(x, stop_event, y=None):
       # x & y are examples
        while not stop_event.is_set():
            do_something()
            # use this in place of time.sleep b/c wait is interrupted by stop events
            # and will immediately exit
            stop_event.wait(1)
    
    st = StoppableThread(target=infinite_running_target, args=(1,), kwargs={"y": 2})
    st.start()
    assert(st.is_alive() is True)
    assert(st.stopped is False)
    st.stop()
    assert(st.is_alive() is False)
    assert(st.stopped is True)

# ExceptionThread
Thread that propogates exceptions raised in the thread to the main context on `join`.  To properly work using the class method `run`, implement `run_with_exception` method instead.

Example using `run_with_exception`:

    class RaiseThread(ExceptionThread):
        def run_with_exception(self):
            raise ValueError('eep!')
    
    rt = RaiseThread()
    rt.start()
    rt.join() # ValueError: 'eep!'

Example using `target`, `args` and `kwargs`:

    def raises_exception_target(x, y=None):
        # x & y are examples
        raise ValueError('eep!')
    
    et = Thread(target=raises_exception_target, args=(1,), kwargs={"y": 2})
    et.start()
    et.join() # ValueError: 'eep!'

# StoppableExceptionThread
Thread that is both stoppable AND propogates exceptions to the main context on `join`. To properly work, use the `run_with_exceptions` method in place of `run`.

See above examples.

Happy Threading!
<commit_msg>more commenting<commit_after># threading-extensions
Some useful, well-tested extensions of threading.Thread

# StoppableThread
Thread with internal stop event.  To properly work, the `run` method or `target` function MUST check for changes in the stop event.  If using `target`, the stop event will be passed in as the last argument.

Example using `run`:

    class DoSomethingThread(StoppableThread):
        def run(self):
            while not self._stop.is_set():
                do_something()
                # use this in place of time.sleep b/c wait is interrupted by stop events
                # and will immediately exit
                self._stop.wait(10)
    
    dt = DoSomethingThread()
    dt.start()
    assert(dt.is_alive() is True)
    assert(dt.stopped is False)
    dt.stop()
    assert(dt.is_alive() is False)
    assert(dt.stopped is True)

Example using `target`, `args` and `kwargs`:

    def infinite_running_target(x, stop_event, y=None):
       # x & y are examples
        while not stop_event.is_set():
            do_something()
            # use this in place of time.sleep b/c wait is interrupted by stop events
            # and will immediately exit
            stop_event.wait(1)
    
    st = StoppableThread(target=infinite_running_target, args=(1,), kwargs={"y": 2})
    st.start()
    assert(st.is_alive() is True)
    assert(st.stopped is False)
    st.stop()
    assert(st.is_alive() is False)
    assert(st.stopped is True)

# ExceptionThread
Thread that propogates exceptions raised in the thread to the main context on `join`.  To properly work using the class method `run`, implement `run_with_exception` method instead.

Example using `run_with_exception`:

    class RaiseThread(ExceptionThread):
        def run_with_exception(self):
            raise ValueError('eep!')
    
    rt = RaiseThread()
    rt.start()
    rt.join() # ValueError: 'eep!'

Example using `target`, `args` and `kwargs`:

    def raises_exception_target(x, y=None):
        # x & y are examples
        raise ValueError('eep!')
    
    et = Thread(target=raises_exception_target, args=(1,), kwargs={"y": 2})
    et.start()
    et.join() # ValueError: 'eep!'

# StoppableExceptionThread
Thread that is both stoppable AND propogates exceptions to the main context on `join`. To properly work using the class method `run`, implement `run_with_exception` method instead.

See above examples.

Happy Threading!

{'fraction_non_alphanumeric': 0.0962809917355372, 'fraction_numerical': 0.002892561983471074, 'mean_word_length': 2.9518367346938774, 'pattern_counts': {'":': 4, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1386539', 'n_tokens_mistral': 1435, 'n_tokens_neox': 1409, 'n_words': 486}