diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..420baaf4e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,88 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf _build/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html + @echo + @echo "Build finished. The HTML pages are in _build/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml + @echo + @echo "Build finished. The HTML pages are in _build/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in _build/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in _build/qthelp, like this:" + @echo "# qcollectiongenerator _build/qthelp/Gramps.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile _build/qthelp/Gramps.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo + @echo "Build finished; the LaTeX files are in _build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes + @echo + @echo "The overview file is in _build/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in _build/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in _build/doctest/output.txt." diff --git a/docs/README.txt b/docs/README.txt new file mode 100644 index 000000000..daa192a6c --- /dev/null +++ b/docs/README.txt @@ -0,0 +1,72 @@ +Installation and building the docs +================================== + +You need to install sphinx. Assuming you have installed the python setuptools, just do: + + sudo easy_install sphinx + +Once installed, go to the docs directory, and do: + + make html + +Which will produce the html output in docs/_build/html + + +Documention Guidelines +======================= + +Doc strings in python files should be written in reStructured text: http://docutils.sourceforge.net/docs/user/rst/quickref.html + +The typical docstring for GRAMPS should look like this: + +"""Brief synopsis + +This is a longer explanation, which may include *italics* or **bold**, or +a link to another method :meth:`~gen.lib.person.Person.get_handle` +Then, you need to provide optional subsection in this order (just to be +consistent and have a uniform documentation, nothing prevent you to switch +the order). + +:param arg1: the first value +:type arg1: int or float or :class:`~gen.lib.baseobj.BaseObject` +:param arg2: the second value +:type arg2: int or float +:param arg3: the third value + +:returns: arg1/arg2 +arg3 +:rtype: float, this is the return type + + +:Examples: + +>>> import template +>>> a = MainClass() +>>> a.function2(1,1,1) +2 + +:note: + can be useful to emphasize + important feature + +:See Also: + :class:`MainClass1` + +:Warnings: + arg2 must be non-zero. + +:Todo: + check that arg2 is non zero. +""" + +For a class, use :cvar variable: for class variaable, :ivar variable: for instance class +variable, .. attribute:: attribute: for attributes, .... +See http://sphinx.pocoo.org/markup/desc.html and http://sphinx.pocoo.org/markup/inline.html + +Tips and Tricks +=============== +Change in many files something: + +perl -pi -w -e "s/L{PersonRef}/:class:\`\~gen.lib.personref.PersonRef\`/g;" *.py + +here L{PersonRef} is changed in :class:`~gen.lib.personref.PersonRef +` \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 000000000..dcaeaa141 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,42 @@ +################## +Code Documentation +################## + +*GRAMPS* provides several general API. The most important is the *gen* module, providing access to all code that can be of interest outside of the GRAMPS program. + +The :mod:`gen` Module +======================= + +.. automodule:: gen + +Contents: + +.. toctree:: + :maxdepth: 2 + + gen/gen_lib + gen/gen_db + gen/gen_proxy + gen/gen_utils + +The GRAMPS Application +======================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + corecli/cli + coregui/gui + utils + +Usefull snippets +=================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + html diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..aaf713684 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,202 @@ +# -*- coding: utf-8 -*- +# +# Gramps documentation build configuration file, created by +# sphinx-quickstart on Sat Jun 20 00:07:37 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +#documentation in root/docs, allow import from root/src where GRAMPS modules life +sourcedir = (os.path.abspath('.')).split(os.sep)[:-1] + ['src'] +sys.path.append((os.sep).join(sourcedir)) +#make it possible to add plugins --> walk the plugin dir and add to sys.path.append +for (dirpath, dirnames, filenames) in os.walk((os.sep).join(sourcedir + ['plugins'])): + # add the directory to the python search path + sys.path.append(dirpath) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Gramps' +copyright = u'2009, The Gramps Project' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '3.2' +# The full version, including alpha/beta/rc tags. +release = '3.2.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Grampsdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Gramps.tex', u'Gramps Documentation', + u'The Gramps Project', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/docs/corecli/cli.rst b/docs/corecli/cli.rst new file mode 100644 index 000000000..a27fe167f --- /dev/null +++ b/docs/corecli/cli.rst @@ -0,0 +1,4 @@ +The :mod:`cli` Module +===================== + +Todo diff --git a/docs/coregui/gui.rst b/docs/coregui/gui.rst new file mode 100644 index 000000000..a10d45b5e --- /dev/null +++ b/docs/coregui/gui.rst @@ -0,0 +1,4 @@ +The :mod:`gui` Module +===================== + +Todo diff --git a/docs/developer_guide.rst b/docs/developer_guide.rst new file mode 100644 index 000000000..c93ac6631 --- /dev/null +++ b/docs/developer_guide.rst @@ -0,0 +1,4 @@ +Developer Guide +=============== + +Please consult the API documentation, and the development part of `our wiki `_\ . diff --git a/docs/gen/gen_db.rst b/docs/gen/gen_db.rst new file mode 100644 index 000000000..5feb19210 --- /dev/null +++ b/docs/gen/gen_db.rst @@ -0,0 +1,9 @@ +########################## +The :mod:`gen.db` Module +########################## + +Contents: + +.. automodule:: gen.db + +**TODO** diff --git a/docs/gen/gen_lib.rst b/docs/gen/gen_lib.rst new file mode 100644 index 000000000..cec709dd8 --- /dev/null +++ b/docs/gen/gen_lib.rst @@ -0,0 +1,483 @@ +########################## +The :mod:`gen.lib` Module +########################## + +Contents: + +.. automodule:: gen.lib + +***************************** +Base objects +***************************** + +BaseObject +==================================== +.. automodule:: gen.lib.baseobj +.. autoclass:: gen.lib.baseobj.BaseObject + :members: + :undoc-members: + :show-inheritance: + +RefBase +==================================== +.. automodule:: gen.lib.refbase +.. autoclass:: RefBase + :members: + :undoc-members: + :show-inheritance: + +PrivacyBase +==================================== +.. automodule:: gen.lib.privacybase +.. autoclass:: PrivacyBase + :members: + :undoc-members: + :show-inheritance: + + +SourceBase +==================================== +.. automodule:: gen.lib.srcbase +.. autoclass:: SourceBase + :members: + :undoc-members: + :show-inheritance: + + +NoteBase +==================================== +.. automodule:: gen.lib.notebase +.. autoclass:: NoteBase + :members: + :undoc-members: + :show-inheritance: + +MediaBase +==================================== +.. automodule:: gen.lib.mediabase +.. autoclass:: MediaBase + :members: + :undoc-members: + :show-inheritance: + +PlaceBase +==================================== +.. automodule:: gen.lib.placebase +.. autoclass:: PlaceBase + :members: + :undoc-members: + :show-inheritance: + + +LocationBase +==================================== +.. automodule:: gen.lib.locationbase +.. autoclass:: LocationBase + :members: + :undoc-members: + :show-inheritance: + + +AddressBase +==================================== +.. automodule:: gen.lib.addressbase +.. autoclass:: AddressBase + :members: + :undoc-members: + :show-inheritance: + + +AttributeBase +==================================== +.. automodule:: gen.lib.attrbase +.. autoclass:: AttributeBase + :members: + :undoc-members: + :show-inheritance: + +DateBase +==================================== +.. automodule:: gen.lib.datebase +.. autoclass:: DateBase + :members: + :undoc-members: + :show-inheritance: + + + +UrlBase +==================================== +.. automodule:: gen.lib.urlbase +.. autoclass:: UrlBase + :members: + :undoc-members: + :show-inheritance: + +***************************** +Primary objects +***************************** + +BasicPrimaryObject +==================================== +.. automodule:: gen.lib.primaryobj +.. autoclass:: BasicPrimaryObject + :members: + :undoc-members: + :show-inheritance: + +PrimaryObject +==================================== +.. autoclass:: PrimaryObject + :members: + :undoc-members: + :show-inheritance: + +Person +==================================== +.. automodule:: gen.lib.person +.. autoclass:: Person + :members: + :undoc-members: + :show-inheritance: + + +Family +==================================== +.. automodule:: gen.lib.family +.. autoclass:: Family + :members: + :undoc-members: + :show-inheritance: + + +Event +==================================== +.. automodule:: gen.lib.event +.. autoclass:: Event + :members: + :undoc-members: + :show-inheritance: + +Place +==================================== +.. automodule:: gen.lib.place +.. autoclass:: Place + :members: + :undoc-members: + :show-inheritance: + + +Source +==================================== +.. automodule:: gen.lib.src +.. autoclass:: Source + :members: + :undoc-members: + :show-inheritance: + + +Media Object +==================================== +.. automodule:: gen.lib.mediaobj +.. autoclass:: MediaObject + :members: + :undoc-members: + :show-inheritance: + + +Repository +==================================== +.. automodule:: gen.lib.repo +.. autoclass:: Repository + :members: + :undoc-members: + :show-inheritance: + +Note +==================================== +.. automodule:: gen.lib.note +.. autoclass:: Note + :members: + :undoc-members: + :show-inheritance: + +***************************** +Secondary objects +***************************** + +Secondary Object +==================================== +.. automodule:: gen.lib.secondaryobj +.. autoclass:: SecondaryObject + :members: + :undoc-members: + :show-inheritance: + + +Address +==================================== +.. automodule:: gen.lib.address +.. autoclass:: Address + :members: + :undoc-members: + :show-inheritance: + +Location +==================================== +.. automodule:: gen.lib.location +.. autoclass:: Location + :members: + :undoc-members: + :show-inheritance: + +Attribute +==================================== +.. automodule:: gen.lib.attribute +.. autoclass:: Attribute + :members: + :undoc-members: + :show-inheritance: + +LdsOrd +==================================== +.. automodule:: gen.lib.ldsord +.. autoclass:: LdsOrd + :members: + :undoc-members: + :show-inheritance: + +Name +==================================== +.. automodule:: gen.lib.name +.. autoclass:: Name + :members: + :undoc-members: + :show-inheritance: + +Url +==================================== +.. automodule:: gen.lib.url +.. autoclass:: Url + :members: + :undoc-members: + :show-inheritance: + + +***************************** +Reference objects +***************************** + +PersonRef +==================================== +.. automodule:: gen.lib.personref +.. autoclass:: PersonRef + :members: + :undoc-members: + :show-inheritance: + +ChildRef +==================================== +.. automodule:: gen.lib.childref +.. autoclass:: ChildRef + :members: + :undoc-members: + :show-inheritance: + +EventRef +==================================== +.. automodule:: gen.lib.eventref +.. autoclass:: EventRef + :members: + :undoc-members: + :show-inheritance: + +MediaRef +==================================== +.. automodule:: gen.lib.mediaref +.. autoclass:: MediaRef + :members: + :undoc-members: + :show-inheritance: + +SourceRef +==================================== +.. automodule:: gen.lib.srcref +.. autoclass:: SourceRef + :members: + :undoc-members: + :show-inheritance: + +RepoRef +==================================== +.. automodule:: gen.lib.reporef +.. autoclass:: RepoRef + :members: + :undoc-members: + :show-inheritance: + +***************************** +Date objects +***************************** +.. automodule:: gen.lib.date + +Date +==================================== +.. autoclass:: Date + :members: + :undoc-members: + :show-inheritance: + +Span +==================================== +.. autoclass:: Span + :members: + :undoc-members: + :show-inheritance: + +DateError +==================================== +.. autoexception:: DateError + +***************************** +Text objects +***************************** + +StyledTextTag +=================== +.. automodule:: gen.lib.styledtexttag +.. autoclass:: StyledTextTag + :members: + :undoc-members: + :show-inheritance: + +StyledText +=========== +.. automodule:: gen.lib.styledtext +.. autoclass:: StyledText + :members: + :undoc-members: + :show-inheritance: + +***************************** +Meta data +***************************** + +GenderStats +============ + +.. automodule:: gen.lib.genderstats +.. autoclass:: GenderStats + :members: + :undoc-members: + :show-inheritance: + +Researcher +=========== +.. automodule:: gen.lib.researcher +.. autoclass:: Researcher + :members: + :undoc-members: + :show-inheritance: + +***************************** +Type classes +***************************** +.. automodule:: gen.lib.grampstype +.. autoclass:: GrampsTypeMeta + :members: + :undoc-members: + :show-inheritance: + +GrampsType +=========== +.. autoclass:: GrampsType + :members: + :undoc-members: + :show-inheritance: + +NameType +=========== +.. automodule:: gen.lib.nametype + :members: + :undoc-members: + :show-inheritance: + +AttributeType +============= +.. automodule:: gen.lib.attrtype + :members: + :undoc-members: + :show-inheritance: + +UrlType +======== +.. automodule:: gen.lib.urltype + :members: + :undoc-members: + :show-inheritance: + +ChildRefType +============= +.. automodule:: gen.lib.childreftype + :members: + :undoc-members: + :show-inheritance: + +RepositoryType +============== +.. automodule:: gen.lib.repotype + :members: + :undoc-members: + :show-inheritance: + +EventType +=========== +.. automodule:: gen.lib.eventtype +.. autoclass:: EventType + :members: + :undoc-members: + :show-inheritance: + +FamilyRelType +============= +.. automodule:: gen.lib.familyreltype + :members: + :undoc-members: + :show-inheritance: + +SourceMediaType +================ +.. automodule:: gen.lib.srcmediatype + :members: + :undoc-members: + :show-inheritance: + +EventRoleType +============== +.. automodule:: gen.lib.eventroletype + :members: + :undoc-members: + :show-inheritance: + +MarkerType +========== +.. automodule:: gen.lib.markertype + :members: + :undoc-members: + :show-inheritance: + +NoteType +========= +.. automodule:: gen.lib.notetype + :members: + :undoc-members: + :show-inheritance: + +StyledTextTagType +================== +.. automodule:: gen.lib.styledtexttagtype + :members: + :undoc-members: + :show-inheritance: + + diff --git a/docs/gen/gen_proxy.rst b/docs/gen/gen_proxy.rst new file mode 100644 index 000000000..52fbefd59 --- /dev/null +++ b/docs/gen/gen_proxy.rst @@ -0,0 +1,9 @@ +############################ +The :mod:`gen.proxy` Module +############################ + +Contents: + +.. automodule:: gen.proxy + +**TODO** diff --git a/docs/gen/gen_utils.rst b/docs/gen/gen_utils.rst new file mode 100644 index 000000000..93e9aec3d --- /dev/null +++ b/docs/gen/gen_utils.rst @@ -0,0 +1,9 @@ +############################ +The :mod:`gen.utils` Module +############################ + +Contents: + +.. automodule:: gen.utils + +**TODO** diff --git a/docs/html.rst b/docs/html.rst new file mode 100644 index 000000000..db500ad82 --- /dev/null +++ b/docs/html.rst @@ -0,0 +1,11 @@ +########################## +The :class:`Html` Class +########################## + +Contents: + +.. automodule:: libhtml +.. autoclass:: Html + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..98d304e65 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,24 @@ +.. Gramps documentation master file, created by + sphinx-quickstart on Sat Jun 20 00:07:37 2009. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Gramps's documentation! +================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + user_guide + developer_guide + api + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/user_guide.rst b/docs/user_guide.rst new file mode 100644 index 000000000..9a2eda0e7 --- /dev/null +++ b/docs/user_guide.rst @@ -0,0 +1,4 @@ +User Guide +========== + +Please consult the manual which you find on `our wiki `_\ . \ No newline at end of file diff --git a/docs/utils.rst b/docs/utils.rst new file mode 100644 index 000000000..ec83fbece --- /dev/null +++ b/docs/utils.rst @@ -0,0 +1,12 @@ +############################ +The :mod:`Utils` Module +############################ + +Contents: + +.. automodule:: Utils + :members: + :undoc-members: + :show-inheritance: + + diff --git a/src/AutoComp.py b/src/AutoComp.py index 1ecdb742b..a6c1d8b1d 100644 --- a/src/AutoComp.py +++ b/src/AutoComp.py @@ -111,14 +111,14 @@ class StandardCustomSelector(object): """ Constructor for the StandardCustomSelector class. - @param cbe: Existing ComboBoxEntry widget to use. - @type cbe: gtk.ComboBoxEntry - @param mapping: The mapping between integer and string constants. - @type mapping: dict - @param custom_key: The key corresponding to the custom string entry - @type custom_key: int - @param active_key: The key for the entry to make active upon creation - @type active_key: int + :param cbe: Existing ComboBoxEntry widget to use. + :type cbe: gtk.ComboBoxEntry + :param mapping: The mapping between integer and string constants. + :type mapping: dict + :param custom_key: The key corresponding to the custom string entry + :type custom_key: int + :param active_key: The key for the entry to make active upon creation + :type active_key: int """ # set variables @@ -190,8 +190,8 @@ class StandardCustomSelector(object): """ Get selected values. - @return: Returns (int,str) tuple corresponding to the selection. - @rtype: tuple + :returns: Returns (int,str) tuple corresponding to the selection. + :rtype: tuple """ active_iter = self.selector.get_active_iter() if active_iter: @@ -215,8 +215,8 @@ class StandardCustomSelector(object): """ Set values according to given tuple. - @param val: (int,str) tuple with the values to set. - @type val: tuple + :param val: (int,str) tuple with the values to set. + :type val: tuple """ key, text = val if key in self.mapping and key != self.custom_key: diff --git a/src/DataViews/PlaceView.py b/src/DataViews/PlaceView.py index e2b7aa54f..bbff7dd35 100644 --- a/src/DataViews/PlaceView.py +++ b/src/DataViews/PlaceView.py @@ -178,6 +178,10 @@ class PlaceView(PageView.ListView): self.mapslistlabel.append(lbl) widget.set_label_widget(self.mapslistlabel[-1]) widget.set_stock_id(gtk.STOCK_JUMP_TO) + if self.drag_info(): + self.list.enable_model_drag_source(gtk.gdk.BUTTON1_MASK, + [('text/plain', 0, 0), self.drag_info().target()], + gtk.gdk.ACTION_COPY) def __create_maps_menu_actions(self): """ diff --git a/src/ExportAssistant.py b/src/ExportAssistant.py index ce08b90f7..e9b21bee8 100644 --- a/src/ExportAssistant.py +++ b/src/ExportAssistant.py @@ -392,7 +392,7 @@ class ExportAssistant(gtk.Assistant, ManagedWindow.ManagedWindow) : The "prepare" signal is emitted when a new page is set as the assistant's current page, but before making the new page visible. - @param page: the new page to prepare for display. + :param page: the new page to prepare for display. """ #determine if we go backward or forward diff --git a/src/ImgManip.py b/src/ImgManip.py index e209e347a..437c4a351 100644 --- a/src/ImgManip.py +++ b/src/ImgManip.py @@ -50,14 +50,14 @@ def resize_to_jpeg(source, destination, width, height): Create the destination, derived from the source, resizing it to the specified size, while converting to JPEG. - @param source: source image file, in any format that gtk recognizes - @type source: unicode - @param destination: destination image file, output written in jpeg format - @type destination: unicode - @param width: desired width of the destination image - @type width: int - @param height: desired height of the destination image - @type height: int + :param source: source image file, in any format that gtk recognizes + :type source: unicode + :param destination: destination image file, output written in jpeg format + :type destination: unicode + :param width: desired width of the destination image + :type width: int + :param height: desired height of the destination image + :type height: int """ img = gtk.gdk.pixbuf_new_from_file(source) scaled = img.scale_simple(width, height, gtk.gdk.INTERP_BILINEAR) @@ -72,10 +72,10 @@ def image_size(source): """ Return the width and size of the specified image. - @param source: source image file, in any format that gtk recongizes - @type source: unicode - @rtype: tuple(int, int) - @returns: a tuple consisting of the width and height + :param source: source image file, in any format that gtk recongizes + :type source: unicode + :rtype: tuple(int, int) + :returns: a tuple consisting of the width and height """ try: img = gtk.gdk.pixbuf_new_from_file(source) @@ -96,14 +96,14 @@ def resize_to_jpeg_buffer(source, width, height): Loads the image, converting the file to JPEG, and resizing it. Instead of saving the file, the data is returned in a buffer. - @param source: source image file, in any format that gtk recognizes - @type source: unicode - @param width: desired width of the destination image - @type width: int - @param height: desired height of the destination image - @type height: int - @rtype: buffer of data - @returns: jpeg image as raw data + :param source: source image file, in any format that gtk recognizes + :type source: unicode + :param width: desired width of the destination image + :type width: int + :param height: desired height of the destination image + :type height: int + :rtype: buffer of data + :returns: jpeg image as raw data """ filed, dest = tempfile.mkstemp() img = gtk.gdk.pixbuf_new_from_file(source) diff --git a/src/ManagedWindow.py b/src/ManagedWindow.py index f5de4409e..92d360236 100644 --- a/src/ManagedWindow.py +++ b/src/ManagedWindow.py @@ -336,10 +336,10 @@ class ManagedWindow(object): # Proceed with the class. ... - @param uistate gramps uistate - @param track {list of parent windows, [] if the main GRAMPS window + :param uistate: gramps uistate + :param track: {list of parent windows, [] if the main GRAMPS window is the parent} - @param obj The object that is used to id the managed window, + :param obj: The object that is used to id the managed window, The inheriting object needs a method build_menu_names(self, obj) which works on this obj and creates menu labels for use in the Gramps Window Menu. @@ -389,11 +389,11 @@ class ManagedWindow(object): """ Set the window that is managed. - @param window if isWindow=False window must be a gtk.Window() object, otherwise None - @param title a label widget in which to write the title, None if not needed - @param text text to use as title of window and in title param - @param msg if not None, use msg as title of window instead of text - @param isWindow {if isWindow than self is the window + :param window: if isWindow=False window must be a gtk.Window() object, otherwise None + :param title: a label widget in which to write the title, None if not needed + :param text: text to use as title of window and in title param + :param msg: if not None, use msg as title of window instead of text + :param isWindow: {if isWindow than self is the window (so self inherits from gtk.Window and from ManagedWindow.ManagedWindow) if not isWindow, than window is the Window to manage, diff --git a/src/ProgressDialog.py b/src/ProgressDialog.py index a10875d6c..72dbf3c09 100644 --- a/src/ProgressDialog.py +++ b/src/ProgressDialog.py @@ -11,8 +11,8 @@ class _GtkProgressBar(gtk.VBox): """ def __init__(self, long_op_status): - """@param long_op_status: the status of the operation. - @type long_op_status: L{gen.utils.LongOpStatus} + """:param long_op_status: the status of the operation. + :type long_op_status: L{gen.utils.LongOpStatus} """ gtk.VBox.__init__(self) @@ -75,8 +75,8 @@ class GtkProgressDialog(gtk.Dialog): process.""" def __init__(self, window_params, title): - """@param title: The title to display on the top of the window. - @type title: string + """:param title: The title to display on the top of the window. + :type title: string """ gtk.Dialog.__init__(self, *window_params) self.connect('delete_event', self._warn) @@ -90,11 +90,11 @@ class GtkProgressDialog(gtk.Dialog): def add(self, long_op_status): """Add a new status object to the progress dialog. - @param long_op_status: the status object. - @type long_op_status: L{gen.utils.LongOpStatus} - @return: a key that can be used as the L{pbar_idx} + :param long_op_status: the status object. + :type long_op_status: L{gen.utils.LongOpStatus} + :returns: a key that can be used as the L{pbar_idx} to the other methods. - @rtype: int + :rtype: int """ pbar = _GtkProgressBar(long_op_status) @@ -111,8 +111,8 @@ class GtkProgressDialog(gtk.Dialog): def remove(self, pbar_idx): """Remove the specified status object from the progress dialog. - @param pbar_idx: the index as returned from L{add} - @type pbar_idx: int + :param pbar_idx: the index as returned from L{add} + :type pbar_idx: int """ pbar = self._progress_bars[pbar_idx] self.vbox.remove(pbar) @@ -122,8 +122,8 @@ class GtkProgressDialog(gtk.Dialog): """Click the progress bar over to the next value. Be paranoid and insure that it doesn't go over 100%. - @param pbar_idx: the index as returned from L{add} - @type pbar_idx: int + :param pbar_idx: the index as returned from L{add} + :type pbar_idx: int """ if pbar_idx < len(self._progress_bars): self._progress_bars[pbar_idx].step() diff --git a/src/Relationship.py b/src/Relationship.py index f48b82471..64b3262e9 100644 --- a/src/Relationship.py +++ b/src/Relationship.py @@ -730,21 +730,21 @@ class RelationshipCalculator(object): reached via a different branch too. Path (firstRel_str and secondRel_str) will of course be different - @param db: database to work on - @param orig_person: first person - @type orig_person: Person Obj - @param other_person: second person, relation is sought between + :param db: database to work on + :param orig_person: first person + :type orig_person: Person Obj + :param other_person: second person, relation is sought between first and second person - @type other_person: Person Obj - @param all_families: if False only Main family is searched, otherwise + :type other_person: Person Obj + :param all_families: if False only Main family is searched, otherwise all families are used - @type all_families: bool - @param all_dist: if False only the shortest distance is returned, + :type all_families: bool + :param all_dist: if False only the shortest distance is returned, otherwise all relationships - @type all_dist: bool - @param only_birth: if True only parents with birth relation are + :type all_dist: bool + :param only_birth: if True only parents with birth relation are considered - @type only_birth: bool + :type only_birth: bool """ #data storage to communicate with recursive functions self.__maxDepthReached = False @@ -1376,15 +1376,15 @@ class RelationshipCalculator(object): See the Wikipedia entry for more information: http://en.wikipedia.org/wiki/Cousin#Mathematical_definitions - @param Ga: The number of generations between the main person and the + :param Ga: The number of generations between the main person and the common ancestor. - @type Ga: int - @param Gb: The number of generations between the group of people and the + :type Ga: int + :param Gb: The number of generations between the group of people and the common ancestor - @type Gb: int - @returns: A string describing the relationship between the person and + :type Gb: int + :returns: A string describing the relationship between the person and the group. - @rtype: str + :rtype: str """ rel_str = "distant relatives" if Ga == 0: @@ -1484,35 +1484,35 @@ class RelationshipCalculator(object): parents in that common family is by birth, then 'only_birth' is not set to False. The only_birth() method is normally used for this. - @param Ga: The number of generations between the main person and the + :param Ga: The number of generations between the main person and the common ancestor. - @type Ga: int - @param Gb: The number of generations between the other person and the + :type Ga: int + :param Gb: The number of generations between the other person and the common ancestor - @type Gb: int - @param gender_a : gender of person a - @type gender_a: int gender - @param gender_b : gender of person b - @type gender_b: int gender - @param reltocommon_a : relation path to common ancestor or common + :type Gb: int + :param gender_a : gender of person a + :type gender_a: int gender + :param gender_b : gender of person b + :type gender_b: int gender + :param reltocommon_a : relation path to common ancestor or common Family for person a. Note that length = Ga - @type reltocommon_a: str - @param reltocommon_b : relation path to common ancestor or common + :type reltocommon_a: str + :param reltocommon_b : relation path to common ancestor or common Family for person b. Note that length = Gb - @type reltocommon_b: str - @param in_law_a : True if path to common ancestors is via the partner + :type reltocommon_b: str + :param in_law_a : True if path to common ancestors is via the partner of person a - @type in_law_a: bool - @param in_law_b : True if path to common ancestors is via the partner + :type in_law_a: bool + :param in_law_b : True if path to common ancestors is via the partner of person b - @type in_law_b: bool - @param only_birth : True if relation between a and b is by birth only + :type in_law_b: bool + :param only_birth : True if relation between a and b is by birth only False otherwise - @type only_birth: bool - @returns: A string describing the relationship between the two people - @rtype: str + :type only_birth: bool + :returns: A string describing the relationship between the two people + :rtype: str NOTE: 1/the self.REL_SIBLING should not be passed to this routine, so we should not check on it. All other self. diff --git a/src/ThumbNails.py b/src/ThumbNails.py index 7ff4c45ae..158929540 100644 --- a/src/ThumbNails.py +++ b/src/ThumbNails.py @@ -72,10 +72,10 @@ def __get_gconf_string(key): Attempt to retrieve a value from the GNOME gconf database based of the passed key. - @param key: GCONF key - @type key: unicode - @returns: Value associated with the GCONF key - @rtype: unicode + :param key: GCONF key + :type key: unicode + :returns: Value associated with the GCONF key + :rtype: unicode """ try: val = CLIENT.get_string(key) @@ -93,10 +93,10 @@ def __get_gconf_bool(key): Attempt to retrieve a value from the GNOME gconf database based of the passed key. - @param key: GCONF key - @type key: unicode - @returns: Value associated with the GCONF key - @rtype: bool + :param key: GCONF key + :type key: unicode + :returns: Value associated with the GCONF key + :rtype: bool """ try: val = CLIENT.get_bool(key) @@ -116,12 +116,12 @@ def __build_thumb_path(path, rectangle=None): (which should be unique), adding the '.png' extension, and prepending with the GRAMPS thumbnail directory. - @type path: unicode - @param path: filename of the source file - @type rectangle: tuple - @param rectangle: subsection rectangle - @rtype: unicode - @returns: full path name to the corresponding thumbnail file. + :type path: unicode + :param path: filename of the source file + :type rectangle: tuple + :param rectangle: subsection rectangle + :rtype: unicode + :returns: full path name to the corresponding thumbnail file. """ extra = "" if rectangle is not None: @@ -141,12 +141,12 @@ def __create_thumbnail_image(src_file, mtype=None, rectangle=None): utility to create a thumbnail. For images, we simply create a smaller image, scaled to thumbnail size. - @param src_file: filename of the source file - @type src_file: unicode - @param mtype: mime type of the specified file (optional) - @type mtype: unicode - @param rectangle: subsection rectangle - @type rectangle: tuple + :param src_file: filename of the source file + :type src_file: unicode + :param mtype: mime type of the specified file (optional) + :type mtype: unicode + :param rectangle: subsection rectangle + :type rectangle: tuple """ filename = __build_thumb_path(src_file, rectangle) @@ -198,17 +198,17 @@ def run_thumbnailer(mime_type, src_file, dest_file, size=const.THUMBSCALE): only succeed if the GNOME environment is installed, since at this point, only the GNOME environment has the ability to generate thumbnails. - @param mime_type: mime type of the source file - @type mime_type: unicode - @param src_file: filename of the source file - @type src_file: unicode - @param dest_file: destination file for the thumbnail image - @type dest_file: unicode - @param size: option parameters specifying the desired size of the + :param mime_type: mime type of the source file + :type mime_type: unicode + :param src_file: filename of the source file + :type src_file: unicode + :param dest_file: destination file for the thumbnail image + :type dest_file: unicode + :param size: option parameters specifying the desired size of the thumbnail - @type size: int - @rtype: bool - @returns: True if the thumbnail was successfully generated + :type size: int + :rtype: bool + :returns: True if the thumbnail was successfully generated """ # only try this if GCONF is present, the thumbnailer has not been @@ -249,14 +249,14 @@ def get_thumbnail_image(src_file, mtype=None, rectangle=None): The image is not generated everytime, but only if the thumbnail does not exist, or if the source file is newer than the thumbnail. - @param src_file: Source media file - @type src_file: unicode - @param mime_type: mime type of the source file - @type mime_type: unicode - @param rectangle: subsection rectangle - @type rectangle: tuple - @returns: thumbnail representing the source file - @rtype: gtk.gdk.Pixbuf + :param src_file: Source media file + :type src_file: unicode + :param mime_type: mime type of the source file + :type mime_type: unicode + :param rectangle: subsection rectangle + :type rectangle: tuple + :returns: thumbnail representing the source file + :rtype: gtk.gdk.Pixbuf """ try: filename = get_thumbnail_path(src_file, mtype, rectangle) @@ -279,14 +279,14 @@ def get_thumbnail_path(src_file, mtype=None, rectangle=None): source file passed to the function. If the thumbnail does not exist, or if it is older than the source file, we create a new thumbnail image. - @param src_file: Source media file - @type src_file: unicode - @param mime_type: mime type of the source file - @type mime_type: unicode - @param rectangle: subsection rectangle - @type rectangle: tuple - @returns: thumbnail representing the source file - @rtype: gtk.gdk.Pixbuf + :param src_file: Source media file + :type src_file: unicode + :param mime_type: mime type of the source file + :type mime_type: unicode + :param rectangle: subsection rectangle + :type rectangle: tuple + :returns: thumbnail representing the source file + :rtype: gtk.gdk.Pixbuf """ filename = __build_thumb_path(src_file, rectangle) if not os.path.isfile(src_file): diff --git a/src/TransUtils.py b/src/TransUtils.py index 9782a5a11..058d47af1 100644 --- a/src/TransUtils.py +++ b/src/TransUtils.py @@ -35,12 +35,12 @@ def sgettext(msgid, sep='|'): the returned value is the portion of msgid following the last separator. Default separator is '|'. - @param msgid: The string to translated. - @type msgid: unicode - @param sep: The separator marking the context. - @type sep: unicode - @return: Translation or the original with context stripped. - @rtype: unicode + :param msgid: The string to translated. + :type msgid: unicode + :param sep: The separator marking the context. + :type sep: unicode + :returns: Translation or the original with context stripped. + :rtype: unicode """ msgval = gettext(msgid) @@ -58,17 +58,17 @@ def sngettext(singular, plural, n, sep='|'): the returned value is the portion of singular following the last separator. Default separator is '|'. - @param singular: The singular form of the string to be translated. + :param singular: The singular form of the string to be translated. may contain a context seperator - @type singular: unicode - @param plural: The plural form of the string to be translated. - @type plural: unicode - @param n: the amount for which to decide the translation - @type n: int - @param sep: The separator marking the context. - @type sep: unicode - @return: Translation or the original with context stripped. - @rtype: unicode + :type singular: unicode + :param plural: The plural form of the string to be translated. + :type plural: unicode + :param n: the amount for which to decide the translation + :type n: int + :param sep: The separator marking the context. + :type sep: unicode + :returns: Translation or the original with context stripped. + :rtype: unicode """ msgval = ngettext(singular, plural,n) diff --git a/src/Utils.py b/src/Utils.py index f91e1a8f0..5b40bfdbc 100644 --- a/src/Utils.py +++ b/src/Utils.py @@ -282,10 +282,10 @@ def get_unicode_path(path): """ Return the Unicode version of a path string. - @type path: str - @param path: The path to be converted to Unicode - @rtype: unicode - @return: The Unicode version of path. + :type path: str + :param path: The path to be converted to Unicode + :rtype: unicode + :returns: The Unicode version of path. """ if os.sys.platform == "win32": return unicode(path) @@ -380,9 +380,9 @@ def probably_alive(person, db, current_date=None, limit=0): reason to believe that someone is dead then we assume they must be alive. - current_date - a date object that is not estimated or modified + :param current_date: a date object that is not estimated or modified (defaults to today) - limit - number of years to check beyond death_date + :param limit: number of years to check beyond death_date """ if current_date is None: current_date = gen.lib.Date() diff --git a/src/gen/__init__.py b/src/gen/__init__.py index 0cba99044..dd4efb2e7 100644 --- a/src/gen/__init__.py +++ b/src/gen/__init__.py @@ -18,4 +18,16 @@ # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # +""" +The gen module provides 5 packages. + 1. gen.lib gives access to all genealogy related objects, like family, + person, ... + 2. gen.db provides access to the bsddb backend storing genea data + 3. gen.proxy provides access to the data via a proxy that filters out + specific data + 4. gen.plug defines a plugin system so plugins can be written that can + work on the data. This can be in CLI or GUI + 5. gen.utils provides some generic utilities +""" + __all__ = [ "proxy", "db", "lib", "utils", "plug" ] diff --git a/src/gen/lib/address.py b/src/gen/lib/address.py index 33614375d..ec2604643 100644 --- a/src/gen/lib/address.py +++ b/src/gen/lib/address.py @@ -82,8 +82,8 @@ class Address(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase, """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return LocationBase.get_text_data_list(self) @@ -91,8 +91,8 @@ class Address(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.source_list @@ -100,8 +100,8 @@ class Address(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :returns: Returns the list of child secondary child objects that may refer notes. + :rtype: list """ return self.source_list @@ -110,8 +110,8 @@ class Address(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase, Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects referencing primary objects. - @rtype: list + :returns: Returns the list of objects referencing primary objects. + :rtype: list """ return self.source_list @@ -120,7 +120,7 @@ class Address(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() diff --git a/src/gen/lib/addressbase.py b/src/gen/lib/addressbase.py index 3d6476385..74b561eaa 100644 --- a/src/gen/lib/addressbase.py +++ b/src/gen/lib/addressbase.py @@ -48,8 +48,8 @@ class AddressBase(object): If the source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: AddressBase + :param source: Object used to initialize the new object + :type source: AddressBase """ if source: self.address_list = [Address(addr) for addr in source.address_list] @@ -70,25 +70,25 @@ class AddressBase(object): def add_address(self, address): """ - Add the L{Address} instance to the object's list of addresses. + Add the :class:`~gen.lib.address.Address` instance to the object's list of addresses. - @param address: L{Address} instance to add to the object's address list - @type address: list + :param address: :class:`~gen.lib.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 L{Address} instance from the address list. + Remove the specified :class:`~gen.lib.address.Address` instance from the address list. If the instance does not exist in the list, the operation has no effect. - @param address: L{Address} instance to remove from the list - @type address: L{Address} + :param address: :class:`~gen.lib.address.Address` instance to remove from the list + :type address: :class:`~gen.lib.address.Address` - @return: True if the address was removed, False if it was not in the list. - @rtype: bool + :returns: True if the address was removed, False if it was not in the list. + :rtype: bool """ if address in self.address_list: self.address_list.remove(address) @@ -98,19 +98,19 @@ class AddressBase(object): def get_address_list(self): """ - Return the list of L{Address} instances associated with the object. + Return the list of :class:`~gen.lib.address.Address` instances associated with the object. - @return: Returns the list of L{Address} instances - @rtype: list + :returns: Returns the list of :class:`~gen.lib.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 L{Address} instances. + Assign the passed list to the object's list of :class:`~gen.lib.address.Address` instances. - @param address_list: List of L{Address} instances to be associated + :param address_list: List of :class:`~gen.lib.address.Address` instances to be associated with the object - @type address_list: list + :type address_list: list """ self.address_list = address_list diff --git a/src/gen/lib/attrbase.py b/src/gen/lib/attrbase.py index 4b006bb35..c7cb06a67 100644 --- a/src/gen/lib/attrbase.py +++ b/src/gen/lib/attrbase.py @@ -48,8 +48,8 @@ class AttributeBase(object): If the source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: AttributeBase + :param source: Object used to initialize the new object + :type source: AttributeBase """ if source: self.attribute_list = [ Attribute(attribute) \ @@ -71,27 +71,27 @@ class AttributeBase(object): def add_attribute(self, attribute): """ - Add the L{Attribute} instance to the object's list of attributes. + Add the :class:`~gen.lib.attribute.Attribute` instance to the object's list of attributes. - @param attribute: L{Attribute} instance to add. - @type attribute: L{Attribute} + :param attribute: :class:`~gen.lib.attribute.Attribute` instance to add. + :type attribute: :class:`~gen.lib.attribute.Attribute` """ assert not isinstance(attribute, unicode) self.attribute_list.append(attribute) def remove_attribute(self, attribute): """ - Remove the specified L{Attribute} instance from the attribute list. + Remove the specified :class:`~gen.lib.attribute.Attribute` instance from the attribute list. If the instance does not exist in the list, the operation has no effect. - @param attribute: L{Attribute} instance to remove from the list - @type attribute: L{Attribute} + :param attribute: :class:`~gen.lib.attribute.Attribute` instance to remove from the list + :type attribute: :class:`~gen.lib.attribute.Attribute` - @return: True if the attribute was removed, False if it was not + :returns: True if the attribute was removed, False if it was not in the list. - @rtype: bool + :rtype: bool """ if attribute in self.attribute_list: self.attribute_list.remove(attribute) @@ -101,19 +101,19 @@ class AttributeBase(object): def get_attribute_list(self): """ - Return the list of L{Attribute} instances associated with the object. + Return the list of :class:`~gen.lib.attribute.Attribute` instances associated with the object. - @returns: Returns the list of L{Attribute} instances. - @rtype: list + :returns: Returns the list of :class:`~gen.lib.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 L{Attribute} instances. + Assign the passed list to the Person's list of :class:`~gen.lib.attribute.Attribute` instances. - @param attribute_list: List of L{Attribute} instances to ba associated + :param attribute_list: List of :class:`~gen.lib.attribute.Attribute` instances to ba associated with the Person - @type attribute_list: list + :type attribute_list: list """ self.attribute_list = attribute_list diff --git a/src/gen/lib/attribute.py b/src/gen/lib/attribute.py index 4de7cde04..fa51855d5 100644 --- a/src/gen/lib/attribute.py +++ b/src/gen/lib/attribute.py @@ -86,8 +86,8 @@ class Attribute(SecondaryObject, PrivacyBase, SourceBase, NoteBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.value] @@ -95,8 +95,8 @@ class Attribute(SecondaryObject, PrivacyBase, SourceBase, NoteBase): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.source_list @@ -104,9 +104,9 @@ class Attribute(SecondaryObject, PrivacyBase, SourceBase, NoteBase): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.source_list @@ -115,8 +115,8 @@ class Attribute(SecondaryObject, PrivacyBase, SourceBase, NoteBase): Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects referencing primary objects. - @rtype: list + :returns: Returns the list of objects referencing primary objects. + :rtype: list """ return self.source_list @@ -125,8 +125,8 @@ class Attribute(SecondaryObject, PrivacyBase, SourceBase, NoteBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() diff --git a/src/gen/lib/baseobj.py b/src/gen/lib/baseobj.py index 97d362de9..573744643 100644 --- a/src/gen/lib/baseobj.py +++ b/src/gen/lib/baseobj.py @@ -63,12 +63,12 @@ class BaseObject(object): Return True if any text data in the object or any of it's child objects matches a given pattern. - @param pattern: The pattern to match. - @type pattern: str - @param case_sensitive: Whether the match is case-sensitive. - @type case_sensitive: bool - @return: Returns whether any text data in the object or any of it's child objects matches a given pattern. - @rtype: bool + :param pattern: The pattern to match. + :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. + :rtype: bool """ # Run through its own items patern_upper = pattern.upper() @@ -97,10 +97,10 @@ class BaseObject(object): Return True if any text data in the object or any of it's child objects matches a given regular expression. - @param pattern: The pattern to match. - @type pattern: str - @return: Returns whether any text data in the object or any of it's child objects matches a given regexp. - @rtype: bool + :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. + :rtype: bool """ # Run through its own items @@ -123,8 +123,8 @@ class BaseObject(object): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [] @@ -132,8 +132,8 @@ class BaseObject(object): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return [] @@ -142,8 +142,8 @@ class BaseObject(object): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: Returns the list of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: Returns the list of (classname, handle) tuples for referenced objects. + :rtype: list """ return [] @@ -152,8 +152,8 @@ class BaseObject(object): Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return [] @@ -162,8 +162,8 @@ class BaseObject(object): Return the list of (classname, handle) tuples for all referenced primary objects, whether directly or through child objects. - @return: Returns the list of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: Returns the list of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_handles() diff --git a/src/gen/lib/childref.py b/src/gen/lib/childref.py index 98662268a..ee649a5e8 100644 --- a/src/gen/lib/childref.py +++ b/src/gen/lib/childref.py @@ -91,8 +91,8 @@ class ChildRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [str(self.frel), str(self.mrel)] @@ -100,8 +100,8 @@ class ChildRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.source_list @@ -109,9 +109,9 @@ class ChildRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.source_list @@ -120,8 +120,8 @@ class ChildRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.ref: @@ -133,8 +133,8 @@ class ChildRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): Return the list of child objects which may, directly or through their children, reference primary objects.. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.source_list diff --git a/src/gen/lib/datebase.py b/src/gen/lib/datebase.py index 7ab00cc0a..0cc79fea5 100644 --- a/src/gen/lib/datebase.py +++ b/src/gen/lib/datebase.py @@ -45,8 +45,8 @@ class DateBase(object): """ Create a new DateBase, copying from source if not None. - @param source: Object used to initialize the new object - @type source: DateBase + :param source: Object used to initialize the new object + :type source: DateBase """ if source: self.date = Date(source.date) @@ -73,10 +73,10 @@ class DateBase(object): def get_date_object(self): """ - Return the L{Date} object associated with the DateBase. + Return the :class:`~gen.lib.date.Date` object associated with the DateBase. - @return: Returns a DateBase L{Date} instance. - @rtype: L{Date} + :returns: Returns a DateBase :class:`~gen.lib.date.Date` instance. + :rtype: :class:`~gen.lib.date.Date` """ if not self.date: self.date = Date() @@ -84,9 +84,9 @@ class DateBase(object): def set_date_object(self, date): """ - Set the L{Date} object associated with the DateBase. + Set the :class:`~gen.lib.date.Date` object associated with the DateBase. - @param date: L{Date} instance to be assigned to the DateBase - @type date: L{Date} + :param date: :class:`~gen.lib.date.Date` instance to be assigned to the DateBase + :type date: :class:`~gen.lib.date.Date` """ self.date = date diff --git a/src/gen/lib/event.py b/src/gen/lib/event.py index 0e96b3cc9..9dd59b1e0 100644 --- a/src/gen/lib/event.py +++ b/src/gen/lib/event.py @@ -47,8 +47,6 @@ from gen.lib.markertype import MarkerType class Event(SourceBase, NoteBase, MediaBase, AttributeBase, DateBase, PlaceBase, PrimaryObject): """ - Introduction - ============ The Event record is used to store information about some type of action that occurred at a particular place at a particular time, such as a birth, death, or marriage. @@ -58,8 +56,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Create a new Event instance, copying from the source if present. - @param source: An event used to initialize the new event - @type source: Event + :param source: An event used to initialize the new event + :type source: Event """ PrimaryObject.__init__(self, source) @@ -91,9 +89,9 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, lists), the database is responsible for converting the data into a form that it can use. - @returns: Returns a python tuple containing the data that should + :returns: Returns a python tuple containing the data that should be considered persistent. - @rtype: tuple + :rtype: tuple """ return (self.handle, self.gramps_id, self.__type.serialize(), DateBase.serialize(self, no_text_date), @@ -109,9 +107,9 @@ class Event(SourceBase, 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 + :param data: tuple containing the persistent data associated the Person object - @type data: tuple + :type data: tuple """ (self.handle, self.gramps_id, the_type, date, self.__description, self.place, @@ -133,13 +131,13 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, Return True if the object has reference to a given handle of given primary object type. - @param classname: The name of the primary object class. - @type classname: str - @param handle: The handle to be checked. - @type handle: str - @return: Returns whether the object has reference to this handle of + :param classname: The name of the primary object class. + :type classname: str + :param handle: The handle to be checked. + :type handle: str + :returns: Returns whether the object has reference to this handle of this object type. - @rtype: bool + :rtype: bool """ if classname == 'Place': return self.place == handle @@ -149,10 +147,10 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Remove all references in this object to object handles in the list. - @param classname: The name of the primary object class. - @type classname: str - @param handle_list: The list of handles to be removed. - @type handle_list: str + :param classname: The name of the primary object class. + :type classname: str + :param handle_list: The list of handles to be removed. + :type handle_list: str """ if classname == 'Place' and self.place in handle_list: self.place = "" @@ -161,12 +159,12 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Replace all references to old handle with those to the new handle. - @param classname: The name of the primary object class. - @type classname: str - @param old_handle: The handle to be replaced. - @type old_handle: str - @param new_handle: The handle to replace the old one with. - @type new_handle: str + :param classname: The name of the primary object class. + :type classname: str + :param old_handle: The handle to be replaced. + :type old_handle: str + :param new_handle: The handle to replace the old one with. + :type new_handle: str """ if classname == 'Place' and self.place == old_handle: self.place = new_handle @@ -175,8 +173,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.__description, str(self.__type), self.gramps_id] @@ -184,8 +182,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.media_list + self.source_list + self.attribute_list @@ -193,9 +191,9 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return self.media_list + self.attribute_list @@ -203,9 +201,9 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.media_list + self.attribute_list + self.source_list @@ -214,8 +212,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.place: @@ -227,8 +225,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.get_sourcref_child_list() + self.source_list @@ -236,8 +234,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return True if the Event is an empty object (no values set). - @returns: True if the Event is empty - @rtype: bool + :returns: True if the Event is empty + :rtype: bool """ date = self.get_date_object() place = self.get_place_handle() @@ -250,10 +248,10 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return True if the passed Event is equivalent to the current Event. - @param other: Event to compare against - @type other: Event - @returns: True if the Events are equal - @rtype: bool + :param other: Event to compare against + :type other: Event + :returns: True if the Events are equal + :rtype: bool """ if other is None: other = Event (None) @@ -279,8 +277,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Set the type of the Event to the passed (int,str) tuple. - @param the_type: Type to assign to the Event - @type the_type: tuple + :param the_type: Type to assign to the Event + :type the_type: tuple """ self.__type.set(the_type) @@ -288,8 +286,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return the type of the Event. - @return: Type of the Event - @rtype: tuple + :returns: Type of the Event + :rtype: tuple """ return self.__type type = property(get_type, set_type, None, 'Returns or sets type of the event') @@ -300,8 +298,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, The string may contain any information. - @param description: Description to assign to the Event - @type description: str + :param description: Description to assign to the Event + :type description: str """ self.__description = description @@ -309,8 +307,8 @@ class Event(SourceBase, NoteBase, MediaBase, AttributeBase, """ Return the description of the Event. - @return: Returns the description of the Event - @rtype: str + :returns: Returns the description of the Event + :rtype: str """ return self.__description description = property(get_description, set_description, None, 'Returns or sets description of the event') diff --git a/src/gen/lib/eventref.py b/src/gen/lib/eventref.py index a12c8e8cc..9597e056f 100644 --- a/src/gen/lib/eventref.py +++ b/src/gen/lib/eventref.py @@ -91,8 +91,8 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.__role.string] @@ -100,8 +100,8 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.attribute_list @@ -109,9 +109,9 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return self.attribute_list @@ -119,9 +119,9 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.attribute_list @@ -130,9 +130,9 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: Returns the list of (classname, handle) tuples for referenced + :returns: Returns the list of (classname, handle) tuples for referenced objects. - @rtype: list + :rtype: list """ ret = self.get_referenced_note_handles() if self.ref: @@ -144,8 +144,8 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): Return the list of child objects which may, directly or through their children, reference primary objects.. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.get_sourcref_child_list() @@ -154,11 +154,11 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): Return True if any of the child objects has reference to this source handle. - @param src_handle: The source handle to be checked. - @type src_handle: str - @return: Returns whether any of it's child objects has reference to + :param src_handle: The source handle to be checked. + :type src_handle: str + :returns: Returns whether any of it's child objects has reference to this source handle. - @rtype: bool + :rtype: bool """ for item in self.get_sourcref_child_list(): if item.has_source_reference(src_handle): @@ -171,8 +171,8 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): Remove references to all source handles in the list in all child objects. - @param src_handle_list: The list of source handles to be removed. - @type src_handle_list: list + :param src_handle_list: The list of source handles to be removed. + :type src_handle_list: list """ for item in self.get_sourcref_child_list(): item.remove_source_references(src_handle_list) @@ -182,10 +182,10 @@ class EventRef(SecondaryObject, PrivacyBase, NoteBase, AttributeBase, RefBase): Replace references to source handles in the list in this object and all child objects. - @param old_handle: The source handle to be replaced. - @type old_handle: str - @param new_handle: The source handle to replace the old one with. - @type new_handle: str + :param old_handle: The source handle to be replaced. + :type old_handle: str + :param new_handle: The source handle to replace the old one with. + :type new_handle: str """ for item in self.get_sourcref_child_list(): item.replace_source_references(old_handle, new_handle) diff --git a/src/gen/lib/eventtype.py b/src/gen/lib/eventtype.py index 18d033c8f..6d29cb5d2 100644 --- a/src/gen/lib/eventtype.py +++ b/src/gen/lib/eventtype.py @@ -40,6 +40,53 @@ from gen.lib.grampstype import GrampsType class EventType(GrampsType): """ Event types. + + .. attribute UNKNOWN: Unknown + .. attribute CUSTOM: Custom + .. attribute ADOPT: Adopted + .. attribute BIRTH: Birth + .. attribute DEATH: Death + .. attribute ADULT_CHRISTEN: Adult Christening + .. attribute BAPTISM: Baptism + .. attribute BAR_MITZVAH: Bar Mitzvah + .. attribute BAS_MITZVAH: Bas Mitzvah + .. attribute BLESS: Blessing + .. attribute BURIAL: Burial + .. attribute CAUSE_DEATH: Cause Of Death + .. attribute CENSUS: Census + .. attribute CHRISTEN: Christening + .. attribute CONFIRMATION: Confirmation + .. attribute CREMATION: Cremation + .. attribute DEGREE: Degree + .. attribute EDUCATION: Education + .. attribute ELECTED: Elected + .. attribute EMIGRATION: Emigration + .. attribute FIRST_COMMUN: First Communion + .. attribute IMMIGRATION: Immigration + .. attribute GRADUATION: Graduation + .. attribute MED_INFO: Medical Information + .. attribute MILITARY_SERV: Military Service + .. attribute NATURALIZATION: Naturalization + .. attribute NOB_TITLE: Nobility Title + .. attribute NUM_MARRIAGES: Number of Marriages + .. attribute OCCUPATION: Occupation + .. attribute ORDINATION: Ordination + .. attribute PROBATE: Probate + .. attribute PROPERTY: Property + .. attribute RELIGION: Religion + .. attribute RESIDENCE: Residence + .. attribute RETIREMENT: Retirement + .. attribute WILL: Will + .. attribute MARRIAGE: Marriage + .. attribute MARR_SETTL: Marriage Settlement + .. attribute MARR_LIC: Marriage License + .. attribute MARR_CONTR: Marriage Contract + .. attribute MARR_BANNS: Marriage Banns + .. attribute ENGAGEMENT: Engagement + .. attribute DIVORCE: Divorce + .. attribute DIV_FILING: Divorce Filing" + .. attribute ANNULMENT: Annulment" + .. attribute MARR_ALT: Alternate Marriage """ UNKNOWN = -1 CUSTOM = 0 diff --git a/src/gen/lib/family.py b/src/gen/lib/family.py index 5e0118256..ea6d6c7af 100644 --- a/src/gen/lib/family.py +++ b/src/gen/lib/family.py @@ -55,14 +55,10 @@ from gen.lib.markertype import MarkerType class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, PrimaryObject): """ - Introduction - ============ The Family record is the GRAMPS in-memory representation of the relationships between people. It contains all the information related to the relationship. - Usage - ===== Family objects are usually created in one of two ways. 1. Creating a new Family object, which is then initialized and @@ -109,9 +105,9 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, lists), the database is responsible for converting the data into a form that it can use. - @returns: Returns a python tuple containing the data that should + :returns: Returns a python tuple containing the data that should be considered persistent. - @rtype: tuple + :rtype: tuple """ return (self.handle, self.gramps_id, self.father_handle, self.mother_handle, @@ -154,13 +150,13 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Return True if the object has reference to a given handle of given primary object type. - @param classname: The name of the primary object class. - @type classname: str - @param handle: The handle to be checked. - @type handle: str - @return: Returns whether the object has reference to this handle of + :param classname: The name of the primary object class. + :type classname: str + :param handle: The handle to be checked. + :type handle: str + :returns: Returns whether the object has reference to this handle of this object type. - @rtype: bool + :rtype: bool """ if classname == 'Event': return handle in [ref.ref for ref in self.event_ref_list] @@ -175,10 +171,10 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Remove all references in this object to object handles in the list. - @param classname: The name of the primary object class. - @type classname: str - @param handle_list: The list of handles to be removed. - @type handle_list: str + :param classname: The name of the primary object class. + :type classname: str + :param handle_list: The list of handles to be removed. + :type handle_list: str """ if classname == 'Event': new_list = [ ref for ref in self.event_ref_list \ @@ -201,12 +197,12 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Replace all references to old handle with those to the new handle. - @param classname: The name of the primary object class. - @type classname: str - @param old_handle: The handle to be replaced. - @type old_handle: str - @param new_handle: The handle to replace the old one with. - @type new_handle: str + :param classname: The name of the primary object class. + :type classname: str + :param old_handle: The handle to be replaced. + :type old_handle: str + :param new_handle: The handle to replace the old one with. + :type new_handle: str """ if classname == 'Event': handle_list = [ref.ref for ref in self.event_ref_list] @@ -233,8 +229,8 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.gramps_id] @@ -242,8 +238,8 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ add_list = [item for item in self.lds_ord_list if item] return self.media_list + self.attribute_list + \ @@ -253,9 +249,9 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ check_list = self.media_list + self.attribute_list + \ self.lds_ord_list + self.child_ref_list + \ @@ -266,9 +262,9 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ check_list = self.media_list + self.attribute_list + \ self.lds_ord_list + self.child_ref_list + self.source_list + \ @@ -280,8 +276,8 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() ret += [('Person', handle) for handle @@ -295,8 +291,8 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, Return the list of child objects which may, directly or through their children, reference primary objects.. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.get_sourcref_child_list() + self.source_list @@ -322,9 +318,9 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, between the two individuals does not match any of the other types. - @param relationship_type: (int,str) tuple of the relationship type + :param relationship_type: (int,str) tuple of the relationship type between the father and mother of the relationship. - @type relationship_type: tuple + :type relationship_type: tuple """ self.type.set(relationship_type) @@ -337,56 +333,56 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def set_father_handle(self, person_handle): """ - Set the database handle for L{Person} that corresponds to male of the + Set the database handle for :class:`~gen.lib.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: L{Person} database handle - @type person_handle: str + :param person_handle: :class:`~gen.lib.person.Person` database handle + :type person_handle: str """ self.father_handle = person_handle def get_father_handle(self): """ - Return the database handle of the L{Person} identified as the father + Return the database handle of the :class:`~gen.lib.person.Person` identified as the father of the Family. - @returns: L{Person} database handle - @rtype: str + :returns: :class:`~gen.lib.person.Person` database handle + :rtype: str """ return self.father_handle def set_mother_handle(self, person_handle): """ - Set the database handle for L{Person} that corresponds to male of the + Set the database handle for :class:`~gen.lib.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: L{Person} database handle - @type person_handle: str + :param person_handle: :class:`~gen.lib.person.Person` database handle + :type person_handle: str """ self.mother_handle = person_handle def get_mother_handle(self): """ - Return the database handle of the L{Person} identified as the mother + Return the database handle of the :class:`~gen.lib.person.Person` identified as the mother of the Family. - @returns: L{Person} database handle - @rtype: str + :returns: :class:`~gen.lib.person.Person` database handle + :rtype: str """ return self.mother_handle def add_child_ref(self, child_ref): """ - Add the database handle for L{Person} to the Family's list of children. + Add the database handle for :class:`~gen.lib.person.Person` to the Family's list of children. - @param child_ref: Child Reference instance - @type child_ref: ChildRef + :param child_ref: Child Reference instance + :type child_ref: ChildRef """ if not isinstance(child_ref, ChildRef): raise ValueError("expecting ChildRef instance") @@ -394,14 +390,14 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def remove_child_ref(self, child_ref): """ - Remove the database handle for L{Person} to the Family's list of - children if the L{Person} is already in the list. + 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. - @param child_ref: Child Reference instance - @type child_ref: ChildRef - @return: True if the handle was removed, False if it was not + :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. - @rtype: bool + :rtype: bool """ if not isinstance(child_ref, ChildRef): raise ValueError("expecting ChildRef instance") @@ -411,14 +407,14 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def remove_child_handle(self, child_handle): """ - Remove the database handle for L{Person} to the Family's list of - children if the L{Person} is already in the list. + 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. - @param child_handle: L{Person} database handle - @type child_handle: str - @return: True if the handle was removed, False if it was not + :param child_handle: :class:`~gen.lib.person.Person` database handle + :type child_handle: str + :returns: True if the handle was removed, False if it was not in the list. - @rtype: bool + :rtype: bool """ new_list = [ref for ref in self.child_ref_list if ref.ref != child_handle ] @@ -426,12 +422,12 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def get_child_ref_list(self): """ - Return the list of L{ChildRef} handles identifying the children of the + Return the list of :class:`~gen.lib.childref.ChildRef` handles identifying the children of the Family. - @return: Returns the list of L{ChildRef} handles assocated with + :returns: Returns the list of :class:`~gen.lib.childref.ChildRef` handles assocated with the Family. - @rtype: list + :rtype: list """ return self.child_ref_list @@ -439,22 +435,22 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, """ Assign the passed list to the Family's list children. - @param child_ref_list: List of Child Reference instances to be + :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 L{ChildRef} instances + :type child_ref_list: list of :class:`~gen.lib.childref.ChildRef` instances """ self.child_ref_list = child_ref_list def add_event_ref(self, event_ref): """ - Add the L{EventRef} to the Family instance's L{EventRef} list. + Add the :class:`~gen.lib.eventref.EventRef` to the Family instance's :class:`~gen.lib.eventref.EventRef` list. - This is accomplished by assigning the L{EventRef} for the valid - L{Event}in the current database. + This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` for the valid + :class:`~gen.lib.event.Event` in the current database. - @param event_ref: the L{EventRef} to be added to the - Person's L{EventRef} list. - @type event_ref: EventRef + :param event_ref: the :class:`~gen.lib.eventref.EventRef` to be added to the + Person's :class:`~gen.lib.eventref.EventRef` list. + :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): raise ValueError("Expecting EventRef instance") @@ -472,20 +468,20 @@ class Family(SourceBase, NoteBase, MediaBase, AttributeBase, LdsOrdBase, def get_event_ref_list(self) : """ - Return the list of L{EventRef} objects associated with L{Event} + Return the list of :class:`~gen.lib.eventref.EventRef` objects associated with :class:`~gen.lib.event.Event` instances. - @returns: Returns the list of L{EventRef} objects associated with + :returns: Returns the list of :class:`~gen.lib.eventref.EventRef` objects associated with the Family instance. - @rtype: list + :rtype: list """ return self.event_ref_list def set_event_ref_list(self, event_ref_list) : """ - Set the Family instance's L{EventRef} list to the passed list. + Set the Family instance's :class:`~gen.lib.eventref.EventRef` list to the passed list. - @param event_ref_list: List of valid L{EventRef} objects - @type event_ref_list: list + :param event_ref_list: List of valid :class:`~gen.lib.eventref.EventRef` objects + :type event_ref_list: list """ self.event_ref_list = event_ref_list diff --git a/src/gen/lib/grampstype.py b/src/gen/lib/grampstype.py index 69e73f8ff..2862e4029 100644 --- a/src/gen/lib/grampstype.py +++ b/src/gen/lib/grampstype.py @@ -22,6 +22,7 @@ """ Base type for all gramps types. + """ #------------------------------------------------------------------------ @@ -52,7 +53,7 @@ def _init_map(data, key_col, data_col, blacklist=None): # #------------------------------------------------------------------------- class GrampsTypeMeta(type): - """Metaclass for L{GrampsType}. + """Metaclass for :class:`~gen.lib.grampstype.GrampsType`. The only thing this metaclass does is calling __class_init__ class method, in order to create the class specific integer/string maps. @@ -70,19 +71,24 @@ class GrampsTypeMeta(type): class GrampsType(object): """Base class for all Gramps object types. - @cvar _DATAMAP: 3-tuple like (index, localized_string, english_string). - @type _DATAMAP: list - @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) - @type _BLACKLIST: list - @cvar POS_: Position of attribute in the serialized format of - an instance. - @type POS_: int + :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) + :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! + :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! + + :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) = range(2) diff --git a/src/gen/lib/ldsord.py b/src/gen/lib/ldsord.py index 96821f882..64f7b81bd 100644 --- a/src/gen/lib/ldsord.py +++ b/src/gen/lib/ldsord.py @@ -156,8 +156,8 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.temple] #return [self.temple,self.get_date()] @@ -166,8 +166,8 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.source_list @@ -175,9 +175,9 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.source_list @@ -186,8 +186,8 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.place: @@ -199,8 +199,8 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.source_list @@ -208,8 +208,8 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, """ Return the type of the Event. - @return: Type of the Event - @rtype: tuple + :returns: Type of the Event + :rtype: tuple """ return self.type @@ -217,8 +217,8 @@ class LdsOrd(SecondaryObject, SourceBase, NoteBase, """ Set the type of the LdsOrd to the passed (int,str) tuple. - @param ord_type: Type to assign to the LdsOrd - @type ord_type: tuple + :param ord_type: Type to assign to the LdsOrd + :type ord_type: tuple """ self.type = ord_type diff --git a/src/gen/lib/ldsordbase.py b/src/gen/lib/ldsordbase.py index 1b11bb271..18f33ff9d 100644 --- a/src/gen/lib/ldsordbase.py +++ b/src/gen/lib/ldsordbase.py @@ -48,8 +48,8 @@ class LdsOrdBase(object): If the source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: LdsOrdBase + :param source: Object used to initialize the new object + :type source: LdsOrdBase """ if source: @@ -74,8 +74,8 @@ class LdsOrdBase(object): """ Add the L{LdsOrd} instance to the object's list of lds_ordes. - @param lds_ord: L{LdsOrd} instance to add to the object's lds_ord list - @type lds_ord: list + :param lds_ord: L{LdsOrd} instance to add to the object's lds_ord list + :type lds_ord: list """ self.lds_ord_list.append(lds_ord) @@ -85,11 +85,11 @@ class LdsOrdBase(object): If the instance does not exist in the list, the operation has no effect. - @param lds_ord: L{LdsOrd} instance to remove from the list - @type lds_ord: L{LdsOrd} + :param lds_ord: L{LdsOrd} instance to remove from the list + :type lds_ord: L{LdsOrd} - @return: True if the lds_ord was removed, False if it was not in the list. - @rtype: bool + :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: self.lds_ord_list.remove(lds_ord) @@ -101,8 +101,8 @@ class LdsOrdBase(object): """ Return the list of L{LdsOrd} instances associated with the object. - @return: Returns the list of L{LdsOrd} instances - @rtype: list + :returns: Returns the list of L{LdsOrd} instances + :rtype: list """ return self.lds_ord_list @@ -110,8 +110,8 @@ class LdsOrdBase(object): """ Assign the passed list to the object's list of L{LdsOrd} instances. - @param lds_ord_list: List of L{LdsOrd} instances to be associated + :param lds_ord_list: List of L{LdsOrd} instances to be associated with the object - @type lds_ord_list: list + :type lds_ord_list: list """ self.lds_ord_list = lds_ord_list diff --git a/src/gen/lib/location.py b/src/gen/lib/location.py index 5d9988cfd..9f697a65d 100644 --- a/src/gen/lib/location.py +++ b/src/gen/lib/location.py @@ -74,8 +74,8 @@ class Location(SecondaryObject, LocationBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.parish] + LocationBase.get_text_data_list(self) diff --git a/src/gen/lib/locationbase.py b/src/gen/lib/locationbase.py index 5f435c2e6..ac8d05436 100644 --- a/src/gen/lib/locationbase.py +++ b/src/gen/lib/locationbase.py @@ -75,8 +75,8 @@ class LocationBase(object): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.city, self.state, self.country, self.postal, self.phone] diff --git a/src/gen/lib/mediabase.py b/src/gen/lib/mediabase.py index 121a3e23e..bab305d35 100644 --- a/src/gen/lib/mediabase.py +++ b/src/gen/lib/mediabase.py @@ -45,8 +45,8 @@ class MediaBase(object): """ Create a new MediaBase, copying from source if not None. - @param source: Object used to initialize the new object - @type source: MediaBase + :param source: Object used to initialize the new object + :type source: MediaBase """ if source: @@ -68,31 +68,31 @@ class MediaBase(object): def add_media_reference(self, media_ref): """ - Add a L{MediaRef} instance to the object's media list. + Add a :class:`~gen.lib.mediaref.MediaRef` instance to the object's media list. - @param media_ref: L{MediaRef} instance to be added to the object's + :param media_ref: :class:`~gen.lib.mediaref.MediaRef` instance to be added to the object's media list. - @type media_ref: L{MediaRef} + :type media_ref: :class:`~gen.lib.mediaref.MediaRef` """ self.media_list.append(media_ref) def get_media_list(self): """ - Return the list of L{MediaRef} instances associated with the object. + Return the list of :class:`~gen.lib.mediaref.MediaRef` instances associated with the object. - @returns: list of L{MediaRef} instances associated with the object - @rtype: list + :returns: list of :class:`~gen.lib.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 L{MediaRef} instances associated with the object. + Set the list of :class:`~gen.lib.mediaref.MediaRef` instances associated with the object. It replaces the previous list. - @param media_ref_list: list of L{MediaRef} instances to be assigned + :param media_ref_list: list of :class:`~gen.lib.mediaref.MediaRef` instances to be assigned to the object. - @type media_ref_list: list + :type media_ref_list: list """ self.media_list = media_ref_list @@ -101,11 +101,11 @@ class MediaBase(object): Return True if the object or any of it's child objects has reference to this media object handle. - @param obj_handle: The media handle to be checked. - @type obj_handle: str - @return: Returns whether the object or any of it's child objects has + :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. - @rtype: bool + :rtype: bool """ return obj_handle in [media_ref.ref for media_ref in self.media_list] @@ -113,8 +113,8 @@ class MediaBase(object): """ Remove references to all media handles in the list. - @param obj_handle_list: The list of media handles to be removed. - @type obj_handle_list: list + :param obj_handle_list: The list of media handles to be removed. + :type obj_handle_list: list """ new_media_list = [ media_ref for media_ref in self.media_list \ if media_ref.ref not in obj_handle_list ] @@ -124,10 +124,10 @@ class MediaBase(object): """ Replace all references to old media handle with the new handle. - @param old_handle: The media handle to be replaced. - @type old_handle: str - @param new_handle: The media handle to replace the old one with. - @type new_handle: str + :param old_handle: The media handle to be replaced. + :type old_handle: str + :param new_handle: The media handle to replace the old one with. + :type new_handle: str """ refs_list = [ media_ref.ref for media_ref in self.media_list ] n_replace = refs_list.count(old_handle) diff --git a/src/gen/lib/mediaobj.py b/src/gen/lib/mediaobj.py index 8e3fd0731..baad6272c 100644 --- a/src/gen/lib/mediaobj.py +++ b/src/gen/lib/mediaobj.py @@ -62,8 +62,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, If source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: MediaObject + :param source: Object used to initialize the new object + :type source: MediaObject """ PrimaryObject.__init__(self, source) SourceBase.__init__(self, source) @@ -96,9 +96,9 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, lists), the database is responsible for converting the data into a form that it can use. - @returns: Returns a python tuple containing the data that should + :returns: Returns a python tuple containing the data that should be considered persistent. - @rtype: tuple + :rtype: tuple """ return (self.handle, self.gramps_id, self.path, self.mime, self.desc, AttributeBase.serialize(self), @@ -114,8 +114,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, 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 object - @type data: tuple + :param data: tuple containing the persistent data associated the object + :type data: tuple """ (self.handle, self.gramps_id, self.path, self.mime, self.desc, attribute_list, source_list, note_list, self.change, @@ -132,8 +132,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.path, self.mime, self.desc, self.gramps_id] @@ -141,8 +141,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.attribute_list + self.source_list @@ -150,9 +150,9 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return self.attribute_list @@ -160,9 +160,9 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.attribute_list + self.source_list @@ -171,8 +171,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() @@ -181,8 +181,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.attribute_list + self.source_list @@ -190,8 +190,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, """ Set the MIME type associated with the MediaObject. - @param mime_type: MIME type to be assigned to the object - @type mime_type: str + :param mime_type: MIME type to be assigned to the object + :type mime_type: str """ self.mime = mime_type @@ -199,8 +199,8 @@ class MediaObject(SourceBase, NoteBase, DateBase, AttributeBase, """ Return the MIME type associated with the MediaObject. - @returns: Returns the associated MIME type - @rtype: str + :returns: Returns the associated MIME type + :rtype: str """ return self.mime diff --git a/src/gen/lib/mediaref.py b/src/gen/lib/mediaref.py index ad8af0416..185b193cf 100644 --- a/src/gen/lib/mediaref.py +++ b/src/gen/lib/mediaref.py @@ -83,8 +83,8 @@ class MediaRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.attribute_list + self.source_list @@ -92,9 +92,9 @@ class MediaRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase, """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return self.attribute_list @@ -102,9 +102,9 @@ class MediaRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.attribute_list + self.source_list @@ -113,8 +113,8 @@ class MediaRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.ref: @@ -126,8 +126,8 @@ class MediaRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase, Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.attribute_list + self.source_list diff --git a/src/gen/lib/name.py b/src/gen/lib/name.py index 522da1d57..1b3c607b0 100644 --- a/src/gen/lib/name.py +++ b/src/gen/lib/name.py @@ -134,8 +134,8 @@ class Name(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.first_name, self.surname, self.suffix, self.title, str(self.type), self.prefix, self.patronymic, self.call] @@ -144,8 +144,8 @@ class Name(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.source_list @@ -153,9 +153,9 @@ class Name(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.source_list @@ -164,8 +164,8 @@ class Name(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase): Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.source_list @@ -174,8 +174,8 @@ class Name(SecondaryObject, PrivacyBase, SourceBase, NoteBase, DateBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() diff --git a/src/gen/lib/note.py b/src/gen/lib/note.py index 329c7d774..7df92e452 100644 --- a/src/gen/lib/note.py +++ b/src/gen/lib/note.py @@ -42,25 +42,27 @@ from gen.lib.styledtext import StyledText class Note(BasicPrimaryObject): """Define a text note. - Starting from GRAMPS 3.1 Note object stores the text in L{StyledText} + Starting from GRAMPS 3.1 Note object stores the text in :class:`gen.lib.styledtext.StyledText` instance, thus it can have text formatting information. - To get and set only the clear text of the note use the L{get} and L{set} - methods. + 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 the formatted version of the Note's text use the - L{get_styledtext} and L{set_styledtext} methods. + :meth:`~gen.lib.note.Note.get_styledtext` and + :meth:`~gen.lib.note.Note.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. - @cvar POS_: Position of attribute in the serialized format of - an instance. - @type POS_: int + :cvar FLOWED: indicates flowed format + :cvar FORMATTED: indicates formatted format (respecting whitespace needed) + :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! + :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! """ (FLOWED, FORMATTED) = range(2) @@ -84,8 +86,8 @@ class Note(BasicPrimaryObject): def serialize(self): """Convert the object to a serialized tuple of data. - @returns: The serialized format of the instance. - @rtype: tuple + :returns: The serialized format of the instance. + :rtype: tuple """ return (self.handle, self.gramps_id, self.text.serialize(), self.format, @@ -95,8 +97,8 @@ class Note(BasicPrimaryObject): def unserialize(self, data): """Convert a serialized tuple of data to an object. - @param data: The serialized format of a Note. - @type: data: tuple + :param data: The serialized format of a Note. + :type: data: tuple """ (self.handle, self.gramps_id, the_text, self.format, @@ -112,8 +114,8 @@ class Note(BasicPrimaryObject): def get_text_data_list(self): """Return the list of all textual attributes of the object. - @returns: The list of all textual attributes of the object. - @rtype: list + :returns: The list of all textual attributes of the object. + :rtype: list """ return [str(self.text)] @@ -121,8 +123,8 @@ class Note(BasicPrimaryObject): def set(self, text): """Set the text associated with the note to the passed string. - @param text: The I{clear} text defining the note contents. - @type text: str + :param text: The *clear* text defining the note contents. + :type text: str """ self.text = StyledText(text) @@ -130,8 +132,8 @@ class Note(BasicPrimaryObject): def get(self): """Return the text string associated with the note. - @returns: The I{clear} text of the note contents. - @rtype: str + :returns: The *clear* text of the note contents. + :rtype: str """ return str(self.text) @@ -139,8 +141,8 @@ class Note(BasicPrimaryObject): def set_styledtext(self, text): """Set the text associated with the note to the passed string. - @param text: The I{formatted} text defining the note contents. - @type text: L{StyledText} + :param text: The *formatted* text defining the note contents. + :type text: :class:`gen.lib.styledtext.StyledText` """ self.text = text @@ -148,8 +150,8 @@ class Note(BasicPrimaryObject): def get_styledtext(self): """Return the text string associated with the note. - @returns: The I{formatted} text of the note contents. - @rtype: L{StyledText} + :returns: The *formatted* text of the note contents. + :rtype: :class:`gen.lib.styledtext.StyledText` """ return self.text @@ -157,8 +159,8 @@ class Note(BasicPrimaryObject): def append(self, text): """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 L{StyledText} + :param text: Text string to be appended to the note. + :type text: str or :class:`gen.lib.styledtext.StyledText` """ self.text = self.text + text @@ -166,8 +168,8 @@ class Note(BasicPrimaryObject): def set_format(self, format): """Set the format of the note to the passed value. - @param: format: The value can either indicate Flowed or Preformatted. - @type format: int + :param format: The value can either indicate Flowed or Preformatted. + :type format: int """ self.format = format @@ -177,8 +179,8 @@ class Note(BasicPrimaryObject): The value can either indicate Flowed or Preformatted. - @returns: 0 indicates Flowed, 1 indicates Preformated - @rtype: int + :returns: 0 indicates Flowed, 1 indicates Preformated + :rtype: int """ return self.format @@ -186,8 +188,8 @@ class Note(BasicPrimaryObject): def set_type(self, the_type): """Set descriptive type of the Note. - @param the_type: descriptive type of the Note - @type the_type: str + :param the_type: descriptive type of the Note + :type the_type: str """ self.type.set(the_type) @@ -195,8 +197,8 @@ class Note(BasicPrimaryObject): def get_type(self): """Get descriptive type of the Note. - @returns: the descriptive type of the Note - @rtype: str + :returns: the descriptive type of the Note + :rtype: str """ return self.type diff --git a/src/gen/lib/notebase.py b/src/gen/lib/notebase.py index 9d2560df8..6f46e412f 100644 --- a/src/gen/lib/notebase.py +++ b/src/gen/lib/notebase.py @@ -41,8 +41,8 @@ class NoteBase(object): """ Create a new NoteBase, copying from source if not None. - @param source: Object used to initialize the new object - @type source: NoteBase + :param source: Object used to initialize the new object + :type source: NoteBase """ if source: @@ -64,13 +64,13 @@ class NoteBase(object): def add_note(self, handle): """ - Add the L{Note} handle to the list of note handles. + Add the :class:`~gen.lib.note.Note` handle to the list of note handles. - @param handle: L{Note} handle to add the list of notes - @type handle: str + :param handle: :class:`~gen.lib.note.Note` handle to add the list of notes + :type handle: str - @return: True if handle was added, False if it already was in the list - @rtype: bool + :returns: True if handle was added, False if it already was in the list + :rtype: bool """ if handle in self.note_list: return False @@ -83,8 +83,8 @@ class NoteBase(object): Remove the specified handle from the list of note handles, and all secondary child objects. - @param handle: L{Note} handle to remove from the list of notes - @type handle: str + :param handle: :class:`~gen.lib.note.Note` handle to remove from the list of notes + :type handle: str """ if handle in self.note_list: self.note_list.remove(handle) @@ -99,27 +99,27 @@ class NoteBase(object): with notes, should return here a list of child objects which are NoteBase - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return [] def get_note_list(self): """ - Return the list of L{Note} handles associated with the object. + Return the list of :class:`~gen.lib.note.Note` handles associated with the object. - @return: The list of L{Note} handles - @rtype: list + :returns: The list of :class:`~gen.lib.note.Note` handles + :rtype: list """ return self.note_list def set_note_list(self, note_list): """ - Assign the passed list to be object's list of L{Note} handles. + Assign the passed list to be object's list of :class:`~gen.lib.note.Note` handles. - @param note_list: List of L{Note} handles to be set on the object - @type note_list: list + :param note_list: List of :class:`~gen.lib.note.Note` handles to be set on the object + :type note_list: list """ self.note_list = note_list @@ -127,10 +127,10 @@ class NoteBase(object): """ Return the list of (classname, handle) tuples for all referenced notes. - This method should be used to get the L{Note} portion of the list + This method should be used to get the :class:`~gen.lib.note.Note` portion of the list by objects that store note lists. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return [('Note', handle) for handle in self.note_list] diff --git a/src/gen/lib/notetype.py b/src/gen/lib/notetype.py index 970087318..b8e7cb013 100644 --- a/src/gen/lib/notetype.py +++ b/src/gen/lib/notetype.py @@ -115,12 +115,12 @@ class NoteType(GrampsType): Exception is a sublist of types that may not be ignored - @param exception: list of integer values corresponding with types that + :param exception: list of integer values corresponding with types that have to be excluded from the ignore list - @type exception: list - @returns: list of integers corresponding with the types to ignore when + :type exception: list + :returns: list of integers corresponding with the types to ignore when showing a list of different NoteType's - @rtype: list + :rtype: list """ ignlist = [x[0] for x in self._DATAMAPIGNORE] diff --git a/src/gen/lib/person.py b/src/gen/lib/person.py index b0681b5d2..06afb7964 100644 --- a/src/gen/lib/person.py +++ b/src/gen/lib/person.py @@ -52,14 +52,10 @@ from gen.lib.markertype import MarkerType class Person(SourceBase, NoteBase, AttributeBase, MediaBase, AddressBase, UrlBase, LdsOrdBase, PrimaryObject): """ - Introduction - ============ The Person record is the GRAMPS in-memory representation of an individual person. It contains all the information related to an individual. - Usage - ===== Person objects are usually created in one of two ways. 1. Creating a new person object, which is then initialized and added to @@ -123,9 +119,9 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, lists), the database is responsible for converting the data into a form that it can use. - @returns: Returns a python tuple containing the data that should + :returns: Returns a python tuple containing the data that should be considered persistent. - @rtype: tuple + :rtype: tuple """ return ( self.handle, # 0 @@ -156,9 +152,9 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, Convert the data held in a tuple created by the serialize method back into the data in a Person object. - @param data: tuple containing the persistent data associated the + :param data: tuple containing the persistent data associated the Person object - @type data: tuple + :type data: tuple """ (self.handle, # 0 self.gramps_id, # 1 @@ -206,13 +202,13 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, Return True if the object has reference to a given handle of given primary object type. - @param classname: The name of the primary object class. - @type classname: str - @param handle: The handle to be checked. - @type handle: str - @return: Returns whether the object has reference to this handle of + :param classname: The name of the primary object class. + :type classname: str + :param handle: The handle to be checked. + :type handle: str + :returns: Returns whether the object has reference to this handle of this object type. - @rtype: bool + :rtype: bool """ if classname == 'Event': return any(ref.ref == handle for ref in self.event_ref_list) @@ -299,8 +295,8 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.gramps_id] @@ -308,8 +304,8 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ check_list = self.lds_ord_list add_list = [item for item in check_list if item] @@ -323,9 +319,9 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return [self.primary_name] + self.media_list + \ self.alternate_names + self.address_list + \ @@ -336,9 +332,9 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return [self.primary_name] + self.media_list + \ self.alternate_names + self.address_list + \ @@ -351,8 +347,8 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return [('Family', handle) for handle in (self.family_list + self.parent_family_list)] \ @@ -363,36 +359,36 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ #don't count double, notes can be found in sourcref return self.get_sourcref_child_list() + self.source_list def set_primary_name(self, name): """ - Set the primary name of the Person to the specified L{Name} instance. + Set the primary name of the Person to the specified :class:`~gen.lib.name.Name` instance. - @param name: L{Name} to be assigned to the person - @type name: L{Name} + :param name: :class:`~gen.lib.name.Name` to be assigned to the person + :type name: :class:`~gen.lib.name.Name` """ self.primary_name = name def get_primary_name(self): """ - Return the L{Name} instance marked as the Person's primary name. + Return the :class:`~gen.lib.name.Name` instance marked as the Person's primary name. - @return: Returns the primary name - @rtype: L{Name} + :returns: Returns the primary name + :rtype: :class:`~gen.lib.name.Name` """ return self.primary_name def get_alternate_names(self): """ - Return the list of alternate L{Name} instances. + Return the list of alternate :class:`~gen.lib.name.Name` instances. - @return: List of L{Name} instances - @rtype: list + :returns: List of :class:`~gen.lib.name.Name` instances + :rtype: list """ return self.alternate_names @@ -400,17 +396,17 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Change the list of alternate names to the passed list. - @param alt_name_list: List of L{Name} instances - @type alt_name_list: list + :param alt_name_list: List of :class:`~gen.lib.name.Name` instances + :type alt_name_list: list """ self.alternate_names = alt_name_list def add_alternate_name(self, name): """ - Add a L{Name} instance to the list of alternative names. + Add a :class:`~gen.lib.name.Name` instance to the list of alternative names. - @param name: L{Name} to add to the list - @type name: L{Name} + :param name: :class:`~gen.lib.name.Name` to add to the list + :type name: :class:`~gen.lib.name.Name` """ self.alternate_names.append(name) @@ -425,12 +421,12 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Set the gender of the Person. - @param gender: Assigns the Person's gender to one of the + :param gender: Assigns the Person's gender to one of the following constants:: Person.MALE Person.FEMALE Person.UNKNOWN - @type gender: int + :type gender: int """ self.gender = gender @@ -438,11 +434,11 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Return the gender of the Person. - @returns: Returns one of the following constants:: + :returns: Returns one of the following constants:: Person.MALE Person.FEMALE Person.UNKNOWN - @rtype: int + :rtype: int """ return self.gender @@ -450,12 +446,12 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Assign the birth event to the Person object. - This is accomplished by assigning the L{EventRef} of the birth event + This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` of the birth event in the current database. - @param event_ref: the L{EventRef} object associated with + :param event_ref: the :class:`~gen.lib.eventref.EventRef` object associated with the Person's birth. - @type event_ref: EventRef + :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): raise ValueError("Expecting EventRef instance") @@ -475,12 +471,12 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, """ Assign the death event to the Person object. - This is accomplished by assigning the L{EventRef} of the death event + This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` of the death event in the current database. - @param event_ref: the L{EventRef} object associated with + :param event_ref: the :class:`~gen.lib.eventref.EventRef` object associated with the Person's death. - @type event_ref: EventRef + :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): raise ValueError("Expecting EventRef instance") @@ -498,13 +494,13 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_birth_ref(self): """ - Return the L{EventRef} for Person's birth event. + Return the :class:`~gen.lib.eventref.EventRef` for Person's birth event. - This should correspond to an L{Event} in the database's L{Event} list. + This should correspond to an :class:`~gen.lib.event.Event` in the database's :class:`~gen.lib.event.Event` list. - @returns: Returns the birth L{EventRef} or None if no birth - L{Event} has been assigned. - @rtype: EventRef + :returns: Returns the birth :class:`~gen.lib.eventref.EventRef` or None if no birth + :class:`~gen.lib.event.Event` has been assigned. + :rtype: EventRef """ if 0 <= self.birth_ref_index < len(self.event_ref_list): @@ -514,13 +510,13 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_death_ref(self): """ - Return the L{EventRef} for the Person's death event. + Return the :class:`~gen.lib.eventref.EventRef` for the Person's death event. - This should correspond to an L{Event} in the database's L{Event} list. + This should correspond to an :class:`~gen.lib.event.Event` in the database's :class:`~gen.lib.event.Event` list. - @returns: Returns the death L{EventRef} or None if no death - L{Event} has been assigned. - @rtype: event_ref + :returns: Returns the death :class:`~gen.lib.eventref.EventRef` or None if no death + :class:`~gen.lib.event.Event` has been assigned. + :rtype: event_ref """ if 0 <= self.death_ref_index < len(self.event_ref_list): @@ -530,14 +526,14 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def add_event_ref(self, event_ref): """ - Add the L{EventRef} to the Person instance's L{EventRef} list. + Add the :class:`~gen.lib.eventref.EventRef` to the Person instance's :class:`~gen.lib.eventref.EventRef` list. - This is accomplished by assigning the L{EventRef} of a valid - L{Event} in the current database. + This is accomplished by assigning the :class:`~gen.lib.eventref.EventRef` of a valid + :class:`~gen.lib.event.Event` in the current database. - @param event_ref: the L{EventRef} to be added to the - Person's L{EventRef} list. - @type event_ref: EventRef + :param event_ref: the :class:`~gen.lib.eventref.EventRef` to be added to the + Person's :class:`~gen.lib.eventref.EventRef` list. + :type event_ref: EventRef """ if event_ref and not isinstance(event_ref, EventRef): raise ValueError("Expecting EventRef instance") @@ -548,23 +544,23 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_event_ref_list(self): """ - Return the list of L{EventRef} objects associated with L{Event} + Return the list of :class:`~gen.lib.eventref.EventRef` objects associated with :class:`~gen.lib.event.Event` instances. - @returns: Returns the list of L{EventRef} objects associated with + :returns: Returns the list of :class:`~gen.lib.eventref.EventRef` objects associated with the Person instance. - @rtype: list + :rtype: list """ return self.event_ref_list def get_primary_event_ref_list(self): """ - Return the list of L{EventRef} objects associated with L{Event} + 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. - @returns: Returns generator of L{EventRef} objects associated with + :returns: Returns generator of :class:`~gen.lib.eventref.EventRef` objects associated with the Person instance. - @rtype: generator + :rtype: generator """ return (ref for ref in self.event_ref_list if ref.get_role() == EventRoleType.PRIMARY @@ -572,49 +568,49 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def set_event_ref_list(self, event_ref_list): """ - Set the Person instance's L{EventRef} list to the passed list. + Set the Person instance's :class:`~gen.lib.eventref.EventRef` list to the passed list. - @param event_ref_list: List of valid L{EventRef} objects - @type event_ref_list: list + :param event_ref_list: List of valid :class:`~gen.lib.eventref.EventRef` objects + :type event_ref_list: list """ self.event_ref_list = event_ref_list def add_family_handle(self, family_handle): """ - Add the L{Family} handle to the Person instance's L{Family} list. + Add the :class:`~gen.lib.family.Family` handle to the Person instance's :class:`~gen.lib.family.Family` list. - This is accomplished by assigning the handle of a valid L{Family} + This is accomplished by assigning the handle of a valid :class:`~gen.lib.family.Family` in the current database. - Adding a L{Family} handle to a Person does not automatically update - the corresponding L{Family}. The developer is responsible to make - sure that when a L{Family} is added to Person, that the Person is - assigned to either the father or mother role in the L{Family}. + 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`. - @param family_handle: handle of the L{Family} to be added to the - Person's L{Family} list. - @type family_handle: str + :param family_handle: handle of the :class:`~gen.lib.family.Family` to be added to the + Person's :class:`~gen.lib.family.Family` list. + :type family_handle: str """ if family_handle not in self.family_list: self.family_list.append(family_handle) def set_preferred_family_handle(self, family_handle): """ - Set the family_handle specified to be the preferred L{Family}. + Set the family_handle specified to be the preferred :class:`~gen.lib.family.Family`. - The preferred L{Family} is determined by the first L{Family} in the - L{Family} list, and is typically used to indicate the preferred - L{Family} for navigation or reporting. + 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 family_handle must already be in the list, or the function call has no effect. - @param family_handle: Handle of the L{Family} to make the preferred - L{Family}. - @type family_handle: str - @returns: True if the call succeeded, False if the family_handle - was not already in the L{Family} list - @rtype: bool + :param family_handle: Handle of the :class:`~gen.lib.family.Family` to make the preferred + :class:`~gen.lib.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 + :rtype: bool """ if family_handle in self.family_list: self.family_list.remove(family_handle) @@ -625,12 +621,13 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_family_handle_list(self) : """ - Return the list of L{Family} handles in which the person is a parent + Return the list of :class:`~gen.lib.family.Family` handles in which the person is a parent or spouse. - @return: Returns the list of handles corresponding to the - L{Family} records with which the person is associated. - @rtype: list + :returns: Returns the list of handles corresponding to the + :class:`~gen.lib.family.Family` records with which the person + is associated. + :rtype: list """ return self.family_list @@ -639,31 +636,31 @@ class Person(SourceBase, 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 L{Family} handles to be associated + :param family_list: List of :class:`~gen.lib.family.Family` handles to be associated with the Person - @type family_list: list + :type family_list: list """ self.family_list = family_list def clear_family_handle_list(self): """ - Remove all L{Family} handles from the L{Family} list. + Remove all :class:`~gen.lib.family.Family` handles from the :class:`~gen.lib.family.Family` list. """ self.family_list = [] def remove_family_handle(self, family_handle): """ - Remove the specified L{Family} handle from the list of + Remove the specified :class:`~gen.lib.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: L{Family} handle to remove from the list - @type family_handle: str + :param family_handle: :class:`~gen.lib.family.Family` handle to remove from the list + :type family_handle: str - @return: True if the handle was removed, False if it was not + :returns: True if the handle was removed, False if it was not in the list. - @rtype: bool + :rtype: bool """ if family_handle in self.family_list: self.family_list.remove(family_handle) @@ -673,40 +670,40 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_parent_family_handle_list(self): """ - Return the list of L{Family} handles in which the person is a child. + Return the list of :class:`~gen.lib.family.Family` handles in which the person is a child. - @return: Returns the list of handles corresponding to the - L{Family} records with which the person is a child. - @rtype: list + :returns: Returns the list of handles corresponding to the + :class:`~gen.lib.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 L{Family} handles in which the person is a child. + Return the list of :class:`~gen.lib.family.Family` handles in which the person is a child. - @return: Returns the list of handles corresponding to the - L{Family} records with which the person is a child. - @rtype: list + :returns: Returns the list of handles corresponding to the + :class:`~gen.lib.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 L{Family} handle to the Person instance's list of families in + Add the :class:`~gen.lib.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 L{Family} in + This is accomplished by assigning the handle of a valid :class:`~gen.lib.family.Family` in the current database. - Adding a L{Family} handle to a Person does not automatically update - the corresponding L{Family}. The developer is responsible to make - sure that when a L{Family} is added to Person, that the Person is - added to the L{Family} instance's child list. + 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. - @param family_handle: handle of the L{Family} to be added to the - Person's L{Family} list. - @type family_handle: str + :param family_handle: handle of the :class:`~gen.lib.family.Family` to be added to the + Person's :class:`~gen.lib.family.Family` list. + :type family_handle: str """ if not isinstance(family_handle, basestring): raise ValueError("expecting handle") @@ -715,25 +712,25 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def clear_parent_family_handle_list(self): """ - Remove all L{Family} handles from the parent L{Family} list. + Remove all :class:`~gen.lib.family.Family` handles from the parent :class:`~gen.lib.family.Family` list. """ self.parent_family_list = [] def remove_parent_family_handle(self, family_handle): """ - Remove the specified L{Family} handle from the list of parent + Remove the specified :class:`~gen.lib.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: L{Family} handle to remove from the list - @type family_handle: str + :param family_handle: :class:`~gen.lib.family.Family` handle to remove from the list + :type family_handle: str - @return: Returns a tuple of three strings, consisting of the + :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. - @rtype: tuple + :rtype: tuple """ if family_handle in self.parent_family_list: self.parent_family_list.remove(family_handle) @@ -743,18 +740,18 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def set_main_parent_family_handle(self, family_handle): """ - Set the main L{Family} in which the Person is a child. + Set the main :class:`~gen.lib.family.Family` in which the Person is a child. - The main L{Family} is the L{Family} typically used for reports and - navigation. This is accomplished by moving the L{Family} to the + 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. - @param family_handle: handle of the L{Family} to be marked - as the main L{Family} - @type family_handle: str - @return: Returns True if the assignment has successful - @rtype: bool + :param family_handle: handle of the :class:`~gen.lib.family.Family` to be marked + as the main :class:`~gen.lib.family.Family` + :type family_handle: str + :returns: Returns True if the assignment has successful + :rtype: bool """ if family_handle in self.parent_family_list: self.parent_family_list.remove(family_handle) @@ -765,12 +762,12 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_main_parents_family_handle(self): """ - Return the handle of the L{Family} considered to be the main L{Family} + 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: Returns the family_handle if a family_handle exists, - If no L{Family} is assigned, None is returned - @rtype: str + :returns: Returns the family_handle if a family_handle exists, + If no :class:`~gen.lib.family.Family` is assigned, None is returned + :rtype: str """ if self.parent_family_list: return self.parent_family_list[0] @@ -779,11 +776,11 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def add_person_ref(self, person_ref): """ - Add the L{PersonRef} to the Person instance's L{PersonRef} list. + Add the :class:`~gen.lib.personref.PersonRef` to the Person instance's :class:`~gen.lib.personref.PersonRef` list. - @param person_ref: the L{PersonRef} to be added to the - Person's L{PersonRef} list. - @type person_ref: PersonRef + :param person_ref: the :class:`~gen.lib.personref.PersonRef` to be added to the + Person's :class:`~gen.lib.personref.PersonRef` list. + :type person_ref: PersonRef """ if person_ref and not isinstance(person_ref, PersonRef): raise ValueError("Expecting PersonRef instance") @@ -791,18 +788,18 @@ class Person(SourceBase, NoteBase, AttributeBase, MediaBase, def get_person_ref_list(self): """ - Return the list of L{PersonRef} objects. + Return the list of :class:`~gen.lib.personref.PersonRef` objects. - @returns: Returns the list of L{PersonRef} objects. - @rtype: list + :returns: Returns the list of :class:`~gen.lib.personref.PersonRef` objects. + :rtype: list """ return self.person_ref_list def set_person_ref_list(self, person_ref_list): """ - Set the Person instance's L{PersonRef} list to the passed list. + Set the Person instance's :class:`~gen.lib.personref.PersonRef` list to the passed list. - @param person_ref_list: List of valid L{PersonRef} objects - @type person_ref_list: list + :param person_ref_list: List of valid :class:`~gen.lib.personref.PersonRef` objects + :type person_ref_list: list """ self.person_ref_list = person_ref_list diff --git a/src/gen/lib/personref.py b/src/gen/lib/personref.py index 3136c3ae3..dcd57571c 100644 --- a/src/gen/lib/personref.py +++ b/src/gen/lib/personref.py @@ -84,8 +84,8 @@ class PersonRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.rel] @@ -93,8 +93,8 @@ class PersonRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.source_list @@ -102,9 +102,9 @@ class PersonRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.source_list @@ -113,8 +113,8 @@ class PersonRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.ref: @@ -126,8 +126,8 @@ class PersonRef(SecondaryObject, PrivacyBase, SourceBase, NoteBase, RefBase): Return the list of child objects which may, directly or through their children, reference primary objects.. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.source_list diff --git a/src/gen/lib/place.py b/src/gen/lib/place.py index 8658054b2..36bed9431 100644 --- a/src/gen/lib/place.py +++ b/src/gen/lib/place.py @@ -55,8 +55,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Create a new Place object, copying from the source if present. - @param source: A Place object used to initialize the new Place - @type source: Place + :param source: A Place object used to initialize the new Place + :type source: Place """ PrimaryObject.__init__(self, source) SourceBase.__init__(self, source) @@ -90,9 +90,9 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): lists), the database is responsible for converting the data into a form that it can use. - @returns: Returns a python tuple containing the data that should + :returns: Returns a python tuple containing the data that should be considered persistent. - @rtype: tuple + :rtype: tuple """ if self.main_loc is None or self.main_loc.serialize() == _EMPTY_LOC: @@ -113,9 +113,9 @@ class Place(SourceBase, 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 + :param data: tuple containing the persistent data associated the Person object - @type data: tuple + :type data: tuple """ (self.handle, self.gramps_id, self.title, self.long, self.lat, main_loc, alt_loc, urls, media_list, source_list, note_list, @@ -137,8 +137,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.long, self.lat, self.title, self.gramps_id] @@ -146,8 +146,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ ret = self.media_list + self.source_list + self.alt_loc + self.urls @@ -159,8 +159,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the list of child secondary objects that may refer sources. - @return: List of child secondary child objects that may refer sources. - @rtype: list + :returns: List of child secondary child objects that may refer sources. + :rtype: list """ return self.media_list @@ -168,9 +168,9 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.media_list + self.source_list @@ -179,8 +179,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.media_list + self.source_list @@ -189,8 +189,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() @@ -198,8 +198,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Set the descriptive title of the Place object. - @param title: descriptive title to assign to the Place - @type title: str + :param title: descriptive title to assign to the Place + :type title: str """ self.title = title @@ -207,8 +207,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the descriptive title of the Place object. - @returns: Returns the descriptive title of the Place - @rtype: str + :returns: Returns the descriptive title of the Place + :rtype: str """ return self.title @@ -216,8 +216,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Set the longitude of the Place object. - @param longitude: longitude to assign to the Place - @type longitude: str + :param longitude: longitude to assign to the Place + :type longitude: str """ self.long = longitude @@ -225,8 +225,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the longitude of the Place object. - @returns: Returns the longitude of the Place - @rtype: str + :returns: Returns the longitude of the Place + :rtype: str """ return self.long @@ -234,8 +234,8 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Set the latitude of the Place object. - @param latitude: latitude to assign to the Place - @type latitude: str + :param latitude: latitude to assign to the Place + :type latitude: str """ self.lat = latitude @@ -243,21 +243,21 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): """ Return the latitude of the Place object. - @returns: Returns the latitude of the Place - @rtype: str + :returns: Returns the latitude of the Place + :rtype: str """ return self.lat def get_main_location(self): """ - Return the L{Location} object representing the primary information for + Return the :class:`~gen.lib.location.Location` object representing the primary information for the Place instance. - If a L{Location} hasn't been assigned yet, an empty one is created. + If a :class:`~gen.lib.location.Location` hasn't been assigned yet, an empty one is created. - @returns: Returns the L{Location} instance representing the primary + :returns: Returns the :class:`~gen.lib.location.Location` instance representing the primary location information about the Place. - @rtype: L{Location} + :rtype: :class:`~gen.lib.location.Location` """ if not self.main_loc: self.main_loc = Location() @@ -265,44 +265,44 @@ class Place(SourceBase, NoteBase, MediaBase, UrlBase, PrimaryObject): def set_main_location(self, location): """ - Assign the main location information about the Place to the L{Location} + Assign the main location information about the Place to the :class:`~gen.lib.location.Location` object passed. - @param location: L{Location} instance to assign to as the main + :param location: :class:`~gen.lib.location.Location` instance to assign to as the main information for the Place. - @type location: L{Location} + :type location: :class:`~gen.lib.location.Location` """ self.main_loc = location def get_alternate_locations(self): """ - Return a list of alternate L{Location} objects the present alternate + Return a list of alternate :class:`~gen.lib.location.Location` objects the present alternate information about the current Place. - A Place can have more than one L{Location}, since names and + A Place can have more than one :class:`~gen.lib.location.Location`, since names and jurisdictions can change over time for the same place. - @returns: Returns the alternate L{Location}s for the Place - @rtype: list of L{Location} objects + :returns: Returns the alternate :class:`~gen.lib.location.Location`\ s for the Place + :rtype: list of :class:`~gen.lib.location.Location` objects """ return self.alt_loc def set_alternate_locations(self, location_list): """ - Replace the current alternate L{Location} object list with the new one. + Replace the current alternate :class:`~gen.lib.location.Location` object list with the new one. - @param location_list: The list of L{Location} objects to assign to the + :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 L{Location} objects + :type location_list: list of :class:`~gen.lib.location.Location` objects """ self.alt_loc = location_list def add_alternate_locations(self, location): """ - Add a L{Location} object to the alternate location list. + Add a :class:`~gen.lib.location.Location` object to the alternate location list. - @param location: L{Location} instance to add - @type location: L{Location} + :param location: :class:`~gen.lib.location.Location` instance to add + :type location: :class:`~gen.lib.location.Location` """ if location not in self.alt_loc: self.alt_loc.append(location) diff --git a/src/gen/lib/placebase.py b/src/gen/lib/placebase.py index f89fb718c..2884c5170 100644 --- a/src/gen/lib/placebase.py +++ b/src/gen/lib/placebase.py @@ -40,8 +40,8 @@ class PlaceBase(object): If the source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: PlaceBase + :param source: Object used to initialize the new object + :type source: PlaceBase """ if source: self.place = source.place @@ -50,18 +50,18 @@ class PlaceBase(object): def set_place_handle(self, place_handle): """ - Set the database handle for L{Place} associated with the object. + Set the database handle for :class:`~gen.lib.place.Place` associated with the object. - @param place_handle: L{Place} database handle - @type place_handle: str + :param place_handle: :class:`~gen.lib.place.Place` database handle + :type place_handle: str """ self.place = place_handle def get_place_handle(self): """ - Return the database handle of the L{Place} assocated with the Event. + Return the database handle of the :class:`~gen.lib.place.Place` assocated with the Event. - @returns: L{Place} database handle - @rtype: str + :returns: :class:`~gen.lib.place.Place` database handle + :rtype: str """ return self.place diff --git a/src/gen/lib/primaryobj.py b/src/gen/lib/primaryobj.py index 04c5bebbd..83117ebaf 100644 --- a/src/gen/lib/primaryobj.py +++ b/src/gen/lib/primaryobj.py @@ -79,8 +79,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): strings. If source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: PrimaryObject + :param source: Object used to initialize the new object + :type source: PrimaryObject """ PrivacyBase.__init__(self, source) if source: @@ -100,9 +100,9 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): The value in the format returned by the time.time() command. - @returns: Time that the data was last changed. The value in the format + :returns: Time that the data was last changed. The value in the format returned by the time.time() command. - @rtype: int + :rtype: int """ return self.change @@ -110,8 +110,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Return the string representation of the last change time. - @returns: string representation of the last change time. - @rtype: str + :returns: string representation of the last change time. + :rtype: str """ if self.change: @@ -124,8 +124,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Set the database handle for the primary object. - @param handle: object database handle - @type handle: str + :param handle: object database handle + :type handle: str """ self.handle = handle @@ -133,8 +133,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Return the database handle for the primary object. - @returns: database handle associated with the object - @rtype: str + :returns: database handle associated with the object + :rtype: str """ return self.handle @@ -142,8 +142,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Set the GRAMPS ID for the primary object. - @param gramps_id: GRAMPS ID - @type gramps_id: str + :param gramps_id: GRAMPS ID + :type gramps_id: str """ self.gramps_id = gramps_id @@ -151,8 +151,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Return the GRAMPS ID for the primary object. - @returns: GRAMPS ID associated with the object - @rtype: str + :returns: GRAMPS ID associated with the object + :rtype: str """ return self.gramps_id @@ -161,13 +161,16 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): Return True if the object has reference to a given handle of given primary object type. - @param classname: The name of the primary object class. - @type classname: str - @param handle: The handle to be checked. - @type handle: str - @return: Returns whether the object has reference to this handle of - this object type. - @rtype: bool + :param classname: The name of the primary object class. + :type classname: str + :param handle: The handle to be checked. + :type handle: str + + :returns: + Returns whether the object has reference to this handle of + this object type. + + :rtype: bool """ return False @@ -175,10 +178,10 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Remove all references in this object to object handles in the list. - @param classname: The name of the primary object class. - @type classname: str - @param handle_list: The list of handles to be removed. - @type handle_list: str + :param classname: The name of the primary object class. + :type classname: str + :param handle_list: The list of handles to be removed. + :type handle_list: str """ pass @@ -186,12 +189,12 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Replace all references to old handle with those to the new handle. - @param classname: The name of the primary object class. - @type classname: str - @param old_handle: The handle to be replaced. - @type old_handle: str - @param new_handle: The handle to replace the old one with. - @type new_handle: str + :param classname: The name of the primary object class. + :type classname: str + :param old_handle: The handle to be replaced. + :type old_handle: str + :param new_handle: The handle to replace the old one with. + :type new_handle: str """ pass @@ -199,8 +202,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): """ Set the marker for the object. - @param marker: marker assigned to the object - @type marker: MarkerType + :param marker: marker assigned to the object + :type marker: MarkerType """ self.marker.set(marker) @@ -210,8 +213,8 @@ class BasicPrimaryObject(BaseObject, PrivacyBase): The exact type depends on the derived class type. - @return: Returns the marker for the object. - @rtype: MarkerType + :returns: Returns the marker for the object. + :rtype: MarkerType """ return self.marker @@ -281,8 +284,8 @@ class PrimaryObject(BasicPrimaryObject): strings. If source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: PrimaryObject + :param source: Object used to initialize the new object + :type source: PrimaryObject """ BasicPrimaryObject.__init__(self, source) @@ -291,13 +294,13 @@ class PrimaryObject(BasicPrimaryObject): Return True if the object has reference to a given handle of given primary object type. - @param classname: The name of the primary object class. - @type classname: str - @param handle: The handle to be checked. - @type handle: str - @return: Returns whether the object has reference to this handle - of this object type. - @rtype: bool + :param classname: The name of the primary object class. + :type classname: str + :param handle: The handle to be checked. + :type handle: str + :returns: Returns whether the object has reference to this handle + of this object type. + :rtype: bool """ if classname == 'Source' and isinstance(self, SourceBase): return self.has_source_reference(handle) @@ -310,10 +313,10 @@ class PrimaryObject(BasicPrimaryObject): """ Remove all references in this object to object handles in the list. - @param classname: The name of the primary object class. - @type classname: str - @param handle_list: The list of handles to be removed. - @type handle_list: str + :param classname: The name of the primary object class. + :type classname: str + :param handle_list: The list of handles to be removed. + :type handle_list: str """ if classname == 'Source' and isinstance(self, SourceBase): self.remove_source_references(handle_list) @@ -326,12 +329,12 @@ class PrimaryObject(BasicPrimaryObject): """ Replace all references to old handle with those to the new handle. - @param classname: The name of the primary object class. - @type classname: str - @param old_handle: The handle to be replaced. - @type old_handle: str - @param new_handle: The handle to replace the old one with. - @type new_handle: str + :param classname: The name of the primary object class. + :type classname: str + :param old_handle: The handle to be replaced. + :type old_handle: str + :param new_handle: The handle to replace the old one with. + :type new_handle: str """ if classname == 'Source' and isinstance(self, SourceBase): self.replace_source_references(old_handle, new_handle) diff --git a/src/gen/lib/privacybase.py b/src/gen/lib/privacybase.py index 9a82e12de..16a3b97ad 100644 --- a/src/gen/lib/privacybase.py +++ b/src/gen/lib/privacybase.py @@ -41,8 +41,8 @@ class PrivacyBase(object): If the source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: PrivacyBase + :param source: Object used to initialize the new object + :type source: PrivacyBase """ if source: @@ -67,9 +67,9 @@ class PrivacyBase(object): """ Set or clears the privacy flag of the data. - @param val: value to assign to the privacy flag. True indicates that + :param val: value to assign to the privacy flag. True indicates that the record is private, False indicates that it is public. - @type val: bool + :type val: bool """ self.private = val @@ -77,7 +77,7 @@ class PrivacyBase(object): """ Return the privacy level of the data. - @returns: True indicates that the record is private - @rtype: bool + :returns: True indicates that the record is private + :rtype: bool """ return self.private diff --git a/src/gen/lib/refbase.py b/src/gen/lib/refbase.py index 603007d4e..28d0251bf 100644 --- a/src/gen/lib/refbase.py +++ b/src/gen/lib/refbase.py @@ -33,7 +33,7 @@ class RefBase(object): """ Base reference class to manage references to other objects. - Any *Ref class should derive from this class. + Any *Ref* classes should derive from this class. """ def __init__(self, source=None): @@ -60,9 +60,9 @@ class RefBase(object): Returns the list of (classname, handle) tuples for all directly referenced primary objects. - @return: Returns the list of (classname, handle) tuples for referenced + :returns: Returns the list of (classname, handle) tuples for referenced objects. - @rtype: list + :rtype: list """ assert False, "Must be overridden in the derived class" diff --git a/src/gen/lib/repo.py b/src/gen/lib/repo.py index 801cc2e5c..11d27ee68 100644 --- a/src/gen/lib/repo.py +++ b/src/gen/lib/repo.py @@ -86,8 +86,8 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.name, str(self.type)] @@ -95,8 +95,8 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.address_list + self.urls @@ -104,9 +104,9 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return self.address_list @@ -114,9 +114,9 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.address_list @@ -125,8 +125,8 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.address_list @@ -135,8 +135,8 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() @@ -145,11 +145,11 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): Return True if any of the child objects has reference to this source handle. - @param src_handle: The source handle to be checked. - @type src_handle: str - @return: Returns whether any of it's child objects has reference to + :param src_handle: The source handle to be checked. + :type src_handle: str + :returns: Returns whether any of it's child objects has reference to this source handle. - @rtype: bool + :rtype: bool """ for item in self.get_sourcref_child_list(): if item.has_source_reference(src_handle): @@ -162,8 +162,8 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): Remove references to all source handles in the list in all child objects. - @param src_handle_list: The list of source handles to be removed. - @type src_handle_list: list + :param src_handle_list: The list of source handles to be removed. + :type src_handle_list: list """ for item in self.get_sourcref_child_list(): item.remove_source_references(src_handle_list) @@ -173,38 +173,38 @@ class Repository(NoteBase, AddressBase, UrlBase, PrimaryObject): Replace references to source handles in the list in this object and all child objects. - @param old_handle: The source handle to be replaced. - @type old_handle: str - @param new_handle: The source handle to replace the old one with. - @type new_handle: str + :param old_handle: The source handle to be replaced. + :type old_handle: str + :param new_handle: The source handle to replace the old one with. + :type new_handle: str """ for item in self.get_sourcref_child_list(): item.replace_source_references(old_handle, new_handle) def set_type(self, the_type): """ - @param the_type: descriptive type of the Repository - @type the_type: str + :param the_type: descriptive type of the Repository + :type the_type: str """ self.type.set(the_type) def get_type(self): """ - @returns: the descriptive type of the Repository - @rtype: str + :returns: the descriptive type of the Repository + :rtype: str """ return self.type def set_name(self, name): """ - @param name: descriptive name of the Repository - @type name: str + :param name: descriptive name of the Repository + :type name: str """ self.name = name def get_name(self): """ - @returns: the descriptive name of the Repository - @rtype: str + :returns: the descriptive name of the Repository + :rtype: str """ return self.name diff --git a/src/gen/lib/reporef.py b/src/gen/lib/reporef.py index a9f435914..b3a147261 100644 --- a/src/gen/lib/reporef.py +++ b/src/gen/lib/reporef.py @@ -83,8 +83,8 @@ class RepoRef(SecondaryObject, PrivacyBase, NoteBase, RefBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.call_number, str(self.media_type)] @@ -93,8 +93,8 @@ class RepoRef(SecondaryObject, PrivacyBase, NoteBase, RefBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.ref: diff --git a/src/gen/lib/src.py b/src/gen/lib/src.py index 4ddc8d4cf..a746f23e2 100644 --- a/src/gen/lib/src.py +++ b/src/gen/lib/src.py @@ -89,13 +89,13 @@ class Source(MediaBase, NoteBase, PrimaryObject): Return True if the object has reference to a given handle of given primary object type. - @param classname: The name of the primary object class. - @type classname: str - @param handle: The handle to be checked. - @type handle: str - @return: Returns whether the object has reference to this handle of + :param classname: The name of the primary object class. + :type classname: str + :param handle: The handle to be checked. + :type handle: str + :returns: Returns whether the object has reference to this handle of this object type. - @rtype: bool + :rtype: bool """ if classname == 'Repository': return handle in [ref.ref for ref in self.reporef_list] @@ -105,10 +105,10 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Remove all references in this object to object handles in the list. - @param classname: The name of the primary object class. - @type classname: str - @param handle_list: The list of handles to be removed. - @type handle_list: str + :param classname: The name of the primary object class. + :type classname: str + :param handle_list: The list of handles to be removed. + :type handle_list: str """ if classname == 'Repository': new_list = [ ref for ref in self.reporef_list \ @@ -119,12 +119,12 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Replace all references to old handle with those to the new handle. - @param classname: The name of the primary object class. - @type classname: str - @param old_handle: The handle to be replaced. - @type old_handle: str - @param new_handle: The handle to replace the old one with. - @type new_handle: str + :param classname: The name of the primary object class. + :type classname: str + :param old_handle: The handle to be replaced. + :type old_handle: str + :param new_handle: The handle to replace the old one with. + :type new_handle: str """ if classname == 'Repository': handle_list = [ref.ref for ref in self.reporef_list] @@ -137,8 +137,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.title, self.author, self.pubinfo, self.abbrev, self.gramps_id] + self.datamap.keys() + self.datamap.values() @@ -147,8 +147,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Return the list of child objects that may carry textual data. - @return: Returns the list of child objects that may carry textual data. - @rtype: list + :returns: Returns the list of child objects that may carry textual data. + :rtype: list """ return self.media_list + self.reporef_list @@ -156,9 +156,9 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return self.media_list @@ -166,9 +166,9 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Return the list of child secondary objects that may refer notes. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer notes. - @rtype: list + :rtype: list """ return self.media_list + self.reporef_list @@ -177,8 +177,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): Return the list of child objects which may, directly or through their children, reference primary objects. - @return: Returns the list of objects refereincing primary objects. - @rtype: list + :returns: Returns the list of objects refereincing primary objects. + :rtype: list """ return self.media_list + self.reporef_list @@ -187,8 +187,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ return self.get_referenced_note_handles() @@ -197,11 +197,11 @@ class Source(MediaBase, NoteBase, PrimaryObject): Return True if any of the child objects has reference to this source handle. - @param src_handle: The source handle to be checked. - @type src_handle: str - @return: Returns whether any of it's child objects has reference to + :param src_handle: The source handle to be checked. + :type src_handle: str + :returns: Returns whether any of it's child objects has reference to this source handle. - @rtype: bool + :rtype: bool """ for item in self.get_sourcref_child_list(): if item.has_source_reference(src_handle): @@ -214,8 +214,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): Remove references to all source handles in the list in all child objects. - @param src_handle_list: The list of source handles to be removed. - @type src_handle_list: list + :param src_handle_list: The list of source handles to be removed. + :type src_handle_list: list """ for item in self.get_sourcref_child_list(): item.remove_source_references(src_handle_list) @@ -225,10 +225,10 @@ class Source(MediaBase, NoteBase, PrimaryObject): Replace references to source handles in the list in this object and all child objects. - @param old_handle: The source handle to be replaced. - @type old_handle: str - @param new_handle: The source handle to replace the old one with. - @type new_handle: str + :param old_handle: The source handle to be replaced. + :type old_handle: str + :param new_handle: The source handle to replace the old one with. + :type new_handle: str """ for item in self.get_sourcref_child_list(): item.replace_source_references(old_handle, new_handle) @@ -249,8 +249,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Set the descriptive title of the Source object. - @param title: descriptive title to assign to the Source - @type title: str + :param title: descriptive title to assign to the Source + :type title: str """ self.title = title @@ -258,8 +258,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Return the descriptive title of the Place object. - @returns: Returns the descriptive title of the Place - @rtype: str + :returns: Returns the descriptive title of the Place + :rtype: str """ return self.title @@ -289,31 +289,31 @@ class Source(MediaBase, NoteBase, PrimaryObject): def add_repo_reference(self, repo_ref): """ - Add a L{RepoRef} instance to the Source's reporef list. + Add a :class:`~gen.lib.reporef,RepoRef` instance to the Source's reporef list. - @param repo_ref: L{RepoRef} instance to be added to the object's + :param repo_ref: :class:`~gen.lib.reporef,RepoRef` instance to be added to the object's reporef list. - @type repo_ref: L{RepoRef} + :type repo_ref: :class:`~gen.lib.reporef,RepoRef` """ self.reporef_list.append(repo_ref) def get_reporef_list(self): """ - Return the list of L{RepoRef} instances associated with the Source. + Return the list of :class:`~gen.lib.reporef,RepoRef` instances associated with the Source. - @Return: list of L{RepoRef} instances associated with the Source - @rtype: list + @Return: list of :class:`~gen.lib.reporef,RepoRef` instances associated with the Source + :rtype: list """ return self.reporef_list def set_reporef_list(self, reporef_list): """ - Set the list of L{RepoRef} instances associated with the Source. + Set the list of :class:`~gen.lib.reporef,RepoRef` instances associated with the Source. It replaces the previous list. - @param reporef_list: list of L{RepoRef} instances to be assigned to + :param reporef_list: list of :class:`~gen.lib.reporef,RepoRef` instances to be assigned to the Source. - @type reporef_list: list + :type reporef_list: list """ self.reporef_list = reporef_list @@ -321,11 +321,11 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Return True if the Source has reference to this Repository handle. - @param repo_handle: The Repository handle to be checked. - @type repo_handle: str - @return: Returns whether the Source has reference to this Repository + :param repo_handle: The Repository handle to be checked. + :type repo_handle: str + :returns: Returns whether the Source has reference to this Repository handle. - @rtype: bool + :rtype: bool """ return repo_handle in [repo_ref.ref for repo_ref in self.reporef_list] @@ -333,8 +333,8 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Remove references to all Repository handles in the list. - @param repo_handle_list: The list of Repository handles to be removed. - @type repo_handle_list: list + :param repo_handle_list: The list of Repository handles to be removed. + :type repo_handle_list: list """ new_reporef_list = [ repo_ref for repo_ref in self.reporef_list \ if repo_ref.ref not in repo_handle_list ] @@ -344,10 +344,10 @@ class Source(MediaBase, NoteBase, PrimaryObject): """ Replace all references to old Repository handle with the new handle. - @param old_handle: The Repository handle to be replaced. - @type old_handle: str - @param new_handle: The Repository handle to replace the old one with. - @type new_handle: str + :param old_handle: The Repository handle to be replaced. + :type old_handle: str + :param new_handle: The Repository handle to replace the old one with. + :type new_handle: str """ refs_list = [ repo_ref.ref for repo_ref in self.reporef_list ] n_replace = refs_list.count(old_handle) diff --git a/src/gen/lib/srcbase.py b/src/gen/lib/srcbase.py index bf925477f..3becc01ef 100644 --- a/src/gen/lib/srcbase.py +++ b/src/gen/lib/srcbase.py @@ -45,8 +45,8 @@ class SourceBase(object): """ Create a new SourceBase, copying from source if not None. - @param source: Object used to initialize the new object - @type source: SourceBase + :param source: Object used to initialize the new object + :type source: SourceBase """ if source: self.source_list = [SourceRef(sref) for sref in source.source_list] @@ -69,9 +69,9 @@ class SourceBase(object): """ Add a source reference to this object. - @param src_ref: The source reference to be added to the + :param src_ref: The source reference to be added to the SourceNote's list of source references. - @type src_ref: L{SourceRef} + :type src_ref: :class:`~gen.lib.srcref.SourceRef` """ self.source_list.append(src_ref) @@ -79,9 +79,9 @@ class SourceBase(object): """ Return the list of source references associated with the object. - @return: Returns the list of L{SourceRef} objects assocated with + :returns: Returns the list of :class:`~gen.lib.srcref.SourceRef` objects assocated with the object. - @rtype: list + :rtype: list """ return self.source_list @@ -89,9 +89,9 @@ class SourceBase(object): """ Return the list of child secondary objects that may refer sources. - @return: Returns the list of child secondary child objects that may + :returns: Returns the list of child secondary child objects that may refer sources. - @rtype: list + :rtype: list """ return [] @@ -100,11 +100,11 @@ class SourceBase(object): Return True if the object or any of it's child objects has reference to this source handle. - @param src_handle: The source handle to be checked. - @type src_handle: str - @return: Returns whether the object or any of it's child objects has + :param src_handle: The source handle to be checked. + :type src_handle: str + :returns: Returns whether the object or any of it's child objects has reference to this source handle. - @rtype: bool + :rtype: bool """ for src_ref in self.source_list: # Using direct access here, not the getter method -- efficiency! @@ -122,8 +122,8 @@ class SourceBase(object): Remove references to all source handles in the list in this object and all child objects. - @param src_handle_list: The list of source handles to be removed. - @type src_handle_list: list + :param src_handle_list: The list of source handles to be removed. + :type src_handle_list: list """ new_source_list = [ src_ref for src_ref in self.source_list \ if src_ref.ref not in src_handle_list ] @@ -137,10 +137,10 @@ class SourceBase(object): Replace references to source handles in the list in this object and all child objects. - @param old_handle: The source handle to be replaced. - @type old_handle: str - @param new_handle: The source handle to replace the old one with. - @type new_handle: str + :param old_handle: The source handle to be replaced. + :type old_handle: str + :param new_handle: The source handle to replace the old one with. + :type new_handle: str """ refs_list = [ src_ref.ref for src_ref in self.source_list ] n_replace = refs_list.count(old_handle) @@ -156,8 +156,8 @@ class SourceBase(object): """ Assign the passed list to the object's list of source references. - @param src_ref_list: List of source references to ba associated + :param src_ref_list: List of source references to ba associated with the object - @type src_ref_list: list of L{SourceRef} instances + :type src_ref_list: list of :class:`~gen.lib.srcref.SourceRef` instances """ self.source_list = src_ref_list diff --git a/src/gen/lib/srcref.py b/src/gen/lib/srcref.py index 0252ce6e5..d6bb62911 100644 --- a/src/gen/lib/srcref.py +++ b/src/gen/lib/srcref.py @@ -99,8 +99,8 @@ class SourceRef(SecondaryObject, DateBase, PrivacyBase, NoteBase, RefBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.page] @@ -109,8 +109,8 @@ class SourceRef(SecondaryObject, DateBase, PrivacyBase, NoteBase, RefBase): Return the list of (classname, handle) tuples for all directly referenced primary objects. - @return: List of (classname, handle) tuples for referenced objects. - @rtype: list + :returns: List of (classname, handle) tuples for referenced objects. + :rtype: list """ ret = self.get_referenced_note_handles() if self.ref: diff --git a/src/gen/lib/styledtext.py b/src/gen/lib/styledtext.py index 6d037e4c4..8e23f9bfc 100644 --- a/src/gen/lib/styledtext.py +++ b/src/gen/lib/styledtext.py @@ -41,8 +41,10 @@ class StyledText(object): formatting tags together. StyledText provides several string methods in order to manipulate - formatted strings, such as L{join}, L{replace}, L{split}, and also - supports the '+' operation (L{__add__}). + 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__`). 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. @@ -51,31 +53,29 @@ class StyledText(object): is intended to replace (or extend) the current report interface. To be continued... FIXME - @ivar string: The clear text part. - @type string: str - @ivar tags: Text tags holding formatting information for the string. - @type tags: list of L{StyledTextTag} + :ivar string: (str) The clear text part. + :ivar tags: (list of :class:`~gen.lib.styledtexttag.StyledTextTag`) Text + tags holding formatting information for the string. - @cvar POS_TEXT: Position of I{string} attribute in the serialized format of - an instance. - @type POS_TEXT: int - @cvar POS_TAGS: Position of I{tags} attribute in the serialized format of - an instance. - @type POS_TAGS: int + :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. - @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! + :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! - @note: - 1. There is no sanity check of tags in L{__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 L{__init__}, however - StyledTextBuffer will merge them automatically if the text is displayed. + :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. """ (POS_TEXT, POS_TAGS) = range(2) @@ -97,10 +97,10 @@ class StyledText(object): def __add__(self, other): """Implement '+' operation on the class. - @param other: string to concatenate to self - @type other: basestring or StyledText - @returns: concatenated strings - @returntype: StyledText + :param other: string to concatenate to self + :type other: basestring or StyledText + :returns: concatenated strings + :returnstype: StyledText """ offset = len(self._string) @@ -128,10 +128,10 @@ class StyledText(object): def join(self, seq): """Emulate __builtin__.str.join method. - @param seq: list of strings to join - @type seq: basestring or StyledText - @returns: joined strings - @returntype: StyledText + :param seq: list of strings to join + :type seq: basestring or StyledText + :returns: joined strings + :returnstype: StyledText """ new_string = self._string.join([str(string) for string in seq]) @@ -154,14 +154,14 @@ class StyledText(object): def replace(self, old, new, count=-1): """Emulate __builtin__.str.replace method. - @param old: substring to be replaced - @type old: basestring or StyledText - @param new: substring to replace by - @type new: StyledText - @param count: if given, only the first count occurrences are replaced - @type count: int - @returns: copy of the string with replaced substring(s) - @returntype: StyledText + :param old: substring to be replaced + :type old: basestring or StyledText + :param new: substring to replace by + :type new: 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 @attention: by the correct implementation parameter I{new} should be StyledText or basestring, however only StyledText @@ -173,12 +173,12 @@ class StyledText(object): def split(self, sep=None, maxsplit=-1): """Emulate __builtin__.str.split method. - @param sep: the delimiter string - @type seq: basestring or StyledText - @param maxsplit: if given, at most maxsplit splits are done - @type maxsplit: int - @returns: a list of the words in the string - @returntype: list of StyledText + :param sep: the delimiter string + :type seq: basestring or 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 """ # split the clear text first @@ -218,8 +218,8 @@ class StyledText(object): def serialize(self): """Convert the object to a serialized tuple of data. - @returns: Serialized format of the instance. - @returntype: tuple + :returns: Serialized format of the instance. + :returnstype: tuple """ if self._tags: @@ -232,8 +232,8 @@ class StyledText(object): def unserialize(self, data): """Convert a serialized tuple of data to an object. - @param data: Serialized format of instance variables. - @type data: tuple + :param data: Serialized format of instance variables. + :type data: tuple """ (self._string, the_tags) = data @@ -248,8 +248,8 @@ class StyledText(object): def get_tags(self): """Return the list of formatting tags. - @returns: The formatting tags applied on the text. - @returntype: list of 0 or more L{StyledTextTag} instances. + :returns: The formatting tags applied on the text. + :returnstype: list of 0 or more :class:`~gen.lib.styledtexttag.StyledTextTag` instances. """ return self._tags diff --git a/src/gen/lib/styledtexttag.py b/src/gen/lib/styledtexttag.py index 5ee4b6164..38ac09ecf 100644 --- a/src/gen/lib/styledtexttag.py +++ b/src/gen/lib/styledtexttag.py @@ -40,17 +40,17 @@ class StyledTextTag(): 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: L{gen.lib.StyledTextTagType} instace + :type name: :class:`~gen.lib.styledtexttagtype.StyledTextTagType` instace @ivar value: Value of the tag. E.g. color hex string for font color, etc. - @type value: str or None + :type value: str or None @ivar ranges: Pointer pairs into the string, where the tag applies. - @type ranges: list of (int(start), int(end)) tuples. + :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 L{GrampsType} supports the instance initialization + @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. @@ -66,8 +66,8 @@ class StyledTextTag(): def serialize(self): """Convert the object to a serialized tuple of data. - @returns: Serialized format of the instance. - @returntype: tuple + :returns: Serialized format of the instance. + :returnstype: tuple """ return (self.name.serialize(), self.value, self.ranges) @@ -75,8 +75,8 @@ class StyledTextTag(): def unserialize(self, data): """Convert a serialized tuple of data to an object. - @param data: Serialized format of instance variables. - @type data: tuple + :param data: Serialized format of instance variables. + :type data: tuple """ (the_name, self.value, self.ranges) = data diff --git a/src/gen/lib/styledtexttagtype.py b/src/gen/lib/styledtexttagtype.py index 2e0b94984..1ec5bcec1 100644 --- a/src/gen/lib/styledtexttagtype.py +++ b/src/gen/lib/styledtexttagtype.py @@ -44,7 +44,7 @@ from gen.lib.grampstype import GrampsType class StyledTextTagType(GrampsType): """Text formatting tag type definition. - Here we only define new class variables. For details see L{GrampsType}. + Here we only define new class variables. For details see :class:`~gen.lib.grampstype.GrampsType`. """ NONE_TYPE = -1 diff --git a/src/gen/lib/url.py b/src/gen/lib/url.py index a407fcae1..bde2a61d7 100644 --- a/src/gen/lib/url.py +++ b/src/gen/lib/url.py @@ -77,8 +77,8 @@ class Url(SecondaryObject, PrivacyBase): """ Return the list of all textual attributes of the object. - @return: Returns the list of all textual attributes of the object. - @rtype: list + :returns: Returns the list of all textual attributes of the object. + :rtype: list """ return [self.path, self.desc] @@ -100,15 +100,15 @@ class Url(SecondaryObject, PrivacyBase): def set_type(self, the_type): """ - @param the_type: descriptive type of the Url - @type the_type: str + :param the_type: descriptive type of the Url + :type the_type: str """ self.type.set(the_type) def get_type(self): """ - @returns: the descriptive type of the Url - @rtype: str + :returns: the descriptive type of the Url + :rtype: str """ return self.type diff --git a/src/gen/lib/urlbase.py b/src/gen/lib/urlbase.py index 165bf14e2..fcdd4cc6b 100644 --- a/src/gen/lib/urlbase.py +++ b/src/gen/lib/urlbase.py @@ -48,8 +48,8 @@ class UrlBase(object): If the source is not None, then object is initialized from values of the source object. - @param source: Object used to initialize the new object - @type source: UrlBase + :param source: Object used to initialize the new object + :type source: UrlBase """ if source: @@ -71,43 +71,43 @@ class UrlBase(object): def get_url_list(self): """ - Return the list of L{Url} instances associated with the object. + Return the list of :class:`~gen.lib.url.Url` instances associated with the object. - @returns: List of L{Url} instances - @rtype: list + :returns: List of :class:`~gen.lib.url.Url` instances + :rtype: list """ return self.urls def set_url_list(self, url_list): """ - Set the list of L{Url} instances to passed the list. + Set the list of :class:`~gen.lib.url.Url` instances to passed the list. - @param url_list: List of L{Url} instances - @type url_list: list + :param url_list: List of :class:`~gen.lib.url.Url` instances + :type url_list: list """ self.urls = url_list def add_url(self, url): """ - Add a L{Url} instance to the object's list of L{Url} instances. + Add a :class:`~gen.lib.url.Url` instance to the object's list of :class:`~gen.lib.url.Url` instances. - @param url: L{Url} instance to be added to the Person's list of + :param url: :class:`~gen.lib.url.Url` instance to be added to the Person's list of related web sites. - @type url: L{Url} + :type url: :class:`~gen.lib.url.Url` """ self.urls.append(url) def remove_url(self, url): """ - Remove the specified L{Url} instance from the url list. + Remove the specified :class:`~gen.lib.url.Url` instance from the url list. If the instance does not exist in the list, the operation has no effect. - @param url: L{Url} instance to remove from the list - @type url: L{Url} + :param url: :class:`~gen.lib.url.Url` instance to remove from the list + :type url: :class:`~gen.lib.url.Url` - @return: True if the url was removed, False if it was not in the list. - @rtype: bool + :returns: True if the url was removed, False if it was not in the list. + :rtype: bool """ if url in self.urls: self.urls.remove(url) diff --git a/src/glade.py b/src/glade.py index 2fac1295e..d9088f29e 100644 --- a/src/glade.py +++ b/src/glade.py @@ -65,18 +65,18 @@ class Glade(gtk.Builder): """ Class Constructor: Returns a new instance of the Glade class - @type filename: string - @param filename: The name of the glade file to be used. Defaults to None - @type dirname: string - @param dirname: The directory to search for the glade file. Defaults to + :type filename: string + :param filename: The name of the glade file to be used. Defaults to None + :type dirname: string + :param dirname: The directory to search for the glade file. Defaults to None which will cause a search for the file in the default directory followed by the directory of the calling module. - @type toplevel: toplevel - @param toplevel: The toplevel object to search for in the glade file. + :type toplevel: toplevel + :param toplevel: The toplevel object to search for in the glade file. Defaults to None, which will cause a search for a toplevel matching the file name. - @rtype: object reference - @return: reference to the newly-created Glade instance + :rtype: object reference + :returns: reference to the newly-created Glade instance """ gtk.Builder.__init__(self) @@ -149,8 +149,8 @@ class Glade(gtk.Builder): def __get_filename(self): """ __get_filename: return filename of glade file - @rtype: string - @return: filename of glade file + :rtype: string + :returns: filename of glade file """ return self.__filename @@ -159,8 +159,8 @@ class Glade(gtk.Builder): def __get_dirname(self): """ __get_dirname: return directory where glade file found - @rtype: string - @return: directory where glade file found + :rtype: string + :returns: directory where glade file found """ return self.__dirname @@ -169,8 +169,8 @@ class Glade(gtk.Builder): def __get_toplevel(self): """ __get_toplevel: return toplevel object - @rtype: object - @return: toplevel object + :rtype: object + :returns: toplevel object """ return self.__toplevel @@ -178,8 +178,8 @@ class Glade(gtk.Builder): """ __set_toplevel: set toplevel object - @type toplevel: string - @param toplevel: The name of the toplevel object to use + :type toplevel: string + :param toplevel: The name of the toplevel object to use """ self.__toplevel = self.get_object(toplevel) @@ -190,12 +190,12 @@ class Glade(gtk.Builder): get_child_object: search for a child object, by name, within a given toplevel. If no toplevel argument is supplied, use the toplevel attribute for this instance - @type value: string - @param value: The name of the child object to find - @type toplevel: string - @param toplevel: The name of the toplevel object to us - @rtype: object - @return: child object + :type value: string + :param value: The name of the child object to find + :type toplevel: string + :param toplevel: The name of the toplevel object to us + :rtype: object + :returns: child object """ if not toplevel: diff --git a/src/plugins/lib/libhtml.py b/src/plugins/lib/libhtml.py index 90642761d..bf4702311 100644 --- a/src/plugins/lib/libhtml.py +++ b/src/plugins/lib/libhtml.py @@ -128,12 +128,12 @@ class Html(list): """ Build and return an XML declaration statement - @type version: decimal number - @param version: version of XML to be used. Defaults to 1.0 - @type encoding: string - @param encoding: encoding method to be used. Defaults to "UTF-8" - @type standalone: string - @param standalone: "yes" or "no". Defaults to "no" + :type version: decimal number + :param version: version of XML to be used. Defaults to 1.0 + :type encoding: string + :param encoding: encoding method to be used. Defaults to "UTF-8" + :type standalone: string + :param standalone: "yes" or "no". Defaults to "no" """ return '' % ( 'version="%s"' % version, @@ -146,15 +146,15 @@ class Html(list): """ Build and return a DOCTYPE statement - @type name: string - @param name: name of this DOCTYPE. Defaults to "html" - @type public: string - @param public: class of this DOCTYPE. Defaults to 'PUBLIC - @type external_id: string - @param external_id: external identifier of this DOCTYPE. + :type name: string + :param name: name of this DOCTYPE. Defaults to "html" + :type public: string + :param public: class of this DOCTYPE. Defaults to 'PUBLIC + :type external_id: string + :param external_id: external identifier of this DOCTYPE. Defaults to XHTML 1.0 STRICT - @type args: object - @param args: 0 or more positional parameters to be added to this + :type args: object + :param args: 0 or more positional parameters to be added to this DOCTYPE. """ return '' % ( @@ -168,12 +168,12 @@ class Html(list): """ Build and return a properly-formated object - @type xmlns: string - @param xmlns: XML namespace string. Default = 'http://www.w3.org/1999/xhtml' - @type lang: string - @param lang: language to be used. Defaul = 'en' - @rtype: reference to new Html instance - @return: reference to the newly-created Html instances for object + :type xmlns: string + :param xmlns: XML namespace string. Default = 'http://www.w3.org/1999/xhtml' + :type lang: string + :param lang: language to be used. Defaul = 'en' + :rtype: reference to new Html instance + :returns: reference to the newly-created Html instances for object """ return Html('html', indent=False, @@ -187,13 +187,13 @@ class Html(list): """ Build and return a properly-formated object - @type title: string or None - @param title: title for HTML page. Default=None. If None no + :type title: string or None + :param title: title for HTML page. Default=None. If None no title tag is written - @type encoding: string - @param encoding: encoding to be used. Default = 'utf-8' - @rtype reference to new Html instance - @return reference to the newly-created Html instances for object + :type encoding: string + :param encoding: encoding to be used. Default = 'utf-8' + :rtype: reference to new Html instance + :returns: reference to the newly-created Html instances for object """ meta1 = 'http-equiv="content-type" content="text/html;charset=%s"' meta2 = 'http-equiv="Content-Style-Type" content="text/css"' @@ -209,14 +209,14 @@ class Html(list): """ This function prepares a new Html class based page and returns - @type title: string - @param title: title for HTML page. Default=None - @type encoding: string - @param encoding: encoding to be used. Default = 'utf-8' - @type lang: string - @param lang: language to be used. Defaul = 'en' - @rtype: three object references - @return: references to the newly-created Html instances for + :type title: string + :param title: title for HTML page. Default=None + :type encoding: string + :param encoding: encoding to be used. Default = 'utf-8' + :type lang: string + :param lang: language to be used. Defaul = 'en' + :rtype: three object references + :returns: references to the newly-created Html instances for page, head and body """ page = Html.html(lang=lang, *args, **keywargs) @@ -238,34 +238,34 @@ class Html(list): """ Class Constructor: Returns a new instance of the Html class - @type tag: string - @param tag: The HTML tag. Default is 'html' - @type args: optional positional parameters - @param args: 0 more positional arguments to be inserted between + :type tag: string + :param tag: The HTML tag. Default is 'html' + :type args: optional positional parameters + :param args: 0 more positional arguments to be inserted between opening and closing HTML tags. - @type indent: boolean or None - @param indent: True ==> indent this object with respect to its parent + :type indent: boolean or None + :param indent: True ==> indent this object with respect to its parent False ==> do not indent this object None ==> no indent for this object (use eg for pre tag) Defaults to True - @type inline: boolean - @param inline: True ==> instructs the write() method to output this + :type inline: boolean + :param inline: True ==> instructs the write() method to output this object and any child objects as a single string False ==> output this object and its contents one string at a time Defaults to False - @type close: boolean or None - @param close: True ==> this tag should be closed normally + :type close: boolean or None + :param close: True ==> this tag should be closed normally e.g. ... False ==> this tag should be automatically closed e.g. None ==> do not provide any closing for this tag - @type keywargs: optional keyword parameters - @param keywargs: 0 or more keyword=argument pairs that should be + :type keywargs: optional keyword parameters + :param keywargs: 0 or more keyword=argument pairs that should be copied into the opening tag as keyword="argument" attributes - @rtype: object reference - @return: reference to the newly-created Html instance + :rtype: object reference + :returns: reference to the newly-created Html instance For full usage of the Html class with examples, please see the wiki page at: http://www.gramps-project.org/wiki/index.php?title=Libhtml @@ -314,11 +314,11 @@ class Html(list): Helper function for +, +=, operators and append() and extend() methods - @type value: object - @param value: object to be added + :type value: object + :param value: object to be added - @rtype: object reference - @return: reference to object with new value added + :rtype: object reference + :returns: reference to object with new value added """ if isinstance(value, Html) or not hasattr(value, '__iter__'): value = [value] @@ -344,24 +344,24 @@ class Html(list): """ Replace current value with new value - @type cur_value: object - @param cur_value: value of object to be replaced - @type value: object - @param value: replacement value + :type cur_value: object + :param cur_value: value of object to be replaced + :type value: object + :param value: replacement value - @rtype: object reference - @return: reference to object with new value added + :rtype: object reference + :returns: reference to object with new value added """ self[self.index(cur_value)] = value # def __sub__(self, value): """ Overload function for - and -= operators - @type value: object - @param value: object to be removed + :type value: object + :param value: object to be removed - @rtype: object reference - @return: reference to object with value removed + :rtype: object reference + :returns: reference to object with value removed """ del self[self.index(value)] return self @@ -372,8 +372,8 @@ class Html(list): """ Returns string representation - @rtype: string - @return: string representation of object + :rtype: string + :returns: string representation of object """ return '%s'*len(self) % tuple(self[:]) # @@ -396,12 +396,12 @@ class Html(list): Output function: performs an insertion-order tree traversal and calls supplied method for each item found. - @type method: function reference - @param method: function to call with each item found - @type indent: string - @param indenf: string to use for indentation. Default = '\t' (tab) - @type tabs: string - @param tabs: starting indentation + :type method: function reference + :param method: function to call with each item found + :type indent: string + :param indenf: string to use for indentation. Default = '\t' (tab) + :type tabs: string + :param tabs: starting indentation """ if self.indent is None: tabs = '' @@ -421,12 +421,12 @@ class Html(list): """ Add an XML statement to the start of the list for this object - @type version: decimal number - @param version: version of XML to be used. Defaults to 1.0 - @type encoding: string - @param encoding: encoding method to be used. Defaults to "UTF-8" - @type standalone: string - @param standalone: "yes" or "no". Defaults to "no" + :type version: decimal number + :param version: version of XML to be used. Defaults to 1.0 + :type encoding: string + :param encoding: encoding method to be used. Defaults to "UTF-8" + :type standalone: string + :param standalone: "yes" or "no". Defaults to "no" """ xmldecl = Html.xmldecl( version=version, @@ -439,13 +439,13 @@ class Html(list): """ Add a DOCTYPE statement to the start of the list - @type name: string - @param name: name of this DOCTYPE. Defaults to "html" - @type external_id: string - @param external_id: external identifier of this DOCTYPE. + :type name: string + :param name: name of this DOCTYPE. Defaults to "html" + :type external_id: string + :param external_id: external identifier of this DOCTYPE. Defaults to XHTML 1.0 STRICT - @type args: object - @param args: 0 or more positional parameters to be added to this + :type args: object + :param args: 0 or more positional parameters to be added to this DOCTYPE. """ doctype = '' % ( @@ -464,8 +464,8 @@ class Html(list): """ Returns HTML tag for this object - @rtype: string - @return: HTML tag + :rtype: string + :returns: HTML tag """ return self[0].split()[0].strip('< >') # @@ -473,8 +473,8 @@ class Html(list): """ Sets a new HTML tag for this object - @type name: string - @param name: new HTML tag + :type name: string + :param name: new HTML tag """ curtag = self.tag if self[-1] == '' % curtag: @@ -486,8 +486,8 @@ class Html(list): """ Returns HTML attributes for this object - @rtype: string - @return: HTML attributes + :rtype: string + :returns: HTML attributes """ attr = self[0].strip('').split(None, 1) return attr[1] if len(attr) > 1 else '' @@ -496,8 +496,8 @@ class Html(list): """ Sets new HTML attributes for this object - @type name: string - @param name: new HTML attributes + :type name: string + :param name: new HTML attributes """ self[0] = self[0][:len(self.tag)+1] + ' ' + value + self[0][-1:] # @@ -512,8 +512,8 @@ class Html(list): """ Returns list of items between opening and closing tags - @rtype: list - @return: list of items between opening and closing HTML tags + :rtype: list + :returns: list of items between opening and closing HTML tags """ return self[1:-1] # @@ -521,8 +521,8 @@ class Html(list): """ Sets new contents between opening and closing tags - @type name: list - @param name: new HTML contents + :type name: list + :param name: new HTML contents """ if len(self) < 2: raise AttributeError, 'No closing tag. Cannot set inside value'