kragniz / kragniz/python-etcd3
Documentation suggestion
- 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
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