Skip to main content

facilities for shared access to files

Project description

Facilities for shared access to files.

Latest release 20230212: Remove dependency on cs.logutils.

Function lockfile(path, ext=None, poll_interval=None, timeout=None)

A context manager which takes and holds a lock file.


  • path: the base associated with the lock file.
  • ext: the extension to the base used to construct the lock file name. Default: ".lock"
  • timeout: maximum time to wait before failing, default None (wait forever).
  • poll_interval: polling frequency when timeout is not 0.

Class SharedAppendFile

A base class to share a modifiable file between multiple users.

The use case was driven from the shared CSV files used by cs.nodedb.csvdb.Backend_CSVFile, where multiple users can read from a common CSV file, and coordinate updates with a lock file.

This presents the following interfaces:

  • __iter__: yields data chunks from the underlying file up to EOF; it blocks no more than reading from the file does. Note that multiple iterators share the same read pointer.

  • open: a context manager returning a writable file for writing updates to the file; it blocks reads from this instance (though not, of course, by other users of the file) and arranges that users of __iter__ do not receive their own written data, thus arranging that __iter__ returns only foreign file updates.

Subclasses would normally override __iter__ to parse the received data into their natural records.

Method SharedAppendFile.__init__(self, pathname, read_only=False, write_only=False, binary=False, newline=None, lock_ext=None, lock_timeout=None, poll_interval=None): Initialise this SharedAppendFile.


  • pathname: the pathname of the file to open.
  • read_only: set to true if we will not write updates.
  • write_only: set to true if we will not read updates.
  • binary: if the file is to be opened in binary mode, otherwise text mode.
  • 'newline: passed to open()`
  • lock_ext: lock file extension.
  • lock_timeout: maxmimum time to wait for obtaining the lock file.
  • poll_interval: poll time when taking a lock file, default DEFAULT_POLL_INTERVAL

Class SharedAppendLines(SharedAppendFile)

A line oriented subclass of SharedAppendFile.

Class SharedCSVFile(SharedAppendLines, SharedAppendFile)

Shared access to a CSV file in UTF-8 encoding.

Class SharedWriteable

Wrapper for a writable file with supported mutex based cooperation.

This is mostly a proxy for the wrapped file exceptthat all .write calls are serialised and when used as a context manager other writers are blocked.

This is to support shared use of an output stream where certain outputs should be contiguous, such as a standard error stream used to maintain a status line or multiline messages.

Release Log

Release 20230212: Remove dependency on cs.logutils.

Release 20211208: Update import.

Release 20201228: New SharedWriteable class to manage concurrent output with a mutexed .write method and a context manager for grouping larger uses.

Release 20190102: Context manager bugfix.

Release 20170608:

  • Facilities for shared files, split out from cs.fileutils.
  • SharedAppend* classes. lockfile function.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cs.sharedfile-20230212.tar.gz (7.3 kB view hashes)

Uploaded Source

Built Distribution

cs.sharedfile-20230212-py3-none-any.whl (7.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page