diff --git a/gramps/gen/db/__init__.py b/gramps/gen/db/__init__.py index 001f613a8..d28ba2790 100644 --- a/gramps/gen/db/__init__.py +++ b/gramps/gen/db/__init__.py @@ -17,59 +17,73 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # -# gen/db/__init__.py # $Id$ # """ - Gramps Database API. +Gramps Database API. - Database Architecture - ===================== +Database Architecture +===================== - Access to the database is made through Python classes. Exactly - what functionality you have is dependent on the properties of the - database. For example, if you are accessing a read-only view, then - you will only have access to a subset of the methods available. +Access to the database is made through Python classes. Exactly +what functionality you have is dependent on the properties of the +database. For example, if you are accessing a read-only view, then +you will only have access to a subset of the methods available. - At the root of any database interface is either DbReadBase and/or - DbWriteBase. These define the methods to read and write to a - database, respectively. +At the root of any database interface is either :py:class:`.DbReadBase` and/or +:py:class:`.DbWriteBase`. These define the methods to read and write to a +database, respectively. - The full database hierarchy is: +The full database hierarchy is: - - B{DbBsddb} - read and write implementation to BSDDB databases (U{gen/db/write}) - - B{DbWriteBase} - virtual and implementation-independent methods for reading data (U{gen/db/base.py}) - - B{DbBsddbRead} - read-only (accessors, getters) implementation to BSDDB databases (U{gen/db/read.py}) - - B{DbDjango} - read and write implementation to Django-based databases (U{web/dbdjango.py}. + * :py:class:`.UpdateCallback` - callback functionality + +- :py:class:`.DbDjango` - read and write implementation to Django-based + databases + + * :py:class:`.DbWriteBase` - virtual and implementation-independent methods + for reading data + + * :py:class:`.DbReadBase` - virtual and implementation-independent methods + for reading data + +DbBsddb +======= + +The :py:class:`.DbBsddb` interface defines a hierarchical database +(non-relational) written in +`PyBSDDB `_. There is no +such thing as a database schema, and the meaning of the data is +defined in the Python classes above. The data is stored as pickled +tuples and unserialized into the primary data types (below). + +DbDjango +======== + +The DbDjango interface defines the Gramps data in terms of +*models* and *relations* from the +`Django project `_. The database +backend can be any implementation that supports Django, including +such popular SQL implementations as sqlite, MySQL, Postgresql, and +Oracle. The data is retrieved from the SQL fields, serialized and +then unserialized into the primary data types (below). + +More details can be found in the manual's +`Using database API `_. """ from .base import * diff --git a/gramps/gen/db/backup.py b/gramps/gen/db/backup.py index adc511c6d..bdf6c292a 100644 --- a/gramps/gen/db/backup.py +++ b/gramps/gen/db/backup.py @@ -83,11 +83,11 @@ def backup(database): Exports the database to a set of backup files. These files consist of the pickled database tables, one file for each table. - The heavy lifting is done by the private __do__export function. The - purpose of this function is to catch any exceptions that occur. + The heavy lifting is done by the private :py:func:`__do__export` function. + The purpose of this function is to catch any exceptions that occur. - @param database: database instance to backup - @type database: DbDir + :param database: database instance to backup + :type database: DbDir """ try: __do_export(database) @@ -98,10 +98,10 @@ def __mk_backup_name(database, base): """ Return the backup name of the database table - @param database: database instance - @type database: DbDir - @param base: base name of the table - @type base: str + :param database: database instance + :type database: DbDir + :param base: base name of the table + :type base: str """ return os.path.join(database.get_save_path(), base + ".gbkp") @@ -109,10 +109,10 @@ def __mk_tmp_name(database, base): """ Return the temporary backup name of the database table - @param database: database instance - @type database: DbDir - @param base: base name of the table - @type base: str + :param database: database instance + :type database: DbDir + :param base: base name of the table + :type base: str """ return os.path.join(database.get_save_path(), base + ".gbkp.new") @@ -121,8 +121,8 @@ def __do_export(database): Loop through each table of the database, saving the pickled data a file. - @param database: database instance to backup - @type database: DbDir + :param database: database instance to backup + :type database: DbDir """ try: for (base, tbl) in __build_tbl_map(database): @@ -151,11 +151,11 @@ def restore(database): Restores the database to a set of backup files. These files consist of the pickled database tables, one file for each table. - The heavy lifting is done by the private __do__restore function. The - purpose of this function is to catch any exceptions that occur. + The heavy lifting is done by the private :py:func:`__do__restore` function. + The purpose of this function is to catch any exceptions that occur. - @param database: database instance to restore - @type database: DbDir + :param database: database instance to restore + :type database: DbDir """ try: __do_restore(database) @@ -167,8 +167,8 @@ def __do_restore(database): Loop through each table of the database, restoring the pickled data to the appropriate database file. - @param database: database instance to backup - @type database: DbDir + :param database: database instance to backup + :type database: DbDir """ for (base, tbl) in __build_tbl_map(database): backup_name = __mk_backup_name(database, base) @@ -181,12 +181,12 @@ def __load_tbl_txn(database, backup_table, tbl): """ Return the temporary backup name of the database table - @param database: database instance - @type database: DbDir - @param backup_table: file containing the backup data - @type backup_table: file - @param tbl: Berkeley db database table - @type tbl: Berkeley db database table + :param database: database instance + :type database: DbDir + :param backup_table: file containing the backup data + :type backup_table: file + :param tbl: Berkeley db database table + :type tbl: Berkeley db database table """ try: while True: @@ -201,8 +201,8 @@ def __build_tbl_map(database): """ Builds a table map of names to database tables. - @param database: database instance to backup - @type database: DbDir + :param database: database instance to backup + :type database: DbDir """ return [ ( PERSON_TBL, database.person_map.db), diff --git a/gramps/gen/db/base.py b/gramps/gen/db/base.py index 88a891019..6caa5173a 100644 --- a/gramps/gen/db/base.py +++ b/gramps/gen/db/base.py @@ -23,7 +23,7 @@ # $Id$ """ -Base class for the GRAMPS databases. All database interfaces should inherit +Base class for the Gramps databases. All database interfaces should inherit from this class. """ @@ -37,7 +37,7 @@ _ = glocale.translation.gettext #------------------------------------------------------------------------- # -# GRAMPS libraries +# Gramps libraries # #------------------------------------------------------------------------- from ..lib.childreftype import ChildRefType @@ -47,7 +47,7 @@ from .exceptions import DbTransactionCancel class DbReadBase(object): """ - GRAMPS database object. This object is a base class for all + Gramps database object. This object is a base class for all database interfaces. All methods raise NotImplementedError and must be implemented in the derived class as required. """ @@ -143,56 +143,56 @@ class DbReadBase(object): def find_next_event_gramps_id(self): """ - Return the next available GRAMPS' ID for a Event object based off the + Return the next available Gramps ID for a Event object based off the event ID prefix. """ raise NotImplementedError def find_next_family_gramps_id(self): """ - Return the next available GRAMPS' ID for a Family object based off the + Return the next available Gramps ID for a Family object based off the family ID prefix. """ raise NotImplementedError def find_next_note_gramps_id(self): """ - Return the next available GRAMPS' ID for a Note object based off the + Return the next available Gramps ID for a Note object based off the note ID prefix. """ raise NotImplementedError def find_next_object_gramps_id(self): """ - Return the next available GRAMPS' ID for a MediaObject object based + Return the next available Gramps ID for a MediaObject object based off the media object ID prefix. """ raise NotImplementedError def find_next_person_gramps_id(self): """ - Return the next available GRAMPS' ID for a Person object based off the + Return the next available Gramps ID for a Person object based off the person ID prefix. """ raise NotImplementedError def find_next_place_gramps_id(self): """ - Return the next available GRAMPS' ID for a Place object based off the + Return the next available Gramps ID for a Place object based off the place ID prefix. """ raise NotImplementedError def find_next_repository_gramps_id(self): """ - Return the next available GRAMPS' ID for a Repository object based + Return the next available Gramps ID for a Repository object based off the repository ID prefix. """ raise NotImplementedError def find_next_source_gramps_id(self): """ - Return the next available GRAMPS' ID for a Source object based off the + Return the next available Gramps ID for a Source object based off the source ID prefix. """ raise NotImplementedError @@ -236,7 +236,7 @@ class DbReadBase(object): def get_event_from_gramps_id(self, val): """ - Find an Event in the database from the passed GRAMPS ID. + Find an Event in the database from the passed Gramps ID. If no such Event exists, None is returned. Needs to be overridden by the derived class. @@ -245,7 +245,7 @@ class DbReadBase(object): def get_event_from_handle(self, handle): """ - Find a Event in the database from the passed gramps' ID. + Find a Event in the database from the passed Gramps ID. If no such Event exists, None is returned. """ @@ -293,7 +293,7 @@ class DbReadBase(object): def get_family_from_gramps_id(self, val): """ - Find a Family in the database from the passed GRAMPS ID. + Find a Family in the database from the passed Gramps ID. If no such Family exists, None is returned. Need to be overridden by the derived class. @@ -302,7 +302,7 @@ class DbReadBase(object): def get_family_from_handle(self, handle): """ - Find a Family in the database from the passed gramps' ID. + Find a Family in the database from the passed Gramps ID. If no such Family exists, None is returned. """ @@ -408,7 +408,7 @@ class DbReadBase(object): def get_note_from_gramps_id(self, val): """ - Find a Note in the database from the passed gramps' ID. + Find a Note in the database from the passed Gramps ID. If no such Note exists, None is returned. Needs to be overridden by the derived classderri. @@ -417,7 +417,7 @@ class DbReadBase(object): def get_note_from_handle(self, handle): """ - Find a Note in the database from the passed gramps' ID. + Find a Note in the database from the passed Gramps ID. If no such Note exists, None is returned. """ @@ -493,7 +493,7 @@ class DbReadBase(object): def get_object_from_gramps_id(self, val): """ - Find a MediaObject in the database from the passed gramps' ID. + Find a MediaObject in the database from the passed Gramps ID. If no such MediaObject exists, None is returned. Needs to be overridden by the derived class. @@ -502,7 +502,7 @@ class DbReadBase(object): def get_object_from_handle(self, handle): """ - Find an Object in the database from the passed gramps' ID. + Find an Object in the database from the passed Gramps ID. If no such Object exists, None is returned. """ @@ -530,7 +530,7 @@ class DbReadBase(object): def get_person_from_gramps_id(self, val): """ - Find a Person in the database from the passed GRAMPS ID. + Find a Person in the database from the passed Gramps ID. If no such Person exists, None is returned. Needs to be overridden by the derived class. @@ -539,7 +539,7 @@ class DbReadBase(object): def get_person_from_handle(self, handle): """ - Find a Person in the database from the passed gramps' ID. + Find a Person in the database from the passed Gramps ID. If no such Person exists, None is returned. """ @@ -575,7 +575,7 @@ class DbReadBase(object): def get_place_from_gramps_id(self, val): """ - Find a Place in the database from the passed gramps' ID. + Find a Place in the database from the passed Gramps ID. If no such Place exists, None is returned. Needs to be overridden by the derived class. @@ -584,7 +584,7 @@ class DbReadBase(object): def get_place_from_handle(self, handle): """ - Find a Place in the database from the passed gramps' ID. + Find a Place in the database from the passed Gramps ID. If no such Place exists, None is returned. """ @@ -691,7 +691,7 @@ class DbReadBase(object): def get_repository_from_gramps_id(self, val): """ - Find a Repository in the database from the passed gramps' ID. + Find a Repository in the database from the passed Gramps ID. If no such Repository exists, None is returned. Needs to be overridden by the derived class. @@ -700,7 +700,7 @@ class DbReadBase(object): def get_repository_from_handle(self, handle): """ - Find a Repository in the database from the passed gramps' ID. + Find a Repository in the database from the passed Gramps ID. If no such Repository exists, None is returned. """ @@ -747,7 +747,7 @@ class DbReadBase(object): def get_source_from_gramps_id(self, val): """ - Find a Source in the database from the passed gramps' ID. + Find a Source in the database from the passed Gramps ID. If no such Source exists, None is returned. Needs to be overridden by the derived class. @@ -756,7 +756,7 @@ class DbReadBase(object): def get_source_from_handle(self, handle): """ - Find a Source in the database from the passed gramps' ID. + Find a Source in the database from the passed Gramps ID. If no such Source exists, None is returned. """ @@ -792,7 +792,7 @@ class DbReadBase(object): def get_citation_from_gramps_id(self, val): """ - Find a Citation in the database from the passed gramps' ID. + Find a Citation in the database from the passed Gramps ID. If no such Citation exists, None is returned. Needs to be overridden by the derived class. @@ -801,7 +801,7 @@ class DbReadBase(object): def get_citation_from_handle(self, handle): """ - Find a Citation in the database from the passed gramps' ID. + Find a Citation in the database from the passed Gramps ID. If no such Citation exists, None is returned. """ @@ -1068,8 +1068,9 @@ class DbReadBase(object): internal data dependent on the database should be rebuilt. Note that all rebuild signals on all objects are emitted at the same time. It is correct to assume that this is always the case. - TODO: it might be better to replace these rebuild signals by one single - database-rebuild signal. + + .. todo:: it might be better to replace these rebuild signals by one + single database-rebuild signal. """ raise NotImplementedError @@ -1081,7 +1082,7 @@ class DbReadBase(object): def set_event_id_prefix(self, val): """ - Set the naming template for GRAMPS Event ID values. + Set the naming template for Gramps Event ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1091,7 +1092,7 @@ class DbReadBase(object): def set_family_id_prefix(self, val): """ - Set the naming template for GRAMPS Family ID values. The string is + Set the naming template for Gramps Family ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, such as F%d or F%04d. @@ -1100,7 +1101,7 @@ class DbReadBase(object): def set_note_id_prefix(self, val): """ - Set the naming template for GRAMPS Note ID values. + Set the naming template for Gramps Note ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1110,7 +1111,7 @@ class DbReadBase(object): def set_object_id_prefix(self, val): """ - Set the naming template for GRAMPS MediaObject ID values. + Set the naming template for Gramps MediaObject ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1120,7 +1121,7 @@ class DbReadBase(object): def set_person_id_prefix(self, val): """ - Set the naming template for GRAMPS Person ID values. + Set the naming template for Gramps Person ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1130,7 +1131,7 @@ class DbReadBase(object): def set_place_id_prefix(self, val): """ - Set the naming template for GRAMPS Place ID values. + Set the naming template for Gramps Place ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1147,7 +1148,7 @@ class DbReadBase(object): def set_repository_id_prefix(self, val): """ - Set the naming template for GRAMPS Repository ID values. + Set the naming template for Gramps Repository ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1157,7 +1158,7 @@ class DbReadBase(object): def set_source_id_prefix(self, val): """ - Set the naming template for GRAMPS Source ID values. + Set the naming template for Gramps Source ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1217,7 +1218,7 @@ class DbReadBase(object): class DbWriteBase(DbReadBase): """ - GRAMPS database object. This object is a base class for all + Gramps database object. This object is a base class for all database interfaces. All methods raise NotImplementedError and must be implemented in the derived class as required. """ @@ -1583,9 +1584,9 @@ class DbWriteBase(DbReadBase): before the start of such database operations. :param transaction: Gramps transaction ... - :type transaction: DbTxn + :type transaction: :py:class:`.DbTxn` :returns: Returns the Gramps transaction. - :rtype: DbTxn + :rtype: :py:class:`.DbTxn` """ raise NotImplementedError diff --git a/gramps/gen/db/read.py b/gramps/gen/db/read.py index 6fd1d8dfb..359aeb49a 100644 --- a/gramps/gen/db/read.py +++ b/gramps/gen/db/read.py @@ -23,7 +23,7 @@ # $Id$ """ -Read classes for the GRAMPS databases. +Read classes for the Gramps databases. """ #------------------------------------------------------------------------- @@ -227,11 +227,13 @@ class DbBsddbTreeCursor(BsddbBaseCursor): class DbBsddbRead(DbReadBase, Callback): """ - Read class for the GRAMPS databases. Implements methods necessary to read + Read class for the Gramps databases. Implements methods necessary to read the various object classes. Currently, there are nine (9) classes: - Person, Family, Event, Place, Source, Citation, MediaObject, - Repository and Note + :py:class:`.Person`, :py:class:`.Family`, :py:class:`.Event`, + :py:class:`.Place`, :py:class:`.Source`, + :py:class:`Citation <.lib.citation.Citation>`, :py:class:`.MediaObject`, + :py:class:`.Repository` and :py:class:`.Note` For each object class, there are methods to retrieve data in various ways. In the methods described below, can be one of person, family, @@ -598,7 +600,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_person_gramps_id(self): """ - Return the next available GRAMPS' ID for a Person object based off the + Return the next available Gramps ID for a Person object based off the person ID prefix. """ self.pmap_index, gid = self.__find_next_gramps_id(self.person_prefix, @@ -607,7 +609,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_place_gramps_id(self): """ - Return the next available GRAMPS' ID for a Place object based off the + Return the next available Gramps ID for a Place object based off the place ID prefix. """ self.lmap_index, gid = self.__find_next_gramps_id(self.place_prefix, @@ -616,7 +618,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_event_gramps_id(self): """ - Return the next available GRAMPS' ID for a Event object based off the + Return the next available Gramps ID for a Event object based off the event ID prefix. """ self.emap_index, gid = self.__find_next_gramps_id(self.event_prefix, @@ -625,7 +627,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_object_gramps_id(self): """ - Return the next available GRAMPS' ID for a MediaObject object based + Return the next available Gramps ID for a MediaObject object based off the media object ID prefix. """ self.omap_index, gid = self.__find_next_gramps_id(self.mediaobject_prefix, @@ -634,7 +636,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_source_gramps_id(self): """ - Return the next available GRAMPS' ID for a Source object based off the + Return the next available Gramps ID for a Source object based off the source ID prefix. """ self.smap_index, gid = self.__find_next_gramps_id(self.source_prefix, @@ -643,7 +645,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_citation_gramps_id(self): """ - Return the next available GRAMPS' ID for a Source object based off the + Return the next available Gramps ID for a Source object based off the source ID prefix. """ self.cmap_index, gid = self.__find_next_gramps_id(self.citation_prefix, @@ -652,7 +654,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_family_gramps_id(self): """ - Return the next available GRAMPS' ID for a Family object based off the + Return the next available Gramps ID for a Family object based off the family ID prefix. """ self.fmap_index, gid = self.__find_next_gramps_id(self.family_prefix, @@ -661,7 +663,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_repository_gramps_id(self): """ - Return the next available GRAMPS' ID for a Respository object based + Return the next available Gramps ID for a Respository object based off the repository ID prefix. """ self.rmap_index, gid = self.__find_next_gramps_id(self.repository_prefix, @@ -670,7 +672,7 @@ class DbBsddbRead(DbReadBase, Callback): def find_next_note_gramps_id(self): """ - Return the next available GRAMPS' ID for a Note object based off the + Return the next available Gramps ID for a Note object based off the note ID prefix. """ self.nmap_index, gid = self.__find_next_gramps_id(self.note_prefix, @@ -704,7 +706,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_from_name_and_gramps_id(self, table_name, gramps_id): """ Returns a gen.lib object (or None) given table_name and - gramps ID. + Gramps ID. Examples: @@ -823,7 +825,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_person_from_gramps_id(self, val): """ - Find a Person in the database from the passed gramps' ID. + Find a Person in the database from the passed Gramps ID. If no such Person exists, None is returned. """ @@ -832,7 +834,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_family_from_gramps_id(self, val): """ - Find a Family in the database from the passed gramps' ID. + Find a Family in the database from the passed Gramps ID. If no such Family exists, None is return. """ @@ -841,7 +843,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_event_from_gramps_id(self, val): """ - Find an Event in the database from the passed gramps' ID. + Find an Event in the database from the passed Gramps ID. If no such Family exists, None is returned. """ @@ -850,7 +852,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_place_from_gramps_id(self, val): """ - Find a Place in the database from the passed gramps' ID. + Find a Place in the database from the passed Gramps ID. If no such Place exists, None is returned. """ @@ -859,7 +861,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_source_from_gramps_id(self, val): """ - Find a Source in the database from the passed gramps' ID. + Find a Source in the database from the passed Gramps ID. If no such Source exists, None is returned. """ @@ -868,7 +870,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_citation_from_gramps_id(self, val): """ - Find a Citation in the database from the passed gramps' ID. + Find a Citation in the database from the passed Gramps ID. If no such Citation exists, None is returned. """ @@ -877,7 +879,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_object_from_gramps_id(self, val): """ - Find a MediaObject in the database from the passed gramps' ID. + Find a MediaObject in the database from the passed Gramps ID. If no such MediaObject exists, None is returned. """ @@ -886,7 +888,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_repository_from_gramps_id(self, val): """ - Find a Repository in the database from the passed gramps' ID. + Find a Repository in the database from the passed Gramps ID. If no such Repository exists, None is returned. """ @@ -895,7 +897,7 @@ class DbBsddbRead(DbReadBase, Callback): def get_note_from_gramps_id(self, val): """ - Find a Note in the database from the passed gramps' ID. + Find a Note in the database from the passed Gramps ID. If no such Note exists, None is returned. """ @@ -1006,9 +1008,10 @@ class DbBsddbRead(DbReadBase, Callback): def all_handles(self, table): """ return all the keys of a database table - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ return table.keys(txn=self.txn) @@ -1019,9 +1022,9 @@ class DbBsddbRead(DbReadBase, Callback): If sort_handles is True, the list is sorted by surnames. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: handle_list = self.all_handles(self.person_map) @@ -1037,9 +1040,9 @@ class DbBsddbRead(DbReadBase, Callback): If sort_handles is True, the list is sorted by Place title. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: @@ -1056,9 +1059,9 @@ class DbBsddbRead(DbReadBase, Callback): If sort_handles is True, the list is sorted by Source title. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: handle_list = self.all_handles(self.source_map) @@ -1074,9 +1077,9 @@ class DbBsddbRead(DbReadBase, Callback): If sort_handles is True, the list is sorted by Citation Volume/Page. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: handle_list = self.all_handles(self.citation_map) @@ -1092,9 +1095,9 @@ class DbBsddbRead(DbReadBase, Callback): If sort_handles is True, the list is sorted by title. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: handle_list = self.all_handles(self.media_map) @@ -1108,9 +1111,9 @@ class DbBsddbRead(DbReadBase, Callback): Return a list of database handles, one handle for each Event in the database. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: return self.all_handles(self.event_map) @@ -1121,9 +1124,9 @@ class DbBsddbRead(DbReadBase, Callback): Return a list of database handles, one handle for each Family in the database. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: return self.all_handles(self.family_map) @@ -1134,9 +1137,9 @@ class DbBsddbRead(DbReadBase, Callback): Return a list of database handles, one handle for each Repository in the database. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: return self.all_handles(self.repository_map) @@ -1147,9 +1150,9 @@ class DbBsddbRead(DbReadBase, Callback): Return a list of database handles, one handle for each Note in the database. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: return self.all_handles(self.note_map) @@ -1162,9 +1165,9 @@ class DbBsddbRead(DbReadBase, Callback): If sort_handles is True, the list is sorted by Tag name. - CAREFUL: For speed the keys are directly returned, so on python3 - bytestrings are returned! Use constfunc.py handle2internal - on this result! + .. warning:: For speed the keys are directly returned, so on python3 + bytestrings are returned! Use constfunc.py handle2internal + on this result! """ if self.db_is_open: handle_list = self.all_handles(self.tag_map) @@ -1315,7 +1318,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_person_id_prefix(self, val): """ - Set the naming template for GRAMPS Person ID values. + Set the naming template for Gramps Person ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1326,7 +1329,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_source_id_prefix(self, val): """ - Set the naming template for GRAMPS Source ID values. + Set the naming template for Gramps Source ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1337,7 +1340,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_citation_id_prefix(self, val): """ - Set the naming template for GRAMPS Citation ID values. + Set the naming template for Gramps Citation ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1348,7 +1351,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_object_id_prefix(self, val): """ - Set the naming template for GRAMPS MediaObject ID values. + Set the naming template for Gramps MediaObject ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1359,7 +1362,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_place_id_prefix(self, val): """ - Set the naming template for GRAMPS Place ID values. + Set the naming template for Gramps Place ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1370,7 +1373,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_family_id_prefix(self, val): """ - Set the naming template for GRAMPS Family ID values. The string is + Set the naming template for Gramps Family ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, such as F%d or F%04d. @@ -1380,7 +1383,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_event_id_prefix(self, val): """ - Set the naming template for GRAMPS Event ID values. + Set the naming template for Gramps Event ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1391,7 +1394,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_repository_id_prefix(self, val): """ - Set the naming template for GRAMPS Repository ID values. + Set the naming template for Gramps Repository ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, @@ -1402,7 +1405,7 @@ class DbBsddbRead(DbReadBase, Callback): def set_note_id_prefix(self, val): """ - Set the naming template for GRAMPS Note ID values. + Set the naming template for Gramps Note ID values. The string is expected to be in the form of a simple text string, or in a format that contains a C/Python style format string using %d, diff --git a/gramps/gen/db/undoredo.py b/gramps/gen/db/undoredo.py index 4898c2cc8..162562338 100644 --- a/gramps/gen/db/undoredo.py +++ b/gramps/gen/db/undoredo.py @@ -86,7 +86,7 @@ _SIGBASE = ('person', 'family', 'source', 'event', 'media', #------------------------------------------------------------------------- class DbUndo(object): """ - Base class for the gramps undo/redo manager. Needs to be subclassed + Base class for the Gramps undo/redo manager. Needs to be subclassed for use with a real backend. """ @@ -186,7 +186,7 @@ class DbUndo(object): def commit(self, txn, msg): """ Commit the transaction to the undo/redo database. "txn" should be - an instance of gramps gramps transaction class + an instance of Gramps transaction class """ txn.set_description(msg) txn.timestamp = time.time() @@ -347,7 +347,7 @@ class DbUndo(object): class DbUndoList(DbUndo): """ - Implementation of the gramps undo database using a Python list + Implementation of the Gramps undo database using a Python list """ def __init__(self, grampsdb): """ @@ -403,7 +403,7 @@ class DbUndoList(DbUndo): class DbUndoBSDDB(DbUndo): """ - Class constructor for gramps undo/redo database using a bsddb recno + Class constructor for Gramps undo/redo database using a bsddb recno database as the backing store. """ diff --git a/gramps/gen/db/upgrade.py b/gramps/gen/db/upgrade.py index 7694344bf..972cae126 100644 --- a/gramps/gen/db/upgrade.py +++ b/gramps/gen/db/upgrade.py @@ -56,11 +56,13 @@ from .dbconst import (PERSON_KEY, FAMILY_KEY, EVENT_KEY, from gramps.gui.dialog import (InfoDialog) def gramps_upgrade_17(self): - """Upgrade database from version 16 to 17. - 1. This upgrade adds tags to event, place, repository, source and - citation objects. - 2. Data of Source becomes SourceAttributes Secondary Object - 3. Add checksum field to media objects. + """ + Upgrade database from version 16 to 17. + + 1. This upgrade adds tags to event, place, repository, source and + citation objects. + 2. Data of Source becomes SourceAttributes Secondary Object + 3. Add checksum field to media objects. """ length = (len(self.event_map) + len(self.place_map) + len(self.repository_map) + len(self.source_map) + @@ -294,20 +296,20 @@ def upgrade_datamap_17(datamap): return new_srcattr_list def gramps_upgrade_16(self): - """Upgrade database from version 15 to 16. This upgrade converts all - SourceRef child objects to Citation Primary objects. + """ + Upgrade database from version 15 to 16. This upgrade converts all + SourceRef child objects to Citation Primary objects. - For each primary object that has a sourceref, what we have to do is: - - (1) create each citation - (2) update the object to reference the Citations - (3) remove backlinks for references from object to Source - (4) add backlinks for references from object to Citations - (5) add backlinks for references from Citation to Source - - the backlinks are all updated at the end by calling - reindex_reference_map + For each primary object that has a sourceref, what we have to do is: + (1) create each citation + (2) update the object to reference the Citations + (3) remove backlinks for references from object to Source + (4) add backlinks for references from object to Citations + (5) add backlinks for references from Citation to Source + + the backlinks are all updated at the end by calling + :py:meth:`reindex_reference_map <.write.DbBsddb.reindex_reference_map>` """ length = (len(self.note_map) + len(self.person_map) + len(self.event_map) + len(self.family_map) + @@ -806,10 +808,12 @@ def convert_source_list_to_citation_list_16(self, source_list): return citation_list def gramps_upgrade_15(self): - """Upgrade database from version 14 to 15. This upgrade adds: - * tagging - * surname list - * remove marker + """ + Upgrade database from version 14 to 15. This upgrade adds: + + * tagging + * surname list + * remove marker """ length = (len(self.note_map) + len(self.person_map) + len(self.event_map) + len(self.family_map) + diff --git a/gramps/gen/db/write.py b/gramps/gen/db/write.py index 870e96f85..55ac52e16 100644 --- a/gramps/gen/db/write.py +++ b/gramps/gen/db/write.py @@ -23,8 +23,8 @@ # $Id$ """ -Provide the Berkeley DB (DbBsddb) database backend for GRAMPS. -This is used since GRAMPS version 3.0 +Provide the Berkeley DB (DbBsddb) database backend for Gramps. +This is used since Gramps version 3.0 """ #------------------------------------------------------------------------- @@ -247,7 +247,7 @@ class DbBsddbAssocCursor(BsddbBaseCursor): #------------------------------------------------------------------------- class DbBsddb(DbBsddbRead, DbWriteBase, UpdateCallback): """ - GRAMPS database write access object. + Gramps database write access object. """ # Set up dictionary for callback signal handler @@ -2133,8 +2133,10 @@ class DbBsddb(DbBsddbRead, DbWriteBase, UpdateCallback): Prepare the database for the start of a new Transaction. Supported transaction parameters: - no_magic: Boolean, defaults to False, indicating if secondary indices - should be disconnected. + + no_magic + Boolean, defaults to False, indicating if secondary indices should be + disconnected. """ if self.txn is not None: msg = self.transaction.get_description()