Improve gen.utils documentation

This commit is contained in:
Nick Hall 2013-11-12 21:43:38 +00:00
parent 2c1ba1496b
commit ceb3f44205
7 changed files with 227 additions and 183 deletions

View File

@ -4,12 +4,12 @@ The :mod:`gramps.gen.utils` Module
.. automodule:: gramps.gen.utils
Utils
**********************************
Utilities
**********************************
Callback
====================================
.. automodule:: gramps.gen.utils.alive
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.callback
:members:
:undoc-members:
@ -18,7 +18,10 @@ Utils
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.cast
Configuration
====================================
.. automodule:: gramps.gen.utils.configmanager
:members:
:undoc-members:
:show-inheritance:
@ -26,7 +29,10 @@ Utils
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.configmanager
Database
====================================
.. automodule:: gramps.gen.utils.alive
:members:
:undoc-members:
:show-inheritance:
@ -34,45 +40,62 @@ Utils
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.file
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.grampslocale
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.id
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.image
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.keyword
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.lds
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.maclocale
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.place
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.string
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.unknown
:members:
:undoc-members:
:show-inheritance:
File
====================================
.. automodule:: gramps.gen.utils.file
:members:
:undoc-members:
:show-inheritance:
Image
====================================
.. automodule:: gramps.gen.utils.image
:members:
:undoc-members:
:show-inheritance:
Locale
====================================
.. automodule:: gramps.gen.utils.grampslocale
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.maclocale
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.keyword
:members:
:undoc-members:
:show-inheritance:
Place
====================================
.. automodule:: gramps.gen.utils.place
:members:
:undoc-members:
:show-inheritance:
Other
====================================
.. automodule:: gramps.gen.utils.cast
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.id
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.lds
:members:
:undoc-members:
:show-inheritance:
.. automodule:: gramps.gen.utils.string
:members:
:undoc-members:
:show-inheritance:

View File

@ -22,8 +22,7 @@
# $Id$
"""
Introduction
============
**Introduction**
Gramps is devided into two parts. The database code, that does not
require any particular GUI libraries, and the gtk-based UI code
@ -54,11 +53,10 @@ class Callback(object):
"""
Callback and signal support objects.
Declaring signals
=================
**Declaring signals**
Classes that want to emit signals need to inherit from the
DBCallback class and ensure that its __init__ method
DBCallback class and ensure that its :meth:`__init__` method
is called. They then need to declare the signals that they
can emit and the types of each callbacks arguments. For
example::
@ -85,8 +83,7 @@ class Callback(object):
signal names in subclasses are not alowed.
Emitting signals
================
**Emitting signals**
Signals are emitted using the emit method. e.g.::
@ -96,8 +93,7 @@ class Callback(object):
The parameters are passed as a tuple so a single parameter
must be passed as a 1 element tuple.
Connecting callbacks to signals
===============================
**Connecting callbacks to signals**
Attaching a callback to the signals is similar to the gtk
connect methods. e.g.::
@ -119,8 +115,7 @@ class Callback(object):
t.connect('test-signal', r.cb_func)
Disconnecting callbacks
=======================
**Disconnecting callbacks**
If you want to disconnect a callback from a signals you must remember the
key returned from the connect call. This key can be passed to the disconnect
@ -144,13 +139,12 @@ class Callback(object):
t.disconnect(key)
Stopping and starting signals
=============================
**Stopping and starting signals**
Signals can be blocked on a per instance bassis or they can be blocked
for all instances of the Callback class. disable_signals() can
be used to block the signals for a single instance and disable_all_signals()
can be used to block signals for the class:
for all instances of the Callback class. :meth:`disable_signals` can
be used to block the signals for a single instance and
:meth:`disable_all_signals` can be used to block signals for the class:
e.g.::
@ -190,14 +184,13 @@ class Callback(object):
Any signals emitted whilst signals are blocked will be lost.
Debugging signal callbacks
==========================
**Debugging signal callbacks**
To help with debugging the signals and callbacks you can turn on
lots of logging information. To switch on logging for a single
instance call self.enable_logging(), to switch it off again call
self.disable_logging(). To switch on logging for all instance
instance call :meth:`enable_logging`, to switch it off again call
:meth:`disable_logging`. To switch on logging for all instance
you can toggle Callback.__LOG_ALL to True.
"""
@ -277,7 +270,7 @@ class Callback(object):
with the signal is emitted. The callable must accept the argument
types declared in the signals signature.
returns a unique key that can be passed to disconnect().
returns a unique key that can be passed to :meth:`disconnect`.
"""
# Check that signal exists.
if signal_name not in self.__signal_map:

View File

@ -23,7 +23,7 @@
# $Id$
"""
This package implements access to GRAMPS configuration.
This package implements access to Gramps configuration.
"""
#---------------------------------------------------------------
@ -79,7 +79,7 @@ class ConfigManager(object):
Configure manager constructor takes an optional filename, and
plugin path.
The data dictionary stores the settings:
The data dictionary stores the settings::
self.data[section][setting] = value
@ -93,11 +93,11 @@ class ConfigManager(object):
simple types.
The default values are given in Python code and stored here
on start-up:
on start-up::
self.default[section][setting] = default_value
Callbacks are stored as callables here:
Callbacks are stored as callables here::
self.callbacks[section][setting] = (id, func)
@ -105,8 +105,8 @@ class ConfigManager(object):
is stored as self.filename. However, you can save to another
filename using self.save(otherfilename).
filename (if given) is a fullpath.
plugins (if given) is a relative path to filename.
:param filename: (if given) is a fullpath.
:param plugins: (if given) is a relative path to filename.
"""
self._cb_id = 0 # callback id counter
@ -124,21 +124,25 @@ class ConfigManager(object):
"""
Register a plugin manager.
name is used as the key of the config manager singleton. It is
also be used as the base filename (unless an override is given,
or use_config_path or use_plugins_path is True).
:param name: is used as the key of the config manager singleton. It is
also be used as the base filename (unless an override is
given, or use_config_path or use_plugins_path is True).
:param override: is used to override the default location of the .ini
file.
:param use_config_path: if True, use this ConfigManager's path as the
new manager's path, ignoring any path given in
override.
Override is either:
override is either:
- a full path+filename ending in .ini
- a filename ending in .ini
- a dir path to put ini file into
- a full path+filename to get dir to put ini file into
- a ConfigManager instance
If use_config_path is True, use this ConfigManager's path as
the new manager's path, ignoring any path given in override.
Examples::
Examples:
>>> config.register_manager("Simple", use_plugins_path=False)
# will use the calling programs directory, and "Simple.ini"
>>> config.register_manager("Simple", __file__,
@ -510,7 +514,7 @@ class ConfigManager(object):
def set(self, key, value):
"""
Set the setting's value. There are only two ways to get into
the data dictionary: via the load() method that reads a file,
the data dictionary: via the :meth:`load` method that reads a file,
or from this method.
"""
if "." in key:

View File

@ -94,9 +94,11 @@ def get_death_or_fallback(db, person, format=None):
def get_age(db, person, fallback=True, calendar="gregorian"):
"""
Compute the age of person. Allow fallback events if fallback=True
person : person handle or person object
Return: tuple of year, month day if valid, None otherwise
Compute the age of person.
:param person: person handle or person object
:param fallback: Allow fallback events if True
:returns: tuple of year, month day if valid, None otherwise
"""
birth = None
death = None
@ -136,8 +138,9 @@ def get_age(db, person, fallback=True, calendar="gregorian"):
def get_timeperiod(db, person):
"""
Compute the timeperiod a person lived in
person : person handle or person object
Return: the year, None otherwise
:param person: person handle or person object
:returns: the year, None otherwise
"""
if isinstance(person, str):
# a handle is passed
@ -254,7 +257,7 @@ def get_participant_from_event(db, event_handle, all_=False):
Obtain the first primary or family participant to an event we find in the
database. Note that an event can have more than one primary or
family participant, only one is returned, adding ellipses if there are
more. If the all_ parameter is true a comma-space separated string with
more. If the all\_ parameter is true a comma-space separated string with
the names of all primary participants is returned and no ellipses is used.
"""
participant = ""
@ -593,31 +596,32 @@ def get_source_and_citation_referents(source_handle, db):
This function finds all primary objects that refer (directly or through
secondary child-objects) to a given source handle in a given database.
Objects -> Citations -> Source
e.g.
Media object M1 -> Citation C1 -> Source S1
Media object M2 -> Citation C1 -> Source S1
Person object P1 -> Citation C2 -> Source S1
| Objects -> Citations -> Source
| e.g.
| Media object M1 -> Citation C1 -> Source S1
| Media object M2 -> Citation C1 -> Source S1
| Person object P1 -> Citation C2 -> Source S1
The returned structure is rather ugly, but provides all the information in
a way that is consistent with the other Util functions.
(
tuple of objects that refer to the source - only first element is present
([C1, C2],),
list of citations with objects that refer to them
[
(C1,
tuple of reference lists
P, F, E, Pl, S, M, R
([], [], [], [], [], [M1, M2]. [])
)
(C2,
tuple of reference lists
P, F, E, Pl, S, M, R
([P1], [], [], [], [], []. [])
)
]
)
| (
| tuple of objects that refer to the source - only first element is present
| ([C1, C2],),
| list of citations with objects that refer to them
| [
| (C1,
| tuple of reference lists
| P, F, E, Pl, S, M, R
| ([], [], [], [], [], [M1, M2]. [])
| )
| (C2,
| tuple of reference lists
| P, F, E, Pl, S, M, R
| ([P1], [], [], [], [], []. [])
| )
| ]
| )
"""
the_lists = get_source_referents(source_handle, db)
LOG.debug('source referents %s' % [the_lists])

View File

@ -145,16 +145,16 @@ class GrampsLocale(object):
new GrampsLocale instance with the specified parameters, but any
parameters left out will be filled in from the first instance.
@localedir: The full path to the top level directory containing
the translation files. Defaults to sys.prefix/share/locale.
:param localedir: The full path to the top level directory containing the
translation files. Defaults to sys.prefix/share/locale.
@lang: A single locale value which is used for unset locale.LC_FOO
:param lang: A single locale value which is used for unset locale.LC_FOO
settings.
@domain: The name of the applicable translation file. The default is
:param domain: The name of the applicable translation file. The default is
"gramps", indicating files in LC_MESSAGES named gramps.mo.
@languages: String with a ':'-separated list of two or five character
:param languages: String with a ':'-separated list of two or five character
codes corresponding to subidrectries in the localedir,
e.g.: "fr" or "zh_CN".
"""
@ -632,7 +632,8 @@ class GrampsLocale(object):
cached, set it from datehandler.LANG_TO_DISPLAY. If one isn't
available for the selected locale, attempt to fall back on the
first_instance's locale before settling on the 'C' displayer.
NB: This is the getter for the date_displayer property
.. note:: This is the getter for the date_displayer property
"""
if self._dd:
return self._dd
@ -665,7 +666,8 @@ class GrampsLocale(object):
cached, set it from datehandler.LANG_TO_PARSER. If one isn't
available for the selected locale, attempt to fall back on the
first_instance's locale before settling on the 'C' parser.
NB: This is the getter for the date_parser property
.. note:: This is the getter for the date_parser property
"""
if self._dp:
return self._dp
@ -712,18 +714,19 @@ class GrampsLocale(object):
"""
Get a translator for an addon.
filename - filename of a file in directory with full path, or
:param filename: filename of a file in directory with full path, or
None to get from self.
domain - the name of the .mo file under the LANG/LC_MESSAGES dir
languages - a list of languages to force
returns - a gettext.translation object
:param domain: the name of the .mo file under the LANG/LC_MESSAGES dir
:param languages: a list of languages to force
:returns: a gettext.translation object
Example::
Example:
_ = glocale.get_addon_translator(languages=["fr_BE.utf8"]).gettext
See the python gettext documentation.
Assumes path/filename
path/locale/LANG/LC_MESSAGES/addon.mo.
.. seealso:: the python gettext documentation.
Assumes path/filename = path/locale/LANG/LC_MESSAGES/addon.mo.
"""
gramps_translator = self._get_translation()
@ -954,8 +957,9 @@ class Lexeme(_LexemeBaseStr):
Created with :meth:`~GrampsTranslations.lexgettext`
.. rubric:: Example
Python code:
::
Python code::
_ = lexgettext
dec = _("localized lexeme inflections||December")
xmas = _("lexeme||Christmas")
@ -965,8 +969,8 @@ class Lexeme(_LexemeBaseStr):
XMAS = xmas.upper()
print ("\n".join([XMAS, text, greeting]))
Translation database (Russian example):
::
Translation database (Russian example)::
msgid "lexeme||December"
msgstr "NOMINATIVE=декабрь|GENITIVE=декабря|ABLATIVE=декабрём|LOCATIVE=декабре"
@ -979,19 +983,20 @@ class Lexeme(_LexemeBaseStr):
msgid "Merry {holiday}!"
msgstr "Счастливого {holiday.f[GENITIVE]}!"
Prints out:
Prints out::
In English locale:
::
CHRISTMAS
Christmas is celebrated in December
Merry Christmas!
In Russian locale:
::
РОЖДЕСТВО
рождество празднуют в декабре
Счастливого рождества!
.. rubric:: Description
Stores an arbitrary number of forms, e.g., inflections.
These forms are accessible under dictionary keys for each form.
The names of the forms are language-specific. They are assigned
@ -1013,14 +1018,15 @@ class Lexeme(_LexemeBaseStr):
the same nominative form in capital letters.
.. rubric:: Motivation
Lexeme is the term used in linguistics for the set of forms taken
by a particular word, e.g. cases for a noun or tenses for a verb.
Gramps often needs to compose sentences from several blocks of
text and single words, often by using python string formatting.
For instance, formatting a date range is done similarly to this:
::
For instance, formatting a date range is done similarly to this::
_("Between {startdate_month} {startdate_year}"
"and {enddate_month} {enddate_year}").format(
startdate_month = m1,

View File

@ -323,30 +323,44 @@ def __convert_float_val(val, typedeg = "lat"):
def conv_lat_lon(latitude, longitude, format="D.D4"):
"""
Convert given string latitude and longitude to a required format.
:param latitude: Latitude
:type latitude: string
:param longitude: Longitude
:type longitude: string
:param format: Ouput format
:type format: string
:returns: a tuple of 2 strings, or a string (for ISO formats). If
conversion fails: returns: (None, None) or None (for ISO formats)
Possible formats:
'D.D4' : degree notation, 4 decimals
========= ============================================================
Format Description
========= ============================================================
'D.D4' degree notation, 4 decimals
eg +12.0154 , -124.3647
'D.D8' : degree notation, 8 decimals (precision like ISO-DMS)
'D.D8' degree notation, 8 decimals (precision like ISO-DMS)
eg +12.01543265 , -124.36473268
'DEG' : degree, minutes, seconds notation
'DEG' degree, minutes, seconds notation
eg 50°52'21.92''N , 124°52'21.92''E ° has UTF-8 code c2b00a
or N50º52'21.92" , E14º52'21.92" º has UTF-8 code c2ba0a
or N50º52.3456' , E14º52.9876' ; decimal minutes, no seconds
'DEG-:' : degree, minutes, seconds notation with :
'DEG-:' degree, minutes, seconds notation with :
eg -50:52:21.92 , 124:52:21.92
'ISO-D' : ISO 6709 degree notation i.e. ±DD.DDDD±DDD.DDDD
'ISO-DM' : ISO 6709 degree, minutes notation
'ISO-D' ISO 6709 degree notation i.e. ±DD.DDDD±DDD.DDDD
'ISO-DM' ISO 6709 degree, minutes notation
i.e. ±DDMM.MMM±DDDMM.MMM
'ISO-DMS' : ISO 6709 degree, minutes, seconds notation
'ISO-DMS' ISO 6709 degree, minutes, seconds notation
i.e. ±DDMMSS.SS±DDDMMSS.SS
'RT90' : Output format for the Swedish coordinate system RT90
'RT90' Output format for the Swedish coordinate system RT90
========= ============================================================
Return value: a tuple of 2 strings, or a string (for ISO formats)
If conversion fails: returns: (None, None) or None (for ISO formats)
Some generalities:
-90 <= latitude <= +90 with +00 the equator
-180 <= longitude < +180 with +000 prime meridian
and -180 180th meridian
* -90 <= latitude <= +90 with +00 the equator
* -180 <= longitude < +180 with +000 prime meridian and -180 the 180th
meridian
"""
# we start the function changing latitude/longitude in english