1.1 --- a/docs/directory-repository.html Sat Sep 08 16:01:41 2007 +0000
1.2 +++ b/docs/directory-repository.html Sat Sep 08 16:02:18 2007 +0000
1.3 @@ -1,32 +1,32 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.6 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.7 -
1.8 - <title>DirectoryRepository - Simple Access to Files in a Directory</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.9 + <title>DirectoryRepository - Simple Access to Files in a Directory</title>
1.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.11 <body>
1.12 <h1>DirectoryRepository - Simple Access to Files in a Directory</h1>
1.13 -<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>
1.14 +<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>
1.15 often provide a convenient means of remembering such information, they
1.16 have certain limitations, notably that they are only available to a
1.17 particular user and cannot be shared with other users, and that their
1.18 data is stored in a form that is not necessarily convenient to access
1.19 -by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code>
1.20 +by other tools or systems.</p><p>The principle behind the <code>DirectoryRepository</code>
1.21 class is that it stores information as files in a designated directory,
1.22 that such files can be accessed by any resource with access to that
1.23 directory, and that a certain degree of locking is provided to avoid
1.24 -contention between resources. Once created, instances of <code>DirectoryRepository</code>
1.25 +contention between resources. Once created, instances of <code>DirectoryRepository</code>
1.26 can be accessed almost like sessions, although it is possible to obtain
1.27 the full paths to files in the repository and to use file objects and
1.28 -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
1.29 +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
1.30 optional parameter specifies the character encoding employed by the
1.31 filesystem to represent filenames. If left unspecified, the
1.32 implementation will attempt to guess the correct encoding or, where
1.33 supported, to use Unicode filenames.</dd><dt><code>delay</code></dt><dd>This
1.34 optional parameter specifies a delay period for which a program will be
1.35 made to wait if a repository file is found to be locked by another
1.36 -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>
1.37 +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>
1.38 places some restrictions on the values that can be used as keys in the
1.39 session-like API since each key must correspond to a filename within
1.40 -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>
1.41 +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>
1.42 clauses is important to ensure that files are not left locked and
1.43 -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>
1.44 +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>