Merge branch 'release/1.3.0'

README.rst

@@ -32,6 +32,21 @@ The module is currently maintained by Rick van Hattem <Wolph@wol.ph>.
 The project resides at https://github.com/WoLpH/portalocker . Bugs and feature
 requests can be submitted there. Patches are also very welcome.
 
+Tips
+----
+
+On some networked filesystems it might be needed to force a `os.fsync()` before closing the file so it's actually written before another client reads the file. Effectively this comes down to:
+
+::
+    
+   with portalocker.Lock('some_file', 'rb+', timeout=60) as fh:
+       # do what you need to do
+       ...
+       
+       # flush and sync to filesystem
+       fh.flush()
+       os.fsync(fh.fileno())
+
 Links
 -----
 

portalocker/__about__.py

@@ -1,7 +1,7 @@
 __package_name__ = 'portalocker'
 __author__ = 'Rick van Hattem'
 __email__ = 'wolph@wol.ph'
-__version__ = '1.2.1'
+__version__ = '1.3.0'
 __description__ = '''Wraps the portalocker recipe for easy usage'''
 __url__ = 'https://github.com/WoLpH/portalocker'
 

portalocker/__init__.py

@@ -11,7 +11,7 @@
 #: Current author's email address
 __email__ = __about__.__email__
 #: Version number
-__version__ = '1.2.1'
+__version__ = '1.3.0'
 #: Package description for Pypi
 __description__ = __about__.__description__
 #: Package homepage

portalocker/exceptions.py

@@ -2,6 +2,10 @@ class BaseLockException(Exception):
     # Error codes:
     LOCK_FAILED = 1
 
+    def __init__(self, *args, **kwargs):
+        self.fh = kwargs.pop('fh', None)
+        Exception.__init__(self, *args, **kwargs)
+
 
 class LockException(BaseLockException):
     pass

portalocker/portalocker.py

@@ -41,7 +41,8 @@ def lock(file_, flags):
                 if exc_value.winerror == winerror.ERROR_LOCK_VIOLATION:
                     raise exceptions.LockException(
                         exceptions.LockException.LOCK_FAILED,
-                        exc_value.strerror)
+                        exc_value.strerror,
+                        fh=file_)
                 else:
                     # Q:  Are there exceptions/codes we should be dealing with
                     # here?
@@ -74,13 +75,15 @@ def lock(file_, flags):
                     # [ ] be more specific here
                     raise exceptions.LockException(
                         exceptions.LockException.LOCK_FAILED,
-                        exc_value.strerror)
+                        exc_value.strerror,
+                        fh=file_)
                 finally:
                     if savepos:
                         file_.seek(savepos)
             except IOError as exc_value:
                 raise exceptions.LockException(
-                    exceptions.LockException.LOCK_FAILED, exc_value.strerror)
+                    exceptions.LockException.LOCK_FAILED, exc_value.strerror,
+                    fh=file_)
 
     def unlock(file_):
         try:
@@ -110,13 +113,15 @@ def unlock(file_):
                 else:
                     raise exceptions.LockException(
                         exceptions.LockException.LOCK_FAILED,
-                        exc_value.strerror)
+                        exc_value.strerror,
+                        fh=file_)
             finally:
                 if savepos:
                     file_.seek(savepos)
         except IOError as exc_value:
             raise exceptions.LockException(
-                exceptions.LockException.LOCK_FAILED, exc_value.strerror)
+                exceptions.LockException.LOCK_FAILED, exc_value.strerror,
+                fh=file_)
 
 elif os.name == 'posix':  # pragma: no cover
     import fcntl
@@ -133,7 +138,7 @@ def lock(file_, flags):
         except locking_exceptions as exc_value:
             # The exception code varies on different systems so we'll catch
             # every IO error
-            raise exceptions.LockException(exc_value)
+            raise exceptions.LockException(exc_value, fh=file_)
 
     def unlock(file_):
         fcntl.flock(file_.fileno(), constants.LOCK_UN)