Metadata-Version: 2.1
Name: zc.lockfile
Version: 1.3.0
Summary: Basic inter-process locks
Home-page: http://www.python.org/pypi/zc.lockfile
Author: Zope Foundation
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: *************************
        Basic inter-process locks
        *************************
        
        The zc.lockfile package provides a basic portable implementation of
        interprocess locks using lock files.  The purpose if not specifically
        to lock files, but to simply provide locks with an implementation
        based on file-locking primitives.  Of course, these locks could be
        used to mediate access to *other* files.  For example, the ZODB file
        storage implementation uses file locks to mediate access to
        file-storage database files.  The database files and lock file files
        are separate files.
        
        .. contents::
        
        Detailed Documentation
        **********************
        
        Lock file support
        =================
        
        The ZODB lock_file module provides support for creating file system
        locks.  These are locks that are implemented with lock files and
        OS-provided locking facilities.  To create a lock, instantiate a
        LockFile object with a file name:
        
            >>> import zc.lockfile
            >>> lock = zc.lockfile.LockFile('lock')
        
        If we try to lock the same name, we'll get a lock error:
        
            >>> import zope.testing.loggingsupport
            >>> handler = zope.testing.loggingsupport.InstalledHandler('zc.lockfile')
            >>> try:
            ...     zc.lockfile.LockFile('lock')
            ... except zc.lockfile.LockError:
            ...     print("Can't lock file")
            Can't lock file
        
        .. We don't log failure to acquire.
        
            >>> for record in handler.records: # doctest: +ELLIPSIS
            ...     print(record.levelname+' '+record.getMessage())
        
        To release the lock, use it's close method:
        
            >>> lock.close()
        
        The lock file is not removed.  It is left behind:
        
            >>> import os
            >>> os.path.exists('lock')
            True
        
        Of course, now that we've released the lock, we can create it again:
        
            >>> lock = zc.lockfile.LockFile('lock')
            >>> lock.close()
        
        .. Cleanup
        
            >>> import os
            >>> os.remove('lock')
        
        Hostname in lock file
        =====================
        
        In a container environment (e.g. Docker), the PID is typically always
        identical even if multiple containers are running under the same operating
        system instance.
        
        Clearly, inspecting lock files doesn't then help much in debugging. To identify
        the container which created the lock file, we need information about the
        container in the lock file. Since Docker uses the container identifier or name
        as the hostname, this information can be stored in the lock file in addition to
        or instead of the PID.
        
        Use the ``content_template`` keyword argument to ``LockFile`` to specify a
        custom lock file content format:
        
            >>> lock = zc.lockfile.LockFile('lock', content_template='{pid};{hostname}')
            >>> lock.close()
        
        If you now inspected the lock file, you would see e.g.:
        
            $ cat lock
             123;myhostname
        
        
        Change History
        ***************
        
        1.3.0 (2018-04-23)
        ==================
        
        - Stop logging failure to acquire locks. Clients can do that if they wish.
        
        - Claim support for Python 3.4 and 3.5.
        
        - Drop Python 3.2 support because pip no longer supports it.
        
        1.2.1 (2016-06-19)
        ==================
        
        - Fixed: unlocking and locking didn't work when a multiprocessing
          process was running (and presumably other conditions).
        
        1.2.0 (2016-06-09)
        ==================
        
        - Added the ability to include the hostname in the lock file content.
        
        - Code and ReST markup cosmetics.
          [alecghica]
        
        1.1.0 (2013-02-12)
        ==================
        
        - Added Trove classifiers and made setup.py zest.releaser friendly.
        
        - Added Python 3.2, 3.3 and PyPy 1.9 support.
        
        - Removed Python 2.4 and Python 2.5 support.
        
        1.0.2 (2012-12-02)
        ==================
        
        - Fixed: the fix included in 1.0.1 caused multiple pids to be written
          to the lock file
        
        1.0.1 (2012-11-30)
        ==================
        
        - Fixed: when there was lock contention, the pid in the lock file was
          lost.
        
          Thanks to Daniel Moisset reporting the problem and providing a fix
          with tests.
        
        - Added test extra to declare test dependency on ``zope.testing``.
        
        - Using Python's ``doctest`` module instead of depreacted
          ``zope.testing.doctest``.
        
        1.0.0 (2008-10-18)
        ==================
        
        - Fixed a small bug in error logging.
        
        1.0.0b1 (2007-07-18)
        ====================
        
        - Initial release
        
        Download
        **********************
        
Keywords: lock
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development
Provides-Extra: test
