kragniz / kragniz/python-etcd3

Documentation suggestion

Open
#1,314 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
450
Forks
194
PR merge metrics
No merged PRs in 30d

Description

Hi,

I recently switched from a home-baked Conul lock to this, mostly for its simplicity. But I got bitten by the assumption that a context manager acquire will throw an exception if it fails to acquire.

```
with etcd.lock('doot-machine') as lock:
# do something
```

The documentation could make this clearer:

```
with etcd.lock('doot-machine') as lock:
if lock.is_acquired():
# do something
```
If you don't check `lock.is_acquired()` the code will execute.

With locking, a failure to acquire would (certainly for me) be a reason to NOT execute the code. If a timeout is set and expires with no lock acquired, then logic would say to me, that it should throw a Timeout exception. I tend to wrap my methods in try/except where appropriate, and let others bubble up as legitimate issues that I log. In the event of a lock acquisition failure, i would prefer it throw an exception that I can handle when I need to, rather than a True/False that I have check every time.

Am I being dumb?

Many thanks,

Geoff

Contributor guide

Open the contributing guide

Research direction

Start by locating the documentation for the etcd.lock context manager and its is_acquired() behavior. Confirm how failed acquisition and timeout are currently described, then clarify that the context body still runs without a successful lock and document the requested exception behavior if it is supported.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
distributed-systems
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.