<a name="L6"></a><tt class="py-lineno"> 6</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># This program is free software; you can redistribute it and/or</tt> </tt>
<a name="L7"></a><tt class="py-lineno"> 7</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># modify it under the terms of the GNU General Public License</tt> </tt>
<a name="L8"></a><tt class="py-lineno"> 8</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># as published by the Free Software Foundation; either version 2 </tt> </tt>
<a name="L9"></a><tt class="py-lineno"> 9</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># of the License, or (at your option) any later version.</tt> </tt>
<a name="L11"></a><tt class="py-lineno"> 11</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># This program is distributed in the hope that it will be useful,</tt> </tt>
<a name="L12"></a><tt class="py-lineno"> 12</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># but WITHOUT ANY WARRANTY; without even the implied warranty of</tt> </tt>
<a name="L13"></a><tt class="py-lineno"> 13</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the</tt> </tt>
<a name="L14"></a><tt class="py-lineno"> 14</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># GNU General Public License for more details. </tt> </tt>
<a name="L16"></a><tt class="py-lineno"> 16</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># You should have received a copy of the GNU General Public License</tt> </tt>
<a name="L17"></a><tt class="py-lineno"> 17</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># along with this program; if not, write to the Free Software</tt> </tt>
<a name="L18"></a><tt class="py-lineno"> 18</tt> <tt class="py-line"><tt class="py-comment"></tt><tt class="py-comment"># Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.</tt> </tt>
<a name="L26"></a><tt class="py-lineno"> 26</tt> <tt class="py-line"><tt class="py-docstring"> Contains the base classes and interfaces used to define a database of records.</tt> </tt>
<a name="L28"></a><tt class="py-lineno"> 28</tt> <tt class="py-line"><tt class="py-docstring"> The databases can be managed in different L{physical stores</tt> </tt>
<a name="L29"></a><tt class="py-lineno"> 29</tt> <tt class="py-line"><tt class="py-docstring"> <Pyblio.Stores>}. To create a new database, get a specific store</tt> </tt>
<a name="L30"></a><tt class="py-lineno"> 30</tt> <tt class="py-line"><tt class="py-docstring"> implementation with the L{get <Pyblio.Store.get>} function, and call</tt> </tt>
<a name="L35"></a><tt class="py-lineno"> 35</tt> <tt class="py-line"><tt class="py-docstring"> Once this is done, the database is ready to accept L{records</tt> </tt>
<a name="L42"></a><tt class="py-lineno"> 42</tt> <tt class="py-line"><tt class="py-docstring"> @see: the L{Database} class to know what operations can be performed</tt> </tt>
<a name="L43"></a><tt class="py-lineno"> 43</tt> <tt class="py-line"><tt class="py-docstring"> on databases.</tt> </tt>
<a name="L64"></a><tt class="py-lineno"> 64</tt> <tt class="py-line"> <tt class="py-docstring">''' A key that uniquely identifies a record in a database.</tt> </tt>
<a name="L66"></a><tt class="py-lineno"> 66</tt> <tt class="py-line"><tt class="py-docstring"> @note: this class is shared by all backend stores.</tt> </tt>
<a name="L77"></a><tt class="py-lineno"> 77</tt> <tt class="py-line"><tt class="py-docstring"> It behaves like a dictionnary, which returns a B{list} of</tt> </tt>
<a name="L78"></a><tt class="py-lineno"> 78</tt> <tt class="py-line"><tt class="py-docstring"> attributes for each key. The attributes types depend on the</tt> </tt>
<a name="L81"></a><tt class="py-lineno"> 81</tt> <tt class="py-line"><tt class="py-docstring"> As a convenience, it is possible to use L{Record.add} to build up</tt> </tt>
<a name="L82"></a><tt class="py-lineno"> 82</tt> <tt class="py-line"><tt class="py-docstring"> a Record, instead of setting its fields manually.</tt> </tt>
<a name="L84"></a><tt class="py-lineno"> 84</tt> <tt class="py-line"><tt class="py-docstring"> @ivar key: the key of the record, unique over the whole</tt> </tt>
<a name="L85"></a><tt class="py-lineno"> 85</tt> <tt class="py-line"><tt class="py-docstring"> database. It is generated by the actual storage layer. This key</tt> </tt>
<a name="L86"></a><tt class="py-lineno"> 86</tt> <tt class="py-line"><tt class="py-docstring"> has only an internal meaning. Do not expose it.</tt> </tt>
<a name="L113"></a><tt class="py-lineno">113</tt> <tt class="py-line"><tt class="py-docstring"> Writes the content of the record as an XML fragment.</tt> </tt>
<a name="L141"></a><tt class="py-lineno">141</tt> <tt class="py-line"><tt class="py-docstring"> This function allows you to add an item to a record. It</tt> </tt>
<a name="L142"></a><tt class="py-lineno">142</tt> <tt class="py-line"><tt class="py-docstring"> converts the specified 'value' by calling 'constructor' on it,</tt> </tt>
<a name="L143"></a><tt class="py-lineno">143</tt> <tt class="py-line"><tt class="py-docstring"> and appends the resulting attribute to the record.</tt> </tt>
<a name="L145"></a><tt class="py-lineno">145</tt> <tt class="py-line"><tt class="py-docstring"> If you specify something like 'a.b' in fields, the 'b'</tt> </tt>
<a name="L146"></a><tt class="py-lineno">146</tt> <tt class="py-line"><tt class="py-docstring"> qualifier for field 'a' is set, for the last 'a' added. It is</tt> </tt>
<a name="L147"></a><tt class="py-lineno">147</tt> <tt class="py-line"><tt class="py-docstring"> possible, if you know that you will only have B{one} 'a', to</tt> </tt>
<a name="L148"></a><tt class="py-lineno">148</tt> <tt class="py-line"><tt class="py-docstring"> set 'a.b' before 'a'.</tt> </tt>
<a name="L158"></a><tt class="py-lineno">158</tt> <tt class="py-line"><tt class="py-docstring"> @param field: the field we want to add in the record</tt> </tt>
<a name="L159"></a><tt class="py-lineno">159</tt> <tt class="py-line"><tt class="py-docstring"> @type field: a string, possibly containing a '.' in the case of structured attributes</tt> </tt>
<a name="L161"></a><tt class="py-lineno">161</tt> <tt class="py-line"><tt class="py-docstring"> @param value: the 'source' value to set in the record. This</tt> </tt>
<a name="L162"></a><tt class="py-lineno">162</tt> <tt class="py-line"><tt class="py-docstring"> value has not yet been converted into an</tt> </tt>
<a name="L165"></a><tt class="py-lineno">165</tt> <tt class="py-line"><tt class="py-docstring"> @param constructor: a function that will turn a 'value' into a</tt> </tt>
<a name="L178"></a><tt class="py-lineno">178</tt> <tt class="py-line"> <tt class="py-comment">#is already of Attribute.XXX-type, so don't do anything.</tt> </tt>
<a name="L235"></a><tt class="py-lineno">235</tt> <tt class="py-line"> <tt class="py-docstring">""" A view of a Result Set represents the Result Set sorted</tt> </tt>
<a name="L236"></a><tt class="py-lineno">236</tt> <tt class="py-line"><tt class="py-docstring"> according to a specific criterion.</tt> </tt>
<a name="L269"></a><tt class="py-lineno">269</tt> <tt class="py-line"><tt class="py-docstring"> These sets can be manually managed by the user or be the result of</tt> </tt>
<a name="L270"></a><tt class="py-lineno">270</tt> <tt class="py-line"><tt class="py-docstring"> a query. They can be made persistent, and are then stored along</tt> </tt>
<a name="L271"></a><tt class="py-lineno">271</tt> <tt class="py-line"><tt class="py-docstring"> with the database.</tt> </tt>
<a name="L273"></a><tt class="py-lineno">273</tt> <tt class="py-line"><tt class="py-docstring"> @note: this class is usually derived by every backend store.</tt> </tt>
</div><div id="ResultSet.add-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="ResultSet.add-expanded"><a name="L278"></a><tt class="py-lineno">278</tt> <tt class="py-line"> <tt class="py-docstring">""" Add a new item in the set.</tt> </tt>
</div><div id="ResultSetStore.update-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="ResultSetStore.update-expanded"><a name="L364"></a><tt class="py-lineno">364</tt> <tt class="py-line"> <tt class="py-docstring">"""Use this to permanently store a ResultSet() in the database.</tt> </tt>
<a name="L366"></a><tt class="py-lineno">366</tt> <tt class="py-line"><tt class="py-docstring"> Note: when a ResultSet object is modified, it is necessary to</tt> </tt>
<a name="L367"></a><tt class="py-lineno">367</tt> <tt class="py-line"><tt class="py-docstring"> call db.rs.update(result_set) to store the updated version.</tt> </tt>
<a name="L377"></a><tt class="py-lineno">377</tt> <tt class="py-line"><tt class="py-docstring"> A database behaves like a dictionnary, linking a L{key</tt> </tt>
<a name="L378"></a><tt class="py-lineno">378</tt> <tt class="py-line"><tt class="py-docstring"> <Pyblio.Store.Key>} with a L{record <Pyblio.Store.Record>}. The</tt> </tt>
<a name="L379"></a><tt class="py-lineno">379</tt> <tt class="py-line"><tt class="py-docstring"> records are B{typed}, and must follow the specifications of a</tt> </tt>
<a name="L392"></a><tt class="py-lineno">392</tt> <tt class="py-line"><tt class="py-docstring"> When the record is added, a L{key <Pyblio.Store.Key>} is generated</tt> </tt>
<a name="L393"></a><tt class="py-lineno">393</tt> <tt class="py-line"><tt class="py-docstring"> which uniquely references the record.</tt> </tt>
<a name="L398"></a><tt class="py-lineno">398</tt> <tt class="py-line"><tt class="py-docstring"> It is possible to use the database as a dictionnary. So, given a key k:</tt> </tt>
<a name="L402"></a><tt class="py-lineno">402</tt> <tt class="py-line"><tt class="py-docstring"> Alternatively, one can access all the records in a database in random</tt> </tt>
<a name="L405"></a><tt class="py-lineno">405</tt> <tt class="py-line"><tt class="py-docstring"> >>> for key, record in db.entries.iteritems ():</tt> </tt>
<a name="L406"></a><tt class="py-lineno">406</tt> <tt class="py-line"><tt class="py-docstring"> >>> # do something with the record...</tt> </tt>
<a name="L411"></a><tt class="py-lineno">411</tt> <tt class="py-line"><tt class="py-docstring"> Simply store the record back once it is updated:</tt> </tt>
<a name="L420"></a><tt class="py-lineno">420</tt> <tt class="py-line"><tt class="py-docstring"> @attention: getting a record from the database returns a I{new copy}</tt> </tt>
<a name="L421"></a><tt class="py-lineno">421</tt> <tt class="py-line"><tt class="py-docstring"> at each access. Updating this copy I{does not} change the stored</tt> </tt>
<a name="L427"></a><tt class="py-lineno">427</tt> <tt class="py-line"><tt class="py-docstring"> @cvar txo: B{DEPRECATED}, use L{schema.txo} instead. A L{TxoGroup}</tt> </tt>
<a name="L428"></a><tt class="py-lineno">428</tt> <tt class="py-line"><tt class="py-docstring"> instance, containing all the taxonomy definitions in the</tt> </tt>
</div><div id="Database._entries_get-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database._entries_get-expanded"><a name="L451"></a><tt class="py-lineno">451</tt> <tt class="py-line"> <tt class="py-docstring">""" Return the result set that contains _all_ the entries. """</tt> </tt>
</div><div id="Database.add-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database.add-expanded"><a name="L459"></a><tt class="py-lineno">459</tt> <tt class="py-line"> <tt class="py-docstring">""" Insert a new entry in the database.</tt> </tt>
<a name="L461"></a><tt class="py-lineno">461</tt> <tt class="py-line"><tt class="py-docstring"> New entries B{MUST} be added with this method, not via an</tt> </tt>
<a name="L462"></a><tt class="py-lineno">462</tt> <tt class="py-line"><tt class="py-docstring"> update with a hand-made Key.</tt> </tt>
</div><div id="Database.__getitem__-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database.__getitem__-expanded"><a name="L490"></a><tt class="py-lineno">490</tt> <tt class="py-line"> <tt class="py-docstring">""" Get a record by key.</tt> </tt>
</div><div id="Database.has_key-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database.has_key-expanded"><a name="L499"></a><tt class="py-lineno">499</tt> <tt class="py-line"> <tt class="py-docstring">""" Check for the existence of a key.</tt> </tt>
</div><div id="Database.collate-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database.collate-expanded"><a name="L511"></a><tt class="py-lineno">511</tt> <tt class="py-line"> <tt class="py-docstring">""" Partition the result set in a list of sets for every value</tt> </tt>
<a name="L512"></a><tt class="py-lineno">512</tt> <tt class="py-line"><tt class="py-docstring"> taken by the specified field"""</tt> </tt>
</div><div id="Database.validate-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database.validate-expanded"><a name="L537"></a><tt class="py-lineno">537</tt> <tt class="py-line"> <tt class="py-docstring">""" Check an entry for conformance against the Schema. This</tt> </tt>
<a name="L538"></a><tt class="py-lineno">538</tt> <tt class="py-line"><tt class="py-docstring"> method may modify the entry to normalize certain fields."""</tt> </tt>
<a name="L574"></a><tt class="py-lineno">574</tt> <tt class="py-line"> <tt class="py-op">(</tt><tt class="py-name">_</tt><tt class="py-op">(</tt><tt class="py-string">'%s: attribute %s has an incorrect type (should be %s but is %s)'</tt><tt class="py-op">)</tt> <tt class="py-op">%</tt> <tt class="py-op">(</tt> </tt>
<a name="L581"></a><tt class="py-lineno">581</tt> <tt class="py-line"> <tt class="py-op">(</tt><tt class="py-name">_</tt><tt class="py-op">(</tt><tt class="py-string">'%s: qualifier %s in attribute %s has an incorrect type (should be %s but is %s)'</tt><tt class="py-op">)</tt> <tt class="py-op">%</tt> <tt class="py-op">(</tt> </tt>
<a name="L598"></a><tt class="py-lineno">598</tt> <tt class="py-line"> <tt class="py-comment"># check if the enum is in the group defined in the schema</tt> </tt>
<a name="L614"></a><tt class="py-lineno">614</tt> <tt class="py-line"><tt class="py-comment"></tt> <tt class="py-comment"># more specific item is also present, there is no need</tt> </tt>
<a name="L615"></a><tt class="py-lineno">615</tt> <tt class="py-line"><tt class="py-comment"></tt> <tt class="py-comment"># to keep the parent)</tt> </tt>
<a name="L621"></a><tt class="py-lineno">621</tt> <tt class="py-line"> <tt class="py-comment"># exp is the list of children of the current txo item</tt> </tt>
<a name="L625"></a><tt class="py-lineno">625</tt> <tt class="py-line"> <tt class="py-comment"># If another txo is a child of the current txo,</tt> </tt>
<a name="L626"></a><tt class="py-lineno">626</tt> <tt class="py-line"><tt class="py-comment"></tt> <tt class="py-comment"># the current one can be removed.</tt> </tt>
</div><div id="Database.xmlwrite-collapsed" style="display:none;" pad="+++" indent="++++++++"></div><div id="Database.xmlwrite-expanded"><a name="L636"></a><tt class="py-lineno">636</tt> <tt class="py-line"> <tt class="py-docstring">""" Output a database in XML format """</tt> </tt>
<a name="L749"></a><tt class="py-lineno">749</tt> <tt class="py-line"> <tt class="py-docstring">""" Return the methods provided by a specific storage layer.</tt> </tt>
<a name="L760"></a><tt class="py-lineno">760</tt> <tt class="py-line"><tt class="py-docstring"> - dbopen (file): open a database in the specific store</tt> </tt>
<a name="L762"></a><tt class="py-lineno">762</tt> <tt class="py-line"><tt class="py-docstring"> - dbimport (file): import an XML database into the specific store</tt> </tt>
<a name="L766"></a><tt class="py-lineno">766</tt> <tt class="py-line"><tt class="py-docstring"> For more information, consult the documentation for the specific</tt> </tt>