Python (and possibly other) bindings could return a real string for database UUIDs

[James Aylett]

Document.get_uuid() in the python bindings returns as bytes, which is the correct representation for std::string in general. However we know that this will always be a UUID (serialised as ASCII I think). We could change .get_uuid() to return str. It would be backwards incompatible, but there may not be enough people actually using it for that to be a problem.

We could also turn this into a property, so it's accessed as .uuid. I can't remember it it's possible to have both .uuid giving the new behaviour and a (perhaps deprecated) .get_uuid() giving the old.

Or this may be completely unnecessary given it can be worked round in user code and I doubt anyone else has even thought about this from a bindings consumer.

[Olly Betts]

It's easy to change - this is how get_description() is set to return a Python str in python3/python.i:

// get_description() should return 'str' via the default typemap.
%typemap(out) std::string get_description() = std::string;

(xapian.version_string() already returns str as well.)

While it probably won't affect many people, changing get_uuid() incompatibly would break our API promises and so seems like it should wait until 3.0.0.

We could add a .uuid property returning str, though perhaps that's more confusing that just changing the existing wrapper's return type for a new release series.

I wonder what else always returns a UTF-8 string but isn't mapped to str in the Python bindings - a quick look found me:

>>> xapian.Stem.get_available_languages()
b'arabic armenian basque catalan czech danish dutch dutch_porter earlymodernenglish english esperanto estonian finnish french german greek hindi hungarian indonesian irish italian lithuanian lovins nepali norwegian persian polish porter portuguese romanian russian serbian sesotho spanish swedish tamil turkish yiddish'

Maybe that would actually be more helpfully mapped to something returning a Python list or something like that.

[Olly Betts]

Our Java bindings also have a binary/text distinction, but it's implemented differently by marking methods which return binary so it looks to me like all the cases mentioned above are already handled as text. There are existing lines in Smoketest.java which should ensure this:

            String v2 = Version.string();

            if (!doc.toString().equals("Document(docid=0, data=a\\xc0\\x80b)")) {

We don't test getUuid() currently, but adding this passes so I'll commit it:

@@ -116,6 +116,10 @@ public class SmokeTest {
                 System.err.println("Unexpected db.getDocCount()");
                 System.exit(1);
             }
+            if (!db.getUuid().equals("")) {
+                System.err.println("Unexpected db.getUUID()");
+                System.exit(1);
+            }
 
             QueryParser qp = new QueryParser();
 

I don't see this distinction in other bindings.

[Olly Betts]

I've also added a test of Stem.getAvailableLanguages() (f40fd1602dd5e8b1a7bad855851bca292704339c).

[James Aylett]

Replying to Olly Betts:

While it probably won't affect many people, changing get_uuid() incompatibly would break our API promises and so seems like it should wait until 3.0.0.

We could add a .uuid property returning str, though perhaps that's more confusing that just changing the existing wrapper's return type for a new release series.

I think it's largely a question of whether it's easier to cope with a deprecation warning or a type error (or similar). Some people may (unwisely) catch the latter but still see the former.

I'm happy waiting until 3.0.0 though, since it's fairly minor, and I doubt more than one or two people are actually using it (and it's easy enough to write code that copes with both if you know it's coming).

I wonder what else always returns a UTF-8 string but isn't mapped to str in the Python bindings - a quick look found me:

>>> xapian.Stem.get_available_languages()
b'arabic armenian basque catalan czech danish dutch dutch_porter earlymodernenglish english esperanto estonian finnish french german greek hindi hungarian indonesian irish italian lithuanian lovins nepali norwegian persian polish porter portuguese romanian russian serbian sesotho spanish swedish tamil turkish yiddish'

Maybe that would actually be more helpfully mapped to something returning a Python list or something like that.

Probably a tuple, since it's a fixed list in the compiled library. Returning bytes is definitely not useful to anyone.