From: Armin Ronacher Date: Fri, 26 Jul 2013 13:45:57 +0000 (+0200) Subject: Added better messages API docs X-Git-Tag: 1.0~20 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad2737e04dc5897c154e8f32409ff8a94668b6cd;p=thirdparty%2Fbabel.git Added better messages API docs --- diff --git a/babel/messages/extract.py b/babel/messages/extract.py index ccb1cfca..44b1eb38 100644 --- a/babel/messages/extract.py +++ b/babel/messages/extract.py @@ -59,14 +59,13 @@ def _strip_comment_tags(comments, tags): comments[:] = map(_strip, comments) -def extract_from_dir(dirname=os.getcwd(), method_map=DEFAULT_MAPPING, +def extract_from_dir(dirname=None, method_map=DEFAULT_MAPPING, options_map=None, keywords=DEFAULT_KEYWORDS, comment_tags=(), callback=None, strip_comment_tags=False): """Extract messages from any source files found in the given directory. - This function generates tuples of the form: - - ``(filename, lineno, message, comments, context)`` + This function generates tuples of the form ``(filename, lineno, message, + comments, context)``. Which extraction method is used per file is determined by the `method_map` parameter, which maps extended glob patterns to extraction method names. @@ -109,7 +108,8 @@ def extract_from_dir(dirname=os.getcwd(), method_map=DEFAULT_MAPPING, ... } ... } - :param dirname: the path to the directory to extract messages from + :param dirname: the path to the directory to extract messages from. If + not given the current working directory is used. :param method_map: a list of ``(pattern, method)`` tuples that maps of extraction method names to extended glob patterns :param options_map: a dictionary of additional options (optional) @@ -128,6 +128,8 @@ def extract_from_dir(dirname=os.getcwd(), method_map=DEFAULT_MAPPING, tags to be removed from the collected comments. :see: `pathmatch` """ + if dirname is None: + dirname = os.getcwd() if options_map is None: options_map = {} @@ -167,9 +169,8 @@ def extract_from_file(method, filename, keywords=DEFAULT_KEYWORDS, comment_tags=(), options=None, strip_comment_tags=False): """Extract messages from a specific file. - This function returns a list of tuples of the form: - - ``(lineno, funcname, message)`` + This function returns a list of tuples of the form ``(lineno, funcname, + message)``. :param filename: the path to the file to extract messages from :param method: a string specifying the extraction method (.e.g. "python") @@ -196,9 +197,7 @@ def extract(method, fileobj, keywords=DEFAULT_KEYWORDS, comment_tags=(), """Extract messages from the given file-like object using the specified extraction method. - This function returns tuples of the form: - - ``(lineno, message, comments)`` + This function returns tuples of the form ``(lineno, message, comments)``. The implementation dispatches the actual extraction to plugins, based on the value of the ``method`` parameter. @@ -325,9 +324,8 @@ def extract_nothing(fileobj, keywords, comment_tags, options): def extract_python(fileobj, keywords, comment_tags, options): """Extract messages from Python source code. - It returns an iterator yielding tuples in the following form:: - - (lineno, funcname, message, comments) + It returns an iterator yielding tuples in the following form ``(lineno, + funcname, message, comments)``. :param fileobj: the seekable, file-like object the messages should be extracted from diff --git a/docs/api/index.rst b/docs/api/index.rst index 208d4dec..e21fa74e 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -9,7 +9,7 @@ public API of Babel. core dates - messages + messages/index numbers plural support diff --git a/docs/api/messages.rst b/docs/api/messages.rst deleted file mode 100644 index aed231e1..00000000 --- a/docs/api/messages.rst +++ /dev/null @@ -1,23 +0,0 @@ -Messages and Catalogs -===================== - -.. module:: babel.messages - -Babel provides functionality to work with message catalogs. There is more -functionality than that available but some of it is currently only -documented in the sourcecode as we have to decide what part of the API -will become public and what should stay internal. - -Basic Interface ---------------- - -.. autoclass:: Message - :members: - -.. autoclass:: Catalog - :members: - -Exceptions ----------- - -.. autoexception:: TranslationError diff --git a/docs/api/messages/catalog.rst b/docs/api/messages/catalog.rst new file mode 100644 index 00000000..8a905bcd --- /dev/null +++ b/docs/api/messages/catalog.rst @@ -0,0 +1,25 @@ +Messages and Catalogs +===================== + +.. module:: babel.messages.catalog + +This module provides a basic interface to hold catalog and message +information. It's generally used to modify a gettext catalog but it is +not being used to actually use the translations. + +Catalogs +-------- + +.. autoclass:: Catalog + :members: + +Messages +-------- + +.. autoclass:: Message + :members: + +Exceptions +---------- + +.. autoexception:: TranslationError diff --git a/docs/api/messages/extract.rst b/docs/api/messages/extract.rst new file mode 100644 index 00000000..805aaff6 --- /dev/null +++ b/docs/api/messages/extract.rst @@ -0,0 +1,36 @@ +Low-Level Extraction Interface +============================== + +.. module:: babel.messages.extract + +The low level extraction interface can be used to extract from directories +or files directly. Normally this is not needed as the command line tools +can do that for you. + +Extraction Functions +-------------------- + +The extraction functions are what the command line tools use internally to +extract strings. + +.. autofunction:: extract_from_dir + +.. autofunction:: extract_from_file + +.. autofunction:: extract + +Language Parsing +---------------- + +The language parsing functions are used to extract strings out of source +files. These are automatically being used by the extraction functions but +sometimes it can be useful to register wrapper functions, then these low +level functions can be invoked. + +New functions can be registered through the setuptools entrypoint system. + +.. autofunction:: extract_python + +.. autofunction:: extract_javascript + +.. autofunction:: extract_nothing diff --git a/docs/api/messages/index.rst b/docs/api/messages/index.rst new file mode 100644 index 00000000..f9b13e4a --- /dev/null +++ b/docs/api/messages/index.rst @@ -0,0 +1,13 @@ +Messages and Catalogs +===================== + +Babel provides functionality to work with message catalogs. This part of +the API documentation shows those parts. + +.. toctree:: + :maxdepth: 2 + + catalog + extract + mofile + pofile diff --git a/docs/api/messages/mofile.rst b/docs/api/messages/mofile.rst new file mode 100644 index 00000000..ee023abd --- /dev/null +++ b/docs/api/messages/mofile.rst @@ -0,0 +1,12 @@ +MO File Support +=============== + +.. module:: babel.messages.mofile + +The MO file support can read and write MO files. It reads them into +:class:`~babel.messages.catalog.Catalog` objects and also writes catalogs +out. + +.. autofunction:: read_mo + +.. autofunction:: write_mo diff --git a/docs/api/messages/pofile.rst b/docs/api/messages/pofile.rst new file mode 100644 index 00000000..1a4ef08f --- /dev/null +++ b/docs/api/messages/pofile.rst @@ -0,0 +1,12 @@ +PO File Support +=============== + +.. module:: babel.messages.pofile + +The PO file support can read and write PO and POT files. It reads them +into :class:`~babel.messages.catalog.Catalog` objects and also writes +catalogs out. + +.. autofunction:: read_po + +.. autofunction:: write_po