Merge lp:~jtv/launchpad/bug-664327 into lp:launchpad

[Jeroen T. Vermeulen]

API: IHasTranslationImports.getTranslationImportQueueEntries

= Bug 664327 =

David, the Ubuntu translations man, has asked us for this new bit of functionality on the web service API: "get the translations import queue for a specific distribution, distroseries, or source package." This will allow him to get more done without bothering us developers, and without us developers bothering the LOSAs. So it's all in a good cause.

We were already exporting a method that could do this: ITranslationsImportQueue.getAllEntries. But we decided against exporting the filter parameters to this method since they erode the naming: when you filter for a specific translation target, you're not getting "all" entries.

Instead, we chose to export a method that's already on the distribution, distroseries, source package etc. (and in an interface that's already exported for other reasons) called IHasTranslationImports.getTranslationImportQueueEntries.

A quick test verifies its presence on the API. To run it:
{{{
./bin/test -vvc lp.translations -t "webservice.*import"
}}}

For Q/A, it will be fun to explore some import queues for existing translation targets.

No lint,

Jeroen

[Gavin Panella (allenap)]

Looks good, +1

[1]

+ @operation_parameters(
+ import_status=Choice(
+ title=_("Status"),
+ description=_("Show only entries with this status"),
+ values=RosettaImportStatus.items,
+ required=False),

I think you can use vocabulary=RosettaImportStatus instead of values.

[2]

+ >>> print target_queue['entries'][0]['path']
+ matching-entry.pot

Unless it's done elsewhere, it would be nice to document what is
returned by this method, rather than just a the path property of the
first entry.

review: Approve (code)

=== modified file 'lib/canonical/launchpad/interfaces/_schema_circular_imports.py'
--- lib/canonical/launchpad/interfaces/_schema_circular_imports.py	2010-10-18 06:14:10 +0000
+++ lib/canonical/launchpad/interfaces/_schema_circular_imports.py	2010-10-22 04:26:21 +0000
@@ -120,6 +120,10 @@
     IPOTemplateSharingSubset,
     IPOTemplateSubset,
     )
+from lp.translations.interfaces.translationimportqueue import (
+    IHasTranslationImports,
+    ITranslationImportQueueEntry,
+    )
 
 
 IBranch['bug_branches'].value_type.schema = IBugBranch
@@ -437,6 +441,11 @@
 # IBugWatch
 patch_reference_property(IBugWatch, 'owner', IPerson)
 
+# IHasTranslationImports
+patch_collection_return_type(
+    IHasTranslationImports, 'getTranslationImportQueueEntries',
+    ITranslationImportQueueEntry)
+
 # IIndexedMessage
 patch_reference_property(IIndexedMessage, 'inside', IBugTask)
 

=== modified file 'lib/lp/translations/interfaces/translationimportqueue.py'
--- lib/lp/translations/interfaces/translationimportqueue.py	2010-08-20 20:31:18 +0000
+++ lib/lp/translations/interfaces/translationimportqueue.py	2010-10-22 04:26:21 +0000
@@ -175,8 +175,8 @@
 class IHasTranslationImports(Interface):
     """An entity on which a translation import queue entry is attached.
 
-    Examples include an IProductSeries, ISourcePackage, IDistroSeries and
-    IPerson.
+    Examples include ProductSeries, SourcePackage, DistroSeries, and
+    Person.
     """
     export_as_webservice_entry(
         singular_name='object_with_translation_imports',
@@ -185,7 +185,21 @@
     def getFirstEntryToImport():
         """Return the first entry of the queue ready to be imported."""
 
-    def getTranslationImportQueueEntries(imports_status=None,
+    @operation_parameters(
+        import_status=Choice(
+            title=_("Status"),
+            description=_("Show only entries with this status"),
+            vocabulary=RosettaImportStatus,
+            required=False),
+        file_extension=TextLine(
+            title=_("Filename extension"),
+            description=_("Show only entries with this filename suffix"),
+            required=False))
+    # Really ITranslationImportQueueEntry.  Fixed up in
+    # _schema_circular_imports.py.
+    @operation_returns_collection_of(Interface)
+    @export_read_operation()
+    def getTranslationImportQueueEntries(import_status=None,
                                          file_extension=None):
         """Return entries in the translation import queue for this entity.
 
@@ -273,7 +287,7 @@
     status = exported(
         Choice(
             title=_("The status of the import."),
-            values=RosettaImportStatus.items,
+            vocabulary=RosettaImportStatus,
             required=True,
             readonly=True))
 

=== modified file 'lib/lp/translations/model/translationimportqueue.py'
--- lib/lp/translations/model/translationimportqueue.py	2010-08-20 20:31:18 +0000
+++ lib/lp/translations/model/translationimportqueue.py	2010-10-22 04:26:21 +0000
@@ -1284,8 +1284,7 @@
         importer = getUtility(ITranslationImporter)
         template_patterns = "(%s)" % ' OR '.join([
             "path LIKE ('%%' || %s)" % quote_like(suffix)
-            for suffix in importer.template_suffixes
-            ])
+            for suffix in importer.template_suffixes])
 
         store = self._getSlaveStore()
         result = store.execute("""
@@ -1445,6 +1444,7 @@
             extensions = None
         else:
             extensions = [file_extension]
-        translation_import_queue = TranslationImportQueue()
+        translation_import_queue = getUtility(ITranslationImportQueue)
         return translation_import_queue.getAllEntries(
-            self, import_status=import_status, file_extensions=extensions)
+            target=self, import_status=import_status,
+            file_extensions=extensions)

=== modified file 'lib/lp/translations/stories/webservice/xx-translationimportqueue.txt'
--- lib/lp/translations/stories/webservice/xx-translationimportqueue.txt	2009-11-17 09:50:33 +0000
+++ lib/lp/translations/stories/webservice/xx-translationimportqueue.txt	2010-10-22 04:26:21 +0000
@@ -1,4 +1,5 @@
-= Translation Import Queue =
+Translation Import Queue
+========================
 
 The queue of uploaded translation files is quite large.  It contains not
 just files waiting to be imported, but also blocked or failed uploads,
@@ -38,7 +39,8 @@
     ...         print_dict_entries(entry, shown_keys=shown_keys)
 
 
-== Enumerating the queue ==
+Enumerating the queue
+---------------------
 
     >>> queue = webservice.get("/+imports").jsonBody()
     >>> queue['total_size']
@@ -73,7 +75,8 @@
      uploader_link http://.../~name16
 
 
-== Entry fields ==
+Entry fields
+------------
 
 Most of the fields in a translation import queue entry are immutable
 from the web service's point of view.
@@ -81,7 +84,8 @@
     >>> from simplejson import dumps
 
 
-=== Path ===
+Path
+....
 
 An entry's file path can be changed by the entry's owner or an admin.
 
@@ -103,7 +107,8 @@
     ...
 
 
-=== Status ===
+Status
+......
 
 For now, it is not possible to set an entry's status through the API.
 
@@ -134,3 +139,29 @@
     HTTP/1.1 401 Unauthorized
     ...
 
+
+Target-specific import queues
+-----------------------------
+
+Objects that implement IHasTranslationImports (also known as "translation
+targets") expose their specific sub-sets of the import queue through
+getTranslationImportQueueEntries.
+
+In this example, a person:
+
+    >>> login(ANONYMOUS)
+    >>> target = factory.makePerson()
+    >>> target_url = '/~%s' % target.name
+    >>> matching_entry = factory.makeTranslationImportQueueEntry(
+    ...     'matching-entry.pot', uploader=target)
+    >>> other_entry = factory.makeTranslationImportQueueEntry(
+    ...     'other-entry.pot')
+    >>> logout()
+
+    >>> target_queue = webservice.named_get(
+    ...     target_url, 'getTranslationImportQueueEntries').jsonBody()
+    >>> print target_queue['total_size']
+    1
+
+    >>> print target_queue['entries'][0]['path']
+    matching-entry.pot