yyds-lock 0.2.0__tar.gz

yyds_lock-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: yyds-lock
+Version: 0.2.0
+Summary: A lightweight cross-platform single-instance process lock for Python.
+Home-page: https://github.com/yyds-fast/yyds-lock
+Author: wzb
+Author-email: wzb@example.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# yyds-lock
+
+[![PyPI version](https://img.shields.io/pypi/v/yyds-lock.svg)](https://pypi.org/project/yyds-lock/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`yyds-lock` is an ultra-lightweight, zero-dependency Python library that guarantees single-instance execution of scripts/processes using operating system level advisory file locks. It is ideal for cron jobs, automation scripts, schedulers, and background daemons.
+
+## Key Features
+
+- 🛡️ **Immunity to Crashes / Force Kills**: Unlike simple PID files or "lock files" that leave stale markers behind if the script crashes, is killed (`kill -9`), or suffers power loss, `yyds-lock` binds the lock to the process file descriptor. The OS automatically and instantly releases the lock as soon as the process ends.
+- 🪶 **Zero Dependencies**: 100% pure Python standard library. The installation size is less than 5KB and does not pollute your environment.
+- 🎛️ **Dual Modes**: Supports both "Instant Exit" (non-blocking, terminates immediately if another instance is running) and "Queue / Wait" (blocking, waits for the existing instance to finish).
+- 💻 **Cross-Platform**: Seamlessly works on Linux, macOS (using `fcntl.flock`), and Windows (using `msvcrt.locking`).
+
+---
+
+## Installation
+
+```bash
+pip install -U yyds-lock
+```
+
+---
+
+## Usage
+
+You can protect your script using either of two simple approaches:
+
+### Pattern A: Direct Call (Best for straightforward scripts / entrypoints)
+
+Place this call at the very top of your entrypoint script. If another instance of the script is already running, the new instance will immediately print an error to stderr and exit with status code `1`.
+
+```python
+import time
+import yyds_lock
+
+# Force single-instance execution.
+yyds_lock.force_single(lock_name="my_automation.lock", block=False)
+
+print("Running heavy automation task...")
+time.sleep(300)
+```
+
+### Pattern B: Decorator (Best for structured functions/main entrypoints)
+
+Decorate your `main` function to enforce mutual exclusion.
+
+```python
+import yyds_lock
+
+@yyds_lock.single_decorator(lock_name="my_task.lock", block=False)
+def main():
+    print("Executing single instance task safely...")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## Configuration / Arguments
+
+Both `force_single` and `single_decorator` accept the following arguments:
+
+- `lock_name` (str): The filename/path of the lock.
+  - If a simple filename is given (e.g. `"my_job.lock"`), it is automatically created in the user's home directory (`~`).
+  - If an absolute or relative path is given (e.g., `"/var/run/my_job.lock"`), it is created at that specific path. The parent directories will be created automatically if they do not exist.
+- `block` (bool):
+  - `False` (default): Exit immediately if the lock cannot be acquired.
+  - `True`: Block and queue, waiting for the active process to finish and release the lock.
+
+---
+
+## How It Works Under the Hood
+
+1. **Linux / macOS**: Uses `fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)` for exclusive advisory locking.
+2. **Windows**: Uses `msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)` to lock the first byte of the file.
+3. The library stores the open file handles in a global dictionary inside the Python runtime. This keeps the file descriptor open and prevents garbage collection (GC) from releasing the lock prematurely.
+4. When the process terminates (normally, via Exception, `sys.exit`, crash, `kill -9`, or power failure), the OS closes the file descriptors, releasing the locks instantly.

yyds_lock-0.2.0/README.md

@@ -0,0 +1,79 @@
+# yyds-lock
+
+[![PyPI version](https://img.shields.io/pypi/v/yyds-lock.svg)](https://pypi.org/project/yyds-lock/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`yyds-lock` is an ultra-lightweight, zero-dependency Python library that guarantees single-instance execution of scripts/processes using operating system level advisory file locks. It is ideal for cron jobs, automation scripts, schedulers, and background daemons.
+
+## Key Features
+
+- 🛡️ **Immunity to Crashes / Force Kills**: Unlike simple PID files or "lock files" that leave stale markers behind if the script crashes, is killed (`kill -9`), or suffers power loss, `yyds-lock` binds the lock to the process file descriptor. The OS automatically and instantly releases the lock as soon as the process ends.
+- 🪶 **Zero Dependencies**: 100% pure Python standard library. The installation size is less than 5KB and does not pollute your environment.
+- 🎛️ **Dual Modes**: Supports both "Instant Exit" (non-blocking, terminates immediately if another instance is running) and "Queue / Wait" (blocking, waits for the existing instance to finish).
+- 💻 **Cross-Platform**: Seamlessly works on Linux, macOS (using `fcntl.flock`), and Windows (using `msvcrt.locking`).
+
+---
+
+## Installation
+
+```bash
+pip install -U yyds-lock
+```
+
+---
+
+## Usage
+
+You can protect your script using either of two simple approaches:
+
+### Pattern A: Direct Call (Best for straightforward scripts / entrypoints)
+
+Place this call at the very top of your entrypoint script. If another instance of the script is already running, the new instance will immediately print an error to stderr and exit with status code `1`.
+
+```python
+import time
+import yyds_lock
+
+# Force single-instance execution.
+yyds_lock.force_single(lock_name="my_automation.lock", block=False)
+
+print("Running heavy automation task...")
+time.sleep(300)
+```
+
+### Pattern B: Decorator (Best for structured functions/main entrypoints)
+
+Decorate your `main` function to enforce mutual exclusion.
+
+```python
+import yyds_lock
+
+@yyds_lock.single_decorator(lock_name="my_task.lock", block=False)
+def main():
+    print("Executing single instance task safely...")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## Configuration / Arguments
+
+Both `force_single` and `single_decorator` accept the following arguments:
+
+- `lock_name` (str): The filename/path of the lock.
+  - If a simple filename is given (e.g. `"my_job.lock"`), it is automatically created in the user's home directory (`~`).
+  - If an absolute or relative path is given (e.g., `"/var/run/my_job.lock"`), it is created at that specific path. The parent directories will be created automatically if they do not exist.
+- `block` (bool):
+  - `False` (default): Exit immediately if the lock cannot be acquired.
+  - `True`: Block and queue, waiting for the active process to finish and release the lock.
+
+---
+
+## How It Works Under the Hood
+
+1. **Linux / macOS**: Uses `fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)` for exclusive advisory locking.
+2. **Windows**: Uses `msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)` to lock the first byte of the file.
+3. The library stores the open file handles in a global dictionary inside the Python runtime. This keeps the file descriptor open and prevents garbage collection (GC) from releasing the lock prematurely.
+4. When the process terminates (normally, via Exception, `sys.exit`, crash, `kill -9`, or power failure), the OS closes the file descriptors, releasing the locks instantly.

yyds_lock-0.2.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"

yyds_lock-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yyds_lock-0.2.0/setup.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python
+# -*- coding:utf-8 -*-
+
+from setuptools import setup, find_packages
+from codecs import open
+import os
+
+about = {}
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, "yyds_lock", "__version__.py"), "r", "utf-8") as f:
+    exec(f.read(), about)
+
+try:
+    with open("README.md", "r", encoding="utf-8") as fh:
+        long_description = fh.read()
+except FileNotFoundError:
+    long_description = about["__description__"]
+
+setup(
+    name=about["__title__"],
+    version=about["__version__"],
+    author=about["__author__"],
+    author_email=about["__author_email__"],
+    description=about["__description__"],
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url=about["__url__"],
+    license=about.get("__license__", "MIT"),
+    packages=find_packages(),
+    include_package_data=True,
+    python_requires='>=3.7',
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Operating System :: OS Independent",
+        "License :: OSI Approved :: MIT License",
+    ],
+    install_requires=[],
+)

yyds_lock-0.2.0/tests/test_lock.py

@@ -0,0 +1,196 @@
+# -*- coding:utf-8 -*-
+
+import unittest
+import os
+import sys
+import time
+import subprocess
+
+# Add the parent directory to Python path to import yyds_lock
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from yyds_lock import force_single, release_single, single_decorator
+
+
+class TestYYDSLock(unittest.TestCase):
+
+    def setUp(self):
+        # Cleanup test locks in home directory if any exist
+        self.test_lock_name = "yyds_test_instance.lock"
+        self.lock_path = os.path.join(os.path.expanduser("~"), self.test_lock_name)
+        if os.path.exists(self.lock_path):
+            try:
+                os.remove(self.lock_path)
+            except OSError:
+                pass
+
+    def tearDown(self):
+        # Release and cleanup test lock
+        release_single(self.test_lock_name)
+        if os.path.exists(self.lock_path):
+            try:
+                os.remove(self.lock_path)
+            except OSError:
+                pass
+
+    def test_basic_acquire_and_release(self):
+        # 1. Acquire first time (should succeed)
+        try:
+            force_single(self.test_lock_name, block=False)
+        except SystemExit:
+            self.fail("force_single exited unexpectedly on first acquire")
+            
+        # 2. Release lock
+        release_single(self.test_lock_name)
+
+    def test_reentrant_same_process(self):
+        # Re-acquiring the same lock in the same process should be a safe no-op
+        try:
+            force_single(self.test_lock_name, block=False)
+            force_single(self.test_lock_name, block=False)
+        except SystemExit:
+            self.fail("force_single exited on reentrant acquire in the same process")
+        finally:
+            release_single(self.test_lock_name)
+
+    def test_decorator_success(self):
+        calls = []
+
+        @single_decorator(lock_name=self.test_lock_name, block=False)
+        def my_function(x):
+            calls.append(x)
+            return x * 2
+
+        res = my_function(10)
+        self.assertEqual(res, 20)
+        self.assertEqual(calls, [10])
+
+    def test_nested_decorators_reentrancy(self):
+        # Test that nested decorators do not release the lock prematurely for the caller
+        runs = []
+
+        @single_decorator(lock_name=self.test_lock_name, block=False)
+        def inner():
+            runs.append("inner")
+
+        @single_decorator(lock_name=self.test_lock_name, block=False)
+        def outer():
+            runs.append("outer_start")
+            inner()
+            # After inner() exits, the lock should STILL be held by outer!
+            from yyds_lock.core import _lock_file_handles, _resolve_lock_path
+            lock_path = _resolve_lock_path(self.test_lock_name)
+            self.assertIn(lock_path, _lock_file_handles)
+            self.assertEqual(_lock_file_handles[lock_path]["ref_count"], 1)
+            runs.append("outer_end")
+
+        outer()
+        self.assertEqual(runs, ["outer_start", "inner", "outer_end"])
+
+        # After outer exits, the lock must be completely released
+        from yyds_lock.core import _lock_file_handles, _resolve_lock_path
+        lock_path = _resolve_lock_path(self.test_lock_name)
+        self.assertNotIn(lock_path, _lock_file_handles)
+
+    def test_subprocess_conflict_non_blocking(self):
+        # Start a background process that holds the lock
+        code_hold = (
+            "import time, sys, os\n"
+            "sys.path.insert(0, os.path.abspath('.'))\n"
+            f"from yyds_lock import force_single\n"
+            f"force_single('{self.test_lock_name}', block=False)\n"
+            "print('LOCKED', flush=True)\n"
+            "time.sleep(2)\n"
+        )
+        
+        proc_hold = subprocess.Popen(
+            [sys.executable, "-c", code_hold],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True
+        )
+        
+        # Wait for background process to output "LOCKED"
+        output = proc_hold.stdout.readline().strip()
+        self.assertEqual(output, "LOCKED")
+        
+        # Now try to acquire the same lock in a second process with block=False
+        code_try = (
+            "import sys, os\n"
+            "sys.path.insert(0, os.path.abspath('.'))\n"
+            f"from yyds_lock import force_single\n"
+            f"force_single('{self.test_lock_name}', block=False)\n"
+            "print('ACQUIRED', flush=True)\n"
+        )
+        
+        proc_try = subprocess.run(
+            [sys.executable, "-c", code_try],
+            capture_output=True,
+            text=True
+        )
+        
+        # The second process must exit with code 1 (since it is already locked)
+        self.assertEqual(proc_try.returncode, 1)
+        self.assertIn("[yyds-lock] 错误: 脚本进程已在运行中", proc_try.stderr)
+        self.assertNotIn("ACQUIRED", proc_try.stdout)
+        
+        # Cleanup
+        proc_hold.stdout.close()
+        proc_hold.stderr.close()
+        proc_hold.wait()
+
+    def test_subprocess_blocking_wait(self):
+        # Start a background process that holds the lock for 1.5 seconds
+        code_hold = (
+            "import time, sys, os\n"
+            "sys.path.insert(0, os.path.abspath('.'))\n"
+            f"from yyds_lock import force_single\n"
+            f"force_single('{self.test_lock_name}', block=False)\n"
+            "print('LOCKED', flush=True)\n"
+            "time.sleep(1.5)\n"
+            "print('RELEASED', flush=True)\n"
+        )
+        
+        proc_hold = subprocess.Popen(
+            [sys.executable, "-c", code_hold],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True
+        )
+        
+        # Wait for background process to output "LOCKED"
+        output = proc_hold.stdout.readline().strip()
+        self.assertEqual(output, "LOCKED")
+        
+        # Try to acquire with block=True in a second process. It should block and then acquire.
+        code_try_block = (
+            "import sys, os, time\n"
+            "sys.path.insert(0, os.path.abspath('.'))\n"
+            f"from yyds_lock import force_single\n"
+            "start = time.time()\n"
+            f"force_single('{self.test_lock_name}', block=True)\n"
+            "print('ACQUIRED_BLOCKED', round(time.time() - start, 1), flush=True)\n"
+        )
+        
+        start_time = time.time()
+        proc_try = subprocess.run(
+            [sys.executable, "-c", code_try_block],
+            capture_output=True,
+            text=True
+        )
+        elapsed = time.time() - start_time
+        
+        # The second process should succeed (exit code 0) after about 1.5 seconds
+        self.assertEqual(proc_try.returncode, 0)
+        self.assertIn("ACQUIRED_BLOCKED", proc_try.stdout)
+        # Should have waited at least 1.0 seconds
+        self.assertGreaterEqual(elapsed, 1.0)
+        
+        # Cleanup
+        proc_hold.stdout.close()
+        proc_hold.stderr.close()
+        proc_hold.wait()
+
+
+if __name__ == "__main__":
+    unittest.main()

yyds_lock-0.2.0/yyds_lock/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding:utf-8 -*-
+
+from yyds_lock.core import force_single, release_single, single_decorator
+from yyds_lock.__version__ import __version__, __title__, __author__
+
+__all__ = [
+    "force_single",
+    "release_single",
+    "single_decorator",
+]

yyds_lock-0.2.0/yyds_lock/__version__.py

@@ -0,0 +1,9 @@
+# -*- coding:utf-8 -*-
+
+__title__ = "yyds-lock"
+__description__ = "A lightweight cross-platform single-instance process lock for Python."
+__url__ = "https://github.com/yyds-fast/yyds-lock"
+__version__ = "0.2.0"
+__author__ = "wzb"
+__author_email__ = "wzb@example.com"
+__license__ = "MIT"

yyds_lock-0.2.0/yyds_lock/core.py

@@ -0,0 +1,149 @@
+# -*- coding:utf-8 -*-
+
+import os
+import sys
+import platform
+import threading
+from functools import wraps
+
+# Global registry for active locks: maps absolute lock file paths to info dicts:
+# {
+#     "handle": file_object,
+#     "ref_count": int
+# }
+_lock_file_handles = {}
+_global_lock = threading.Lock()
+
+def _resolve_lock_path(lock_name: str) -> str:
+    """
+    Resolves the lock name to an absolute canonical path.
+    """
+    if os.path.isabs(lock_name) or "/" in lock_name or "\\" in lock_name:
+        return os.path.abspath(lock_name)
+    else:
+        return os.path.abspath(os.path.join(os.path.expanduser("~"), lock_name))
+
+def force_single(lock_name: str = "yyds_instance.lock", block: bool = False):
+    """
+    Enforces that only a single instance of the script/process runs.
+    
+    :param lock_name: Name of the lock file, created in the user's home directory.
+                      Can also be a relative or absolute path.
+    :param block: If True, blocks and queues until the lock is available.
+                  If False, instantly prints an error message to stderr and exits with code 1.
+    """
+    global _lock_file_handles
+    
+    lock_path = _resolve_lock_path(lock_name)
+    
+    with _global_lock:
+        # If the current process already holds this lock, increment reference count and return safely
+        if lock_path in _lock_file_handles:
+            _lock_file_handles[lock_path]["ref_count"] += 1
+            return
+            
+    # Ensure parent directory exists
+    lock_dir = os.path.dirname(lock_path)
+    if lock_dir:
+        os.makedirs(lock_dir, exist_ok=True)
+        
+    # Open the lock file in append/read-write mode
+    handle = open(lock_path, "a+")
+    sys_type = platform.system().lower()
+    
+    if sys_type == "windows":
+        import msvcrt
+        mode = msvcrt.LK_LOCK if block else msvcrt.LK_NBLCK
+        try:
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), mode, 1)
+        except (IOError, OSError):
+            handle.close()
+            print(f"\033[31m[yyds-lock] 错误: 脚本进程已在运行中，当前实例自动退出！\033[0m", file=sys.stderr)
+            sys.exit(1)
+            
+    else:  # Linux / macOS / Unix
+        import fcntl
+        mode = fcntl.LOCK_EX
+        if not block:
+            mode |= fcntl.LOCK_NB
+            
+        try:
+            fcntl.flock(handle.fileno(), mode)
+        except (IOError, OSError):
+            handle.close()
+            print(f"\033[31m[yyds-lock] 错误: 脚本进程已在运行中，当前实例自动退出！\033[0m", file=sys.stderr)
+            sys.exit(1)
+            
+    with _global_lock:
+        # Double check to prevent rare race condition
+        if lock_path in _lock_file_handles:
+            # Another thread acquired it in the meantime (highly unlikely with _global_lock, but safe fallback)
+            _lock_file_handles[lock_path]["ref_count"] += 1
+            # Release our newly acquired OS lock as we already have one
+            try:
+                if sys_type == "windows":
+                    handle.seek(0)
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            except (IOError, OSError):
+                pass
+            handle.close()
+        else:
+            _lock_file_handles[lock_path] = {
+                "handle": handle,
+                "ref_count": 1
+            }
+
+def release_single(lock_name: str = "yyds_instance.lock"):
+    """
+    Manually releases a lock if it was acquired by the current process.
+    """
+    global _lock_file_handles
+    
+    lock_path = _resolve_lock_path(lock_name)
+    handle_to_close = None
+    
+    with _global_lock:
+        lock_info = _lock_file_handles.get(lock_path)
+        if not lock_info:
+            return
+            
+        lock_info["ref_count"] -= 1
+        if lock_info["ref_count"] > 0:
+            return
+            
+        # Ref count reached 0, proceed to release lock
+        handle_to_close = lock_info["handle"]
+        _lock_file_handles.pop(lock_path, None)
+        
+    if handle_to_close:
+        sys_type = platform.system().lower()
+        try:
+            if sys_type == "windows":
+                import msvcrt
+                handle_to_close.seek(0)
+                msvcrt.locking(handle_to_close.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(handle_to_close.fileno(), fcntl.LOCK_UN)
+        except (IOError, OSError):
+            pass
+        finally:
+            handle_to_close.close()
+
+def single_decorator(lock_name: str = "yyds_instance.lock", block: bool = False):
+    """
+    Decorator syntax sugar for running a function as a single instance.
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            force_single(lock_name, block)
+            try:
+                return func(*args, **kwargs)
+            finally:
+                release_single(lock_name)
+        return wrapper
+    return decorator

yyds_lock-0.2.0/yyds_lock.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: yyds-lock
+Version: 0.2.0
+Summary: A lightweight cross-platform single-instance process lock for Python.
+Home-page: https://github.com/yyds-fast/yyds-lock
+Author: wzb
+Author-email: wzb@example.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# yyds-lock
+
+[![PyPI version](https://img.shields.io/pypi/v/yyds-lock.svg)](https://pypi.org/project/yyds-lock/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`yyds-lock` is an ultra-lightweight, zero-dependency Python library that guarantees single-instance execution of scripts/processes using operating system level advisory file locks. It is ideal for cron jobs, automation scripts, schedulers, and background daemons.
+
+## Key Features
+
+- 🛡️ **Immunity to Crashes / Force Kills**: Unlike simple PID files or "lock files" that leave stale markers behind if the script crashes, is killed (`kill -9`), or suffers power loss, `yyds-lock` binds the lock to the process file descriptor. The OS automatically and instantly releases the lock as soon as the process ends.
+- 🪶 **Zero Dependencies**: 100% pure Python standard library. The installation size is less than 5KB and does not pollute your environment.
+- 🎛️ **Dual Modes**: Supports both "Instant Exit" (non-blocking, terminates immediately if another instance is running) and "Queue / Wait" (blocking, waits for the existing instance to finish).
+- 💻 **Cross-Platform**: Seamlessly works on Linux, macOS (using `fcntl.flock`), and Windows (using `msvcrt.locking`).
+
+---
+
+## Installation
+
+```bash
+pip install -U yyds-lock
+```
+
+---
+
+## Usage
+
+You can protect your script using either of two simple approaches:
+
+### Pattern A: Direct Call (Best for straightforward scripts / entrypoints)
+
+Place this call at the very top of your entrypoint script. If another instance of the script is already running, the new instance will immediately print an error to stderr and exit with status code `1`.
+
+```python
+import time
+import yyds_lock
+
+# Force single-instance execution.
+yyds_lock.force_single(lock_name="my_automation.lock", block=False)
+
+print("Running heavy automation task...")
+time.sleep(300)
+```
+
+### Pattern B: Decorator (Best for structured functions/main entrypoints)
+
+Decorate your `main` function to enforce mutual exclusion.
+
+```python
+import yyds_lock
+
+@yyds_lock.single_decorator(lock_name="my_task.lock", block=False)
+def main():
+    print("Executing single instance task safely...")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## Configuration / Arguments
+
+Both `force_single` and `single_decorator` accept the following arguments:
+
+- `lock_name` (str): The filename/path of the lock.
+  - If a simple filename is given (e.g. `"my_job.lock"`), it is automatically created in the user's home directory (`~`).
+  - If an absolute or relative path is given (e.g., `"/var/run/my_job.lock"`), it is created at that specific path. The parent directories will be created automatically if they do not exist.
+- `block` (bool):
+  - `False` (default): Exit immediately if the lock cannot be acquired.
+  - `True`: Block and queue, waiting for the active process to finish and release the lock.
+
+---
+
+## How It Works Under the Hood
+
+1. **Linux / macOS**: Uses `fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)` for exclusive advisory locking.
+2. **Windows**: Uses `msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)` to lock the first byte of the file.
+3. The library stores the open file handles in a global dictionary inside the Python runtime. This keeps the file descriptor open and prevents garbage collection (GC) from releasing the lock prematurely.
+4. When the process terminates (normally, via Exception, `sys.exit`, crash, `kill -9`, or power failure), the OS closes the file descriptors, releasing the locks instantly.

yyds_lock-0.2.0/yyds_lock.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+setup.py
+tests/test_lock.py
+yyds_lock/__init__.py
+yyds_lock/__version__.py
+yyds_lock/core.py
+yyds_lock.egg-info/PKG-INFO
+yyds_lock.egg-info/SOURCES.txt
+yyds_lock.egg-info/dependency_links.txt
+yyds_lock.egg-info/top_level.txt

yyds_lock-0.2.0/yyds_lock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

yyds_lock-0.2.0/yyds_lock.egg-info/top_level.txt

@@ -0,0 +1 @@
+yyds_lock