# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-zc.lockfile
VERSION=		4.0
KEYWORDS=		python
VARIANTS=		v13 v14
SDESC[v13]=		Basic inter-process locks (3.13)
SDESC[v14]=		Basic inter-process locks (3.14)
HOMEPAGE=		https://github.com/zopefoundation/zc.lockfile
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/3b/7f/3a614b65bc4b181578b1d50a78663ee02d5d2d3b859712f3d3597c8afe6f
DISTFILE[1]=		zc_lockfile-4.0-py3-none-any.whl:main
DIST_SUBDIR=		python-src
DF_INDEX=		1
SPKGS[v13]=		single
SPKGS[v14]=		single

OPTIONS_AVAILABLE=	PY313 PY314
OPTIONS_STANDARD=	none
VOPTS[v13]=		PY313=ON PY314=OFF
VOPTS[v14]=		PY313=OFF PY314=ON

DISTNAME=		zc_lockfile-4.0.dist-info

GENERATED=		yes

[PY313].RUN_DEPENDS_ON=			python-setuptools:single:v13
[PY313].USES_ON=			python:v13,wheel

[PY314].RUN_DEPENDS_ON=			python-setuptools:single:v14
[PY314].USES_ON=			python:v14,wheel

[FILE:2803:descriptions/desc.single]
*************************
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
***************

4.0 (2025-09-18)
================

- Replace pkg_resources namespace with PEP 420 native namespace.


[FILE:122:distinfo]
aa3aa295257bebaa09ea9ad5cb288bf9f98f88de6932f96b6659f62715d83581         9143 python-src/zc_lockfile-4.0-py3-none-any.whl