From 1ef6a987daf59cb300c23b36856c1ecf1133c217 Mon Sep 17 00:00:00 2001 From: Nick Hall Date: Mon, 11 Nov 2013 23:10:35 +0000 Subject: [PATCH] Improve gen.lib documentation --- docs/gen/gen_lib.rst | 42 ++++- gramps/gen/lib/__init__.py | 2 +- gramps/gen/lib/address.py | 9 +- gramps/gen/lib/addressbase.py | 34 ++-- gramps/gen/lib/attrbase.py | 40 +++-- gramps/gen/lib/attribute.py | 12 +- gramps/gen/lib/attrtype.py | 6 +- gramps/gen/lib/baseobj.py | 17 +- gramps/gen/lib/childref.py | 8 +- gramps/gen/lib/citation.py | 16 +- gramps/gen/lib/citationbase.py | 58 +++---- gramps/gen/lib/date.py | 135 ++++++++------- gramps/gen/lib/datebase.py | 15 +- gramps/gen/lib/event.py | 18 +- gramps/gen/lib/eventref.py | 12 +- gramps/gen/lib/family.py | 137 ++++++++------- gramps/gen/lib/genderstats.py | 5 +- gramps/gen/lib/grampstype.py | 25 +-- gramps/gen/lib/ldsord.py | 8 +- gramps/gen/lib/ldsordbase.py | 35 ++-- gramps/gen/lib/location.py | 6 +- gramps/gen/lib/locationbase.py | 2 +- gramps/gen/lib/mediabase.py | 28 ++-- gramps/gen/lib/mediaobj.py | 13 +- gramps/gen/lib/mediaref.py | 10 +- gramps/gen/lib/name.py | 15 +- gramps/gen/lib/note.py | 47 ++---- gramps/gen/lib/notebase.py | 26 +-- gramps/gen/lib/notetype.py | 4 +- gramps/gen/lib/person.py | 284 +++++++++++++++++--------------- gramps/gen/lib/personref.py | 8 +- gramps/gen/lib/place.py | 43 ++--- gramps/gen/lib/placebase.py | 12 +- gramps/gen/lib/placeref.py | 8 +- gramps/gen/lib/primaryobj.py | 29 ++-- gramps/gen/lib/privacybase.py | 2 +- gramps/gen/lib/refbase.py | 4 +- gramps/gen/lib/repo.py | 8 +- gramps/gen/lib/reporef.py | 8 +- gramps/gen/lib/researcher.py | 2 +- gramps/gen/lib/secondaryobj.py | 2 +- gramps/gen/lib/src.py | 42 ++--- gramps/gen/lib/styledtext.py | 127 +++++++------- gramps/gen/lib/styledtexttag.py | 30 ++-- gramps/gen/lib/surname.py | 30 ++-- gramps/gen/lib/surnamebase.py | 45 ++--- gramps/gen/lib/tableobj.py | 11 +- gramps/gen/lib/tag.py | 12 +- gramps/gen/lib/tagbase.py | 6 +- gramps/gen/lib/url.py | 12 +- gramps/gen/lib/urlbase.py | 30 ++-- 51 files changed, 828 insertions(+), 712 deletions(-) diff --git a/docs/gen/gen_lib.rst b/docs/gen/gen_lib.rst index 1ee89a584..bc349c43c 100644 --- a/docs/gen/gen_lib.rst +++ b/docs/gen/gen_lib.rst @@ -24,14 +24,28 @@ AddressBase :undoc-members: :show-inheritance: -AttributeBase +AttributeRootBase ==================================== .. automodule:: gramps.gen.lib.attrbase +.. autoclass:: AttributeRootBase + :members: + :undoc-members: + :show-inheritance: + +AttributeBase +==================================== .. autoclass:: AttributeBase :members: :undoc-members: :show-inheritance: +SrcAttributeBase +==================================== +.. autoclass:: SrcAttributeBase + :members: + :undoc-members: + :show-inheritance: + CitationBase ==================================== .. automodule:: gramps.gen.lib.citationbase @@ -40,6 +54,13 @@ CitationBase :undoc-members: :show-inheritance: +IndirectCitationBase +==================================== +.. autoclass:: IndirectCitationBase + :members: + :undoc-members: + :show-inheritance: + DateBase ==================================== .. automodule:: gramps.gen.lib.datebase @@ -247,6 +268,13 @@ Attribute :undoc-members: :show-inheritance: +AttributeRoot +==================================== +.. autoclass:: AttributeRoot + :members: + :undoc-members: + :show-inheritance: + LdsOrd ==================================== .. automodule:: gramps.gen.lib.ldsord @@ -340,7 +368,7 @@ RepoRef :show-inheritance: ***************************** -Table object +Table objects ***************************** Table object @@ -350,6 +378,14 @@ Table object :undoc-members: :show-inheritance: +Tag +==================================== +.. automodule:: gramps.gen.lib.tag +.. autoclass:: Tag + :members: + :undoc-members: + :show-inheritance: + ***************************** Date objects ***************************** @@ -534,7 +570,7 @@ Privacy ***************************** PrivateSourceNote -============ +================= .. automodule:: gramps.gen.lib.privsrcnote .. autoclass:: PrivateSourceNote diff --git a/gramps/gen/lib/__init__.py b/gramps/gen/lib/__init__.py index 8f9939774..dff328aaa 100644 --- a/gramps/gen/lib/__init__.py +++ b/gramps/gen/lib/__init__.py @@ -21,7 +21,7 @@ # $Id$ -"""The core library of GRAMPS objects +"""The core library of Gramps objects """ # Dates from .date import Date, DateError, Span diff --git a/gramps/gen/lib/address.py b/gramps/gen/lib/address.py index a8a4185af..64a4d8811 100644 --- a/gramps/gen/lib/address.py +++ b/gramps/gen/lib/address.py @@ -24,7 +24,7 @@ # $Id$ """ -Address class for GRAMPS. +Address class for Gramps. """ #------------------------------------------------------------------------- @@ -147,7 +147,8 @@ class Address(SecondaryObject, PrivacyBase, CitationBase, NoteBase, DateBase, """ Return the list of child secondary objects that may refer notes. - :returns: Returns the list of child secondary child objects that may refer notes. + :returns: Returns the list of child secondary child objects that may + refer notes. :rtype: list """ return [] @@ -179,7 +180,7 @@ class Address(SecondaryObject, PrivacyBase, CitationBase, NoteBase, DateBase, date, to other. :param other: The address to compare this one to. - :rtype other: Address + :type other: Address :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -200,7 +201,7 @@ class Address(SecondaryObject, PrivacyBase, CitationBase, NoteBase, DateBase, acquisition. :param acquisition: The address to merge with the present address. - :rtype acquisition: Address + :type acquisition: Address """ self._merge_privacy(acquisition) self._merge_note_list(acquisition) diff --git a/gramps/gen/lib/addressbase.py b/gramps/gen/lib/addressbase.py index ba8a73c83..6d8a10255 100644 --- a/gramps/gen/lib/addressbase.py +++ b/gramps/gen/lib/addressbase.py @@ -22,7 +22,7 @@ # $Id$ """ -AddressBase class for GRAMPS. +AddressBase class for Gramps. """ #------------------------------------------------------------------------- @@ -100,24 +100,28 @@ class AddressBase(object): def add_address(self, address): """ - Add the :class:`~gen.lib.address.Address` instance to the object's list of addresses. + Add the :class:`~.address.Address` instance to the object's list of + addresses. - :param address: :class:`~gen.lib.address.Address` instance to add to the object's address list + :param address: :class:`~.address.Address` instance to add to the + object's address list :type address: list """ self.address_list.append(address) def remove_address(self, address): """ - Remove the specified :class:`~gen.lib.address.Address` instance from the address list. + Remove the specified :class:`~.address.Address` instance from the address list. If the instance does not exist in the list, the operation has no effect. - :param address: :class:`~gen.lib.address.Address` instance to remove from the list - :type address: :class:`~gen.lib.address.Address` + :param address: :class:`~.address.Address` instance to remove from the + list + :type address: :class:`~.address.Address` - :returns: True if the address was removed, False if it was not in the list. + :returns: True if the address was removed, False if it was not in the + list. :rtype: bool """ if address in self.address_list: @@ -128,19 +132,21 @@ class AddressBase(object): def get_address_list(self): """ - Return the list of :class:`~gen.lib.address.Address` instances associated with the object. + Return the list of :class:`~.address.Address` instances associated with + the object. - :returns: Returns the list of :class:`~gen.lib.address.Address` instances + :returns: Returns the list of :class:`~.address.Address` instances :rtype: list """ return self.address_list def set_address_list(self, address_list): """ - Assign the passed list to the object's list of :class:`~gen.lib.address.Address` instances. + Assign the passed list to the object's list of + :class:`~.address.Address` instances. - :param address_list: List of :class:`~gen.lib.address.Address` instances to be associated - with the object + :param address_list: List of :class:`~.address.Address` instances to be + associated with the object :type address_list: list """ self.address_list = address_list @@ -150,8 +156,8 @@ class AddressBase(object): Merge the list of addresses from acquisition with our own. :param acquisition: the address list of this object will be merged with - the current address list. - :rtype acquisition: AddressBase + the current address list. + :type acquisition: AddressBase """ address_list = self.address_list[:] for addendum in acquisition.get_address_list(): diff --git a/gramps/gen/lib/attrbase.py b/gramps/gen/lib/attrbase.py index 56b8b7cf0..42dc5d857 100644 --- a/gramps/gen/lib/attrbase.py +++ b/gramps/gen/lib/attrbase.py @@ -22,7 +22,7 @@ # $Id$ """ -AttributeBase class for GRAMPS. +AttributeRootBase class for Gramps. """ #------------------------------------------------------------------------- @@ -37,7 +37,7 @@ from ..constfunc import STRTYPE #------------------------------------------------------------------------- # -# AttributeBase class +# AttributeRootBase class # #------------------------------------------------------------------------- class AttributeRootBase(object): @@ -107,26 +107,29 @@ class AttributeRootBase(object): def add_attribute(self, attribute): """ - Add the :class:`~gen.lib.attribute.Attribute` instance to the object's list of attributes. + Add the :class:`~.attribute.Attribute` instance to the object's list of + attributes. - :param attribute: :class:`~gen.lib.attribute.Attribute` instance to add. - :type attribute: :class:`~gen.lib.attribute.Attribute` + :param attribute: :class:`~.attribute.Attribute` instance to add. + :type attribute: :class:`~.attribute.Attribute` """ assert not isinstance(attribute, STRTYPE) self.attribute_list.append(attribute) def remove_attribute(self, attribute): """ - Remove the specified :class:`~gen.lib.attribute.Attribute` instance from the attribute list. + Remove the specified :class:`~.attribute.Attribute` instance from the + attribute list. If the instance does not exist in the list, the operation has no effect. - :param attribute: :class:`~gen.lib.attribute.Attribute` instance to remove from the list - :type attribute: :class:`~gen.lib.attribute.Attribute` + :param attribute: :class:`~.attribute.Attribute` instance to remove + from the list + :type attribute: :class:`~.attribute.Attribute` - :returns: True if the attribute was removed, False if it was not - in the list. + :returns: True if the attribute was removed, False if it was not in the + list. :rtype: bool """ if attribute in self.attribute_list: @@ -137,19 +140,21 @@ class AttributeRootBase(object): def get_attribute_list(self): """ - Return the list of :class:`~gen.lib.attribute.Attribute` instances associated with the object. + Return the list of :class:`~.attribute.Attribute` instances associated + with the object. - :returns: Returns the list of :class:`~gen.lib.attribute.Attribute` instances. + :returns: Returns the list of :class:`~.attribute.Attribute` instances. :rtype: list """ return self.attribute_list def set_attribute_list(self, attribute_list): """ - Assign the passed list to the Person's list of :class:`~gen.lib.attribute.Attribute` instances. + Assign the passed list to the Person's list of + :class:`~.attribute.Attribute` instances. - :param attribute_list: List of :class:`~gen.lib.attribute.Attribute` instances to ba associated - with the Person + :param attribute_list: List of :class:`~.attribute.Attribute` instances + to ba associated with the Person :type attribute_list: list """ self.attribute_list = attribute_list @@ -159,8 +164,8 @@ class AttributeRootBase(object): Merge the list of attributes from acquisition with our own. :param acquisition: the attribute list of this object will be merged - with the current attribute list. - :rtype acquisition: AttributeBase + with the current attribute list. + :type acquisition: AttributeBase """ attr_list = self.attribute_list[:] for addendum in acquisition.get_attribute_list(): @@ -179,4 +184,3 @@ class AttributeBase(AttributeRootBase): class SrcAttributeBase(AttributeRootBase): _CLASS = SrcAttribute - diff --git a/gramps/gen/lib/attribute.py b/gramps/gen/lib/attribute.py index f21c5fd87..cb31284e1 100644 --- a/gramps/gen/lib/attribute.py +++ b/gramps/gen/lib/attribute.py @@ -23,7 +23,7 @@ # $Id$ """ -Attribute class for GRAMPS. +Attribute class for Gramps. """ #------------------------------------------------------------------------- @@ -54,9 +54,9 @@ class AttributeRoot(SecondaryObject, PrivacyBase): to a place (a position held, residence, etc.) or may not (eye colour, height, caste, profession, etc.). They may have sources and notes and media. - Compare with :class:`~gen.lib.event.Event` + Compare with :class:`~.event.Event` - GRAMPS at the moment does not support this GEDCOM Attribute structure. + Gramps at the moment does not support this GEDCOM Attribute structure. """ def __init__(self, source=None): @@ -176,7 +176,7 @@ class AttributeRoot(SecondaryObject, PrivacyBase): value, to other. :param other: The attribute to compare this one to. - :rtype other: Attribute + :type other: Attribute :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -195,7 +195,7 @@ class AttributeRoot(SecondaryObject, PrivacyBase): Lost: type and value of acquisition. :param acquisition: the attribute to merge with the present attribute. - :rtype acquisition: Attribute + :type acquisition: Attribute """ self._merge_privacy(acquisition) @@ -314,7 +314,7 @@ class Attribute(AttributeRoot, CitationBase, NoteBase): Lost: type and value of acquisition. :param acquisition: the attribute to merge with the present attribute. - :rtype acquisition: Attribute + :type acquisition: Attribute """ AttributeRoot.merge(self, acquisition) self._merge_citation_list(acquisition) diff --git a/gramps/gen/lib/attrtype.py b/gramps/gen/lib/attrtype.py index 9e1e47705..8e83b7822 100644 --- a/gramps/gen/lib/attrtype.py +++ b/gramps/gen/lib/attrtype.py @@ -21,7 +21,7 @@ # $Id$ """ -Provide the different Attribute Types for GRAMPS. +Provide the different Attribute Types for Gramps. """ #------------------------------------------------------------------------- @@ -89,10 +89,10 @@ class AttributeType(GrampsType): Exception is a sublist of types that may not be ignored :param exception: list of integer values corresponding with types that - have to be excluded from the ignore list + have to be excluded from the ignore list :type exception: list :returns: list of integers corresponding with the types to ignore when - showing a list of different NoteType's + showing a list of different types :rtype: list """ diff --git a/gramps/gen/lib/baseobj.py b/gramps/gen/lib/baseobj.py index b73512fa3..290e14b35 100644 --- a/gramps/gen/lib/baseobj.py +++ b/gramps/gen/lib/baseobj.py @@ -21,7 +21,7 @@ # $Id$ """ -Base Object class for GRAMPS +Base Object class for Gramps """ #------------------------------------------------------------------------- @@ -45,7 +45,7 @@ from ..constfunc import cuni #------------------------------------------------------------------------- class BaseObject(object): """ - The BaseObject is the base class for all data objects in GRAMPS, + The BaseObject is the base class for all data objects in Gramps, whether primary or not. Its main goal is to provide common capabilites to all objects, such as @@ -111,7 +111,8 @@ class BaseObject(object): :type pattern: str :param case_sensitive: Whether the match is case-sensitive. :type case_sensitive: bool - :returns: Returns whether any text data in the object or any of it's child objects matches a given pattern. + :returns: Returns whether any text data in the object or any of it's + child objects matches a given pattern. :rtype: bool """ # Run through its own items @@ -143,7 +144,8 @@ class BaseObject(object): :param pattern: The pattern to match. :type pattern: str - :returns: Returns whether any text data in the object or any of it's child objects matches a given regexp. + :returns: Returns whether any text data in the object or any of it's + child objects matches a given regexp. :rtype: bool """ @@ -186,7 +188,8 @@ class BaseObject(object): Return the list of (classname, handle) tuples for all directly referenced primary objects. - :returns: Returns the list of (classname, handle) tuples for referenced objects. + :returns: Returns the list of (classname, handle) tuples for referenced + objects. :rtype: list """ return [] @@ -206,7 +209,8 @@ class BaseObject(object): Return the list of (classname, handle) tuples for all referenced primary objects, whether directly or through child objects. - :returns: Returns the list of (classname, handle) tuples for referenced objects. + :returns: Returns the list of (classname, handle) tuples for referenced + objects. :rtype: list """ ret = self.get_referenced_handles() @@ -234,4 +238,3 @@ class BaseObject(object): @classmethod def create(cls, data): return cls().unserialize(data) - diff --git a/gramps/gen/lib/childref.py b/gramps/gen/lib/childref.py index 6c7736dc3..8acf7b2e5 100644 --- a/gramps/gen/lib/childref.py +++ b/gramps/gen/lib/childref.py @@ -24,7 +24,7 @@ # $Id$ """ -Child Reference class for GRAMPS. +Child Reference class for Gramps. """ #------------------------------------------------------------------------- # @@ -157,7 +157,7 @@ class ChildRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase): Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return [] @@ -192,7 +192,7 @@ class ChildRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase): to other. :param other: The childref to compare this one to. - :rtype other: ChildRef + :type other: ChildRef :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -211,7 +211,7 @@ class ChildRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase): Lost: hlink, mrel and frel of acquisition. :param acquisition: The childref to merge with the present childref. - :rtype acquisition: ChildRef + :type acquisition: ChildRef """ self._merge_privacy(acquisition) self._merge_note_list(acquisition) diff --git a/gramps/gen/lib/citation.py b/gramps/gen/lib/citation.py index 94130eda5..f3e33b885 100644 --- a/gramps/gen/lib/citation.py +++ b/gramps/gen/lib/citation.py @@ -23,7 +23,7 @@ # $Id$ """ -Citation object for GRAMPS. +Citation object for Gramps. """ #------------------------------------------------------------------------- @@ -55,7 +55,7 @@ from .handle import Handle # #------------------------------------------------------------------------- class Citation(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, - DateBase, PrimaryObject): + DateBase, PrimaryObject): """ A record of a citation of a source of information. @@ -189,7 +189,7 @@ class Citation(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, :param handle: The handle to be checked. :type handle: str :returns: Returns whether the object has reference to this handle of - this object type. + this object type. :rtype: bool """ if classname == 'Note': @@ -233,7 +233,7 @@ class Citation(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return self.media_list @@ -261,7 +261,7 @@ class Citation(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.media_list @@ -292,10 +292,10 @@ class Citation(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, def merge(self, acquisition): """ - Merge the content of acquisition into this source. + Merge the content of acquisition into this citation. - :param acquisition: The source to merge with the present source. - :rtype acquisition: Source + :param acquisition: The citation to merge with the present citation. + :type acquisition: Citation """ self._merge_privacy(acquisition) self._merge_note_list(acquisition) diff --git a/gramps/gen/lib/citationbase.py b/gramps/gen/lib/citationbase.py index 577a96c27..156b92728 100644 --- a/gramps/gen/lib/citationbase.py +++ b/gramps/gen/lib/citationbase.py @@ -23,7 +23,7 @@ # $Id$ """ -CitationBase class for GRAMPS. +CitationBase class for Gramps. """ #------------------------------------------------------------------------- @@ -115,11 +115,11 @@ class CitationBase(object): def add_citation(self, handle): """ - Add the :class:`~gen.lib.citation.Citation` handle to the list of - citation handles. + Add the :class:`~.citation.Citation` handle to the list of citation + handles. - :param handle: :class:`~gen.lib.citation.Citation` handle to add the - list of citations + :param handle: :class:`~.citation.Citation` handle to add the list of + citations :type handle: str :returns: True if handle was added, False if it already was in the list @@ -160,27 +160,27 @@ class CitationBase(object): CitationBase :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return [] def get_citation_list(self): """ - Return the list of :class:`~gen.lib.citation.Citation` handles - associated with the object. + Return the list of :class:`~.citation.Citation` handles associated with + the object. - :returns: The list of :class:`~gen.lib.citation.Citation` handles + :returns: The list of :class:`~.citation.Citation` handles :rtype: list """ return self.citation_list def get_all_citation_lists(self): """ - Return the list of :class:`~gen.lib.citation.Citation` handles - associated with the object or with child objects. + Return the list of :class:`~.citation.Citation` handles associated with + the object or with child objects. - :returns: The list of :class:`~gen.lib.citation.Citation` handles + :returns: The list of :class:`~.citation.Citation` handles :rtype: list """ list = self.citation_list @@ -213,11 +213,11 @@ class CitationBase(object): def set_citation_list(self, citation_list): """ - Assign the passed list to be object's list of - :class:`~gen.lib.citation.Citation` handles. + Assign the passed list to be object's list of + :class:`~.citation.Citation` handles. - :param citation_list: List of :class:`~gen.lib.citation.Citation` - handles to be set on the object + :param citation_list: List of :class:`~.citation.Citation` handles to + be set on the object :type citation_list: list """ self.citation_list = citation_list @@ -227,8 +227,8 @@ class CitationBase(object): Merge the list of citations from acquisition with our own. :param acquisition: The citation list of this object will be merged - with the current citation list. - :rtype acquisition: CitationBase + with the current citation list. + :type acquisition: CitationBase """ for addendum in acquisition.citation_list: self.add_citation(addendum) @@ -238,9 +238,8 @@ class CitationBase(object): Return the list of (classname, handle) tuples for all referenced citations. - This method should be used to get the - :class:`~gen.lib.citation.Citation` portion of the list by objects - that store citation lists. + This method should be used to get the :class:`~.citation.Citation` + portion of the list by objects that store citation lists. :returns: List of (classname, handle) tuples for referenced objects. :rtype: list @@ -278,12 +277,13 @@ class IndirectCitationBase(object): Citation management logic for objects that don't have citations for the primary objects, but only for the child (secondary) ones. - The derived class must implement get_citation_child_list method - to return the list of child secondary objects that may refer - citations. + The derived class must implement the + :meth:`~CitationBase.get_citation_child_list` method to return the list of + child secondary objects that may refer citations. - Note: for most objects, this functionality is inherited from - CitationBase, which checks both the object and the child objects. + .. note:: for most objects, this functionality is inherited from + :class:`CitationBase`, which checks both the object and the child + objects. """ def has_citation_reference(self, citation_handle): """ @@ -293,7 +293,7 @@ class IndirectCitationBase(object): :param citation_handle: The citation handle to be checked. :type citation_handle: str :returns: Returns whether any of it's child objects has reference to - this citation handle. + this citation handle. :rtype: bool """ for item in self.get_citation_child_list(): @@ -304,8 +304,8 @@ class IndirectCitationBase(object): def replace_citation_references(self, old_handle, new_handle): """ - Replace references to citation handles in - all child objects and merge equivalent entries. + Replace references to citation handles in all child objects and merge + equivalent entries. :param old_handle: The citation handle to be replaced. :type old_handle: str diff --git a/gramps/gen/lib/date.py b/gramps/gen/lib/date.py index 03f53dff0..8c7d5d731 100644 --- a/gramps/gen/lib/date.py +++ b/gramps/gen/lib/date.py @@ -283,11 +283,11 @@ class Span(object): """ Get the representation as a time or age. - If dlocale is passed in (a GrampsLocale) then + If dlocale is passed in (a :class:`.GrampsLocale`) then the translated value will be returned instead. - @param dlocale: allow deferred translation of strings - @type dlocale: a GrampsLocale instance + :param dlocale: allow deferred translation of strings + :type dlocale: a :class:`.GrampsLocale` instance """ trans_text = dlocale.translation.sgettext # trans_text is a defined keyword (see po/update_po.py, po/genpot.sh) @@ -398,20 +398,23 @@ class Span(object): def format(self, precision=2, as_age=True): """ Force a string representation at a level of precision. - 1 = only most significant level (year, month, day) - 2 = only most two significant levels (year, month, day) - 3 = at most three items of signifance (year, month, day) + + == ==================================================== + 1 only most significant level (year, month, day) + 2 only most two significant levels (year, month, day) + 3 at most three items of signifance (year, month, day) + == ==================================================== """ self.precision = precision return self.get_repr(as_age) def _format(self, diff_tuple, dlocale=glocale): """ - If dlocale is passed in (a GrampsLocale) then + If dlocale is passed in (a :class:`.GrampsLocale`) then the translated value will be returned instead. - @param dlocale: allow deferred translation of strings - @type dlocale: a GrampsLocale instance + :param dlocale: allow deferred translation of strings + :type dlocale: a :class:`.GrampsLocale` instance """ trans_text = dlocale.translation.sgettext ngettext = dlocale.translation.ngettext @@ -515,7 +518,7 @@ class Span(object): #------------------------------------------------------------------------- class Date(object): """ - The core date handling class for GRAMPs. + The core date handling class for Gramps. Supports partial dates, compound dates and alternate calendars. """ @@ -950,16 +953,15 @@ class Date(object): look for anything other than a straight match, or a simple comparison of the sortval. - comparison =,== : - Returns True if any part of other_date matches any part of self - comparison < : - Returns True if any part of other_date < any part of self - comparison << : - Returns True if all parts of other_date < all parts of self - comparison > : - Returns True if any part of other_date > any part of self - comparison >> : - Returns True if all parts of other_date > all parts of self + ========== ======================================================= + Comparison Returns + ========== ======================================================= + =,== True if any part of other_date matches any part of self + < True if any part of other_date < any part of self + << True if all parts of other_date < all parts of self + > True if any part of other_date > any part of self + >> True if all parts of other_date > all parts of self + ========== ======================================================= """ if (other_date.modifier == Date.MOD_TEXTONLY or self.modifier == Date.MOD_TEXTONLY): @@ -1118,7 +1120,8 @@ class Date(object): The sort value is an integer representing the value. The sortval is the integer number of days that have elapsed since Monday, January 1, 4713 BC in the proleptic Julian calendar. - See http://en.wikipedia.org/wiki/Julian_day + + .. seealso:: http://en.wikipedia.org/wiki/Julian_day """ return self.sortval @@ -1126,15 +1129,17 @@ class Date(object): """ Return an integer indicating the calendar selected. - The valid values are:: + The valid values are: - MOD_NONE = no modifier (default) - MOD_BEFORE = before - MOD_AFTER = after - MOD_ABOUT = about - MOD_RANGE = date range - MOD_SPAN = date span - MOD_TEXTONLY = text only + ============ ===================== + MOD_NONE no modifier (default) + MOD_BEFORE before + MOD_AFTER after + MOD_ABOUT about + MOD_RANGE date range + MOD_SPAN date span + MOD_TEXTONLY text only + ============ ===================== """ return self.modifier @@ -1152,11 +1157,13 @@ class Date(object): """ Return an integer indicating the calendar selected. - The valid values are:: + The valid values are: - QUAL_NONE = normal (default) - QUAL_ESTIMATED = estimated - QUAL_CALCULATED = calculated + =============== ================ + QUAL_NONE normal (default) + QUAL_ESTIMATED estimated + QUAL_CALCULATED calculated + =============== ================ """ return self.quality @@ -1173,15 +1180,17 @@ class Date(object): """ Return an integer indicating the calendar selected. - The valid values are:: + The valid values are: - CAL_GREGORIAN - Gregorian calendar - CAL_JULIAN - Julian calendar - CAL_HEBREW - Hebrew (Jewish) calendar - CAL_FRENCH - French Republican calendar - CAL_PERSIAN - Persian calendar - CAL_ISLAMIC - Islamic calendar - CAL_SWEDISH - Swedish calendar 1700-03-01 -> 1712-02-30! + ============= ========================================== + CAL_GREGORIAN Gregorian calendar + CAL_JULIAN Julian calendar + CAL_HEBREW Hebrew (Jewish) calendar + CAL_FRENCH French Republican calendar + CAL_PERSIAN Persian calendar + CAL_ISLAMIC Islamic calendar + CAL_SWEDISH Swedish calendar 1700-03-01 -> 1712-02-30! + ============= ========================================== """ return self.calendar @@ -1305,7 +1314,8 @@ class Date(object): """ Set the year, month, and day values. - @param remove_stop_date Required parameter for a compound date. + :param remove_stop_date: + Required parameter for a compound date. When True, the stop date is changed to the same date as well. When False, the stop date is not changed. """ @@ -1400,7 +1410,8 @@ class Date(object): def copy_ymd(self, year=0, month=0, day=0, remove_stop_date=None): """ Return a Date copy with year, month, and day set. - @param remove_stop_date Same as in set_yr_mon_day. + + :param remove_stop_date: Same as in set_yr_mon_day. """ retval = Date(self) retval.set_yr_mon_day(year, month, day, remove_stop_date) @@ -1520,28 +1531,26 @@ class Date(object): """ Set the date to the specified value. - Parameters are:: - - quality - The date quality for the date (see get_quality - for more information). - Defaults to the previous value for the date. - modified - The date modifier for the date (see get_modifier - for more information) - Defaults to the previous value for the date. - calendar - The calendar associated with the date (see - get_calendar for more information). - Defaults to the previous value for the date. - value - A tuple representing the date information. For a - non-compound date, the format is (DD, MM, YY, slash) - and for a compound date the tuple stores data as - (DD, MM, YY, slash1, DD, MM, YY, slash2) - Defaults to the previous value for the date. - text - A text string holding either the verbatim user input + :param quality: The date quality for the date (see :meth:`get_quality` + for more information). + Defaults to the previous value for the date. + :param modified: The date modifier for the date (see + :meth:`get_modifier` for more information) + Defaults to the previous value for the date. + :param calendar: The calendar associated with the date (see + :meth:`get_calendar` for more information). + Defaults to the previous value for the date. + :param value: A tuple representing the date information. For a + non-compound date, the format is (DD, MM, YY, slash) + and for a compound date the tuple stores data as + (DD, MM, YY, slash1, DD, MM, YY, slash2) + Defaults to the previous value for the date. + :param text: A text string holding either the verbatim user input or a comment relating to the date. Defaults to the previous value for the date. - newyear - The newyear code, or tuple representing (month, day) - of newyear day. - Defaults to 0. + :param newyear: The newyear code, or tuple representing (month, day) + of newyear day. + Defaults to 0. The sort value is recalculated. """ diff --git a/gramps/gen/lib/datebase.py b/gramps/gen/lib/datebase.py index 524f91040..fc88d2a76 100644 --- a/gramps/gen/lib/datebase.py +++ b/gramps/gen/lib/datebase.py @@ -21,7 +21,7 @@ # $Id$ """ -DateBase class for GRAMPS. +DateBase class for Gramps. """ #------------------------------------------------------------------------- @@ -108,10 +108,10 @@ class DateBase(object): def get_date_object(self): """ - Return the :class:`~gen.lib.date.Date` object associated with the DateBase. + Return the :class:`~.date.Date` object associated with the DateBase. - :returns: Returns a DateBase :class:`~gen.lib.date.Date` instance. - :rtype: :class:`~gen.lib.date.Date` + :returns: Returns a DateBase :class:`~.date.Date` instance. + :rtype: :class:`~.date.Date` """ if not self.date: self.date = Date() @@ -119,9 +119,10 @@ class DateBase(object): def set_date_object(self, date): """ - Set the :class:`~gen.lib.date.Date` object associated with the DateBase. + Set the :class:`~.date.Date` object associated with the DateBase. - :param date: :class:`~gen.lib.date.Date` instance to be assigned to the DateBase - :type date: :class:`~gen.lib.date.Date` + :param date: :class:`~.date.Date` instance to be assigned to the + DateBase + :type date: :class:`~.date.Date` """ self.date = date diff --git a/gramps/gen/lib/event.py b/gramps/gen/lib/event.py index d5410680f..4baa3813c 100644 --- a/gramps/gen/lib/event.py +++ b/gramps/gen/lib/event.py @@ -23,7 +23,7 @@ # $Id$ """ -Event object for GRAMPS. +Event object for Gramps. """ #------------------------------------------------------------------------- @@ -66,7 +66,7 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, (that we may not know precisely, though), at some place, may involve several people (witnesses, officers, notaries, priests, etc.) and may of course have sources, notes, media, etc. - Compare this with attribute: :class:`~gen.lib.attribute.Attribute` + Compare this with attribute: :class:`~.attribute.Attribute` """ def __init__(self, source=None): @@ -107,7 +107,7 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, a form that it can use. :returns: Returns a python tuple containing the data that should - be considered persistent. + be considered persistent. :rtype: tuple """ return (self.handle, self.gramps_id, self.__type.serialize(), @@ -181,8 +181,8 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, Convert the data held in a tuple created by the serialize method back into the data in an Event structure. - :param data: tuple containing the persistent data associated the - Person object + :param data: tuple containing the persistent data associated with the + Event object :type data: tuple """ (self.handle, self.gramps_id, the_type, date, @@ -210,7 +210,7 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, :param handle: The handle to be checked. :type handle: str :returns: Returns whether the object has reference to this handle of - this object type. + this object type. :rtype: bool """ if classname == 'Place': @@ -266,7 +266,7 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return self.media_list + self.attribute_list @@ -276,7 +276,7 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.media_list + self.attribute_list @@ -358,7 +358,7 @@ class Event(CitationBase, NoteBase, MediaBase, AttributeBase, Lost: handle, id, marker, type, date, place, description of acquisition. :param acquisition: The event to merge with the present event. - :rtype acquisition: Event + :type acquisition: Event """ self._merge_privacy(acquisition) self._merge_attribute_list(acquisition) diff --git a/gramps/gen/lib/eventref.py b/gramps/gen/lib/eventref.py index 63d66e456..adad274ec 100644 --- a/gramps/gen/lib/eventref.py +++ b/gramps/gen/lib/eventref.py @@ -24,7 +24,7 @@ # $Id$ """ -Event Reference class for GRAMPS +Event Reference class for Gramps """ #------------------------------------------------------------------------- @@ -161,7 +161,7 @@ class EventRef(PrivacyBase, NoteBase, AttributeBase, RefBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return self.attribute_list @@ -171,7 +171,7 @@ class EventRef(PrivacyBase, NoteBase, AttributeBase, RefBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.attribute_list @@ -182,7 +182,7 @@ class EventRef(PrivacyBase, NoteBase, AttributeBase, RefBase, referenced primary objects. :returns: Returns the list of (classname, handle) tuples for referenced - objects. + objects. :rtype: list """ ret = self.get_referenced_note_handles() @@ -206,7 +206,7 @@ class EventRef(PrivacyBase, NoteBase, AttributeBase, RefBase, role, to other. :param other: The eventref to compare this one to. - :rtype other: EventRef + :type other: EventRef :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -225,7 +225,7 @@ class EventRef(PrivacyBase, NoteBase, AttributeBase, RefBase, Lost: hlink and role of acquisition. :param acquisition: The eventref to merge with the present eventref. - :param acquisition: EventRef + :type acquisition: EventRef """ self._merge_privacy(acquisition) self._merge_attribute_list(acquisition) diff --git a/gramps/gen/lib/family.py b/gramps/gen/lib/family.py index be0e60344..86e614a98 100644 --- a/gramps/gen/lib/family.py +++ b/gramps/gen/lib/family.py @@ -24,7 +24,7 @@ # $Id$ """ -Family object for GRAMPS. +Family object for Gramps. """ #------------------------------------------------------------------------- @@ -62,16 +62,16 @@ from .handle import Handle class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, PrimaryObject): """ - The Family record is the GRAMPS in-memory representation of the + The Family record is the Gramps in-memory representation of the relationships between people. It contains all the information related to the relationship. Family objects are usually created in one of two ways. 1. Creating a new Family object, which is then initialized and - added to the database. + added to the database. 2. Retrieving an object from the database using the records - handle. + handle. Once a Family object has been modified, it must be committed to the database using the database object's commit_family function, @@ -113,7 +113,7 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, a form that it can use. :returns: Returns a python tuple containing the data that should - be considered persistent. + be considered persistent. :rtype: tuple """ return (self.handle, self.gramps_id, self.father_handle, @@ -223,7 +223,7 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, :param handle: The handle to be checked. :type handle: str :returns: Returns whether the object has reference to this handle of - this object type. + this object type. :rtype: bool """ if classname == 'Event': @@ -341,7 +341,7 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ check_list = self.media_list + self.attribute_list + \ @@ -353,7 +353,7 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ check_list = self.media_list + self.attribute_list + \ @@ -396,7 +396,7 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Lost: handle, id, relation, father, mother of acquisition. :param acquisition: The family to merge with the present family. - :rtype acquisition: Family + :type acquisition: Family """ if self.type != acquisition.type and self.type == FamilyRelType.UNKNOWN: self.set_relationship(acquisition.get_relationship()) @@ -418,22 +418,28 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, The type is a tuple whose first item is an integer constant and whose second item is the string. The valid values are: - - C{FamilyRelType.MARRIED} : indicates a legally recognized married - relationship between two individuals. This may be either - an opposite or a same sex relationship. - - C{FamilyRelType.UNMARRIED} : indicates a relationship between two - individuals that is not a legally recognized relationship. - - C{FamilyRelType.CIVIL_UNION} : indicates a legally recongnized, - non-married relationship between two individuals of the - same sex. - - C{FamilyRelType.UNKNOWN} : indicates that the type of relationship - between the two individuals is not know. - - C{FamilyRelType.CUSTOM} : indicates that the type of relationship - between the two individuals does not match any of the - other types. + ========================= ============================================ + Type Description + ========================= ============================================ + FamilyRelType.MARRIED indicates a legally recognized married + relationship between two individuals. This + may be either an opposite or a same sex + relationship. + FamilyRelType.UNMARRIED indicates a relationship between two + individuals that is not a legally recognized + relationship. + FamilyRelType.CIVIL_UNION indicates a legally recongnized, non-married + relationship between two individuals of the + same sex. + FamilyRelType.UNKNOWN indicates that the type of relationship + between the two individuals is not know. + FamilyRelType.CUSTOM indicates that the type of relationship + between the two individuals does not match + any of the other types. + ========================= ============================================ :param relationship_type: (int,str) tuple of the relationship type - between the father and mother of the relationship. + between the father and mother of the relationship. :type relationship_type: tuple """ self.type.set(relationship_type) @@ -447,53 +453,54 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def set_father_handle(self, person_handle): """ - Set the database handle for :class:`~gen.lib.person.Person` that corresponds to male of the - relationship. + Set the database handle for :class:`~.person.Person` that corresponds + to male of the relationship. For a same sex relationship, this can represent either of people involved in the relationship. - :param person_handle: :class:`~gen.lib.person.Person` database handle + :param person_handle: :class:`~.person.Person` database handle :type person_handle: str """ self.father_handle = person_handle def get_father_handle(self): """ - Return the database handle of the :class:`~gen.lib.person.Person` identified as the father - of the Family. + Return the database handle of the :class:`~.person.Person` identified + as the father of the Family. - :returns: :class:`~gen.lib.person.Person` database handle + :returns: :class:`~.person.Person` database handle :rtype: str """ return self.father_handle def set_mother_handle(self, person_handle): """ - Set the database handle for :class:`~gen.lib.person.Person` that corresponds to male of the - relationship. + Set the database handle for :class:`~.person.Person` that corresponds + to male of the relationship. For a same sex relationship, this can represent either of people involved in the relationship. - :param person_handle: :class:`~gen.lib.person.Person` database handle + :param person_handle: :class:`~.person.Person` database handle :type person_handle: str """ self.mother_handle = person_handle def get_mother_handle(self): """ - Return the database handle of the :class:`~gen.lib.person.Person` identified as the mother - of the Family. + Return the database handle of the :class:`~.person.Person` identified + as the mother of the Family. - :returns: :class:`~gen.lib.person.Person` database handle + :returns: :class:`~.person.Person` database handle :rtype: str """ return self.mother_handle def add_child_ref(self, child_ref): """ - Add the database handle for :class:`~gen.lib.person.Person` to the Family's list of children. + Add the database handle for :class:`~.person.Person` to the Family's + list of children. :param child_ref: Child Reference instance :type child_ref: ChildRef @@ -504,13 +511,13 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def remove_child_ref(self, child_ref): """ - Remove the database handle for :class:`~gen.lib.person.Person` to the Family's list of - children if the :class:`~gen.lib.person.Person` is already in the list. + Remove the database handle for :class:`~.person.Person` to the Family's + list of children if the :class:`~.person.Person` is already in the list. :param child_ref: Child Reference instance :type child_ref: ChildRef :returns: True if the handle was removed, False if it was not - in the list. + in the list. :rtype: bool """ if not isinstance(child_ref, ChildRef): @@ -521,13 +528,13 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def remove_child_handle(self, child_handle): """ - Remove the database handle for :class:`~gen.lib.person.Person` to the Family's list of - children if the :class:`~gen.lib.person.Person` is already in the list. + Remove the database handle for :class:`~.person.Person` to the Family's + list of children if the :class:`~.person.Person` is already in the list. - :param child_handle: :class:`~gen.lib.person.Person` database handle + :param child_handle: :class:`~.person.Person` database handle :type child_handle: str :returns: True if the handle was removed, False if it was not - in the list. + in the list. :rtype: bool """ new_list = [ref for ref in self.child_ref_list @@ -536,11 +543,11 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def get_child_ref_list(self): """ - Return the list of :class:`~gen.lib.childref.ChildRef` handles identifying the children of the - Family. + Return the list of :class:`~.childref.ChildRef` handles identifying the + children of the Family. - :returns: Returns the list of :class:`~gen.lib.childref.ChildRef` handles associated with - the Family. + :returns: Returns the list of :class:`~.childref.ChildRef` handles + associated with the Family. :rtype: list """ return self.child_ref_list @@ -551,7 +558,7 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, :param child_ref_list: List of Child Reference instances to be associated as the Family's list of children. - :type child_ref_list: list of :class:`~gen.lib.childref.ChildRef` instances + :type child_ref_list: list of :class:`~.childref.ChildRef` instances """ self.child_ref_list = child_ref_list @@ -560,8 +567,8 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Merge the list of child references from acquisition with our own. :param acquisition: the childref list of this family will be merged - with the current childref list. - :rtype acquisition: Family + with the current childref list. + :type acquisition: Family """ childref_list = self.child_ref_list[:] for addendum in acquisition.get_child_ref_list(): @@ -577,13 +584,14 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def add_event_ref(self, event_ref): """ - Add the :class:`~gen.lib.eventref.EventRef` to the Family instance's :class:`~gen.lib.eventref.EventRef` list. + Add the :class:`~.eventref.EventRef` to the Family instance's + :class:`~.eventref.EventRef` list. - This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` for the valid - :class:`~gen.lib.event.Event` in the current database. + This is accomplished by assigning the :class:`~.eventref.EventRef` for + the valid :class:`~.event.Event` in the current database. - :param event_ref: the :class:`~gen.lib.eventref.EventRef` to be added to the - Person's :class:`~gen.lib.eventref.EventRef` list. + :param event_ref: the :class:`~.eventref.EventRef` to be added to the + Person's :class:`~.eventref.EventRef` list. :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): @@ -602,20 +610,22 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def get_event_ref_list(self) : """ - Return the list of :class:`~gen.lib.eventref.EventRef` objects associated with :class:`~gen.lib.event.Event` - instances. + Return the list of :class:`~.eventref.EventRef` objects associated with + :class:`~.event.Event` instances. - :returns: Returns the list of :class:`~gen.lib.eventref.EventRef` objects associated with - the Family instance. + :returns: Returns the list of :class:`~.eventref.EventRef` objects + associated with the Family instance. :rtype: list """ return self.event_ref_list def set_event_ref_list(self, event_ref_list) : """ - Set the Family instance's :class:`~gen.lib.eventref.EventRef` list to the passed list. + Set the Family instance's :class:`~.eventref.EventRef` list to the + passed list. - :param event_ref_list: List of valid :class:`~gen.lib.eventref.EventRef` objects + :param event_ref_list: List of valid :class:`~.eventref.EventRef` + objects :type event_ref_list: list """ self.event_ref_list = event_ref_list @@ -625,8 +635,8 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Merge the list of event references from acquisition with our own. :param acquisition: the event references list of this object will be - merged with the current event references list. - :rtype acquisition: Person + merged with the current event references list. + :type acquisition: Person """ eventref_list = self.event_ref_list[:] for addendum in acquisition.get_event_ref_list(): @@ -639,4 +649,3 @@ class Family(CitationBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, break else: self.event_ref_list.append(addendum) - diff --git a/gramps/gen/lib/genderstats.py b/gramps/gen/lib/genderstats.py index 42de4ff5b..c2e8820c8 100644 --- a/gramps/gen/lib/genderstats.py +++ b/gramps/gen/lib/genderstats.py @@ -22,7 +22,7 @@ # $Id$ """ -Gender statistics kept in GRAMPS database. +Gender statistics kept in Gramps database. """ #------------------------------------------------------------------------- @@ -71,7 +71,8 @@ class GenderStats(object): return (0, 0, 0) def count_name (self, name, gender): - """count a given name under gender in the gender stats + """ + Count a given name under gender in the gender stats. """ keyname = self._get_key_from_name(name) if not keyname: diff --git a/gramps/gen/lib/grampstype.py b/gramps/gen/lib/grampstype.py index ddd701fb3..fc67f8b30 100644 --- a/gramps/gen/lib/grampstype.py +++ b/gramps/gen/lib/grampstype.py @@ -49,16 +49,19 @@ _UNKNOWN = _('Unknown') # #------------------------------------------------------------------------- class GrampsTypeMeta(type): - """Metaclass for :class:`~gen.lib.grampstype.GrampsType`. + """ + Metaclass for :class:`~.grampstype.GrampsType`. Create the class-specific integer/string maps. - """ def __init__(cls, name, bases, namespace): # Helper function to create the maps def init_map(data, key_col, data_col, blacklist=None): - """Initialize the map, building a new map from the specified columns.""" + """ + Initialize the map, building a new map from the specified + columns. + """ if blacklist: return dict([(item[key_col], item[data_col]) for item in data if not item[0] in blacklist]) @@ -88,25 +91,25 @@ GrampsTypeC = GrampsTypeMeta(str('GrampsTypeC'), (object, ), {}) class GrampsType(GrampsTypeC): """Base class for all Gramps object types. - :cvar _DATAMAP: (list) 3-tuple like (index, localized_string, english_string). + :cvar _DATAMAP: + (list) 3-tuple like (index, localized_string, english_string). :cvar _BLACKLIST: - List of indices to ignore (obsolete/retired entries). - (gramps policy is never to delete type values, or reuse the name (TOKEN) - of any specific type value) + List of indices to ignore (obsolete/retired entries). + (gramps policy is never to delete type values, or reuse the name (TOKEN) + of any specific type value) :cvar POS_: (int) Position of attribute in the serialized format of an instance. - :attention: The POS_ class variables reflect the serialized object, they - have to be updated in case the data structure or the L{serialize} method - changes! + .. warning:: The POS_ class variables reflect the serialized object, + they have to be updated in case the data structure or the + :meth:`serialize` method changes! :cvar _CUSTOM: (int) a custom type object :cvar _DEFAULT: (int) the default type, used on creation :attribute value: (int) Returns or sets integer value :attribute string: (str) Returns or sets string value - """ (POS_VALUE, POS_STRING) = list(range(2)) diff --git a/gramps/gen/lib/ldsord.py b/gramps/gen/lib/ldsord.py index cd9d943bf..3bc10df34 100644 --- a/gramps/gen/lib/ldsord.py +++ b/gramps/gen/lib/ldsord.py @@ -24,7 +24,7 @@ # $Id$ """ -LDS Ordinance class for GRAMPS. +LDS Ordinance class for Gramps. """ #------------------------------------------------------------------------- @@ -230,7 +230,7 @@ class LdsOrd(SecondaryObject, CitationBase, NoteBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return [] @@ -267,7 +267,7 @@ class LdsOrd(SecondaryObject, CitationBase, NoteBase, place, status, sealed_to, to other. :param other: The ldsord to compare this one to. - :rtype other: LdsOrd + :type other: LdsOrd :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -290,7 +290,7 @@ class LdsOrd(SecondaryObject, CitationBase, NoteBase, Lost: type, date, temple, place, status, sealed_to of acquistion. :param acquisition: The ldsord to merge with the present ldsord. - :rtype acquisition: LdsOrd + :type acquisition: LdsOrd """ self._merge_privacy(acquisition) self._merge_note_list(acquisition) diff --git a/gramps/gen/lib/ldsordbase.py b/gramps/gen/lib/ldsordbase.py index 90f13c0d9..20890a4b2 100644 --- a/gramps/gen/lib/ldsordbase.py +++ b/gramps/gen/lib/ldsordbase.py @@ -22,7 +22,7 @@ # $Id$ """ -LdsOrdBase class for GRAMPS. +LdsOrdBase class for Gramps. """ #------------------------------------------------------------------------- @@ -105,23 +105,28 @@ class LdsOrdBase(object): def add_lds_ord(self, lds_ord): """ - Add the :class:`~gen.lib.ldsord.LdsOrd` instance to the object's list of lds_ordes. + Add the :class:`~.ldsord.LdsOrd` instance to the object's list of + lds_ords. - :param lds_ord: :class:`~gen.lib.ldsord.LdsOrd` instance to add to the object's lds_ord list + :param lds_ord: :class:`~.ldsord.LdsOrd` instance to add to the object's + lds_ord list :type lds_ord: list """ self.lds_ord_list.append(lds_ord) def remove_lds_ord(self, lds_ord): """ - Remove the specified :class:`~gen.lib.ldsord.LdsOrd` instance from the lds_ord list. + Remove the specified :class:`~.ldsord.LdsOrd` instance from the lds_ord + list. If the instance does not exist in the list, the operation has no effect. - :param lds_ord: :class:`~gen.lib.ldsord.LdsOrd` instance to remove from the list - :type lds_ord: :class:`~gen.lib.ldsord.LdsOrd` + :param lds_ord: :class:`~.ldsord.LdsOrd` instance to remove from the + list + :type lds_ord: :class:`~.ldsord.LdsOrd` - :returns: True if the lds_ord was removed, False if it was not in the list. + :returns: True if the lds_ord was removed, False if it was not in the + list. :rtype: bool """ if lds_ord in self.lds_ord_list: @@ -132,19 +137,21 @@ class LdsOrdBase(object): def get_lds_ord_list(self): """ - Return the list of :class:`~gen.lib.ldsord.LdsOrd` instances associated with the object. + Return the list of :class:`~.ldsord.LdsOrd` instances associated with + the object. - :returns: Returns the list of :class:`~gen.lib.ldsord.LdsOrd` instances + :returns: Returns the list of :class:`~.ldsord.LdsOrd` instances :rtype: list """ return self.lds_ord_list def set_lds_ord_list(self, lds_ord_list): """ - Assign the passed list to the object's list of :class:`~gen.lib.ldsord.LdsOrd` instances. + Assign the passed list to the object's list of :class:`~.ldsord.LdsOrd` + instances. - :param lds_ord_list: List of :class:`~gen.lib.ldsord.LdsOrd` instances to be associated - with the object + :param lds_ord_list: List of :class:`~.ldsord.LdsOrd` instances to be + associated with the object :type lds_ord_list: list """ self.lds_ord_list = lds_ord_list @@ -154,8 +161,8 @@ class LdsOrdBase(object): Merge the list of ldsord from acquisition with our own. :param acquisition: the ldsord list of this object will be merged with - the current ldsord list. - :rtype acquisition: LdsOrdBase + the current ldsord list. + :type acquisition: LdsOrdBase """ ldsord_list = self.lds_ord_list[:] for addendum in acquisition.get_lds_ord_list(): diff --git a/gramps/gen/lib/location.py b/gramps/gen/lib/location.py index 627abec5b..99cc4ae29 100644 --- a/gramps/gen/lib/location.py +++ b/gramps/gen/lib/location.py @@ -23,7 +23,7 @@ # $Id$ """ -Location class for GRAMPS. +Location class for Gramps. """ #------------------------------------------------------------------------- @@ -136,7 +136,7 @@ class Location(SecondaryObject, LocationBase): Return if this location is equivalent to other. :param other: The location to compare this one to. - :rtype other: Location + :type other: Location :returns: Constant inidicating degree of equivalence. :rtype: int """ @@ -152,7 +152,7 @@ class Location(SecondaryObject, LocationBase): Lost: everything of acquisition. :param acquisition: The location to merge with the present location. - :rtype acquisition: Location + :type acquisition: Location """ pass diff --git a/gramps/gen/lib/locationbase.py b/gramps/gen/lib/locationbase.py index dcdef4ac8..16233aea3 100644 --- a/gramps/gen/lib/locationbase.py +++ b/gramps/gen/lib/locationbase.py @@ -22,7 +22,7 @@ # $Id$ """ -LocationBase class for GRAMPS. +LocationBase class for Gramps. """ #------------------------------------------------------------------------- diff --git a/gramps/gen/lib/mediabase.py b/gramps/gen/lib/mediabase.py index cb70adcdf..83b83795c 100644 --- a/gramps/gen/lib/mediabase.py +++ b/gramps/gen/lib/mediabase.py @@ -22,7 +22,7 @@ # $Id$ """ -MediaBase class for GRAMPS. +MediaBase class for Gramps. """ #------------------------------------------------------------------------- @@ -98,30 +98,32 @@ class MediaBase(object): def add_media_reference(self, media_ref): """ - Add a :class:`~gen.lib.mediaref.MediaRef` instance to the object's media list. + Add a :class:`~.mediaref.MediaRef` instance to the object's media list. - :param media_ref: :class:`~gen.lib.mediaref.MediaRef` instance to be added to the object's - media list. - :type media_ref: :class:`~gen.lib.mediaref.MediaRef` + :param media_ref: :class:`~.mediaref.MediaRef` instance to be added to + the object's media list. + :type media_ref: :class:`~.mediaref.MediaRef` """ self.media_list.append(media_ref) def get_media_list(self): """ - Return the list of :class:`~gen.lib.mediaref.MediaRef` instances associated with the object. + Return the list of :class:`~.mediaref.MediaRef` instances associated + with the object. - :returns: list of :class:`~gen.lib.mediaref.MediaRef` instances associated with the object + :returns: list of :class:`~.mediaref.MediaRef` instances associated + with the object :rtype: list """ return self.media_list def set_media_list(self, media_ref_list): """ - Set the list of :class:`~gen.lib.mediaref.MediaRef` instances associated with the object. - It replaces the previous list. + Set the list of :class:`~.mediaref.MediaRef` instances associated with + the object. It replaces the previous list. - :param media_ref_list: list of :class:`~gen.lib.mediaref.MediaRef` instances to be assigned - to the object. + :param media_ref_list: list of :class:`~.mediaref.MediaRef` instances + to be assigned to the object. :type media_ref_list: list """ self.media_list = media_ref_list @@ -131,7 +133,7 @@ class MediaBase(object): Merge the list of media references from acquisition with our own. :param acquisition: the media list of this object will be merged with - the current media reference list. + the current media reference list. :rtype acquisition: MediaBase """ media_list = self.media_list[:] @@ -154,7 +156,7 @@ class MediaBase(object): :param obj_handle: The media handle to be checked. :type obj_handle: str :returns: Returns whether the object or any of it's child objects has - reference to this media handle. + reference to this media handle. :rtype: bool """ return obj_handle in [media_ref.ref for media_ref in self.media_list] diff --git a/gramps/gen/lib/mediaobj.py b/gramps/gen/lib/mediaobj.py index 66291fa8d..39700f04a 100644 --- a/gramps/gen/lib/mediaobj.py +++ b/gramps/gen/lib/mediaobj.py @@ -24,7 +24,7 @@ # $Id$ """ -Media object for GRAMPS. +Media object for Gramps. """ #------------------------------------------------------------------------- @@ -110,7 +110,7 @@ class MediaObject(CitationBase, NoteBase, DateBase, AttributeBase, a form that it can use. :returns: Returns a python tuple containing the data that should - be considered persistent. + be considered persistent. :rtype: tuple """ return (self.handle, self.gramps_id, self.path, self.mime, self.desc, @@ -183,7 +183,7 @@ class MediaObject(CitationBase, NoteBase, DateBase, AttributeBase, def unserialize(self, data): """ Convert the data held in a tuple created by the serialize method - back into the data in an Event structure. + back into the data in a MediaObject structure. :param data: tuple containing the persistent data associated the object :type data: tuple @@ -222,7 +222,7 @@ class MediaObject(CitationBase, NoteBase, DateBase, AttributeBase, Return the list of child secondary objects that may refer to citations. :returns: Returns the list of child secondary child objects that may - refer to citations. + refer to citations. :rtype: list """ return self.attribute_list @@ -232,7 +232,7 @@ class MediaObject(CitationBase, NoteBase, DateBase, AttributeBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.attribute_list @@ -266,7 +266,7 @@ class MediaObject(CitationBase, NoteBase, DateBase, AttributeBase, Lost: handle, id, file, date of acquisition. :param acquisition: The media object to merge with the present object. - :rtype acquisition: MediaObject + :type acquisition: MediaObject """ self._merge_privacy(acquisition) self._merge_attribute_list(acquisition) @@ -322,4 +322,3 @@ class MediaObject(CitationBase, NoteBase, DateBase, AttributeBase, def get_checksum(self): """Return the checksum of the image.""" return self.checksum - diff --git a/gramps/gen/lib/mediaref.py b/gramps/gen/lib/mediaref.py index af806d32f..1c58c5776 100644 --- a/gramps/gen/lib/mediaref.py +++ b/gramps/gen/lib/mediaref.py @@ -24,7 +24,7 @@ # $Id$ """ -Media Reference class for GRAMPS. +Media Reference class for Gramps. """ #------------------------------------------------------------------------- @@ -140,7 +140,7 @@ class MediaRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase, Return the list of child secondary objects that may refer Citations. :returns: Returns the list of child secondary child objects that may - refer Citations. + refer Citations. :rtype: list """ return self.attribute_list @@ -150,7 +150,7 @@ class MediaRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.attribute_list @@ -185,7 +185,7 @@ class MediaRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase, reference and region, to other. :param other: The object reference to compare this one to. - :rtype other: MediaRef + :type other: MediaRef :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -204,7 +204,7 @@ class MediaRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase, Lost: hlink and region or acquisition. :param acquisition: The object reference to merge with the present one. - :rtype acquisition: MediaRef + :type acquisition: MediaRef """ self._merge_privacy(acquisition) self._merge_attribute_list(acquisition) diff --git a/gramps/gen/lib/name.py b/gramps/gen/lib/name.py index 2a842e191..01451dd8c 100644 --- a/gramps/gen/lib/name.py +++ b/gramps/gen/lib/name.py @@ -24,7 +24,7 @@ # $Id$ """ -Name class for GRAMPS. +Name class for Gramps. """ #------------------------------------------------------------------------- @@ -239,7 +239,7 @@ class Name(SecondaryObject, PrivacyBase, SurnameBase, CitationBase, NoteBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return [] @@ -271,7 +271,7 @@ class Name(SecondaryObject, PrivacyBase, SurnameBase, CitationBase, NoteBase, call, surname_list, suffix, title and date, to other. :param other: The name to compare this name to. - :rtype other: Name + :type other: Name :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -296,7 +296,7 @@ class Name(SecondaryObject, PrivacyBase, SurnameBase, CitationBase, NoteBase, acquisition. :param acquisition: The name to merge with the present name. - :rtype acquisition: Name + :type acquisition: Name """ # TODO what to do with sort and display? self._merge_privacy(acquisition) @@ -312,7 +312,7 @@ class Name(SecondaryObject, PrivacyBase, SurnameBase, CitationBase, NoteBase, equivalent names (e.g. Ivanova and Ivanov in Russian are usually considered equivalent. - Note that there is also a database wide grouping set_name_group_mapping + .. note:: There is also a database wide grouping set_name_group_mapping So one might map a name Smith to SmithNew, and have one person still grouped with name Smith. Hence, group_as can be equal to surname! """ @@ -494,8 +494,9 @@ class Name(SecondaryObject, PrivacyBase, SurnameBase, CitationBase, NoteBase, def get_gedcom_parts(self): """ Returns a GEDCOM-formatted name dictionary. - Note, field patronymic and prefix are deprecated, prefix_list and - surname list, added. + + .. note:: Fields patronymic and prefix are deprecated, prefix_list and + surname list, added. """ retval = {} retval['given'] = self.first_name.strip() diff --git a/gramps/gen/lib/note.py b/gramps/gen/lib/note.py index bfc75fe7d..4423d29c9 100644 --- a/gramps/gen/lib/note.py +++ b/gramps/gen/lib/note.py @@ -23,7 +23,7 @@ # $Id$ """ -Note class for GRAMPS. +Note class for Gramps. """ #------------------------------------------------------------------------- @@ -47,15 +47,15 @@ from .handle import Handle class Note(BasicPrimaryObject): """Define a text note. - Starting from GRAMPS 3.1 Note object stores the text in :class:`gen.lib.styledtext.StyledText` - instance, thus it can have text formatting information. + Starting from Gramps 3.1 Note object stores the text in + :class:`~.styledtext.StyledText` instance, thus it can have text formatting + information. - To get and set only the clear text of the note use the - :meth:`~gen.lib.note.Note.get` and :meth:`~gen.lib.note.Note.set` methods. + To get and set only the clear text of the note use the :meth:`get` and + :meth:`set` methods. To get and set the formatted version of the Note's text use the - :meth:`~gen.lib.note.Note.get_styledtext` and - :meth:`~gen.lib.note.Note.set_styledtext` methods. + :meth:`get_styledtext` and :meth:`set_styledtext` methods. The note may be 'preformatted' or 'flowed', which indicates that the text string is considered to be in paragraphs, separated by newlines. @@ -65,10 +65,9 @@ class Note(BasicPrimaryObject): :cvar POS_: (int) Position of attribute in the serialized format of an instance. - :attention: The POS_ class variables reflect the serialized object, they - have to be updated in case the data structure or the - :meth:`~gen.lib.note.Note.serialize` method changes! - + .. warning:: The POS_ class variables reflect the serialized object, + they have to be updated in case the data structure or the + :meth:`serialize` method changes! """ (FLOWED, FORMATTED) = list(range(2)) @@ -151,7 +150,6 @@ class Note(BasicPrimaryObject): :param data: The serialized format of a Note. :type: data: tuple - """ (self.handle, self.gramps_id, the_text, self.format, the_type, self.change, tag_list, self.private) = data @@ -168,7 +166,6 @@ class Note(BasicPrimaryObject): :returns: The list of all textual attributes of the object. :rtype: list - """ return [str(self.text)] @@ -189,7 +186,7 @@ class Note(BasicPrimaryObject): Lost: handle, id, type, format, text and styles of acquisition. :param acquisition: The note to merge with the present note. - :rtype acquisition: Note + :type acquisition: Note """ self._merge_privacy(acquisition) self._merge_tag_list(acquisition) @@ -199,7 +196,6 @@ class Note(BasicPrimaryObject): :param text: The *clear* text defining the note contents. :type text: str - """ self.text = StyledText(text) @@ -208,7 +204,6 @@ class Note(BasicPrimaryObject): :returns: The *clear* text of the note contents. :rtype: unicode - """ return cuni(self.text) @@ -216,8 +211,7 @@ class Note(BasicPrimaryObject): """Set the text associated with the note to the passed string. :param text: The *formatted* text defining the note contents. - :type text: :class:`gen.lib.styledtext.StyledText` - + :type text: :class:`~.styledtext.StyledText` """ self.text = text @@ -225,8 +219,7 @@ class Note(BasicPrimaryObject): """Return the text string associated with the note. :returns: The *formatted* text of the note contents. - :rtype: :class:`gen.lib.styledtext.StyledText` - + :rtype: :class:`~.styledtext.StyledText` """ return self.text @@ -234,8 +227,7 @@ class Note(BasicPrimaryObject): """Append the specified text to the text associated with the note. :param text: Text string to be appended to the note. - :type text: str or :class:`gen.lib.styledtext.StyledText` - + :type text: str or :class:`~.styledtext.StyledText` """ self.text = self.text + text @@ -244,7 +236,6 @@ class Note(BasicPrimaryObject): :param format: The value can either indicate Flowed or Preformatted. :type format: int - """ self.format = format @@ -255,7 +246,6 @@ class Note(BasicPrimaryObject): :returns: 0 indicates Flowed, 1 indicates Preformated :rtype: int - """ return self.format @@ -264,7 +254,6 @@ class Note(BasicPrimaryObject): :param the_type: descriptive type of the Note :type the_type: str - """ self.type.set(the_type) @@ -273,7 +262,6 @@ class Note(BasicPrimaryObject): :returns: the descriptive type of the Note :rtype: str - """ return self.type @@ -282,9 +270,10 @@ class Note(BasicPrimaryObject): Get the jump links from this note. Links can be external, to urls, or can be internal to gramps objects. - Return examples: - [("gramps", "Person", "handle", "7657626365362536"), - ("external", "www", "url", "http://example.com")] + Return examples:: + + [("gramps", "Person", "handle", "7657626365362536"), + ("external", "www", "url", "http://example.com")] :returns: list of [(domain, type, propery, value), ...] :rtype: list diff --git a/gramps/gen/lib/notebase.py b/gramps/gen/lib/notebase.py index a70116e9e..2c9c12691 100644 --- a/gramps/gen/lib/notebase.py +++ b/gramps/gen/lib/notebase.py @@ -22,7 +22,7 @@ # $Id$ """ -NoteBase class for GRAMPS. +NoteBase class for Gramps. """ from .handle import Handle @@ -94,9 +94,9 @@ class NoteBase(object): def add_note(self, handle): """ - Add the :class:`~gen.lib.note.Note` handle to the list of note handles. + Add the :class:`~.note.Note` handle to the list of note handles. - :param handle: :class:`~gen.lib.note.Note` handle to add the list of notes + :param handle: :class:`~.note.Note` handle to add the list of notes :type handle: str :returns: True if handle was added, False if it already was in the list @@ -113,7 +113,8 @@ class NoteBase(object): Remove the specified handle from the list of note handles, and all secondary child objects. - :param handle: :class:`~gen.lib.note.Note` handle to remove from the list of notes + :param handle: :class:`~.note.Note` handle to remove from the list of + notes :type handle: str """ if handle in self.note_list: @@ -137,9 +138,10 @@ class NoteBase(object): def get_note_list(self): """ - Return the list of :class:`~gen.lib.note.Note` handles associated with the object. + Return the list of :class:`~.note.Note` handles associated with the + object. - :returns: The list of :class:`~gen.lib.note.Note` handles + :returns: The list of :class:`~.note.Note` handles :rtype: list """ return self.note_list @@ -167,9 +169,11 @@ class NoteBase(object): def set_note_list(self, note_list): """ - Assign the passed list to be object's list of :class:`~gen.lib.note.Note` handles. + Assign the passed list to be object's list of :class:`~.note.Note` + handles. - :param note_list: List of :class:`~gen.lib.note.Note` handles to be set on the object + :param note_list: List of :class:`~.note.Note` handles to be set on the + object :type note_list: list """ self.note_list = note_list @@ -179,7 +183,7 @@ class NoteBase(object): Merge the list of notes from acquisition with our own. :param acquisition: The note list of this object will be merged with - the current note list. + the current note list. :rtype acquisition: NoteBase """ for addendum in acquisition.note_list: @@ -189,8 +193,8 @@ class NoteBase(object): """ Return the list of (classname, handle) tuples for all referenced notes. - This method should be used to get the :class:`~gen.lib.note.Note` portion of the list - by objects that store note lists. + This method should be used to get the :class:`~.note.Note` portion of + the list by objects that store note lists. :returns: List of (classname, handle) tuples for referenced objects. :rtype: list diff --git a/gramps/gen/lib/notetype.py b/gramps/gen/lib/notetype.py index 3d65e7bd9..949226a65 100644 --- a/gramps/gen/lib/notetype.py +++ b/gramps/gen/lib/notetype.py @@ -122,10 +122,10 @@ class NoteType(GrampsType): Exception is a sublist of types that may not be ignored :param exception: list of integer values corresponding with types that - have to be excluded from the ignore list + have to be excluded from the ignore list :type exception: list :returns: list of integers corresponding with the types to ignore when - showing a list of different NoteType's + showing a list of different types :rtype: list """ diff --git a/gramps/gen/lib/person.py b/gramps/gen/lib/person.py index 6c14860aa..22e11892d 100644 --- a/gramps/gen/lib/person.py +++ b/gramps/gen/lib/person.py @@ -24,7 +24,7 @@ # $Id$ """ -Person object for GRAMPS. +Person object for Gramps. """ from __future__ import unicode_literals @@ -62,14 +62,14 @@ from .handle import Handle class Person(CitationBase, NoteBase, AttributeBase, MediaBase, AddressBase, UrlBase, LdsOrdBase, PrimaryObject): """ - The Person record is the GRAMPS in-memory representation of an + The Person record is the Gramps in-memory representation of an individual person. It contains all the information related to an individual. Person objects are usually created in one of two ways. 1. Creating a new person object, which is then initialized and added to - the database. + the database. 2. Retrieving an object from the database using the records handle. Once a Person object has been modified, it must be committed @@ -87,8 +87,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Create a new Person instance. After initialization, most data items have empty or null values, - including the database - handle. + including the database handle. """ PrimaryObject.__init__(self) CitationBase.__init__(self) @@ -135,7 +134,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, a form that it can use. :returns: Returns a python tuple containing the data that should - be considered persistent. + be considered persistent. :rtype: tuple """ return ( @@ -250,7 +249,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, back into the data in a Person object. :param data: tuple containing the persistent data associated the - Person object + Person object :type data: tuple """ (self.handle, # 0 @@ -304,7 +303,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, :param handle: The handle to be checked. :type handle: str :returns: Returns whether the object has reference to this handle of - this object type. + this object type. :rtype: bool """ if classname == 'Event': @@ -466,7 +465,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return ([self.primary_name] + @@ -484,7 +483,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return ([self.primary_name] + @@ -535,7 +534,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Merge the content of acquisition into this person. :param acquisition: The person to merge with the present person. - :rtype acquisition: Person + :type acquisition: Person """ acquisition_id = acquisition.get_gramps_id() if acquisition_id: @@ -564,27 +563,29 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def set_primary_name(self, name): """ - Set the primary name of the Person to the specified :class:`~gen.lib.name.Name` instance. + Set the primary name of the Person to the specified :class:`~.name.Name` + instance. - :param name: :class:`~gen.lib.name.Name` to be assigned to the person - :type name: :class:`~gen.lib.name.Name` + :param name: :class:`~.name.Name` to be assigned to the person + :type name: :class:`~.name.Name` """ self.primary_name = name def get_primary_name(self): """ - Return the :class:`~gen.lib.name.Name` instance marked as the Person's primary name. + Return the :class:`~.name.Name` instance marked as the Person's primary + name. :returns: Returns the primary name - :rtype: :class:`~gen.lib.name.Name` + :rtype: :class:`~.name.Name` """ return self.primary_name def get_alternate_names(self): """ - Return the list of alternate :class:`~gen.lib.name.Name` instances. + Return the list of alternate :class:`~.name.Name` instances. - :returns: List of :class:`~gen.lib.name.Name` instances + :returns: List of :class:`~.name.Name` instances :rtype: list """ return self.alternate_names @@ -593,7 +594,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, """ Change the list of alternate names to the passed list. - :param alt_name_list: List of :class:`~gen.lib.name.Name` instances + :param alt_name_list: List of :class:`~.name.Name` instances :type alt_name_list: list """ self.alternate_names = alt_name_list @@ -603,7 +604,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Merge the list of alternate names from acquisition with our own. :param acquisition: the list of alternate names of this object will be - merged with the current alternate name list. + merged with the current alternate name list. :rtype acquisition: Person """ name_list = self.alternate_names[:] @@ -623,10 +624,10 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def add_alternate_name(self, name): """ - Add a :class:`~gen.lib.name.Name` instance to the list of alternative names. + Add a :class:`~.name.Name` instance to the list of alternative names. - :param name: :class:`~gen.lib.name.Name` to add to the list - :type name: :class:`~gen.lib.name.Name` + :param name: :class:`~.name.Name` to add to the list + :type name: :class:`~.name.Name` """ self.alternate_names.append(name) @@ -645,10 +646,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Set the gender of the Person. :param gender: Assigns the Person's gender to one of the - following constants:: - Person.MALE - Person.FEMALE - Person.UNKNOWN + following constants: + + - Person.MALE + - Person.FEMALE + - Person.UNKNOWN :type gender: int """ self.gender = gender @@ -657,10 +659,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, """ Return the gender of the Person. - :returns: Returns one of the following constants:: - Person.MALE - Person.FEMALE - Person.UNKNOWN + :returns: Returns one of the following constants: + + - Person.MALE + - Person.FEMALE + - Person.UNKNOWN :rtype: int """ return self.gender @@ -669,11 +672,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, """ Assign the birth event to the Person object. - This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` of the birth event - in the current database. + This is accomplished by assigning the :class:`~.eventref.EventRef` of + the birth event in the current database. - :param event_ref: the :class:`~gen.lib.eventref.EventRef` object associated with - the Person's birth. + :param event_ref: the :class:`~.eventref.EventRef` object associated + with the Person's birth. :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): @@ -694,11 +697,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, """ Assign the death event to the Person object. - This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` of the death event - in the current database. + This is accomplished by assigning the :class:`~.eventref.EventRef` of + the death event in the current database. - :param event_ref: the :class:`~gen.lib.eventref.EventRef` object associated with - the Person's death. + :param event_ref: the :class:`~.eventref.EventRef` object associated + with the Person's death. :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): @@ -717,12 +720,13 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_birth_ref(self): """ - Return the :class:`~gen.lib.eventref.EventRef` for Person's birth event. + Return the :class:`~.eventref.EventRef` for Person's birth event. - This should correspond to an :class:`~gen.lib.event.Event` in the database's :class:`~gen.lib.event.Event` list. + This should correspond to an :class:`~.event.Event` in the database's + :class:`~.event.Event` list. - :returns: Returns the birth :class:`~gen.lib.eventref.EventRef` or None if no birth - :class:`~gen.lib.event.Event` has been assigned. + :returns: Returns the birth :class:`~.eventref.EventRef` or None if no + birth :class:`~.event.Event` has been assigned. :rtype: EventRef """ @@ -733,12 +737,13 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_death_ref(self): """ - Return the :class:`~gen.lib.eventref.EventRef` for the Person's death event. + Return the :class:`~.eventref.EventRef` for the Person's death event. - This should correspond to an :class:`~gen.lib.event.Event` in the database's :class:`~gen.lib.event.Event` list. + This should correspond to an :class:`~.event.Event` in the database's + :class:`~.event.Event` list. - :returns: Returns the death :class:`~gen.lib.eventref.EventRef` or None if no death - :class:`~gen.lib.event.Event` has been assigned. + :returns: Returns the death :class:`~.eventref.EventRef` or None if no + death :class:`~.event.Event` has been assigned. :rtype: event_ref """ @@ -749,13 +754,14 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def add_event_ref(self, event_ref): """ - Add the :class:`~gen.lib.eventref.EventRef` to the Person instance's :class:`~gen.lib.eventref.EventRef` list. + Add the :class:`~.eventref.EventRef` to the Person instance's + :class:`~.eventref.EventRef` list. - This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` of a valid - :class:`~gen.lib.event.Event` in the current database. + This is accomplished by assigning the :class:`~.eventref.EventRef` of a + valid :class:`~.event.Event` in the current database. - :param event_ref: the :class:`~gen.lib.eventref.EventRef` to be added to the - Person's :class:`~gen.lib.eventref.EventRef` list. + :param event_ref: the :class:`~.eventref.EventRef` to be added to the + Person's :class:`~.eventref.EventRef` list. :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): @@ -767,22 +773,23 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_event_ref_list(self): """ - Return the list of :class:`~gen.lib.eventref.EventRef` objects associated with :class:`~gen.lib.event.Event` - instances. + Return the list of :class:`~.eventref.EventRef` objects associated with + :class:`~.event.Event` instances. - :returns: Returns the list of :class:`~gen.lib.eventref.EventRef` objects associated with - the Person instance. + :returns: Returns the list of :class:`~.eventref.EventRef` objects + associated with the Person instance. :rtype: list """ return self.event_ref_list def get_primary_event_ref_list(self): """ - Return the list of :class:`~gen.lib.eventref.EventRef` objects associated with :class:`~gen.lib.event.Event` - instances that have been marked as primary events. + Return the list of :class:`~.eventref.EventRef` objects associated with + :class:`~.event.Event` instances that have been marked as primary + events. - :returns: Returns generator of :class:`~gen.lib.eventref.EventRef` objects associated with - the Person instance. + :returns: Returns generator of :class:`~.eventref.EventRef` objects + associated with the Person instance. :rtype: generator """ return (ref for ref in self.event_ref_list @@ -791,9 +798,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def set_event_ref_list(self, event_ref_list): """ - Set the Person instance's :class:`~gen.lib.eventref.EventRef` list to the passed list. + Set the Person instance's :class:`~.eventref.EventRef` list to the + passed list. - :param event_ref_list: List of valid :class:`~gen.lib.eventref.EventRef` objects + :param event_ref_list: List of valid :class:`~.eventref.EventRef` + objects. :type event_ref_list: list """ self.event_ref_list = event_ref_list @@ -803,7 +812,7 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Merge the list of event references from acquisition with our own. :param acquisition: the event references list of this object will be - merged with the current event references list. + merged with the current event references list. :rtype acquisition: Person """ eventref_list = self.event_ref_list[:] @@ -826,18 +835,20 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def add_family_handle(self, family_handle): """ - Add the :class:`~gen.lib.family.Family` handle to the Person instance's :class:`~gen.lib.family.Family` list. + Add the :class:`~.family.Family` handle to the Person instance's + :class:`~.family.Family` list. - This is accomplished by assigning the handle of a valid :class:`~gen.lib.family.Family` - in the current database. + This is accomplished by assigning the handle of a valid + :class:`~.family.Family` in the current database. - Adding a :class:`~gen.lib.family.Family` handle to a Person does not automatically update - the corresponding :class:`~gen.lib.family.Family`. The developer is responsible to make - sure that when a :class:`~gen.lib.family.Family` is added to Person, that the Person is - assigned to either the father or mother role in the :class:`~gen.lib.family.Family`. + Adding a :class:`~.family.Family` handle to a Person does not + automatically update the corresponding :class:`~.family.Family`. The + developer is responsible to make sure that when a + :class:`~.family.Family` is added to Person, that the Person is assigned + to either the father or mother role in the :class:`~.family.Family`. - :param family_handle: handle of the :class:`~gen.lib.family.Family` to be added to the - Person's :class:`~gen.lib.family.Family` list. + :param family_handle: handle of the :class:`~.family.Family` to be added + to the Person's :class:`~.family.Family` list. :type family_handle: str """ if family_handle not in self.family_list: @@ -845,20 +856,22 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def set_preferred_family_handle(self, family_handle): """ - Set the family_handle specified to be the preferred :class:`~gen.lib.family.Family`. + Set the family_handle specified to be the preferred + :class:`~.family.Family`. - The preferred :class:`~gen.lib.family.Family` is determined by the first :class:`~gen.lib.family.Family` in the - :class:`~gen.lib.family.Family` list, and is typically used to indicate the preferred - :class:`~gen.lib.family.Family` for navigation or reporting. + The preferred :class:`~.family.Family` is determined by the first + :class:`~.family.Family` in the :class:`~.family.Family` list, and is + typically used to indicate the preferred :class:`~.family.Family` for + navigation or reporting. The family_handle must already be in the list, or the function call has no effect. - :param family_handle: Handle of the :class:`~gen.lib.family.Family` to make the preferred - :class:`~gen.lib.family.Family`. + :param family_handle: Handle of the :class:`~.family.Family` to make the + preferred :class:`~.family.Family`. :type family_handle: str :returns: True if the call succeeded, False if the family_handle - was not already in the :class:`~gen.lib.family.Family` list + was not already in the :class:`~.family.Family` list. :rtype: bool """ if family_handle in self.family_list: @@ -870,12 +883,12 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_family_handle_list(self) : """ - Return the list of :class:`~gen.lib.family.Family` handles in which the person is a parent - or spouse. + Return the list of :class:`~.family.Family` handles in which the person + is a parent or spouse. :returns: Returns the list of handles corresponding to the - :class:`~gen.lib.family.Family` records with which the person - is associated. + :class:`~.family.Family` records with which the person + is associated. :rtype: list """ return self.family_list @@ -885,30 +898,32 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, Assign the passed list to the Person's list of families in which it is a parent or spouse. - :param family_list: List of :class:`~gen.lib.family.Family` handles to be associated - with the Person + :param family_list: List of :class:`~.family.Family` handles to be + associated with the Person :type family_list: list """ self.family_list = family_list def clear_family_handle_list(self): """ - Remove all :class:`~gen.lib.family.Family` handles from the :class:`~gen.lib.family.Family` list. + Remove all :class:`~.family.Family` handles from the + :class:`~.family.Family` list. """ self.family_list = [] def remove_family_handle(self, family_handle): """ - Remove the specified :class:`~gen.lib.family.Family` handle from the list of + Remove the specified :class:`~.family.Family` handle from the list of marriages/partnerships. If the handle does not exist in the list, the operation has no effect. - :param family_handle: :class:`~gen.lib.family.Family` handle to remove from the list + :param family_handle: :class:`~.family.Family` handle to remove from + the list :type family_handle: str :returns: True if the handle was removed, False if it was not - in the list. + in the list. :rtype: bool """ if family_handle in self.family_list: @@ -919,39 +934,44 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_parent_family_handle_list(self): """ - Return the list of :class:`~gen.lib.family.Family` handles in which the person is a child. + Return the list of :class:`~.family.Family` handles in which the person + is a child. :returns: Returns the list of handles corresponding to the - :class:`~gen.lib.family.Family` records with which the person is a child. + :class:`~.family.Family` records with which the person is a + child. :rtype: list """ return self.parent_family_list def set_parent_family_handle_list(self, family_list): """ - Return the list of :class:`~gen.lib.family.Family` handles in which the person is a child. + Return the list of :class:`~.family.Family` handles in which the person + is a child. :returns: Returns the list of handles corresponding to the - :class:`~gen.lib.family.Family` records with which the person is a child. + :class:`~.family.Family` records with which the person is a + child. :rtype: list """ self.parent_family_list = family_list def add_parent_family_handle(self, family_handle): """ - Add the :class:`~gen.lib.family.Family` handle to the Person instance's list of families in - which it is a child. + Add the :class:`~.family.Family` handle to the Person instance's list of + families in which it is a child. - This is accomplished by assigning the handle of a valid :class:`~gen.lib.family.Family` in - the current database. + This is accomplished by assigning the handle of a valid + :class:`~.family.Family` in the current database. - Adding a :class:`~gen.lib.family.Family` handle to a Person does not automatically update - the corresponding :class:`~gen.lib.family.Family`. The developer is responsible to make - sure that when a :class:`~gen.lib.family.Family` is added to Person, that the Person is - added to the :class:`~gen.lib.family.Family` instance's child list. + Adding a :class:`~.family.Family` handle to a Person does not + automatically update the corresponding :class:`~.family.Family`. The + developer is responsible to make sure that when a + :class:`~.family.Family` is added to Person, that the Person is + added to the :class:`~.family.Family` instance's child list. - :param family_handle: handle of the :class:`~gen.lib.family.Family` to be added to the - Person's :class:`~gen.lib.family.Family` list. + :param family_handle: handle of the :class:`~.family.Family` to be added + to the Person's :class:`~.family.Family` list. :type family_handle: str """ if not isinstance(family_handle, STRTYPE): @@ -961,24 +981,26 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def clear_parent_family_handle_list(self): """ - Remove all :class:`~gen.lib.family.Family` handles from the parent :class:`~gen.lib.family.Family` list. + Remove all :class:`~.family.Family` handles from the parent + :class:`~.family.Family` list. """ self.parent_family_list = [] def remove_parent_family_handle(self, family_handle): """ - Remove the specified :class:`~gen.lib.family.Family` handle from the list of parent - families (families in which the parent is a child). + Remove the specified :class:`~.family.Family` handle from the list of + parent families (families in which the parent is a child). If the handle does not exist in the list, the operation has no effect. - :param family_handle: :class:`~gen.lib.family.Family` handle to remove from the list + :param family_handle: :class:`~.family.Family` handle to remove from the + list :type family_handle: str :returns: Returns a tuple of three strings, consisting of the - removed handle, relationship to mother, and relationship - to father. None is returned if the handle is not in the - list. + removed handle, relationship to mother, and relationship + to father. None is returned if the handle is not in the + list. :rtype: tuple """ if family_handle in self.parent_family_list: @@ -989,15 +1011,15 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def set_main_parent_family_handle(self, family_handle): """ - Set the main :class:`~gen.lib.family.Family` in which the Person is a child. + Set the main :class:`~.family.Family` in which the Person is a child. - The main :class:`~gen.lib.family.Family` is the :class:`~gen.lib.family.Family` typically used for reports and - navigation. This is accomplished by moving the :class:`~gen.lib.family.Family` to the - beginning of the list. The family_handle must be in the list for this - to have any effect. + The main :class:`~.family.Family` is the :class:`~.family.Family` + typically used for reports and navigation. This is accomplished by + moving the :class:`~.family.Family` to the beginning of the list. The + family_handle must be in the list for this to have any effect. - :param family_handle: handle of the :class:`~gen.lib.family.Family` to be marked - as the main :class:`~gen.lib.family.Family` + :param family_handle: handle of the :class:`~.family.Family` to be + marked as the main :class:`~.family.Family` :type family_handle: str :returns: Returns True if the assignment has successful :rtype: bool @@ -1011,11 +1033,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_main_parents_family_handle(self): """ - Return the handle of the :class:`~gen.lib.family.Family` considered to be the main :class:`~gen.lib.family.Family` - in which the Person is a child. + Return the handle of the :class:`~.family.Family` considered to be the + main :class:`~.family.Family` in which the Person is a child. :returns: Returns the family_handle if a family_handle exists, - If no :class:`~gen.lib.family.Family` is assigned, None is returned + If no :class:`~.family.Family` is assigned, None is returned :rtype: str """ if self.parent_family_list: @@ -1025,10 +1047,11 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def add_person_ref(self, person_ref): """ - Add the :class:`~gen.lib.personref.PersonRef` to the Person instance's :class:`~gen.lib.personref.PersonRef` list. + Add the :class:`~.personref.PersonRef` to the Person instance's + :class:`~.personref.PersonRef` list. - :param person_ref: the :class:`~gen.lib.personref.PersonRef` to be added to the - Person's :class:`~gen.lib.personref.PersonRef` list. + :param person_ref: the :class:`~.personref.PersonRef` to be added to the + Person's :class:`~.personref.PersonRef` list. :type person_ref: PersonRef """ if person_ref and not isinstance(person_ref, PersonRef): @@ -1037,18 +1060,20 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, def get_person_ref_list(self): """ - Return the list of :class:`~gen.lib.personref.PersonRef` objects. + Return the list of :class:`~.personref.PersonRef` objects. - :returns: Returns the list of :class:`~gen.lib.personref.PersonRef` objects. + :returns: Returns the list of :class:`~.personref.PersonRef` objects. :rtype: list """ return self.person_ref_list def set_person_ref_list(self, person_ref_list): """ - Set the Person instance's :class:`~gen.lib.personref.PersonRef` list to the passed list. + Set the Person instance's :class:`~.personref.PersonRef` list to the + passed list. - :param person_ref_list: List of valid :class:`~gen.lib.personref.PersonRef` objects + :param person_ref_list: List of valid :class:`~.personref.PersonRef` + objects :type person_ref_list: list """ self.person_ref_list = person_ref_list @@ -1057,8 +1082,8 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, """ Merge the list of person references from acquisition with our own. - :param acquisition: the list of person references of this person will b - merged with the current person references list. + :param acquisition: the list of person references of this person will be + merged with the current person references list. :rtype acquisition: Person """ personref_list = self.person_ref_list[:] @@ -1072,4 +1097,3 @@ class Person(CitationBase, NoteBase, AttributeBase, MediaBase, break else: self.person_ref_list.append(addendum) - diff --git a/gramps/gen/lib/personref.py b/gramps/gen/lib/personref.py index ab64c8cb8..f73d907f6 100644 --- a/gramps/gen/lib/personref.py +++ b/gramps/gen/lib/personref.py @@ -24,7 +24,7 @@ # $Id$ """ -Person Reference class for GRAMPS. +Person Reference class for Gramps. """ #------------------------------------------------------------------------- @@ -148,7 +148,7 @@ class PersonRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase): Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return [] @@ -183,7 +183,7 @@ class PersonRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase): and relation, to other. :param other: The personref to compare this one to. - :rtype other: PersonRef + :type other: PersonRef :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -203,7 +203,7 @@ class PersonRef(SecondaryObject, PrivacyBase, CitationBase, NoteBase, RefBase): Lost: hlink and relation of acquisition. :param acquisition: The personref to merge with the present personref. - :param acquisition: PersonRef + :type acquisition: PersonRef """ self._merge_privacy(acquisition) self._merge_citation_list(acquisition) diff --git a/gramps/gen/lib/place.py b/gramps/gen/lib/place.py index ff1a94f96..b8aed5e58 100644 --- a/gramps/gen/lib/place.py +++ b/gramps/gen/lib/place.py @@ -24,7 +24,7 @@ # $Id$ """ -Place object for GRAMPS. +Place object for Gramps. """ from __future__ import unicode_literals @@ -102,7 +102,7 @@ class Place(CitationBase, NoteBase, MediaBase, UrlBase, PrimaryObject): a form that it can use. :returns: Returns a python tuple containing the data that should - be considered persistent. + be considered persistent. :rtype: tuple """ return (self.handle, self.gramps_id, self.title, self.long, self.lat, @@ -185,8 +185,8 @@ class Place(CitationBase, NoteBase, MediaBase, UrlBase, PrimaryObject): Convert the data held in a tuple created by the serialize method back into the data in a Place object. - :param data: tuple containing the persistent data associated the - Person object + :param data: tuple containing the persistent data associated with the + Place object :type data: tuple """ (self.handle, self.gramps_id, self.title, self.long, self.lat, @@ -270,7 +270,7 @@ class Place(CitationBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Merge the content of acquisition into this place. :param acquisition: The place to merge with the present place. - :rtype acquisition: Place + :type acquisition: Place """ self._merge_privacy(acquisition) self._merge_locations(acquisition) @@ -422,7 +422,7 @@ class Place(CitationBase, NoteBase, MediaBase, UrlBase, PrimaryObject): location list. :param acquisition: instance to merge - :type acquisition: :class:'~gen.lib.place.Place + :type acquisition: :class:'~.place.Place """ placeref_list = self.placeref_list[:] add_list = acquisition.placeref_list @@ -470,33 +470,36 @@ class Place(CitationBase, NoteBase, MediaBase, UrlBase, PrimaryObject): def get_alternate_locations(self): """ - Return a list of alternate :class:`~gen.lib.location.Location` objects the present alternate - information about the current Place. + Return a list of alternate :class:`~.location.Location` objects the + present alternate information about the current Place. - A Place can have more than one :class:`~gen.lib.location.Location`, since names and - jurisdictions can change over time for the same place. + A Place can have more than one :class:`~.location.Location`, since names + and jurisdictions can change over time for the same place. - :returns: Returns the alternate :class:`~gen.lib.location.Location`\ s for the Place - :rtype: list of :class:`~gen.lib.location.Location` objects + :returns: Returns the alternate :class:`~.location.Location`\ s for the + Place + :rtype: list of :class:`~.location.Location` objects """ return self.alt_loc def set_alternate_locations(self, location_list): """ - Replace the current alternate :class:`~gen.lib.location.Location` object list with the new one. + Replace the current alternate :class:`~.location.Location` object list + with the new one. - :param location_list: The list of :class:`~gen.lib.location.Location` objects to assign to the - Place's internal list. - :type location_list: list of :class:`~gen.lib.location.Location` objects + :param location_list: The list of :class:`~.location.Location` objects + to assign to the Place's internal list. + :type location_list: list of :class:`~.location.Location` objects """ self.alt_loc = location_list def add_alternate_locations(self, location): """ - Add a :class:`~gen.lib.location.Location` object to the alternate location list. + Add a :class:`~.location.Location` object to the alternate location + list. - :param location: :class:`~gen.lib.location.Location` instance to add - :type location: :class:`~gen.lib.location.Location` + :param location: :class:`~.location.Location` instance to add + :type location: :class:`~.location.Location` """ if location not in self.alt_loc: self.alt_loc.append(location) @@ -507,7 +510,7 @@ class Place(CitationBase, NoteBase, MediaBase, UrlBase, PrimaryObject): location list. :param acquisition: instance to merge - :type acquisition: :class:'~gen.lib.place.Place + :type acquisition: :class:'~.place.Place """ altloc_list = self.alt_loc[:] add_list = acquisition.get_alternate_locations() diff --git a/gramps/gen/lib/placebase.py b/gramps/gen/lib/placebase.py index d4cd306c4..aad27ccf5 100644 --- a/gramps/gen/lib/placebase.py +++ b/gramps/gen/lib/placebase.py @@ -21,7 +21,7 @@ # $Id$ """ -PlaceBase class for GRAMPS. +PlaceBase class for Gramps. """ #------------------------------------------------------------------------- @@ -50,18 +50,20 @@ class PlaceBase(object): def set_place_handle(self, place_handle): """ - Set the database handle for :class:`~gen.lib.place.Place` associated with the object. + Set the database handle for :class:`~.place.Place` associated with the + object. - :param place_handle: :class:`~gen.lib.place.Place` database handle + :param place_handle: :class:`~.place.Place` database handle :type place_handle: str """ self.place = place_handle def get_place_handle(self): """ - Return the database handle of the :class:`~gen.lib.place.Place` associated with the Event. + Return the database handle of the :class:`~.place.Place` associated + with the :class:`~.event.Event`. - :returns: :class:`~gen.lib.place.Place` database handle + :returns: :class:`~.place.Place` database handle :rtype: str """ return self.place diff --git a/gramps/gen/lib/placeref.py b/gramps/gen/lib/placeref.py index 9482ae4cb..229a61893 100644 --- a/gramps/gen/lib/placeref.py +++ b/gramps/gen/lib/placeref.py @@ -135,7 +135,7 @@ class PlaceRef(RefBase, DateBase, SecondaryObject): Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return [] @@ -145,7 +145,7 @@ class PlaceRef(RefBase, DateBase, SecondaryObject): Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return [] @@ -156,7 +156,7 @@ class PlaceRef(RefBase, DateBase, SecondaryObject): referenced primary objects. :returns: Returns the list of (classname, handle) tuples for referenced - objects. + objects. :rtype: list """ return [('Place', self.ref)] @@ -177,7 +177,7 @@ class PlaceRef(RefBase, DateBase, SecondaryObject): role, to other. :param other: The eventref to compare this one to. - :rtype other: EventRef + :type other: PlaceRef :returns: Constant indicating degree of equivalence. :rtype: int """ diff --git a/gramps/gen/lib/primaryobj.py b/gramps/gen/lib/primaryobj.py index 2487932de..f67725943 100644 --- a/gramps/gen/lib/primaryobj.py +++ b/gramps/gen/lib/primaryobj.py @@ -22,7 +22,7 @@ # $Id$ """ -Basic Primary Object class for GRAMPS. +Basic Primary Object class for Gramps. """ #------------------------------------------------------------------------- @@ -43,14 +43,14 @@ from .tagbase import TagBase #------------------------------------------------------------------------- class BasicPrimaryObject(TableObject, PrivacyBase, TagBase): """ - The BasicPrimaryObject is the base class for Note objects. + The BasicPrimaryObject is the base class for :class:`~.note.Note` objects. - It is also the base class for the PrimaryObject class. + It is also the base class for the :class:`PrimaryObject` class. - The PrimaryObject is the base class for all other primary objects in the - database. Primary objects are the core objects in the database. - Each object has a database handle and a GRAMPS ID value. The database - handle is used as the record number for the database, and the GRAMPS + The :class:`PrimaryObject` is the base class for all other primary objects + in the database. Primary objects are the core objects in the database. + Each object has a database handle and a Gramps ID value. The database + handle is used as the record number for the database, and the Gramps ID is the user visible version. """ @@ -75,18 +75,18 @@ class BasicPrimaryObject(TableObject, PrivacyBase, TagBase): def set_gramps_id(self, gramps_id): """ - Set the GRAMPS ID for the primary object. + Set the Gramps ID for the primary object. - :param gramps_id: GRAMPS ID + :param gramps_id: Gramps ID :type gramps_id: str """ self.gramps_id = gramps_id def get_gramps_id(self): """ - Return the GRAMPS ID for the primary object. + Return the Gramps ID for the primary object. - :returns: GRAMPS ID associated with the object + :returns: Gramps ID associated with the object :rtype: str """ return self.gramps_id @@ -177,8 +177,8 @@ class PrimaryObject(BasicPrimaryObject): database. Primary objects are the core objects in the database. - Each object has a database handle and a GRAMPS ID value. The database - handle is used as the record number for the database, and the GRAMPS + Each object has a database handle and a Gramps ID value. The database + handle is used as the record number for the database, and the Gramps ID is the user visible version. """ @@ -205,7 +205,7 @@ class PrimaryObject(BasicPrimaryObject): :param handle: The handle to be checked. :type handle: str :returns: Returns whether the object has reference to this handle - of this object type. + of this object type. :rtype: bool """ if classname == 'Citation' and isinstance(self, CitationBase): @@ -266,4 +266,3 @@ class PrimaryObject(BasicPrimaryObject): Replace the handle reference with the new reference. """ pass - diff --git a/gramps/gen/lib/privacybase.py b/gramps/gen/lib/privacybase.py index fea50c205..1ca7ea2dc 100644 --- a/gramps/gen/lib/privacybase.py +++ b/gramps/gen/lib/privacybase.py @@ -22,7 +22,7 @@ # $Id$ """ -PrivacyBase Object class for GRAMPS. +PrivacyBase Object class for Gramps. """ #------------------------------------------------------------------------- diff --git a/gramps/gen/lib/refbase.py b/gramps/gen/lib/refbase.py index 7e6d4c759..873ab6447 100644 --- a/gramps/gen/lib/refbase.py +++ b/gramps/gen/lib/refbase.py @@ -21,7 +21,7 @@ # $Id$ """ -Base Reference class for GRAMPS. +Base Reference class for Gramps. """ from .handle import Handle @@ -94,7 +94,7 @@ class RefBase(object): referenced primary objects. :returns: Returns the list of (classname, handle) tuples for referenced - objects. + objects. :rtype: list """ assert False, "Must be overridden in the derived class" diff --git a/gramps/gen/lib/repo.py b/gramps/gen/lib/repo.py index 9c54a154b..b875ae2db 100644 --- a/gramps/gen/lib/repo.py +++ b/gramps/gen/lib/repo.py @@ -23,7 +23,7 @@ # $Id$ """ -Repository object for GRAMPS. +Repository object for Gramps. """ #------------------------------------------------------------------------- @@ -162,7 +162,7 @@ class Repository(NoteBase, AddressBase, UrlBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return self.address_list @@ -172,7 +172,7 @@ class Repository(NoteBase, AddressBase, UrlBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.address_list @@ -203,7 +203,7 @@ class Repository(NoteBase, AddressBase, UrlBase, Merge the content of acquisition into this repository. :param acquisition: The repository to merge with the present repository. - :rtype acquisition: Repository + :type acquisition: Repository """ self._merge_privacy(acquisition) self._merge_address_list(acquisition) diff --git a/gramps/gen/lib/reporef.py b/gramps/gen/lib/reporef.py index deb23dd70..2b600d71c 100644 --- a/gramps/gen/lib/reporef.py +++ b/gramps/gen/lib/reporef.py @@ -23,7 +23,7 @@ # $Id$ """ -Repository Reference class for GRAMPS +Repository Reference class for Gramps """ #------------------------------------------------------------------------- @@ -155,7 +155,7 @@ class RepoRef(SecondaryObject, PrivacyBase, NoteBase, RefBase): reference, call number and medium, to other. :param other: The repository reference to compare this one to. - :rtype other: RepoRef + :type other: RepoRef :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -173,8 +173,8 @@ class RepoRef(SecondaryObject, PrivacyBase, NoteBase, RefBase): Merge the content of acquisition into this repository reference. :param acquisition: The repository reference to merge with the present - repository reference. - :rtype acquisition: RepoRef + repository reference. + :type acquisition: RepoRef """ self._merge_privacy(acquisition) self._merge_note_list(acquisition) diff --git a/gramps/gen/lib/researcher.py b/gramps/gen/lib/researcher.py index 9a3ec3513..1706204f3 100644 --- a/gramps/gen/lib/researcher.py +++ b/gramps/gen/lib/researcher.py @@ -22,7 +22,7 @@ # $Id$ """ -Researcher information for GRAMPS. +Researcher information for Gramps. """ #------------------------------------------------------------------------- diff --git a/gramps/gen/lib/secondaryobj.py b/gramps/gen/lib/secondaryobj.py index 2490bd5db..08da0d4f9 100644 --- a/gramps/gen/lib/secondaryobj.py +++ b/gramps/gen/lib/secondaryobj.py @@ -21,7 +21,7 @@ # $Id$ """ -Secondary Object class for GRAMPS. +Secondary Object class for Gramps. """ #------------------------------------------------------------------------- diff --git a/gramps/gen/lib/src.py b/gramps/gen/lib/src.py index 16e2254d1..2b6aa6292 100644 --- a/gramps/gen/lib/src.py +++ b/gramps/gen/lib/src.py @@ -24,7 +24,7 @@ # $Id$ """ -Source object for GRAMPS. +Source object for Gramps. """ #------------------------------------------------------------------------- @@ -143,7 +143,7 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, def unserialize(self, data): """ Convert the data held in a tuple created by the serialize method - back into the data in an Event structure. + back into the data in a Source structure. """ (self.handle, # 0 self.gramps_id, # 1 @@ -177,7 +177,7 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, :param handle: The handle to be checked. :type handle: str :returns: Returns whether the object has reference to this handle of - this object type. + this object type. :rtype: bool """ if classname == 'Repository': @@ -240,7 +240,7 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, Return the list of child secondary objects that may refer citations. :returns: Returns the list of child secondary child objects that may - refer citations. + refer citations. :rtype: list """ return self.media_list @@ -250,7 +250,7 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, Return the list of child secondary objects that may refer notes. :returns: Returns the list of child secondary child objects that may - refer notes. + refer notes. :rtype: list """ return self.media_list + self.reporef_list @@ -281,7 +281,7 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, Merge the content of acquisition into this source. :param acquisition: The source to merge with the present source. - :rtype acquisition: Source + :type acquisition: Source """ self._merge_privacy(acquisition) self._merge_note_list(acquisition) @@ -334,30 +334,32 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, def add_repo_reference(self, repo_ref): """ - Add a :class:`~gen.lib.reporef,RepoRef` instance to the Source's reporef list. + Add a :class:`~.reporef.RepoRef` instance to the Source's reporef list. - :param repo_ref: :class:`~gen.lib.reporef,RepoRef` instance to be added to the object's - reporef list. - :type repo_ref: :class:`~gen.lib.reporef,RepoRef` + :param repo_ref: :class:`~.reporef.RepoRef` instance to be added to the + object's reporef list. + :type repo_ref: :class:`~.reporef.RepoRef` """ self.reporef_list.append(repo_ref) def get_reporef_list(self): """ - Return the list of :class:`~gen.lib.reporef,RepoRef` instances associated with the Source. + Return the list of :class:`~.reporef.RepoRef` instances associated with + the Source. - @Return: list of :class:`~gen.lib.reporef,RepoRef` instances associated with the Source + :returns: list of :class:`~.reporef.RepoRef` instances associated with + the Source :rtype: list """ return self.reporef_list def set_reporef_list(self, reporef_list): """ - Set the list of :class:`~gen.lib.reporef,RepoRef` instances associated with the Source. - It replaces the previous list. + Set the list of :class:`~.reporef.RepoRef` instances associated with + the Source. It replaces the previous list. - :param reporef_list: list of :class:`~gen.lib.reporef,RepoRef` instances to be assigned to - the Source. + :param reporef_list: list of :class:`~.reporef.RepoRef` instances to be + assigned to the Source. :type reporef_list: list """ self.reporef_list = reporef_list @@ -367,8 +369,9 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, Merge the list of repository references from acquisition with our own. :param acquisition: the repository references list of this object will - be merged with the current repository references list. - :rtype acquisition: RepoRef + be merged with the current repository references + list. + :type acquisition: RepoRef """ reporef_list = self.reporef_list[:] for addendum in acquisition.get_reporef_list(): @@ -389,7 +392,7 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, :param repo_handle: The Repository handle to be checked. :type repo_handle: str :returns: Returns whether the Source has reference to this Repository - handle. + handle. :rtype: bool """ return repo_handle in [repo_ref.ref for repo_ref in self.reporef_list] @@ -414,7 +417,6 @@ class Source(MediaBase, NoteBase, SrcAttributeBase, IndirectCitationBase, :type old_handle: str :param new_handle: The Repository handle to replace the old one with. :type new_handle: str - indikken """ refs_list = [ repo_ref.ref for repo_ref in self.reporef_list ] new_ref = None diff --git a/gramps/gen/lib/styledtext.py b/gramps/gen/lib/styledtext.py index 827ba2fd4..143dea02b 100644 --- a/gramps/gen/lib/styledtext.py +++ b/gramps/gen/lib/styledtext.py @@ -41,46 +41,44 @@ from ..constfunc import cuni, STRTYPE class StyledText(object): """Helper class to enable character based text formatting. - StyledText is a wrapper class binding the clear text string and it's - formatting tags together. + :py:class:`StyledText` is a wrapper class binding the clear text string and + it's formatting tags together. - StyledText provides several string methods in order to manipulate - formatted strings, such as :meth:`~gen.lib.styledtext.StyledText.join`, - :meth:`~gen.lib.styledtext.StyledText.replace`, - :meth:`~gen.lib.styledtext.StyledText.split`, and also - supports the '+' operation (:meth:`~gen.lib.styledtext.StyledText.__add__`). + :py:class:`StyledText` provides several string methods in order to + manipulate formatted strings, such as :py:meth:`join`, :py:meth:`replace`, + :py:meth:`split`, and also supports the '+' operation (:py:meth:`__add__`). - To get the clear text of the StyledText use the built-in str() function. - To get the list of formatting tags use the L{get_tags} method. + To get the clear text of the :py:class:`StyledText` use the built-in + :py:func:`str()` function. To get the list of formatting tags use the + :py:meth:`get_tags` method. - StyledText supports the I{creation} of formatted texts too. This feature + StyledText supports the *creation* of formatted texts too. This feature is intended to replace (or extend) the current report interface. To be continued... FIXME :ivar string: (str) The clear text part. - :ivar tags: (list of :class:`~gen.lib.styledtexttag.StyledTextTag`) Text - tags holding formatting information for the string. + :ivar tags: (list of :py:class:`.StyledTextTag`) Text tags holding + formatting information for the string. :cvar POS_TEXT: Position of *string* attribute in the serialized format of - an instance. - :cvar POS_TAGS: (int) Position of *tags* attribute in the serialized format of - an instance. + an instance. + :cvar POS_TAGS: (int) Position of *tags* attribute in the serialized format + of an instance. - :attention: The POS_ class variables reflect the serialized object, - they have to be updated in case the data structure or the L{serialize} - method changes! + .. warning:: The POS_ class variables reflect the serialized object, + they have to be updated in case the data structure or the + :py:meth:`serialize` method changes! - :note: - 1. There is no sanity check of tags in - :meth:`~gen.lib.styledtext.StyledText.__init__`, because when a - StyledText is displayed it is passed to a StyledTextBuffer, which - in turn will 'eat' all invalid tags (including out-of-range tags too). - 2. After string methods the tags can become fragmented. That means the - same tag may appear more than once in the tag list with different ranges. - There could be a 'merge_tags' functionality in - :meth:`~gen.lib.styledtext.StyledText.__init__`, however - StyledTextBuffer will merge them automatically if the text is displayed. - + .. note:: + 1. There is no sanity check of tags in :py:meth:`__init__`, because when a + :py:class:`StyledText` is displayed it is passed to a + :py:class:`.StyledTextBuffer`, which in turn will 'eat' all invalid + tags (including out-of-range tags too). + 2. After string methods the tags can become fragmented. That means the same + tag may appear more than once in the tag list with different ranges. + There could be a 'merge_tags' functionality in :py:meth:`__init__`, + however :py:class:`StyledTextBuffer` will merge them automatically if + the text is displayed. """ (POS_TEXT, POS_TAGS) = list(range(2)) @@ -102,9 +100,9 @@ class StyledText(object): """Implement '+' operation on the class. :param other: string to concatenate to self - :type other: basestring or StyledText - :returns: concatenated strings - :returnstype: StyledText + :type other: basestring or :py:class:`StyledText` + :return: concatenated strings + :rtype: :py:class:`StyledText` """ offset = len(self._string) @@ -185,13 +183,13 @@ class StyledText(object): # string methods in alphabetical order: def join(self, seq): - """Emulate __builtin__.str.join method. + """ + Emulate :py:meth:`__builtin__.str.join` method. :param seq: list of strings to join - :type seq: basestring or StyledText - :returns: joined strings - :returnstype: StyledText - + :type seq: basestring or :py:class:`StyledText` + :return: joined strings + :rtype: :py:class:`StyledText` """ new_string = self._string.join([str(string) for string in seq]) @@ -211,34 +209,35 @@ class StyledText(object): return self.__class__(new_string, new_tags) def replace(self, old, new, count=-1): - """Emulate __builtin__.str.replace method. + """ + Emulate :py:meth:`__builtin__.str.replace` method. :param old: substring to be replaced - :type old: basestring or StyledText + :type old: basestring or :py:class:`StyledText` :param new: substring to replace by - :type new: StyledText + :type new: :py:class:`StyledText` :param count: if given, only the first count occurrences are replaced :type count: int - :returns: copy of the string with replaced substring(s) - :returnstype: StyledText + :return: copy of the string with replaced substring(s) + :rtype: :py:class:`StyledText` - @attention: by the correct implementation parameter I{new} - should be StyledText or basestring, however only StyledText - is currently supported. + .. warning:: by the correct implementation parameter *new* should be + :py:class:`StyledText` or basestring, however only + :py:class:`StyledText` is currently supported. """ # quick and dirty solution: works only if new.__class__ == StyledText return new.join(self.split(old, count)) def split(self, sep=None, maxsplit=-1): - """Emulate __builtin__.str.split method. + """ + Emulate :py:meth:`__builtin__.str.split` method. :param sep: the delimiter string - :type seq: basestring or StyledText + :type seq: basestring or :py:class:`StyledText` :param maxsplit: if given, at most maxsplit splits are done :type maxsplit: int - :returns: a list of the words in the string - :returnstype: list of StyledText - + :return: a list of the words in the string + :rtype: list of :py:class:`StyledText` """ # split the clear text first if sep is not None: @@ -275,11 +274,11 @@ class StyledText(object): # other public methods def serialize(self): - """Convert the object to a serialized tuple of data. - - :returns: Serialized format of the instance. - :returnstype: tuple + """ + Convert the object to a serialized tuple of data. + :return: Serialized format of the instance. + :rtype: tuple """ if self._tags: the_tags = [tag.serialize() for tag in self._tags] @@ -305,7 +304,7 @@ class StyledText(object): of structs. Otherwise, the struct is just the value of the attribute. - :returns: Returns a struct containing the data of the object. + :return: Returns a struct containing the data of the object. :rtype: dict """ if self._tags: @@ -322,17 +321,19 @@ class StyledText(object): """ Given a struct data representation, return a serialized object. - :returns: Returns a serialized object + :return: Returns a serialized object """ default = StyledText() - return (struct.get("string", default.string), [StyledTextTag.from_struct(t) for t in struct.get("tags", default.tags)]) + return (struct.get("string", default.string), + [StyledTextTag.from_struct(t) + for t in struct.get("tags", default.tags)]) def unserialize(self, data): - """Convert a serialized tuple of data to an object. + """ + Convert a serialized tuple of data to an object. :param data: Serialized format of instance variables. :type data: tuple - """ (self._string, the_tags) = data @@ -345,11 +346,11 @@ class StyledText(object): return self def get_tags(self): - """Return the list of formatting tags. - - :returns: The formatting tags applied on the text. - :returnstype: list of 0 or more :class:`~gen.lib.styledtexttag.StyledTextTag` instances. + """ + Return the list of formatting tags. + :return: The formatting tags applied on the text. + :rtype: list of 0 or more :py:class:`.StyledTextTag` instances. """ return self._tags diff --git a/gramps/gen/lib/styledtexttag.py b/gramps/gen/lib/styledtexttag.py index 66baaf5d4..11298931d 100644 --- a/gramps/gen/lib/styledtexttag.py +++ b/gramps/gen/lib/styledtexttag.py @@ -36,26 +36,26 @@ from .styledtexttagtype import StyledTextTagType # #------------------------------------------------------------------------- class StyledTextTag(object): - """Hold formatting information for StyledText. + """Hold formatting information for :py:class:`.StyledText`. - StyledTextTag is a container class, it's attributes are directly accessed. + :py:class:`StyledTextTag` is a container class, it's attributes are + directly accessed. - @ivar name: Type (or name) of the tag instance. E.g. 'bold', etc. - :type name: :class:`~gen.lib.styledtexttagtype.StyledTextTagType` instace - @ivar value: Value of the tag. E.g. color hex string for font color, etc. + :ivar name: Type (or name) of the tag instance. E.g. 'bold', etc. + :type name: :py:class:`.StyledTextTagType` instace + :ivar value: Value of the tag. E.g. color hex string for font color, etc. :type value: str or None - @ivar ranges: Pointer pairs into the string, where the tag applies. + :ivar ranges: Pointer pairs into the string, where the tag applies. :type ranges: list of (int(start), int(end)) tuples. """ def __init__(self, name=None, value=None, ranges=None): """Setup initial instance variable values. - @note: Since :class:`~gen.lib.grampstype.GrampsType` supports the instance initialization - with several different base types, please note that C{name} parameter - can be int, str, unicode, tuple, or even another L{StyledTextTagType} - instance. - + .. note:: Since :py:class:`.GrampsType` supports the instance + initialization with several different base types, please note + that ``name`` parameter can be int, str, unicode, tuple, + or even another :py:class:`.StyledTextTagType` instance. """ self.name = StyledTextTagType(name) self.value = value @@ -68,8 +68,8 @@ class StyledTextTag(object): def serialize(self): """Convert the object to a serialized tuple of data. - :returns: Serialized format of the instance. - :returnstype: tuple + :return: Serialized format of the instance. + :rtype: tuple """ return (self.name.serialize(), self.value, self.ranges) @@ -91,7 +91,7 @@ class StyledTextTag(object): of structs. Otherwise, the struct is just the value of the attribute. - :returns: Returns a struct containing the data of the object. + :return: Returns a struct containing the data of the object. :rtype: dict """ return {"_class": "StyledTextTag", @@ -104,7 +104,7 @@ class StyledTextTag(object): """ Given a struct data representation, return a serialized object. - :returns: Returns a serialized object + :return: Returns a serialized object """ default = StyledTextTag() return (StyledTextTagType.from_struct(struct.get("name", {})), diff --git a/gramps/gen/lib/surname.py b/gramps/gen/lib/surname.py index 3be7333af..c89a2014a 100644 --- a/gramps/gen/lib/surname.py +++ b/gramps/gen/lib/surname.py @@ -22,7 +22,7 @@ # $Id$ """ -Surname class for GRAMPS. +Surname class for Gramps. """ #------------------------------------------------------------------------- @@ -47,8 +47,9 @@ class Surname(SecondaryObject): """ def __init__(self, source=None, data=None): - """Create a new Surname instance, copying from the source if provided. - By default a surname is created as primary, use set_primary to change + """ + Create a new Surname instance, copying from the source if provided. + By default a surname is created as primary, use set_primary to change """ if source: self.surname = source.surname @@ -145,7 +146,7 @@ class Surname(SecondaryObject): ..., to other. :param other: The surname to compare this name to. - :rtype other: Surame + :type other: Surname :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -166,7 +167,7 @@ class Surname(SecondaryObject): Lost: primary, surname, prefix, connector, origintype :param acquisition: The surname to merge with the present surname. - :rtype acquisition: Surname + :type acquisition: Surname """ pass @@ -212,13 +213,15 @@ class Surname(SecondaryObject): return self.origintype def set_connector(self, connector): - """Set the connector for the Surname instance. This defines how a + """ + Set the connector for the Surname instance. This defines how a surname connects to the next surname (eg in Spanish names). """ self.connector = connector def get_connector(self): - """Get the connector for the Surname instance. This defines how a + """ + Get the connector for the Surname instance. This defines how a surname connects to the next surname (eg in Spanish names). """ return self.connector @@ -228,11 +231,12 @@ class Surname(SecondaryObject): return self.primary def set_primary(self, primary=True): - """Set if this surname is the primary surname.replace - Use :class:`~gen.lib.surname.SurnameBase` to set the primary surname - via :method:`~gen.lib.surname.SurnameBase.set_primary_surname` - - :param primary: primay surname or not - :type primary: bool + """ + Set if this surname is the primary surname.replace + Use :class:`~.surnamebase.SurnameBase` to set the primary surname + via :meth:`~.surnamebase.SurnameBase.set_primary_surname` + + :param primary: primay surname or not + :type primary: bool """ self.primary = primary diff --git a/gramps/gen/lib/surnamebase.py b/gramps/gen/lib/surnamebase.py index a128b3eea..23a75c83d 100644 --- a/gramps/gen/lib/surnamebase.py +++ b/gramps/gen/lib/surnamebase.py @@ -21,7 +21,7 @@ # $Id$ """ -SurnameBase class for GRAMPS. +SurnameBase class for Gramps. """ from ..const import GRAMPS_LOCALE as glocale @@ -102,28 +102,29 @@ class SurnameBase(object): def add_surname(self, surname): """ - Add the :class:`~gen.lib.surname.Surname` instance to the object's + Add the :class:`~.surname.Surname` instance to the object's list of surnames. - :param surname: :class:`~gen.lib.surname.Surname` instance to add to - the object's address list. + :param surname: :class:`~.surname.Surname` instance to add to the + object's address list. :type address: list """ self.surname_list.append(surname) def remove_surname(self, surname): """ - Remove the specified :class:`~gen.lib.surname.Surname` instance from - the surname list. + Remove the specified :class:`~.surname.Surname` instance from the + surname list. If the instance does not exist in the list, the operation has no effect. - :param surname: :class:`~gen.lib.surname.Surname` instance to remove - from the list - :type surname: :class:`~gen.lib.surname.Surname` + :param surname: :class:`~.surname.Surname` instance to remove + from the list + :type surname: :class:`~.surname.Surname` - :returns: True if the surname was removed, False if it was not in the list. + :returns: True if the surname was removed, False if it was not in the + list. :rtype: bool """ if surname in self.surname_list: @@ -134,10 +135,10 @@ class SurnameBase(object): def get_surname_list(self): """ - Return the list of :class:`~gen.lib.surname.Surname` instances a - ssociated with the object. + Return the list of :class:`~.surname.Surname` instances + associated with the object. - :returns: Returns the list of :class:`~gen.lib.surname.Surname` instances + :returns: Returns the list of :class:`~.surname.Surname` instances :rtype: list """ return self.surname_list @@ -145,10 +146,10 @@ class SurnameBase(object): def set_surname_list(self, surname_list): """ Assign the passed list to the object's list of - :class:`~gen.lib.surname.Surname` instances. + :class:`~.surname.Surname` instances. - :param surname_list: List of :class:`~gen.lib.surname.surname` instances - to be associated with the object + :param surname_list: List of :class:`~.surname.Surname` instances to be + associated with the object :type surname_list: list """ self.surname_list = surname_list @@ -157,10 +158,10 @@ class SurnameBase(object): """ Return the surname that is the primary surname - :returns: Returns the surname instance that - is the primary surname. If primary not set, and there is a surname, - the first surname is given, if no surnames, None is returned - :rtype: :class:`~gen.lib.surname.Surname` or None + :returns: Returns the surname instance that is the primary surname. If + primary not set, and there is a surname, the first surname is + given, if no surnames, None is returned + :rtype: :class:`~.surname.Surname` or None """ for surname in self.surname_list: if surname.primary: @@ -192,8 +193,8 @@ class SurnameBase(object): alternate name. For completeness, the code is present nevertheless. :param acquisition: the surname list of this object will be merged with - the current surname list. - :rtype acquisition: SurnameBase + the current surname list. + :type acquisition: SurnameBase """ surname_list = self.surname_list[:] for addendum in acquisition.get_surname_list(): diff --git a/gramps/gen/lib/tableobj.py b/gramps/gen/lib/tableobj.py index 3eae632ca..c5d0a1523 100644 --- a/gramps/gen/lib/tableobj.py +++ b/gramps/gen/lib/tableobj.py @@ -86,10 +86,10 @@ class TableObject(BaseObject): """ Return the time that the data was last changed. - The value in the format returned by the time.time() command. + The value in the format returned by the :meth:`time.time()` command. :returns: Time that the data was last changed. The value in the format - returned by the time.time() command. + returned by the :meth:`time.time()` command. :rtype: int """ return self.change @@ -98,10 +98,11 @@ class TableObject(BaseObject): """ Modify the time that the data was last changed. - The value must be in the format returned by the time.time() command. + The value must be in the format returned by the :meth:`time.time()` + command. - @param change: new time - @type change: int in format as time.time() command + :param change: new time + :type change: int in format as :meth:`time.time()` command """ self.change = change diff --git a/gramps/gen/lib/tag.py b/gramps/gen/lib/tag.py index 890c9dfd2..b2ed68885 100644 --- a/gramps/gen/lib/tag.py +++ b/gramps/gen/lib/tag.py @@ -22,7 +22,7 @@ # $Id$ """ -Tag object for GRAMPS. +Tag object for Gramps. """ #------------------------------------------------------------------------- @@ -78,7 +78,7 @@ class Tag(TableObject): a form that it can use. :returns: Returns a python tuple containing the data that should - be considered persistent. + be considered persistent. :rtype: tuple """ return (self.handle, @@ -92,8 +92,8 @@ class Tag(TableObject): Convert the data held in a tuple created by the serialize method back into the data in a Tag structure. - :param data: tuple containing the persistent data associated the - Person object + :param data: tuple containing the persistent data associated with the + object :type data: tuple """ (self.handle, @@ -143,8 +143,8 @@ class Tag(TableObject): """ Set the name of the Tag to the passed string. - :param the_type: Name to assign to the Tag - :type the_type: str + :param name: Name to assign to the Tag + :type name: str """ self.__name = name diff --git a/gramps/gen/lib/tagbase.py b/gramps/gen/lib/tagbase.py index eb0f4af7d..3f9fe38ab 100644 --- a/gramps/gen/lib/tagbase.py +++ b/gramps/gen/lib/tagbase.py @@ -145,7 +145,7 @@ class TagBase(object): """ Return the list of (classname, handle) tuples for all referenced tags. - This method should be used to get the :class:`~gen.lib.tag.Tag` portion + This method should be used to get the :class:`~.tag.Tag` portion of the list by objects that store tag lists. :returns: List of (classname, handle) tuples for referenced objects. @@ -158,8 +158,8 @@ class TagBase(object): Merge the list of tag from acquisition with our own. :param acquisition: The tag list of this object will be merged with - the current tag list. - :rtype acquisition: TagBase + the current tag list. + :type acquisition: TagBase """ for addendum in acquisition.get_tag_list(): self.add_tag(addendum) diff --git a/gramps/gen/lib/url.py b/gramps/gen/lib/url.py index ebce90c02..1cf105dff 100644 --- a/gramps/gen/lib/url.py +++ b/gramps/gen/lib/url.py @@ -22,7 +22,7 @@ # $Id$ """ -Url class for GRAMPS. +Url class for Gramps. """ #------------------------------------------------------------------------- @@ -132,7 +132,7 @@ class Url(SecondaryObject, PrivacyBase): name and description, to other. :param other: The url to compare this one to. - :rtype other: Url + :type other: Url :returns: Constant indicating degree of equivalence. :rtype: int """ @@ -151,7 +151,7 @@ class Url(SecondaryObject, PrivacyBase): Merge the content of acquisition into this url. :param acquisition: The url to merge with the present url. - :rtype acquisition: Url + :type acquisition: Url """ self._merge_privacy(acquisition) @@ -186,7 +186,7 @@ class Url(SecondaryObject, PrivacyBase): return self.type def are_equal(self, other): - """Deprecated - use is_equal instead.""" + """Deprecated - use :meth:`~.SecondaryObject.is_equal` instead.""" warn( "Use is_equal instead of are_equal", DeprecationWarning, 2) return self.is_equal(other) @@ -195,14 +195,16 @@ class Url(SecondaryObject, PrivacyBase): """ Returns a 6 tuple-based object with the following items: + ======== === ================================= Property Pos Meaning - -------- --- --------------------------------- + ======== === ================================= scheme 0 URL scheme specifier netloc 1 Network location part path 2 Hierarchical path params 3 Parameters for last path element query 4 Query component fragment 5 Fragment identifier + ======== === ================================= """ return urlparse(self.path) diff --git a/gramps/gen/lib/urlbase.py b/gramps/gen/lib/urlbase.py index 2b1533a49..fc7f29157 100644 --- a/gramps/gen/lib/urlbase.py +++ b/gramps/gen/lib/urlbase.py @@ -21,7 +21,7 @@ # $Id$ """ -UrlBase class for GRAMPS. +UrlBase class for Gramps. """ #------------------------------------------------------------------------- @@ -99,18 +99,19 @@ class UrlBase(object): def get_url_list(self): """ - Return the list of :class:`~gen.lib.url.Url` instances associated with the object. + Return the list of :class:`~.url.Url` instances associated with the + object. - :returns: List of :class:`~gen.lib.url.Url` instances + :returns: List of :class:`~.url.Url` instances :rtype: list """ return self.urls def set_url_list(self, url_list): """ - Set the list of :class:`~gen.lib.url.Url` instances to passed the list. + Set the list of :class:`~.url.Url` instances to passed the list. - :param url_list: List of :class:`~gen.lib.url.Url` instances + :param url_list: List of :class:`~.url.Url` instances :type url_list: list """ self.urls = url_list @@ -120,8 +121,8 @@ class UrlBase(object): Merge the list of urls from acquisition with our own. :param acquisition: The url list of this object will be merged with - the current url list. - :rtype acquisition: UrlBase + the current url list. + :type acquisition: UrlBase """ url_list = self.urls[:] for addendum in acquisition.get_url_list(): @@ -137,22 +138,23 @@ class UrlBase(object): def add_url(self, url): """ - Add a :class:`~gen.lib.url.Url` instance to the object's list of :class:`~gen.lib.url.Url` instances. + Add a :class:`~.url.Url` instance to the object's list of + :class:`~.url.Url` instances. - :param url: :class:`~gen.lib.url.Url` instance to be added to the Person's list of - related web sites. - :type url: :class:`~gen.lib.url.Url` + :param url: :class:`~.url.Url` instance to be added to the Person's + list of related web sites. + :type url: :class:`~.url.Url` """ self.urls.append(url) def remove_url(self, url): """ - Remove the specified :class:`~gen.lib.url.Url` instance from the url list. + Remove the specified :class:`~.url.Url` instance from the url list. If the instance does not exist in the list, the operation has no effect. - :param url: :class:`~gen.lib.url.Url` instance to remove from the list - :type url: :class:`~gen.lib.url.Url` + :param url: :class:`~.url.Url` instance to remove from the list + :type url: :class:`~.url.Url` :returns: True if the url was removed, False if it was not in the list. :rtype: bool