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

Improve date handler documentation

Browse Source
This commit is contained in:
Nick Hall 2013-11-13 18:41:52 +00:00
parent 55a3c9813f
commit 19b39b5dc0
5 changed files with 51 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
gramps/gen/datehandler/_datedisplay.py
View File

@ -82,14 +82,12 @@ class DateDisplay(object):
_("DAY MON YEAR") _("DAY MON YEAR")
) )
""" """
:Note: .. note:: Will be overridden if a locale-specific date displayer exists.
Will be overridden if a locale-specific date displayer exists.
If your localized ``_display_gregorian`` / ``_display_calendar`` are overridden, If your localized :meth:`~_display_calendar`/:meth:`~_display_gregorian` are
you should override the whole formats list according to your own formats, overridden,you should override the whole formats list according to your own
and you need not localize the format names here. formats, and you need not localize the format names here. This ``formats``
this ``formats`` must agree with must agree with :meth:`~_display_calendar`/:meth:`~_display_gregorian`.
:meth:`~_display_calendar`/:meth:`~_display_gregorian`
""" """
del _ del _

18
gramps/gen/datehandler/_datehandler.py
View File

@ -101,16 +101,16 @@ def register_datehandler(locales,parse_class,display_class):
classes with the specified language locales. classes with the specified language locales.
Set the parser_class and display_class ._locale attribute Set the parser_class and display_class ._locale attribute
to the corresponding GrampsLocale object. to the corresponding :class:`.GrampsLocale` object.
@param locales: tuple of strings containing language codes. :param locales: tuple of strings containing language codes.
The character encoding is not included, so the language The character encoding is not included, so the language
should be in the form of fr_FR, not fr_FR.utf8 should be in the form of fr_FR, not fr_FR.utf8
@type locales: tuple :type locales: tuple
@param parse_class: Class to be associated with parsing :param parse_class: Class to be associated with parsing
@type parse_class: DateParse :type parse_class: :class:`.DateParser`
@param display_class: Class to be associated with displaying :param display_class: Class to be associated with displaying
@type display_class: DateDisplay :type display_class: :class:`.DateDisplay`
""" """
for lang_str in locales: for lang_str in locales:
LANG_TO_PARSER[lang_str] = parse_class LANG_TO_PARSER[lang_str] = parse_class

31
gramps/gen/datehandler/_dateparser.py
View File

@ -158,18 +158,17 @@ def _build_prefix_table(month_to_int, month_variants):
def _generate_variants(months): def _generate_variants(months):
""" """
Generate all month variants for passing to _build_prefix_table Generate all month variants for passing to _build_prefix_table
@param months an iterable ordered collection, :param months: an iterable ordered collection, 1st item is empty, the rest
1st item is empty, the rest 1..N, for a 1..N, for a calendar with N months overall, contain, each,
calendar with N months overall, contain, each, an iterable of alternative specifications.
an iterable of alternative specifications. Each such specification can be:
Each such specification can be: 1) a Lexeme, supporting .variants() to return the list of
1) a Lexeme, supporting .variants() variants underneath
to return the list of variants underneath 2) a literal string
2) a literal string 3) a |-separated string of alternatives
3) a |-separated string of alternatives Empty strings are discarded.
Empty strings are discarded. :return: generator of lists per month with all variants listed once only
@return generator of lists per month with all variants listed once only the 1st item will be empty
the 1st item will be empty
""" """
for month_lexemes_and_alternatives in months: for month_lexemes_and_alternatives in months:
@ -193,7 +192,7 @@ def _generate_variants(months):
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
class DateParser(object): class DateParser(object):
""" """
Convert a text string into a Date object. If the date cannot be Convert a text string into a :class:`.Date` object. If the date cannot be
converted, the text string is assigned. converted, the text string is assigned.
""" """
@ -377,7 +376,9 @@ class DateParser(object):
may be called first as DateParser.init_strings(self) so that the may be called first as DateParser.init_strings(self) so that the
invariant expresions don't need to be repeteadly coded. All differences invariant expresions don't need to be repeteadly coded. All differences
can be coded after DateParser.init_strings(self) call, that way they can be coded after DateParser.init_strings(self) call, that way they
override stuff from this method. See DateParserRU() as an example. override stuff from this method.
.. seealso:: :class:`.DateParserRU` as an example.
""" """
_ = self._locale.translation.gettext _ = self._locale.translation.gettext
self.__init_prefix_tables() self.__init_prefix_tables()
@ -876,7 +877,7 @@ class DateParser(object):
def parse(self, text): def parse(self, text):
""" """
Parses the text, returning a Date object. Parses the text, returning a :class:`.Date` object.
""" """
new_date = Date() new_date = Date()
try: try:

17
gramps/gen/datehandler/_datestrings.py
View File

@ -40,7 +40,7 @@ log = logging.getLogger(".DateStrings")
#------------------------------------------------------------------------- #-------------------------------------------------------------------------
class DateStrings(object): class DateStrings(object):
""" """
String tables for :class:`~DateDisplay` and :class:`~DateParser`. String tables for :class:`.DateDisplay` and :class:`.DateParser`.
""" """
# This table needs not be localized, it's only for parsing # This table needs not be localized, it's only for parsing
@ -233,16 +233,17 @@ __doc__ += """
__main__ __main__
-------- --------
Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target language, Run this code with the appropriate ``LANG`` and ``LC_DATE`` set for your target
in order to generate the .po snippets initialized with the strings from your locale language, in order to generate the .po snippets initialized with the strings
(from the deprecated data provided in _grampslocale). from your locale (from the deprecated data provided in _grampslocale).
E.g., for French::
E.g., for French:
::
LANG=fr_FR.utf8 LC_ALL=fr_FR.utf8 GRAMPS_RESOURCES=$PWD python -m gramps.gen.datehandler._datestrings LANG=fr_FR.utf8 LC_ALL=fr_FR.utf8 GRAMPS_RESOURCES=$PWD python -m gramps.gen.datehandler._datestrings
Then merge the output into your language's .po file, and further modify the strings as needed. Then merge the output into your language's .po file, and further modify the
Then remove the strings from your language's ``DateParserXX`` and ``DateHandlerXX`` classes. strings as needed. Then remove the strings from your language's
:class:`DateParserXX` and :class:`DateHandlerXX` classes.
""" """
if __name__ == '__main__': if __name__ == '__main__':

24
gramps/gen/datehandler/_dateutils.py
View File

@ -61,27 +61,27 @@ def set_format(value):
def set_date(date_base, text) : def set_date(date_base, text) :
""" """
Set the date of the DateBase instance. Set the date of the :class:`.DateBase` instance.
The date is parsed into a Date instance. The date is parsed into a :class:`.Date` instance.
@param date_base: The DateBase instance to set the date to.
@type date_base: DateBase
@param text: The text to use for the text string in date
@type text: str
:param date_base: The :class:`.DateBase` instance to set the date to.
:type date_base: :class:`.DateBase`
:param text: The text to use for the text string in date
:type text: str
""" """
parser.set_date(date_base.get_date_object(), text) parser.set_date(date_base.get_date_object(), text)
def get_date(date_base) : def get_date(date_base) :
""" """
Return a string representation of the date of the DateBase instance. Return a string representation of the date of the :class:`.DateBase`
instance.
This representation is based off the default date display format This representation is based off the default date display format
determined by the locale's DateDisplay instance. determined by the locale's :class:`.DateDisplay` instance.
@return: Returns a string representing the DateBase date
@rtype: str :return: Returns a string representing the :class:`.DateBase` date
:rtype: str
""" """
return displayer.display(date_base.get_date_object()) return displayer.display(date_base.get_date_object())