1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 3 4 <title>DirectoryRepository - Simple Access to Files in a Directory</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 5 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 6 <body> 7 <h1>DirectoryRepository - Simple Access to Files in a Directory</h1> 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> 9 often provide a convenient means of remembering such information, they 10 have certain limitations, notably that they are only available to a 11 particular user and cannot be shared with other users, and that their 12 data is stored in a form that is not necessarily convenient to access 13 by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code> 14 class is that it stores information as files in a designated directory, 15 that such files can be accessed by any resource with access to that 16 directory, and that a certain degree of locking is provided to avoid 17 contention between resources. Once created, instances of <code>DirectoryRepository</code> 18 can be accessed almost like sessions, although it is possible to obtain 19 the full paths to files in the repository and to use file objects and 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 21 optional parameter specifies the character encoding employed by the 22 filesystem to represent filenames. If left unspecified, the 23 implementation will attempt to guess the correct encoding or, where 24 supported, to use Unicode filenames.</dd><dt><code>delay</code></dt><dd>This 25 optional parameter specifies a delay period for which a program will be 26 made to wait if a repository file is found to be locked by another 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> 28 places some restrictions on the values that can be used as keys in the 29 session-like API since each key must correspond to a filename within 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 />edit_path = repository.lock(name)<br />f = open(edit_path, "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> 31 clauses is important to ensure that files are not left locked and 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>