free-threading 1.0.0__tar.gz

free_threading-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 freethreading contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

free_threading-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: free-threading
+Version: 1.0.0
+Summary: Thread-first true parallelism
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gil,nogil,thread,process,worker,threading,free-threading,multithreading,multiprocessing,concurrency,parallelism
+Author: Iskander Gaba
+Author-email: iskander@hey.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Project-URL: Documentation, https://freethreading.readthedocs.io
+Project-URL: Repository, https://github.com/iskandergaba/freethreading
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# freethreading — Thread-first true parallelism
+
+[![PyPI Version](https://img.shields.io/pypi/v/freethreading.svg?label=PyPI)](https://pypi.org/project/freethreading/)
+![Python Version](https://img.shields.io/pypi/pyversions/freethreading?label=Python)
+![License](https://img.shields.io/pypi/l/freethreading?label=License)
+[![CI Build](https://github.com/iskandergaba/freethreading/actions/workflows/ci.yml/badge.svg)](https://github.com/iskandergaba/freethreading/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/iskandergaba/freethreading/graph/badge.svg?token=LWBRgtlX8j)](https://codecov.io/gh/iskandergaba/freethreading)
+[![Docs](https://readthedocs.org/projects/freethreading/badge/?version=latest)](https://freethreading.readthedocs.io/en/latest)
+
+`freethreading` is a lightweight wrapper that provides a unified API for true parallel execution in Python. It
+automatically uses `threading` on free-threaded Python builds (where the
+[Global Interpreter Lock (GIL)](https://docs.python.org/3/glossary.html#term-global-interpreter-lock) is disabled) and
+falls back to `multiprocessing` on standard ones. This enables true parallelism across Python versions while preferring the efficiency of [threads](https://en.wikipedia.org/wiki/Thread_(computing)) over
+[processes](https://en.wikipedia.org/wiki/Process_(computing)) whenever possible.
+
+</div>
+
+## Installation
+
+ To install `freethreading`, simply run:
+
+```shell
+pip install free-threading
+```
+
+To install the latest development version, you can run:
+
+```shell
+pip install git+https://github.com/iskandergaba/free-threading.git
+```
+
+## Quick Start
+
+`freethreading` is a drop-in replacement for *most* pre-existing `threading` and `multiprocessing` code. To achieve
+this, the module exposes only non-deprecated common functionality shared between both backends while discarding any
+backend-specific APIs. The following examples show how to get started.
+
+`freethreading` remains consistent with the standard library, so wrapper classes work as drop-in replacements for those
+used by `threading` and `multiprocessing`. Here's how they work:
+
+```python
+# threading
+from queue import Queue
+from threading import Event, Lock
+
+# multiprocessing
+from multiprocessing import Event, Lock, Queue
+
+# freethreading (replaces both)
+from freethreading import Event, Lock, Queue
+event = Event()
+lock = Lock()
+queue = Queue()
+lock.acquire()
+# True
+event.set()
+queue.put("data")
+event.is_set()
+# True
+queue.get()
+# 'data'
+lock.release()
+```
+
+`freethreading` functions merge as much functionality from both backends as possible to ensure consistent behavior
+across backends and simplify adoption. Here's what that looks like:
+
+```python
+# threading
+from threading import enumerate, get_ident
+
+# multiprocessing
+from multiprocessing import active_children
+from os import getpid
+
+# freethreading (replaces both)
+from freethreading import active_children, enumerate, get_ident
+len(active_children())  # excludes current thread or process
+# 0
+len(enumerate())  # includes current thread or process
+# 1
+get_ident()  # current thread or process identifier
+# 140247834...
+```
+
+Only `Worker`, `WorkerPool`, `WorkerPoolExecutor`, and `current_worker` differ from the standard library naming, using
+"worker" as a term for both threads and processes. Here is an example:
+
+```python
+# threading
+from concurrent.futures import ThreadPoolExecutor
+from threading import Thread, current_thread
+
+# multiprocessing
+from concurrent.futures import ProcessPoolExecutor
+from multiprocessing import Process, current_process
+
+# freethreading (replaces both)
+from freethreading import Worker, WorkerPool, WorkerPoolExecutor, current_worker
+current_worker().name
+# 'MainThread' or 'MainProcess'
+
+def task():
+    print(f"Hello from {current_worker().name}!")
+
+# Using Worker (Thread or Process) to run a task
+w = Worker(target=task, name="MyWorker")
+w.start()
+w.join()
+# Hello from MyWorker!
+
+# Using WorkerPool (Pool or ThreadPool) to distribute work
+def square(x):
+    return x * x
+
+with WorkerPool(workers=2) as pool:
+    print(pool.map(square, range(5)))
+# [0, 1, 4, 9, 16]
+
+# Using WorkerPoolExecutor (ThreadPoolExecutor or ProcessPoolExecutor) to run a task
+with WorkerPoolExecutor(max_workers=2) as executor:
+    future = executor.submit(task)
+# 'Hello from ThreadPoolExecutor-0_0!' or 'Hello from ForkProcess-2!'
+```
+
+## Documentation
+
+For more details, check out the full documentation at [freethreading.readthedocs.io](https://freethreading.readthedocs.io).
+

free_threading-1.0.0/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+# freethreading — Thread-first true parallelism
+
+[![PyPI Version](https://img.shields.io/pypi/v/freethreading.svg?label=PyPI)](https://pypi.org/project/freethreading/)
+![Python Version](https://img.shields.io/pypi/pyversions/freethreading?label=Python)
+![License](https://img.shields.io/pypi/l/freethreading?label=License)
+[![CI Build](https://github.com/iskandergaba/freethreading/actions/workflows/ci.yml/badge.svg)](https://github.com/iskandergaba/freethreading/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/iskandergaba/freethreading/graph/badge.svg?token=LWBRgtlX8j)](https://codecov.io/gh/iskandergaba/freethreading)
+[![Docs](https://readthedocs.org/projects/freethreading/badge/?version=latest)](https://freethreading.readthedocs.io/en/latest)
+
+`freethreading` is a lightweight wrapper that provides a unified API for true parallel execution in Python. It
+automatically uses `threading` on free-threaded Python builds (where the
+[Global Interpreter Lock (GIL)](https://docs.python.org/3/glossary.html#term-global-interpreter-lock) is disabled) and
+falls back to `multiprocessing` on standard ones. This enables true parallelism across Python versions while preferring the efficiency of [threads](https://en.wikipedia.org/wiki/Thread_(computing)) over
+[processes](https://en.wikipedia.org/wiki/Process_(computing)) whenever possible.
+
+</div>
+
+## Installation
+
+ To install `freethreading`, simply run:
+
+```shell
+pip install free-threading
+```
+
+To install the latest development version, you can run:
+
+```shell
+pip install git+https://github.com/iskandergaba/free-threading.git
+```
+
+## Quick Start
+
+`freethreading` is a drop-in replacement for *most* pre-existing `threading` and `multiprocessing` code. To achieve
+this, the module exposes only non-deprecated common functionality shared between both backends while discarding any
+backend-specific APIs. The following examples show how to get started.
+
+`freethreading` remains consistent with the standard library, so wrapper classes work as drop-in replacements for those
+used by `threading` and `multiprocessing`. Here's how they work:
+
+```python
+# threading
+from queue import Queue
+from threading import Event, Lock
+
+# multiprocessing
+from multiprocessing import Event, Lock, Queue
+
+# freethreading (replaces both)
+from freethreading import Event, Lock, Queue
+event = Event()
+lock = Lock()
+queue = Queue()
+lock.acquire()
+# True
+event.set()
+queue.put("data")
+event.is_set()
+# True
+queue.get()
+# 'data'
+lock.release()
+```
+
+`freethreading` functions merge as much functionality from both backends as possible to ensure consistent behavior
+across backends and simplify adoption. Here's what that looks like:
+
+```python
+# threading
+from threading import enumerate, get_ident
+
+# multiprocessing
+from multiprocessing import active_children
+from os import getpid
+
+# freethreading (replaces both)
+from freethreading import active_children, enumerate, get_ident
+len(active_children())  # excludes current thread or process
+# 0
+len(enumerate())  # includes current thread or process
+# 1
+get_ident()  # current thread or process identifier
+# 140247834...
+```
+
+Only `Worker`, `WorkerPool`, `WorkerPoolExecutor`, and `current_worker` differ from the standard library naming, using
+"worker" as a term for both threads and processes. Here is an example:
+
+```python
+# threading
+from concurrent.futures import ThreadPoolExecutor
+from threading import Thread, current_thread
+
+# multiprocessing
+from concurrent.futures import ProcessPoolExecutor
+from multiprocessing import Process, current_process
+
+# freethreading (replaces both)
+from freethreading import Worker, WorkerPool, WorkerPoolExecutor, current_worker
+current_worker().name
+# 'MainThread' or 'MainProcess'
+
+def task():
+    print(f"Hello from {current_worker().name}!")
+
+# Using Worker (Thread or Process) to run a task
+w = Worker(target=task, name="MyWorker")
+w.start()
+w.join()
+# Hello from MyWorker!
+
+# Using WorkerPool (Pool or ThreadPool) to distribute work
+def square(x):
+    return x * x
+
+with WorkerPool(workers=2) as pool:
+    print(pool.map(square, range(5)))
+# [0, 1, 4, 9, 16]
+
+# Using WorkerPoolExecutor (ThreadPoolExecutor or ProcessPoolExecutor) to run a task
+with WorkerPoolExecutor(max_workers=2) as executor:
+    future = executor.submit(task)
+# 'Hello from ThreadPoolExecutor-0_0!' or 'Hello from ForkProcess-2!'
+```
+
+## Documentation
+
+For more details, check out the full documentation at [freethreading.readthedocs.io](https://freethreading.readthedocs.io).

free_threading-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "free-threading"
+version = "1.0.0"
+description = "Thread-first true parallelism"
+license = "MIT"
+readme = "README.md"
+authors = [
+    { name = "Iskander Gaba", email = "iskander@hey.com" },
+]
+keywords = [
+    "gil",
+    "nogil",
+    "thread",
+    "process",
+    "worker",
+    "threading",
+    "free-threading",
+    "multithreading",
+    "multiprocessing",
+    "concurrency",
+    "parallelism",
+]
+requires-python = ">=3.10"
+
+[project.urls]
+repository = "https://github.com/iskandergaba/freethreading"
+documentation = "https://freethreading.readthedocs.io"
+
+[dependency-groups]
+dev = [
+    "ruff~=0.14.0",
+    "pytest~=9.0.0",
+    "pytest-cov~=7.0.0",
+    "sphinx-autobuild~=2024.10.0",
+]
+docs = [
+    "sphinx-autoapi~=3.6.0",
+    "python-docs-theme~=2025.10"
+]
+
+[tool.poetry]
+packages = [{ include = "freethreading", from = "src" }]
+
+[tool.uv.dependency-groups]
+docs = { requires-python = ">=3.12" }
+
+[tool.ruff.lint]
+extend-select = ["E501"]