Merge pull request #13 from caffeine-addictt/doc-update-for-pre-release-of-v012

Doc update for pre release of v0.1.2

Author: caffeine-addictt

README.md

@@ -75,7 +75,7 @@ _Below is an example of how you can instruct your audience on installing and set
 2. Import thread into your library!
    ```py
    import thread
-   from thread import Thread, ...
+   from thread import Thread, ParallelProcessing
    ```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -96,8 +96,8 @@ Our docs are [here!](/docs/getting-started.md)
 
 - [x] Bug fixes
 - [x] Set Thread class to inherit from threading.Thread
-- [ ] Add kill method
-- [ ] Docs Update
+- [x] Add kill method
+- [x] Docs Update
 - [ ] v0.1.2 Release
 
 See the [open issues](https://github.com/caffeine-addictt/thread/issues) for a full list of proposed features (and known issues).

docs/getting-started.md

@@ -8,13 +8,8 @@ Here's to you get started.
 
 ## Prerequisites
 
-* Python 3.11+
+* Python 3.9+
 
-The project is quite heavily type-annotated, and we use `Concatenate[Any, ...]` in some function declarations.
-However `Python <=3.10` does not support `...` being the last argument as laid out in [this stack overflow question](https://stackoverflow.com/questions/74893354/is-literal-ellipsis-really-valid-as-paramspec-last-argument).
-
-If possible, I may release a sister version of thread that is compatible with `Python 3.9+` in the future, but for the time being,
-support will extend only from Python 3.11+
 
 <br />
 

docs/parallel-processing.md

@@ -94,7 +94,7 @@ my_processor.start()
 
 * **overflow_kwargs : Overflow_In
   > These are arguments parsed to [**thread.Thread**](./threading.md#parameters)<br />
-  > [!NOTE]
+  > [!NOTE]<br />
   > If `args` is present, then it will automatically be removed from kwargs and joined with `overflow_args`
 
 * **Raises** AssertionError: max_threads is invalid
@@ -107,9 +107,9 @@ my_processor.start()
 These are attributes of [`ParallelProcessing`](#importing-the-class) class
 
 * results : List[Data_Out]
-  > The result value
-  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
-  > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
+  > The result value<br />
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)<br />
+  > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)<br />
   > **Raises** [`ThreadStillRunningError`](./exceptions.md#threadStillRunningError)
 
 <br />
@@ -131,10 +131,18 @@ These are methods of [`ParallelProcessing`](#importing-the-class) class
   > Halts the current thread execution until the thread completes
 
 * join : () -> JoinTerminatedStatus
-  > Halts the current thread execution until a thread completes or exceeds the timeout
-  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
+  > Halts the current thread execution until a thread completes or exceeds the timeout<br />
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)<br />
   > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
 
+* kill : (yielding: bool = False, timeout: float = 5) -> bool
+  > Schedules the thread to be killed<br />
+  > If yielding is True, it halts the current thread execution until the thread is killed or the timeout is exceeded<br />
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadnotinitializederror)<br />
+  > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)<br />
+  > [!NOTE]<br />
+  > This only schedules the thread to be killed, and does not immediately kill the thread
+
 <br />
 
 

docs/threading.md

@@ -11,6 +11,7 @@ I will lay out how to use the `thread.Thread` class!
     <li><a href='#parameters'> Parameters </a></li>
     <li><a href='#attributes'> Attributes </a></li>
     <li><a href='#methods'> Class Methods </a></li>
+    <li><a href='#behviours'> Behaviours </a></li>
   </ul>
 </details>
 
@@ -49,9 +50,6 @@ A thread can be ran by invoking the `start()` method
 my_thread.start()
 ```
 
-> [!NOTE]
-> The **threading.Thread()** class from python will only be initialized when **start()** is invoked
-
 <br />
 
 
@@ -83,6 +81,11 @@ my_thread.start()
 * daemon : bool = False
   > This is an argument parsed to `threading.Thread`
 
+* group : None = None
+  > This is an argument parsed to `threading.Thread`<br />
+  > [!NOTE]<br />
+  > This does nothing
+
 * *overflow_args : Overflow_In
   > These are arguments parsed to `threading.Thread`
 
@@ -98,10 +101,13 @@ These are attributes of [`Thread`](#importing-the-class) class
 
 * result : Data_Out
   > The result value of the thread
-  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
-  > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)<br />
+  > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)<br />
   > **Raises** [`ThreadStillRunningError`](./exceptions.md#threadStillRunningError)
 
+* status : str
+  > The current status of the thread
+
 <br />
 
 
@@ -118,18 +124,54 @@ These are methods of [`Thread`](#importing-the-class) class
   > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
 
 * add_hook : ((Data_Out) -> Any | None) -> None
-  > Hooks will be automatically invoked after a thread successfully completes, parsing the return value as the first argument
-  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
+  > Hooks will be automatically invoked after a thread successfully completes, parsing the return value as the first argument<br />
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)<br />
   > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
 
 * get_return_value : () -> Data_Out
   > Halts the current thread execution until the thread completes
 
 * join : () -> JoinTerminatedStatus
-  > Halts the current thread execution until a thread completes or exceeds the timeout
-  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
+  > Halts the current thread execution until a thread completes or exceeds the timeout<br />
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)<br />
   > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
 
+* kill : (yielding: bool = False, timeout: float = 5) -> bool
+  > Schedules the thread to be killed<br />
+  > If yielding is True, it halts the current thread execution until the thread is killed or the timeout is exceeded<br />
+  > **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadnotinitializederror)<br />
+  > **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)<br />
+  > [!NOTE]<br />
+  > This only schedules the thread to be killed, and does not immediately kill the thread
+
+<br />
+
+
+## Behviours
+
+These are a list of thread behvaiours
+
+### Killing Threads - Introduced in v0.1.2
+
+While preferably not utilized, we do support killing threads.<br />
+We mark a thread to be killed, and will only be killed when the thread invokes `sys.settrace()`.
+
+> [!IMPORTANT]<br />
+> This means that if your `target` has a long `time.wait()` call, it will only be killed after it moves onto the next line.
+
+<br />
+
+Want an alternative? Learn about [Daemonized Threads!](https://www.geeksforgeeks.org/python-daemon-threads/)
+
+<br />
+
+
+### Gracefull Exiting - Introduced in v0.1.2
+
+When the program is abruptly stopped with `CTRL+C` for example, active threads will now attempt to gracefully kill itself.<br />
+
+This is not to be an "end-all be-all" for managing threads. You should still try to properly exit a thread before abruptly exiting the program, or utilize a `Daemonized Thread`.
+
 <br />