Mark most of unstable API as stable

This is with the exception of the 'path' functions.
This commit is contained in:
Stef Walter 2013-12-11 10:32:25 +01:00
parent 71e2791ea3
commit dd6fcf87bb
18 changed files with 44 additions and 184 deletions

View File

@ -64,22 +64,6 @@ var schema = new Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING }); Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
</programlisting></informalexample> </programlisting></informalexample>
<para>
Some parts of the <application>libsecret</application> API are not yet stable.
It is <emphasis>not</emphasis> recommended that you use these unstable parts
from javascript. Your code <emphasis>will break</emphasis> when the unstable API
changes, and due to the lack of a compiler you will have no way of knowing when
it does. If you must use the unstable API, you would do it like this:
</para>
<informalexample><programlisting language="javascript">
// Warning: if you use the unstable API from javascript, your're going to have a bad time
const SecretUnstable = imports.gi.SecretUnstable;
// ... and a here's sample line of code which uses the import
var collection = SecretUnstable.Collection.for_alias(null, "default", null);
</programlisting></informalexample>
</chapter> </chapter>
<chapter id="using-python"> <chapter id="using-python">
@ -98,22 +82,6 @@ schema = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING }) Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
</programlisting></informalexample> </programlisting></informalexample>
<para>
Some parts of the <application>libsecret</application> API are not yet stable.
It is <emphasis>not</emphasis> recommended that you use these unstable parts
from python. Your code <emphasis>will break</emphasis> when the unstable API
changes, and due to the lack of a compiler you will have no way of knowing when
it does. If you must use the unstable API, you would do it like this:
</para>
<informalexample><programlisting language="py">
# Warning: if you use the unstable API from python, your're going to have a bad time
from gi.repository import SecretUnstable
# ... and a here's sample line of code which uses the import
collection = SecretUnstable.Collection.for_alias(None, "default", None);
</programlisting></informalexample>
</chapter> </chapter>
<chapter id="using-vala"> <chapter id="using-vala">

View File

@ -39,22 +39,22 @@ BUILT_SOURCES = \
STABLE_FILES = \ STABLE_FILES = \
secret-attributes.h secret-attributes.c \ secret-attributes.h secret-attributes.c \
secret-password.h secret-password.c \
secret-schema.h secret-schema.c \
secret-schemas.h secret-schemas.c \
secret-types.h \
$(NULL)
UNSTABLE_FILES = \
secret-collection.h secret-collection.c \ secret-collection.h secret-collection.c \
secret-item.h secret-item.c \ secret-item.h secret-item.c \
secret-methods.c \ secret-methods.c \
secret-paths.h secret-paths.c \ secret-password.h secret-password.c \
secret-prompt.h secret-prompt.c \ secret-prompt.h secret-prompt.c \
secret-schema.h secret-schema.c \
secret-schemas.h secret-schemas.c \
secret-service.h secret-service.c \ secret-service.h secret-service.c \
secret-types.h \
secret-value.h secret-value.c \ secret-value.h secret-value.c \
$(NULL) $(NULL)
UNSTABLE_FILES = \
secret-paths.h secret-paths.c \
$(NULL)
PRIVATE_FILES = \ PRIVATE_FILES = \
secret-private.h \ secret-private.h \
secret-session.c \ secret-session.c \
@ -144,7 +144,9 @@ SecretUnstable_0_gir_FILES = $(UNSTABLE_FILES)
SecretUnstable_0_gir_SCANNERFLAGS = --c-include "libsecret/secret.h" --identifier-prefix=Secret --symbol-prefix=secret --include-uninstalled=$(builddir)/Secret-@SECRET_MAJOR@.gir SecretUnstable_0_gir_SCANNERFLAGS = --c-include "libsecret/secret.h" --identifier-prefix=Secret --symbol-prefix=secret --include-uninstalled=$(builddir)/Secret-@SECRET_MAJOR@.gir
girdir = $(datadir)/gir-1.0 girdir = $(datadir)/gir-1.0
gir_DATA = $(INTROSPECTION_GIRS) gir_DATA = Secret-@SECRET_MAJOR@.gir
noinst_DATA = SecretUnstable-0.gir
typelibsdir = $(libdir)/girepository-1.0 typelibsdir = $(libdir)/girepository-1.0
typelibs_DATA = $(INTROSPECTION_GIRS:.gir=.typelib) typelibs_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)
@ -217,6 +219,7 @@ CLEANFILES += \
$(pkgconfig_DATA) \ $(pkgconfig_DATA) \
$(gir_DATA) \ $(gir_DATA) \
$(typelibs_DATA) \ $(typelibs_DATA) \
$(noinst_DATA) \
temp-dbus-generated.c \ temp-dbus-generated.c \
temp-dbus-generated.h \ temp-dbus-generated.h \
$(NULL) $(NULL)

View File

@ -40,10 +40,7 @@
* lookup the items in the collection. There may not be any items exposed when * lookup the items in the collection. There may not be any items exposed when
* the collection is locked. * the collection is locked.
* *
* These functions have an unstable API and may change across versions. Use * Stability: Stable
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/ */
/** /**
@ -1467,7 +1464,7 @@ secret_collection_search (SecretCollection *self,
* *
* Complete asynchronous operation to search for items in a collection. * Complete asynchronous operation to search for items in a collection.
* *
* Returns: (transfer full) (element-type SecretUnstable.Item): * Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search * a list of items that matched the search
*/ */
GList * GList *
@ -1557,7 +1554,7 @@ collection_load_items_sync (SecretCollection *self,
* This function may block indefinetely. Use the asynchronous version * This function may block indefinetely. Use the asynchronous version
* in user interface threads. * in user interface threads.
* *
* Returns: (transfer full) (element-type SecretUnstable.Item): * Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search * a list of items that matched the search
*/ */
GList * GList *
@ -1778,7 +1775,7 @@ secret_collection_get_flags (SecretCollection *self)
* *
* Get the list of items in this collection. * Get the list of items in this collection.
* *
* Returns: (transfer full) (element-type SecretUnstable.Item): a list of items, * Returns: (transfer full) (element-type Secret.Item): a list of items,
* when done, the list should be freed with g_list_free, and each item should * when done, the list should be freed with g_list_free, and each item should
* be released with g_object_unref() * be released with g_object_unref()
*/ */

View File

@ -50,10 +50,7 @@
* *
* Items can be created with secret_item_create() or secret_service_store(). * Items can be created with secret_item_create() or secret_service_store().
* *
* These functions have an unstable API and may change across versions. Use * Stability: Stable
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/ */
/** /**
@ -1405,7 +1402,7 @@ on_loads_secrets_session (GObject *source,
/** /**
* secret_item_load_secrets: * secret_item_load_secrets:
* @items: (element-type SecretUnstable.Item): the items to retrieve secrets for * @items: (element-type Secret.Item): the items to retrieve secrets for
* @cancellable: optional cancellation object * @cancellable: optional cancellation object
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
@ -1504,7 +1501,7 @@ secret_item_load_secrets_finish (GAsyncResult *result,
/** /**
* secret_item_load_secrets_sync: * secret_item_load_secrets_sync:
* @items: (element-type SecretUnstable.Item): the items to retrieve secrets for * @items: (element-type Secret.Item): the items to retrieve secrets for
* @cancellable: optional cancellation object * @cancellable: optional cancellation object
* @error: location to place an error on failure * @error: location to place an error on failure
* *

View File

@ -342,7 +342,7 @@ secret_service_search (SecretService *service,
* *
* Complete asynchronous operation to search for items. * Complete asynchronous operation to search for items.
* *
* Returns: (transfer full) (element-type SecretUnstable.Item): * Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search * a list of items that matched the search
*/ */
GList * GList *
@ -432,7 +432,7 @@ service_load_items_sync (SecretService *service,
* This function may block indefinetely. Use the asynchronous version * This function may block indefinetely. Use the asynchronous version
* in user interface threads. * in user interface threads.
* *
* Returns: (transfer full) (element-type SecretUnstable.Item): * Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search * a list of items that matched the search
*/ */
GList * GList *

View File

@ -39,10 +39,7 @@
* Each of the functions accept a variable list of attributes names and their * Each of the functions accept a variable list of attributes names and their
* values. Include a %NULL to terminate the list of attributes. * values. Include a %NULL to terminate the list of attributes.
* *
* These functions have an unstable API and may change across versions. Use * Stability: Stable
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/ */
/** /**

View File

@ -36,9 +36,6 @@
* service using the DBus API directly, and only wish to use a few calls * service using the DBus API directly, and only wish to use a few calls
* in libsecret. * in libsecret.
* *
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable * Stability: Unstable
*/ */
@ -906,7 +903,7 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self,
* *
* Items that are locked will not be included the results. * Items that are locked will not be included the results.
* *
* Returns: (transfer full) (element-type utf8 SecretUnstable.Value): a newly * Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to #SecretValue * allocated hash table of item_path keys to #SecretValue
* values. * values.
*/ */
@ -949,7 +946,7 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self,
* *
* Items that are locked will not be included the results. * Items that are locked will not be included the results.
* *
* Returns: (transfer full) (element-type utf8 SecretUnstable.Value): a newly * Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to #SecretValue * allocated hash table of item_path keys to #SecretValue
* values. * values.
*/ */

View File

@ -38,10 +38,7 @@
* SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
* virtual methods of the #SecretService class. * virtual methods of the #SecretService class.
* *
* These functions have an unstable API and may change across versions. Use * Stability: Stable
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/ */
/** /**

View File

@ -66,10 +66,7 @@
* In order to customize prompt handling, override the <literal>prompt_async</literal> * In order to customize prompt handling, override the <literal>prompt_async</literal>
* and <literal>prompt_finish</literal> virtual methods of the #SecretService class. * and <literal>prompt_finish</literal> virtual methods of the #SecretService class.
* *
* These functions have an unstable API and may change across versions. Use * Stability: Stable
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/ */
/** /**
@ -1101,7 +1098,7 @@ secret_service_get_flags (SecretService *self)
* initializing #SecretService proxy object, then this method will return * initializing #SecretService proxy object, then this method will return
* %NULL. Use secret_service_load_collections() to load the collections. * %NULL. Use secret_service_load_collections() to load the collections.
* *
* Returns: (transfer full) (element-type SecretUnstable.Collection) (allow-none): a * Returns: (transfer full) (element-type Secret.Collection) (allow-none): a
* list of the collections in the secret service * list of the collections in the secret service
*/ */
GList * GList *

View File

@ -38,10 +38,7 @@
* #SecretValue is reference counted and immutable. The secret data is only * #SecretValue is reference counted and immutable. The secret data is only
* freed when all references have been released via secret_value_unref(). * freed when all references have been released via secret_value_unref().
* *
* These functions have an unstable API and may change across versions. Use * Stability: Stable
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/ */
static gboolean is_password_value (SecretValue *value); static gboolean is_password_value (SecretValue *value);
@ -226,7 +223,7 @@ secret_value_ref (SecretValue *value)
/** /**
* secret_value_unref: * secret_value_unref:
* @value: (type SecretUnstable.Value) (allow-none): value to unreference * @value: (type Secret.Value) (allow-none): value to unreference
* *
* Unreference a #SecretValue. When the last reference is gone, then * Unreference a #SecretValue. When the last reference is gone, then
* the value will be freed. * the value will be freed.

View File

@ -20,10 +20,16 @@
#define __SECRET_INSIDE_HEADER__ #define __SECRET_INSIDE_HEADER__
#include <libsecret/secret-attributes.h> #include <libsecret/secret-attributes.h>
#include <libsecret/secret-collection.h>
#include <libsecret/secret-enum-types.h>
#include <libsecret/secret-item.h>
#include <libsecret/secret-password.h> #include <libsecret/secret-password.h>
#include <libsecret/secret-prompt.h>
#include <libsecret/secret-schema.h> #include <libsecret/secret-schema.h>
#include <libsecret/secret-schemas.h> #include <libsecret/secret-schemas.h>
#include <libsecret/secret-service.h>
#include <libsecret/secret-types.h> #include <libsecret/secret-types.h>
#include <libsecret/secret-value.h>
/* SECRET_WITH_UNSTABLE is defined in the secret-unstable.pc pkg-config file */ /* SECRET_WITH_UNSTABLE is defined in the secret-unstable.pc pkg-config file */
#if defined(SECRET_WITH_UNSTABLE) || defined(SECRET_API_SUBJECT_TO_CHANGE) #if defined(SECRET_WITH_UNSTABLE) || defined(SECRET_API_SUBJECT_TO_CHANGE)
@ -32,13 +38,7 @@
#warning "Some parts of the libsecret API are unstable. Define SECRET_API_SUBJECT_TO_CHANGE to acknowledge" #warning "Some parts of the libsecret API are unstable. Define SECRET_API_SUBJECT_TO_CHANGE to acknowledge"
#endif #endif
#include <libsecret/secret-collection.h>
#include <libsecret/secret-enum-types.h>
#include <libsecret/secret-item.h>
#include <libsecret/secret-paths.h> #include <libsecret/secret-paths.h>
#include <libsecret/secret-prompt.h>
#include <libsecret/secret-service.h>
#include <libsecret/secret-value.h>
#endif /* SECRET_WITH_UNSTABLE || SECRET_API_SUBJECT_TO_CHANGE */ #endif /* SECRET_WITH_UNSTABLE || SECRET_API_SUBJECT_TO_CHANGE */

View File

@ -59,7 +59,7 @@ JS_TESTS = \
test-lookup-password.js \ test-lookup-password.js \
test-clear-password.js \ test-clear-password.js \
test-store-password.js \ test-store-password.js \
test-unstable.js $(NULL)
JS_ENV = \ JS_ENV = \
LD_LIBRARY_PATH=$(builddir)/../.libs:$(builddir)/.libs \ LD_LIBRARY_PATH=$(builddir)/../.libs:$(builddir)/.libs \
@ -69,7 +69,7 @@ PY_TESTS = \
test-lookup-password.py \ test-lookup-password.py \
test-clear-password.py \ test-clear-password.py \
test-store-password.py \ test-store-password.py \
test-unstable.py $(NULL)
PY_ENV = $(JS_ENV) PY_ENV = $(JS_ENV)

View File

@ -15,7 +15,7 @@ import sys
import unittest import unittest
from gi.repository import MockService as Mock from gi.repository import MockService as Mock
from gi.repository import Secret, SecretUnstable, GLib from gi.repository import Secret, GLib
STORE_SCHEMA = Secret.Schema.new("org.mock.Schema", STORE_SCHEMA = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, Secret.SchemaFlags.NONE,
@ -31,7 +31,7 @@ class TestRemove(unittest.TestCase):
Mock.start("mock-service-normal.py") Mock.start("mock-service-normal.py")
def tearDown(self): def tearDown(self):
SecretUnstable.Service.disconnect() Secret.Service.disconnect()
Mock.stop() Mock.stop()
def testSynchronous(self): def testSynchronous(self):

View File

@ -14,7 +14,7 @@
import unittest import unittest
from gi.repository import MockService as Mock from gi.repository import MockService as Mock
from gi.repository import Secret, SecretUnstable, GLib from gi.repository import Secret, GLib
STORE_SCHEMA = Secret.Schema.new("org.mock.Schema", STORE_SCHEMA = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, Secret.SchemaFlags.NONE,
@ -30,7 +30,7 @@ class TestLookup(unittest.TestCase):
Mock.start("mock-service-normal.py") Mock.start("mock-service-normal.py")
def tearDown(self): def tearDown(self):
SecretUnstable.Service.disconnect() Secret.Service.disconnect()
Mock.stop() Mock.stop()
def testSynchronous(self): def testSynchronous(self):

View File

@ -14,7 +14,7 @@
import unittest import unittest
from gi.repository import MockService as Mock from gi.repository import MockService as Mock
from gi.repository import Secret, SecretUnstable, GLib from gi.repository import Secret, GLib
STORE_SCHEMA = Secret.Schema.new("org.mock.Schema", STORE_SCHEMA = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, Secret.SchemaFlags.NONE,
@ -30,7 +30,7 @@ class TestStore(unittest.TestCase):
Mock.start("mock-service-normal.py") Mock.start("mock-service-normal.py")
def tearDown(self): def tearDown(self):
SecretUnstable.Service.disconnect() Secret.Service.disconnect()
Mock.stop() Mock.stop()
def testSynchronous(self): def testSynchronous(self):

View File

@ -1,27 +0,0 @@
/*
* Copyright 2012 Red Hat Inc.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* by the Free Software Foundation; either version 2.1 of the licence or (at
* your option) any later version.
*
* See the included COPYING file for more information.
*/
const Mock = imports.gi.MockService;
const Secret = imports.gi.SecretUnstable;
const GLib = imports.gi.GLib;
const JsUnit = imports.jsUnit;
const assertNotEquals = JsUnit.assertNotEquals;
Mock.start("mock-service-normal.py");
var service = Secret.Service.get_sync(Secret.ServiceFlags.NONE, null);
var path = service.read_alias_dbus_path_sync("default", null);
/* Just running this without error is good enough for us to test the unstable gir */
assertNotEquals(path, null);
Mock.stop();

View File

@ -1,63 +0,0 @@
#!/usr/bin/env python
#
# Copyright 2012 Red Hat Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation; either version 2.1 of the licence or (at
# your option) any later version.
#
# See the included COPYING file for more information.
#
import unittest
from gi.repository import MockService as Mock
from gi.repository import SecretUnstable, Secret, GLib
EXAMPLE_SCHEMA = Secret.Schema.new('org.mock.type.Store',
Secret.SchemaFlags.NONE,
{
'number': Secret.SchemaAttributeType.INTEGER,
'string': Secret.SchemaAttributeType.STRING,
'even': Secret.SchemaAttributeType.BOOLEAN,
}
)
attributes = {
'number': '8',
'string': 'eight',
'even': 'true'
}
class TestStore(unittest.TestCase):
def setUp(self):
Mock.start("mock-service-normal.py")
def tearDown(self):
SecretUnstable.Service.disconnect()
Mock.stop()
def testSynchronous(self):
service = SecretUnstable.Service.get_sync(SecretUnstable.ServiceFlags.NONE, None);
path = service.read_alias_dbus_path_sync("default", None);
# Just running this without error is good enough for us to test the unstable gir
self.assertNotEqual(path, None);
def testValueGet(self):
Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
'the label', 'the password', None)
service = SecretUnstable.Service.get_sync(SecretUnstable.ServiceFlags.NONE, None)
items = service.search_sync(EXAMPLE_SCHEMA, { 'even': 'true' },
SecretUnstable.SearchFlags.ALL | SecretUnstable.SearchFlags.LOAD_SECRETS,
None)
item = items[0]
item_secret = item.get_secret()
self.assertEqual(item_secret.get(), "the password")
if __name__ == '__main__':
unittest.main()

View File

@ -12,7 +12,7 @@
private void test_read_alias () { private void test_read_alias () {
try { try {
var service = Secret.Service.get_sync(Secret.ServiceFlags.NONE); var service = Secret.Service.get_sync(Secret.ServiceFlags.NONE);
var path = service.read_alias_dbus_path_sync("default", null); var path = Secret.service_read_alias_dbus_path_sync(service, "default", null);
GLib.assert (path != null); GLib.assert (path != null);
} catch ( GLib.Error e ) { } catch ( GLib.Error e ) {
GLib.error (e.message); GLib.error (e.message);