paulb@515 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@515 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
paulb@515 | 3 | |
paulb@515 | 4 | <title>DirectoryRepository - Simple Access to Files in a Directory</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@515 | 5 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
paulb@515 | 6 | <body> |
paulb@515 | 7 | <h1>DirectoryRepository - Simple Access to Files in a Directory</h1> |
paulb@515 | 8 | <p>In applications it is often convenient to be able to save or remember information provided or edited by a user. Whilst <a href="sessions.html">sessions</a> |
paulb@515 | 9 | often provide a convenient means of remembering such information, they |
paulb@515 | 10 | have certain limitations, notably that they are only available to a |
paulb@515 | 11 | particular user and cannot be shared with other users, and that their |
paulb@515 | 12 | data is stored in a form that is not necessarily convenient to access |
paulb@515 | 13 | by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code> |
paulb@515 | 14 | class is that it stores information as files in a designated directory, |
paulb@515 | 15 | that such files can be accessed by any resource with access to that |
paulb@515 | 16 | directory, and that a certain degree of locking is provided to avoid |
paulb@515 | 17 | contention between resources. Once created, instances of <code>DirectoryRepository</code> |
paulb@515 | 18 | can be accessed almost like sessions, although it is possible to obtain |
paulb@515 | 19 | the full paths to files in the repository and to use file objects and |
paulb@515 | 20 | methods to obtain and deposit content in such files.</p><div class="WebStack"><h3>WebStack API - DirectoryRepository Initialisation</h3><p>The <code>DirectoryRepository</code> class (found in the <code>WebStack.Repositories.Directory</code> module) accepts the following parameters when being initialised:</p><dl><dt><code>path</code></dt><dd>This parameter specifies the path to the directory in the filesystem where repository files are to be stored.</dd><dt><code>fsencoding</code></dt><dd>This |
paulb@515 | 21 | optional parameter specifies the character encoding employed by the |
paulb@515 | 22 | filesystem to represent filenames. If left unspecified, the |
paulb@515 | 23 | implementation will attempt to guess the correct encoding or, where |
paulb@515 | 24 | supported, to use Unicode filenames.</dd><dt><code>delay</code></dt><dd>This |
paulb@515 | 25 | optional parameter specifies a delay period for which a program will be |
paulb@515 | 26 | made to wait if a repository file is found to be locked by another |
paulb@515 | 27 | process.</dd></dl></div><h2>Initialisation Strategies</h2><p>One might choose to initialise a repository in the initialisation method of a resource:</p><pre># Inside a module defining a resource...<br /><br />class MyResource:<br /> def __init__(self):<br /> repository_dir = os.path.join(os.path.split(__file__)[0], "repository")<br /> self.repository = DirectoryRepository(repository_dir, "iso-8859-1")</pre><p>Here, the repository will reside alongside the resource's module in the filesystem.</p><h2>Session-like Access</h2><p>One might use a repository with a session-like API as follows:</p><pre># Given a name and some data, possibly provided in user input, store the data in the repository.<br /><br />repository[name] = data </pre><p>Note that <code>DirectoryRepository</code> |
paulb@515 | 28 | places some restrictions on the values that can be used as keys in the |
paulb@515 | 29 | session-like API since each key must correspond to a filename within |
paulb@515 | 30 | the designated directory.</p><h2>Advanced Access</h2><p>The <code>DirectoryRepository</code> class also provides various methods to support access to files in the repository using standard file objects and methods:</p><pre># Given a name and some data...<br /><br />repository.lock(name)<br />f = open(repository.full_path(name), "wb")<br />try:<br /> f.write(data)<br />finally:<br /> f.close()<br /> repository.unlock(name)</pre><p>The usage of <code>try</code> and <code>finally</code> |
paulb@515 | 31 | clauses is important to ensure that files are not left locked and |
paulb@515 | 32 | inaccessible due to unhandled exceptions being raised. See the <a href="../apidocs/public/WebStack.Repositories.Directory.DirectoryRepository-class.html">API documentation</a> for the <code>DirectoryRepository</code> class for more information about the available methods and their behaviour.</p></body></html> |