Metadata-Version: 2.1
Name: locks
Version: 0.1.1
Summary: POSIX file system locking using flock
Home-page: https://github.com/rossmacarthur/locks
Author: Ross MacArthur
Author-email: ross@macarthur.io
License: MIT
Download-URL: https://github.com/rossmacarthur/locks/archive/0.1.1.tar.gz
Project-URL: Issue Tracker, https://github.com/rossmacarthur/locks/issues
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Description-Content-Type: text/markdown
Requires-Dist: monotonic (>=1.0)

# locks

[![PyPI version](https://img.shields.io/pypi/v/locks.svg?style=flat-square)](https://pypi.org/project/locks/)
[![Build status](https://img.shields.io/travis/rossmacarthur/locks/master.svg?style=flat-square)](https://travis-ci.org/rossmacarthur/locks)

POSIX file system locking using [flock](https://linux.die.net/man/2/flock).

## Getting started

Install this package with

```sh
pip install locks
```

## Usage

The simplest usage is to block indefinitely until the lock is acquired

```python
from locks import Mutex

with Mutex('/tmp/file.lock'):
    # do exclusive stuff here
```

Alternatively, block until a timeout is reached

```python
from locks import Mutex

try:
    with Mutex('/tmp/file.lock', timeout=0.5):
        # do exclusive stuff here
except BlockingIOError:
    # handle the failure to acquire the lock
```

Finally, a common paradigm is to attempt to acquire the lock without blocking,
do something, and then block indefinitely. Here `callback` will be called once
if we cannot immediately acquire the lock, and then we will block indefinitely.

```python
def callback():
    print("Blocking: waiting for file lock on '/tmp/file.lock'")

with Mutex('/tmp/file.lock', callback=callback):
    # do exclusive stuff here
```

If both `callback` and `timeout` are used then we will attempt to
acquire the lock until the `timeout` is reached, and then we will block
indefinitely.

## License

This project is licensed under the MIT License. See the [LICENSE] file.

[LICENSE]: LICENSE


