Skip to content

Commit fc0092f

Browse files
caffeine-addicttcaffeine-addictt
committed
+ basic docs
1 parent 7a4846d commit fc0092f

File tree

3 files changed

+331
-0
lines changed

3 files changed

+331
-0
lines changed

‎docs/getting-started.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Getting started with thread
2+
3+
Thanks for using thread! I hope you find it useful for your projects.
4+
5+
Here's to you get started.
6+
7+
---
8+
9+
## Prerequisites
10+
11+
* Python 3.11+
12+
13+
The project is quite heavily type-annotated, and we use `Concatenate[Any, ...]` in some function declarations.
14+
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).
15+
16+
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,
17+
support will extend only from Python 3.11+
18+
19+
<br />
20+
21+
22+
## Installing
23+
24+
### From pip (Recommended)
25+
```sh
26+
pip install thread
27+
```
28+
29+
### Building from source (Not Recommended)
30+
```sh
31+
# Clone this repository
32+
git clone https://github.com/caffeine-addictt/thread
33+
34+
# Install dependencies
35+
pip install poetry
36+
37+
# Build the distribution
38+
python3 -m poetry build
39+
40+
# Install the distribution
41+
pip install -e .
42+
```
43+
44+
<br />
45+
46+
47+
## Importing thread
48+
49+
Import thread into your .py file
50+
```py
51+
import thread
52+
```
53+
54+
Now you have successfully installed thread!
55+
56+
[See here](./threading.md) for how to using the `thread.Thread` class!

‎docs/parallel-processing.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Parallel Processing Documentation
2+
3+
I will lay out how to use the `thread.ParallelProcessing` class!
4+
5+
<br />
6+
<details>
7+
<summary>Jump to</summary>
8+
<ul>
9+
<li><a href='#importing-the-class'> Import the class</a></li>
10+
<li><a href='#initializing-a-thread'> Initialize a thread </a></li>
11+
</ul>
12+
</details>
13+
14+
15+
Don't have the thread library? [See here](./getting-started.md) for installing thread
16+
17+
---
18+
19+
## Importing the class
20+
21+
```py
22+
from thread import ParallelProcessing
23+
```
24+
25+
<br />
26+
27+
28+
## How does it work?
29+
30+
Parallel Processing works best by optimizing data processing with large datasets.
31+
32+
What it does:
33+
```py
34+
dataset = [1, 2, 3, ..., 2e10]
35+
36+
# Splits into chunks as evenly as possible
37+
# thread_count = min(max_threads, len(dataset))
38+
# n == len(chunks) == len(thread_count)
39+
chunks = [[1, 2, 3, ...], [50, 51, 52, ...], ...]
40+
41+
# Initialize and run n threads
42+
# each thread handles 1 chunk of data and parses it into the function
43+
44+
# processed data is arranged back in order
45+
46+
# processed data is returned as a list[Data_Out]
47+
```
48+
49+
<br />
50+
51+
52+
## Initializing a parallel process
53+
54+
A simple example
55+
```py
56+
def my_data_processor(Data_In) -> Data_Out: ...
57+
58+
# Reccommended way
59+
my_processor = ParallelProcessing(
60+
function = my_data_processor,
61+
dataset = [i in range(0, n)]
62+
)
63+
64+
# OR
65+
# Not the reccommended way
66+
my_processor = ParallelProcessing(my_data_processor, [i in range(0, n)])
67+
```
68+
69+
It can be ran by invoking the `start()` method
70+
```py
71+
my_processor.start()
72+
```
73+
74+
> [!NOTE]
75+
> The **threading.ParallelProcessing()** class from python will only be initialized when **start()** is invoked
76+
77+
<br />
78+
79+
80+
### Parameters
81+
82+
* function : (DataProcessor, dataset, *args, **kwargs) -> Any | Data_Out
83+
> This should be a function that takes in a dataset and/or anything and returns Data_Out and/or anything
84+
85+
* dataset : Sequence[Data_In] = ()
86+
> This should be an interable sequence of arguments parsed to the `DataProcessor` function<br />
87+
> (e.g. tuple('foo', 'bar'))
88+
89+
* *overflow_args : Overflow_In
90+
> These are arguments parsed to [**thread.Thread**](./threading.md#parameters)
91+
92+
* **overflow_kwargs : Overflow_In
93+
> These are arguments parsed to [**thread.Thread**](./threading.md#parameters)<br />
94+
> [!NOTE]
95+
> If `args` is present, then it will automatically be removed from kwargs and joined with `overflow_args`
96+
97+
* **Raises** AssertionError: max_threads is invalid
98+
99+
<br />
100+
101+
102+
### Attributes
103+
104+
These are attributes of [`ParallelProcessing`](#importing-the-class) class
105+
106+
* results : List[Data_Out]
107+
> The result value
108+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
109+
> **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
110+
> **Raises** [`ThreadStillRunningError`](./exceptions.md#threadStillRunningError)
111+
112+
<br />
113+
114+
115+
### Methods
116+
117+
These are methods of [`ParallelProcessing`](#importing-the-class) class
118+
119+
* start : () -> None
120+
> Initializes the threads and starts it<br />
121+
> **Raises** [`ThreadStillRunningError`](./exceptions.md#threadStillRunningError)
122+
123+
* is_alive : () -> bool
124+
> Indicates whether the thread is still alive<br />
125+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
126+
127+
* get_return_values : () -> Data_Out
128+
> Halts the current thread execution until the thread completes
129+
130+
* join : () -> JoinTerminatedStatus
131+
> Halts the current thread execution until a thread completes or exceeds the timeout
132+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
133+
> **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
134+
135+
<br />
136+
137+
138+
Now you know how to use the [`Thread`](#importing-the-class) class!
139+
140+
[See here](./parallel-processing.md) for how to using the `thread.ParallelProcessing` class!

‎docs/threading.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Thread Class documentation
2+
3+
I will lay out how to use the `thread.Thread` class!
4+
5+
<br />
6+
<details>
7+
<summary>Jump to</summary>
8+
<ul>
9+
<li><a href='#importing-the-class'> Import the class</a></li>
10+
<li><a href='#initializing-a-thread'> Initialize a thread </a></li>
11+
</ul>
12+
</details>
13+
14+
15+
Don't have the thread library? [See here](./getting-started.md) for installing thread
16+
17+
---
18+
19+
## Importing the class
20+
21+
```py
22+
from thread import Thread
23+
```
24+
25+
<br />
26+
27+
28+
## Initializing a thread
29+
30+
A simple thread can be prepared to be initialized with this
31+
```py
32+
def my_target(): ...
33+
34+
# Reccommended way
35+
my_thread = Thread(
36+
target = my_target
37+
)
38+
39+
# OR
40+
# Not the reccommended way
41+
my_thread = Thread(my_target)
42+
```
43+
44+
A thread can be ran by invoking the `start()` method
45+
```py
46+
my_thread.start()
47+
```
48+
49+
> [!NOTE]
50+
> The **threading.Thread()** class from python will only be initialized when **start()** is invoked
51+
52+
<br />
53+
54+
55+
### Parameters
56+
57+
* target : (Data_In, *args, **kwargs) -> Any | Data_Out
58+
> This should be a function that takes in anything and returns anything
59+
60+
* args : Sequence[Data_In] = ()
61+
> This should be an interable sequence of arguments parsed to the `target` function <br />
62+
> (e.g. tuple('foo', 'bar'))
63+
64+
* kwargs : Mapping[str, Data_In] = {}
65+
> This should be the kwargs pased to the `target` function<br />
66+
> (e.g. dict(foo = 'bar'))
67+
68+
* ignore_errors : Sequence[type[Exception]] = ()
69+
> This should be an interable sequence of all exceptions to ignore.<br />
70+
> To ignore all exceptions, parse tuple(Exception)
71+
72+
* suppress_errors : bool = False
73+
> This should be a boolean indicating whether exceptions will be raised.<br />
74+
> If true, exceptions will only write to internal `errors` property<br />
75+
> If false, exceptions will propagate if not ignored
76+
77+
* name : Optional[str] = None
78+
> This is an argument parsed to `threading.Thread`
79+
80+
* daemon : bool = False
81+
> This is an argument parsed to `threading.Thread`
82+
83+
* *overflow_args : Overflow_In
84+
> These are arguments parsed to `threading.Thread`
85+
86+
* **overflow_kwargs : Overflow_In
87+
> These are arguments parsed to `threading.Thread`
88+
89+
<br />
90+
91+
92+
### Attributes
93+
94+
These are attributes of [`Thread`](#importing-the-class) class
95+
96+
* result : Data_Out
97+
> The result value of the thread
98+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
99+
> **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
100+
> **Raises** [`ThreadStillRunningError`](./exceptions.md#threadStillRunningError)
101+
102+
<br />
103+
104+
105+
### Methods
106+
107+
These are methods of [`Thread`](#importing-the-class) class
108+
109+
* start : () -> None
110+
> Initializes the thread and starts it<br />
111+
> **Raises** [`ThreadStillRunningError`](./exceptions.md#threadStillRunningError)
112+
113+
* is_alive : () -> bool
114+
> Indicates whether the thread is still alive<br />
115+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
116+
117+
* add_hook : ((Data_Out) -> Any | None) -> None
118+
> Hooks will be automatically invoked after a thread successfully completes, parsing the return value as the first argument
119+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
120+
> **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
121+
122+
* get_return_value : () -> Data_Out
123+
> Halts the current thread execution until the thread completes
124+
125+
* join : () -> JoinTerminatedStatus
126+
> Halts the current thread execution until a thread completes or exceeds the timeout
127+
> **Raises** [`ThreadNotInitializedError`](./exceptions.md#threadNotInitializedError)
128+
> **Raises** [`ThreadNotRunningError`](./exceptions.md#threadnotrunningerror)
129+
130+
<br />
131+
132+
133+
Now you know how to use the [`Thread`](#importing-the-class) class!
134+
135+
[See here](./parallel-processing.md) for how to using the `thread.ParallelProcessing` class!

0 commit comments

Comments
 (0)