Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve gen.db documentation

Browse Source 
Convert old markup to reStructuredText.
Use warning and todo directives where appropriate.
Add some new links to classes and methods.
Use consistent case for "Gramps".
This commit is contained in:
Nick Hall 2013-11-10 23:18:13 +00:00
parent 09a3717edb
commit c665b8d262
7 changed files with 228 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
gramps/gen/db/__init__.py
View File

@ -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<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/write.py?view=markup>})
- B{DbWriteBase} - virtual and implementation-independent methods for reading data (U{gen/db/base.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/base.py?view=markup>})
- B{DbBsddbRead} - read-only (accessors, getters) implementation to BSDDB databases (U{gen/db/read.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/read.py?view=markup})
- B{DbReadBase} - virtual and implementation-independent methods for reading data (U{gen/db/base.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/base.py?view=markup})
- B{Callback} - callback and signal functions (U{gen/utils/callback.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/utils/callback.py?view=markup})
- B{UpdateCallback} - callback functionality (U{gen/updatecallback.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/read.py?view=markup gen/updatecallback.py?view=markup>})
- B{DbDjango} - read and write implementation to Django-based databases (U{web/dbdjango.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/webapp/dbdjango.py?view=markup})
- B{DbWriteBase} - virtual and implementation-independent methods for reading data (U{gen/db/base.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/base.py?view=markup})
- B{DbReadBase} - virtual and implementation-independent methods for reading data (U{gen/db/base.py<http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/db/base.py?view=markup})
- :py:class:`.DbBsddb` - read and write implementation to BSDDB databases
DbBsddb
=======
* :py:class:`.DbWriteBase` - virtual and implementation-independent methods
for reading data
The DbBsddb interface defines a hierarchical database
(non-relational) written in
U{http://www.jcea.es/programacion/pybsddb.htm 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).
* :py:class:`.DbBsddbRead` - read-only (accessors, getters) implementation
to BSDDB databases
DbDjango
========
+ :py:class:`.DbReadBase` - virtual and implementation-independent
methods for reading data
The DbDjango interface defines the Gramps data in terms of
I{models} and I{relations} from the
U{Django project<http://www.djangoproject.com/}. 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).
+ :py:class:`.Callback` - callback and signal functions
More details can be found in the manual's U{Using database API<http://www.gramps-project.org/wiki/index.php?title=Using_database_API>}.
* :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 <http://www.jcea.es/programacion/pybsddb.htm>`_. 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 <http://www.djangoproject.com/>`_. 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 <http://www.gramps-project.org/wiki/index.php?title=Using_database_API>`_.
"""
from .base import *

56
gramps/gen/db/backup.py
View File

@ -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),

85
gramps/gen/db/base.py
View File

@ -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

133
gramps/gen/db/read.py
View File

@ -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, <object> 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,

8
gramps/gen/db/undoredo.py
View File

@ -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.
"""

46
gramps/gen/db/upgrade.py
View File

@ -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) +

12
gramps/gen/db/write.py
View File

@ -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()