Support reentrant locking on lock file path via optional singleton instance

[nefrob]

Description

Re: #282.

• When _singleton_per_lock_file is set instantiating a new lock with the same lock path will return the existing instance of the lock. This means you can reacquire the lock without passing the lock object around
• Otherwise a new lock object is returned every time (default behavior for backwards compatibility)

Based on the flock docs (and likely similar for windows/soft cases)

If a process uses open(2) (or similar) to obtain more than one
file descriptor for the same file, these file descriptors are
treated independently by flock(). An attempt to lock the file
using one of these file descriptors may be denied by a lock that
the calling process has already placed via another file
descriptor.

(https://man7.org/linux/man-pages/man2/flock.2.html)

a Python solution seems most general and easy here. If anyone has time to dig into different OS file locking mechanisms and see if there is a native solution that would likely be preferable.

Action Items

• docs updates?
• concurrency? If the use case fro non-thread-local locks is to create the lock on the main thread, share it with threads, then cleanup the lock when they complete then this should be safe as the threads will only ever read the instance from the class instances dictionary. If supporting hand-off of the lock to thread processes is within the thread-local options then we should acquire a global lock around the instances dictionary for safety (at the cost of speed)

[nefrob]

Downloading pypy locally to investigate test failures. Not sure what the strategy for the type failures is (ex. switch from Sequence to list, drop the type entirely and noqa or resolve via getting type stubs for mypy?). I misunderstoof mypy errors, it just wants type hints for the data inside the container objects.

[gaborbernat]

Don't disable ruff checks, address them.

[gaborbernat]

[nefrob]

Thanks so much for the help!

[YouJiacheng]

I think there might be a bug: all derived class of BaseFileLock share the same _instances:

from filelock import UnixFileLock, BaseFileLock

assert UnixFileLock._instances is BaseFileLock._instances

This can be resolved by meta class or simpler __init_subclass__ (python>=3.6)

[YouJiacheng]

BTW, maybe we should check if args like mode and timeout is the same as the singleton?

[nefrob]

@YouJiacheng good callout. I think I avoided a metaclass in the first place because BaseFileLock inherits from ABC which sets its metaclass already. I can take a look at this later today.

Checking mode and timeout don't seem particularly relevant if we determine two singleton locks are the sam object (so will have the same values), unless you meant something else there.

[YouJiacheng]

Okay, __init_subclass__ can be used instead of metaclass.

By checking mode and timeout, I mean: if mode and timeout are different, but lock_file are the same, there should be some warning, since the second mode and timeout will be ignored.

[nefrob]

@YouJiacheng here is the fix using __init_subclass__: #318.

As for the other question, deciding on how to handle that seems like something for @gaborbernat to decide on. We could:

1. raise an error
2. update the existing singleton lock
3. ignore doing anything (current behavior)

[gaborbernat]

1. raise an error

Would be my vote.

[nefrob]

Fix for incompatible singleton args: #320.