Fasteners
=========
[![Documentation status](https://readthedocs.org/projects/fasteners/badge/?version=latest)](https://readthedocs.org/projects/fasteners/?badge=latest)
[![Downloads](https://img.shields.io/pypi/dm/fasteners.svg)](https://pypi.python.org/pypi/fasteners/)
[![Latest version](https://img.shields.io/pypi/v/fasteners.svg)](https://pypi.python.org/pypi/fasteners/)
Cross-platform locks for threads and processes.
π© Install
----------
```
pip install fasteners
```
π© Usage
--------
Lock for processes has the same API as the
[threading.Lock](https://docs.python.org/3/library/threading.html#threading.Lock)
for threads:
```python
import fasteners
import threading
lock = threading.Lock() # for threads
lock = fasteners.InterProcessLock('path/to/lock.file') # for processes
with lock:
... # exclusive access
# or alternatively
lock.acquire()
... # exclusive access
lock.release()
```
Reader Writer lock has a similar API, which is the same for threads or processes:
```python
import fasteners
rw_lock = fasteners.ReaderWriterLock() # for threads
rw_lock = fasteners.InterProcessReaderWriterLock('path/to/lock.file') # for processes
with rw_lock.write_lock():
... # write access
with rw_lock.read_lock():
... # read access
# or alternatively
rw_lock.acquire_read_lock()
... # read access
rw_lock.release_read_lock()
rw_lock.acquire_write_lock()
... # write access
rw_lock.release_write_lock()
```
π© Overview
-----------
Python standard library provides a lock for threads (both a reentrant one, and a
non-reentrant one, see below). Fasteners extends this, and provides a lock for
processes, as well as Reader Writer locks for both threads and processes.
Definitions of terms used in this overview can be found in the
[glossary](https://fasteners.readthedocs.io/en/latest/guide/glossary/).
The specifics of the locks are as follows:
### Process locks
The `fasteners.InterProcessLock` uses [fcntl](https://man7.org/linux/man-pages/man2/fcntl.2.html) on Unix-like systems and
msvc [_locking](https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/locking?view=msvc-160) on Windows.
As a result, if used cross-platform it guarantees an intersection of their features:
| lock | reentrant | mandatory |
|------|-----------|-----------|
| fcntl | β | β |
| _locking | β | β |
| fasteners.InterProcessLock | β | β |
The `fasteners.InterProcessReaderWriterLock` also uses fcntl on Unix-like systems and
[LockFileEx](https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-lockfileex) on Windows. Their
features are as follows:
| lock | reentrant | mandatory | upgradable | preference |
|------|-----------|-----------|------------|------------|
| fcntl | β | β | β | reader |
| LockFileEx | β | β | β | reader |
| fasteners.InterProcessReaderWriterLock | β | β | β | reader |
### Thread locks
Fasteners does not provide a simple thread lock, but for the sake of comparison note that the `threading` module
provides both a reentrant and non-reentrant locks:
| lock | reentrant | mandatory |
|------|-----------|-----------|
| threading.Lock | β | β |
| threading.RLock | β | β |
The `fasteners.ReaderWriterLock` at the moment is as follows:
| lock | reentrant | mandatory | upgradable | preference |
|------|-----------|-----------|-------------|------------|
| fasteners.ReaderWriterLock | β | β | β | writer |
If your threads are created by some other means than the standard library `threading`
module (for example `eventlet`), you may need to provide the corresponding thread
identification and synchronisation functions to the `ReaderWriterLock`.
Raw data
{
"_id": null,
"home_page": "https://github.com/harlowja/fasteners",
"name": "fasteners",
"maintainer": "Paulius \u0160arka",
"docs_url": "https://pythonhosted.org/fasteners/",
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "lock thread process fasteners",
"author": "Joshua Harlow",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/5f/d4/e834d929be54bfadb1f3e3b931c38e956aaa3b235a46a3c764c26c774902/fasteners-0.19.tar.gz",
"platform": null,
"description": "Fasteners\n=========\n\n[![Documentation status](https://readthedocs.org/projects/fasteners/badge/?version=latest)](https://readthedocs.org/projects/fasteners/?badge=latest)\n[![Downloads](https://img.shields.io/pypi/dm/fasteners.svg)](https://pypi.python.org/pypi/fasteners/)\n[![Latest version](https://img.shields.io/pypi/v/fasteners.svg)](https://pypi.python.org/pypi/fasteners/)\n\nCross-platform locks for threads and processes.\n\n\ud83d\udd29 Install\n----------\n\n```\npip install fasteners\n```\n\n\ud83d\udd29 Usage\n--------\nLock for processes has the same API as the \n[threading.Lock](https://docs.python.org/3/library/threading.html#threading.Lock)\nfor threads:\n```python\nimport fasteners\nimport threading\n\nlock = threading.Lock() # for threads\nlock = fasteners.InterProcessLock('path/to/lock.file') # for processes\n\nwith lock:\n ... # exclusive access\n\n# or alternatively \n\nlock.acquire()\n... # exclusive access\nlock.release()\n```\n\nReader Writer lock has a similar API, which is the same for threads or processes:\n\n```python\nimport fasteners\n\nrw_lock = fasteners.ReaderWriterLock() # for threads\nrw_lock = fasteners.InterProcessReaderWriterLock('path/to/lock.file') # for processes\n\nwith rw_lock.write_lock():\n ... # write access\n\nwith rw_lock.read_lock():\n ... # read access\n\n# or alternatively\n\nrw_lock.acquire_read_lock()\n... # read access\nrw_lock.release_read_lock()\n\nrw_lock.acquire_write_lock()\n... # write access\nrw_lock.release_write_lock()\n```\n\n\ud83d\udd29 Overview\n-----------\n\nPython standard library provides a lock for threads (both a reentrant one, and a\nnon-reentrant one, see below). Fasteners extends this, and provides a lock for\nprocesses, as well as Reader Writer locks for both threads and processes.\nDefinitions of terms used in this overview can be found in the\n[glossary](https://fasteners.readthedocs.io/en/latest/guide/glossary/).\n\nThe specifics of the locks are as follows:\n\n### Process locks\n\nThe `fasteners.InterProcessLock` uses [fcntl](https://man7.org/linux/man-pages/man2/fcntl.2.html) on Unix-like systems and \nmsvc [_locking](https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/locking?view=msvc-160) on Windows. \nAs a result, if used cross-platform it guarantees an intersection of their features:\n\n| lock | reentrant | mandatory |\n|------|-----------|-----------|\n| fcntl | \u2718 | \u2718 |\n| _locking | \u2714 | \u2714 |\n| fasteners.InterProcessLock | \u2718 | \u2718 |\n\n\nThe `fasteners.InterProcessReaderWriterLock` also uses fcntl on Unix-like systems and \n[LockFileEx](https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-lockfileex) on Windows. Their \nfeatures are as follows:\n\n| lock | reentrant | mandatory | upgradable | preference | \n|------|-----------|-----------|------------|------------|\n| fcntl | \u2718 | \u2718 | \u2714 | reader |\n| LockFileEx | \u2714 | \u2714 | \u2718 | reader |\n| fasteners.InterProcessReaderWriterLock | \u2718 | \u2718 | \u2718 | reader |\n\n\n### Thread locks\n\nFasteners does not provide a simple thread lock, but for the sake of comparison note that the `threading` module\nprovides both a reentrant and non-reentrant locks:\n\n| lock | reentrant | mandatory |\n|------|-----------|-----------|\n| threading.Lock | \u2718 | \u2718 |\n| threading.RLock | \u2714 | \u2718 |\n\n\nThe `fasteners.ReaderWriterLock` at the moment is as follows:\n\n| lock | reentrant | mandatory | upgradable | preference | \n|------|-----------|-----------|-------------|------------|\n| fasteners.ReaderWriterLock | \u2714 | \u2718 | \u2718 | writer |\n\nIf your threads are created by some other means than the standard library `threading`\nmodule (for example `eventlet`), you may need to provide the corresponding thread\nidentification and synchronisation functions to the `ReaderWriterLock`.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A python package that provides useful locks",
"version": "0.19",
"project_urls": {
"Homepage": "https://github.com/harlowja/fasteners"
},
"split_keywords": [
"lock",
"thread",
"process",
"fasteners"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "61bffd60001b3abc5222d8eaa4a204cd8c0ae78e75adc688f33ce4bf25b7fafa",
"md5": "0e45841c638ae0fb3c228844904007f2",
"sha256": "758819cb5d94cdedf4e836988b74de396ceacb8e2794d21f82d131fd9ee77237"
},
"downloads": -1,
"filename": "fasteners-0.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e45841c638ae0fb3c228844904007f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18679,
"upload_time": "2023-09-19T17:11:18",
"upload_time_iso_8601": "2023-09-19T17:11:18.725026Z",
"url": "https://files.pythonhosted.org/packages/61/bf/fd60001b3abc5222d8eaa4a204cd8c0ae78e75adc688f33ce4bf25b7fafa/fasteners-0.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5fd4e834d929be54bfadb1f3e3b931c38e956aaa3b235a46a3c764c26c774902",
"md5": "e957e11c2e00629e44166e1d2881798e",
"sha256": "b4f37c3ac52d8a445af3a66bce57b33b5e90b97c696b7b984f530cf8f0ded09c"
},
"downloads": -1,
"filename": "fasteners-0.19.tar.gz",
"has_sig": false,
"md5_digest": "e957e11c2e00629e44166e1d2881798e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 24832,
"upload_time": "2023-09-19T17:11:20",
"upload_time_iso_8601": "2023-09-19T17:11:20.228211Z",
"url": "https://files.pythonhosted.org/packages/5f/d4/e834d929be54bfadb1f3e3b931c38e956aaa3b235a46a3c764c26c774902/fasteners-0.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-19 17:11:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "harlowja",
"github_project": "fasteners",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fasteners"
}