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.
Parameters:
* `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.
Parameters:
* `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.
Raw data
{
"_id": null,
"home_page": "https://bitbucket.org/cameron_simpson/css/commits/all",
"name": "cs.sharedfile",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python2,python3",
"author": "Cameron Simpson",
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/11/77/77753a753cd7b4eadec92901da92c0e0101279e206ede1f4bfb9ebefec92/cs.sharedfile-20230212.tar.gz",
"platform": null,
"description": "Facilities for shared access to files.\n\n*Latest release 20230212*:\nRemove dependency on cs.logutils.\n\n## Function `lockfile(path, ext=None, poll_interval=None, timeout=None)`\n\nA context manager which takes and holds a lock file.\n\nParameters:\n* `path`: the base associated with the lock file.\n* `ext`:\n the extension to the base used to construct the lock file name.\n Default: `\".lock\"`\n* `timeout`: maximum time to wait before failing,\n default None (wait forever).\n* `poll_interval`: polling frequency when timeout is not 0.\n\n## Class `SharedAppendFile`\n\nA base class to share a modifiable file between multiple users.\n\nThe use case was driven from the shared CSV files used by\n`cs.nodedb.csvdb.Backend_CSVFile`, where multiple users can\nread from a common CSV file, and coordinate updates with a\nlock file.\n\nThis presents the following interfaces:\n* `__iter__`: yields data chunks from the underlying file up\n to EOF; it blocks no more than reading from the file does.\n Note that multiple iterators share the same read pointer.\n\n* `open`: a context manager returning a writable file for writing\n updates to the file; it blocks reads from this instance\n (though not, of course, by other users of the file) and\n arranges that users of `__iter__` do not receive their own\n written data, thus arranging that `__iter__` returns only\n foreign file updates.\n\nSubclasses would normally override `__iter__` to parse the\nreceived data into their natural records.\n\n*Method `SharedAppendFile.__init__(self, pathname, read_only=False, write_only=False, binary=False, newline=None, lock_ext=None, lock_timeout=None, poll_interval=None)`*:\nInitialise this SharedAppendFile.\n\nParameters:\n* `pathname`: the pathname of the file to open.\n* `read_only`: set to true if we will not write updates.\n* `write_only`: set to true if we will not read updates.\n* `binary`: if the file is to be opened in binary mode, otherwise text mode.\n* 'newline`: passed to `open()`\n* `lock_ext`: lock file extension.\n* `lock_timeout`: maxmimum time to wait for obtaining the lock file.\n* `poll_interval`: poll time when taking a lock file,\n default `DEFAULT_POLL_INTERVAL`\n\n## Class `SharedAppendLines(SharedAppendFile)`\n\nA line oriented subclass of `SharedAppendFile`.\n\n## Class `SharedCSVFile(SharedAppendLines, SharedAppendFile)`\n\nShared access to a CSV file in UTF-8 encoding.\n\n## Class `SharedWriteable`\n\nWrapper for a writable file with supported mutex based cooperation.\n\nThis is mostly a proxy for the wrapped file\nexceptthat all `.write` calls are serialised\nand when used as a context manager\nother writers are blocked.\n\nThis is to support shared use of an output stream\nwhere certain outputs should be contiguous,\nsuch as a standard error stream used to maintain a status line\nor multiline messages.\n\n# Release Log\n\n\n\n*Release 20230212*:\nRemove dependency on cs.logutils.\n\n*Release 20211208*:\nUpdate import.\n\n*Release 20201228*:\nNew SharedWriteable class to manage concurrent output with a mutexed .write method and a context manager for grouping larger uses.\n\n*Release 20190102*:\nContext manager bugfix.\n\n*Release 20170608*:\n* Facilities for shared files, split out from cs.fileutils.\n* SharedAppend* classes. lockfile function.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "facilities for shared access to files",
"version": "20230212",
"split_keywords": [
"python2",
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c1968db33742be8b4f032e1ba504ec61ff6789841423880196a65b8eedf5572",
"md5": "fd10bdc80f18593a61adff5a79a044bc",
"sha256": "d7860f86ce83a933b029453a750540c0322049c5fa403a624e681a75c01e792b"
},
"downloads": -1,
"filename": "cs.sharedfile-20230212-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd10bdc80f18593a61adff5a79a044bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7196,
"upload_time": "2023-02-12T00:12:56",
"upload_time_iso_8601": "2023-02-12T00:12:56.469047Z",
"url": "https://files.pythonhosted.org/packages/2c/19/68db33742be8b4f032e1ba504ec61ff6789841423880196a65b8eedf5572/cs.sharedfile-20230212-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "117777753a753cd7b4eadec92901da92c0e0101279e206ede1f4bfb9ebefec92",
"md5": "2a3b8a4fa28a737943924650947a6d4e",
"sha256": "1e96db56715baf025b046e8a7df7eb5d3fa186ded7d963fadeeb7d71a8c2b8e0"
},
"downloads": -1,
"filename": "cs.sharedfile-20230212.tar.gz",
"has_sig": false,
"md5_digest": "2a3b8a4fa28a737943924650947a6d4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7328,
"upload_time": "2023-02-12T00:12:58",
"upload_time_iso_8601": "2023-02-12T00:12:58.442618Z",
"url": "https://files.pythonhosted.org/packages/11/77/77753a753cd7b4eadec92901da92c0e0101279e206ede1f4bfb9ebefec92/cs.sharedfile-20230212.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-12 00:12:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "cs.sharedfile"
}
JSON