Secret.Collection¶

Subclasses:: None

Methods¶

Inherited:: Gio.DBusProxy (25), GObject.Object (37), Gio.AsyncInitable (4), Gio.DBusInterface (3), Gio.Initable (2)
Structs:: GObject.ObjectClass (5)

class	`create` (service, label, alias, flags, cancellable, callback, *user_data)
class	`create_finish` (result)
class	`create_sync` (service, label, alias, flags, cancellable)
class	`for_alias` (service, alias, flags, cancellable, callback, *user_data)
class	`for_alias_finish` (result)
class	`for_alias_sync` (service, alias, flags, cancellable)
	`delete` (cancellable, callback, *user_data)
	`delete_finish` (result)
	`delete_sync` (cancellable)
	`get_created` ()
	`get_flags` ()
	`get_items` ()
	`get_label` ()
	`get_locked` ()
	`get_modified` ()
	`get_service` ()
	`load_items` (cancellable, callback, *user_data)
	`load_items_finish` (result)
	`load_items_sync` (cancellable)
	`refresh` ()
	`search` (schema, attributes, flags, cancellable, callback, *user_data)
	`search_finish` (result)
	`search_sync` (schema, attributes, flags, cancellable)
	`set_label` (label, cancellable, callback, *user_data)
	`set_label_finish` (result)
	`set_label_sync` (label, cancellable)

Virtual Methods¶

Inherited:: Gio.DBusProxy (2), GObject.Object (7), Gio.AsyncInitable (2), Gio.DBusInterface (3), Gio.Initable (1)

Properties¶

Inherited:: Gio.DBusProxy (9)

Name	Type	Flags	Short Description
`created`	`int`	r/w	Item creation date
`flags`	`Secret.CollectionFlags`	r/w/co	Collection flags
`label`	`str`	r/w	Item label
`locked`	`bool`	r	Item locked
`modified`	`int`	r/w	Item modified date
`service`	`Secret.Service`	r/w/co	Secret Service

Signals¶

Inherited:: Gio.DBusProxy (2), GObject.Object (1)

Fields¶

Inherited:: Gio.DBusProxy (2), GObject.Object (1)

Name	Type	Access	Description
parent	`Gio.DBusProxy`	r

Class Details¶

class Secret.Collection(**kwargs)¶

Bases:: Gio.DBusProxy
Abstract:: No
Structure:: Secret.CollectionClass

A proxy object representing a collection of secrets in the Secret Service.

Secret.Collection represents a collection of secret items stored in the Secret Service.

A collection can be in a locked or unlocked state. Use [method`SecretService`.lock] or [method`SecretService`.unlock] to lock or unlock the collection.

Use the [property`SecretCollection`:py:data::items<Secret.Collection.props.items>] property or [method`SecretCollection`.get_items] to lookup the items in the collection. There may not be any items exposed when the collection is locked.

classmethod create(service, label, alias, flags, cancellable, callback, *user_data)¶

Parameters:

service (Secret.Service or None) – a secret service object
label (str) – label for the new collection
alias (str or None) – alias to assign to the collection
flags (Secret.CollectionCreateFlags) – currently unused
cancellable (Gio.Cancellable or None) – optional cancellation object
callback (Gio.AsyncReadyCallback or None) – called when the operation completes
user_data (object or None) – data to pass to the callback

Create a new collection in the secret service.

This method returns immediately and completes asynchronously. The secret service may prompt the user. [method`Service`.prompt] will be used to handle any prompts that are required.

An alias is a well-known tag for a collection, such as ‘default’ (ie: the default collection to store items in). This allows other applications to easily identify and share a collection. If you specify an alias, and a collection with that alias already exists, then a new collection will not be created. The previous one will be returned instead.

If service is None, then [func`Service`.get] will be called to get the default [class`Service`] proxy.

classmethod create_finish(result)¶

Parameters:: result (Gio.AsyncResult) – the asynchronous result passed to the callback
Raises:: GLib.Error
Returns:: the new collection, which should be unreferenced with [method`GObject`.Object.unref]
Return type:: Secret.Collection

Finish operation to create a new collection in the secret service.

classmethod create_sync(service, label, alias, flags, cancellable)¶

Parameters:

service (Secret.Service or None) – a secret service object
label (str) – label for the new collection
alias (str or None) – alias to assign to the collection
flags (Secret.CollectionCreateFlags) – currently unused
cancellable (Gio.Cancellable or None) – optional cancellation object

Raises:

GLib.Error

Returns:

the new collection, which should be unreferenced with [method`GObject`.Object.unref]

Return type:

Secret.Collection

Create a new collection in the secret service.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. [method`Service`.prompt] will be used to handle any prompts that are required.

An alias is a well-known tag for a collection, such as default (ie: the default collection to store items in). This allows other applications to easily identify and share a collection. If you specify an alias, and a collection with that alias already exists, then a new collection will not be created. The previous one will be returned instead.

If service is None, then [func`Service`.get_sync] will be called to get the default [class`Service`] proxy.

classmethod for_alias(service, alias, flags, cancellable, callback, *user_data)¶

Parameters:

service (Secret.Service or None) – a secret service object
alias (str) – the alias to lookup
flags (Secret.CollectionFlags) – options for the collection initialization
cancellable (Gio.Cancellable or None) – optional cancellation object
callback (Gio.AsyncReadyCallback or None) – called when the operation completes
user_data (object or None) – data to pass to the callback

Lookup which collection is assigned to this alias. Aliases help determine well known collections, such as ‘default’.

If service is None, then [func`Service`.get] will be called to get the default [class`Service`] proxy.

This method will return immediately and complete asynchronously.

classmethod for_alias_finish(result)¶

Parameters:: result (Gio.AsyncResult) – asynchronous result passed to callback
Raises:: GLib.Error
Returns:: the collection, or None if none assigned to the alias
Return type:: Secret.Collection or None

Finish an asynchronous operation to lookup which collection is assigned to an alias.

classmethod for_alias_sync(service, alias, flags, cancellable)¶

Parameters:

service (Secret.Service or None) – a secret service object
alias (str) – the alias to lookup
flags (Secret.CollectionFlags) – options for the collection initialization
cancellable (Gio.Cancellable or None) – optional cancellation object

Raises:

GLib.Error

Returns:

the collection, or None if none assigned to the alias

Return type:

Secret.Collection or None

Lookup which collection is assigned to this alias. Aliases help determine well known collections, such as default.

If service is None, then [func`Service`.get_sync] will be called to get the default [class`Service`] proxy.

This method may block and should not be used in user interface threads.

delete(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) – optional cancellation object
callback (Gio.AsyncReadyCallback or None) – called when the operation completes
user_data (object or None) – data to pass to the callback

Delete this collection.

This method returns immediately and completes asynchronously. The secret service may prompt the user. [method`Service`.prompt] will be used to handle any prompts that show up.

delete_finish(result)¶

Parameters:: result (Gio.AsyncResult) – asynchronous result passed to the callback
Raises:: GLib.Error
Returns:: whether the collection was successfully deleted or not
Return type:: bool

Complete operation to delete this collection.

delete_sync(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional cancellation object
Raises:: GLib.Error
Returns:: whether the collection was successfully deleted or not
Return type:: bool

Delete this collection.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. [method`Service`.prompt] will be used to handle any prompts that show up.

get_created()¶

Returns:: the created date and time
Return type:: int

Get the created date and time of the collection.

The return value is the number of seconds since the unix epoch, January 1st 1970.

get_flags()¶

Returns:: the flags for features initialized
Return type:: Secret.CollectionFlags

Get the flags representing what features of the Secret.Collection proxy have been initialized.

Use [method`Collection`.load_items] to initialize further features and change the flags.

get_items()¶

Returns:: a list of items, when done, the list should be freed with [func`GLib`.List.free], and each item should be released with [method`GObject`.Object.unref]
Return type:: [Secret.Item]

Get the list of items in this collection.

get_label()¶

Returns:: the label, which should be freed with [func`GLib`.free]
Return type:: str

Get the label of this collection.

get_locked()¶

Returns:: whether the collection is locked or not
Return type:: bool

Get whether the collection is locked or not.

Use [method`Service`.lock] or [method`Service`.unlock] to lock or unlock the collection.

get_modified()¶

Returns:: the modified date and time
Return type:: int

Get the modified date and time of the collection.

The return value is the number of seconds since the unix epoch, January 1st 1970.

get_service()¶

Returns:: the Secret Service object
Return type:: Secret.Service

Get the Secret Service object that this collection was created with.

load_items(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) – optional cancellation object
callback (Gio.AsyncReadyCallback or None) – called when the operation completes
user_data (object or None) – data to be passed to the callback

Ensure that the Secret.Collection proxy has loaded all the items present in the Secret Service.

This affects the result of [method`Collection`.get_items].

For collections returned from [method`Service`.get_collections] the items will have already been loaded.

This method will return immediately and complete asynchronously.

load_items_finish(result)¶

Parameters:: result (Gio.AsyncResult) – the asynchronous result passed to the callback
Raises:: GLib.Error
Returns:: whether the load was successful or not
Return type:: bool

Complete an asynchronous operation to ensure that the Secret.Collection proxy has loaded all the items present in the Secret Service.

load_items_sync(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional cancellation object
Raises:: GLib.Error
Returns:: whether the load was successful or not
Return type:: bool

Ensure that the Secret.Collection proxy has loaded all the items present in the Secret Service. This affects the result of [method`Collection`.get_items].

For collections returned from [method`Service`.get_collections] the items will have already been loaded.

This method may block indefinitely and should not be used in user interface threads.

refresh()¶

Refresh the properties on this collection. This fires off a request to refresh, and the properties will be updated later.

Calling this method is not normally necessary, as the secret service will notify the client when properties change.

search(schema, attributes, flags, cancellable, callback, *user_data)¶

Parameters:

schema (Secret.Schema or None) – the schema for the attributes
attributes ({str: str}) – search for items matching these attributes
flags (Secret.SearchFlags) – search option flags
cancellable (Gio.Cancellable or None) – optional cancellation object
callback (Gio.AsyncReadyCallback or None) – called when the operation completes
user_data (object or None) – data to pass to the callback

Search for items matching the attributes in the collection. The attributes should be a table of string keys and string values.

If Secret.SearchFlags.ALL is set in flags, then all the items matching the search will be returned. Otherwise only the first item will be returned. This is almost always the unlocked item that was most recently stored.

If Secret.SearchFlags.UNLOCK is set in flags, then items will be unlocked if necessary. In either case, locked and unlocked items will match the search and be returned. If the unlock fails, the search does not fail.

If Secret.SearchFlags.LOAD_SECRETS is set in flags, then the items will have their secret values loaded and available via [method`Item`.get_secret].

This function returns immediately and completes asynchronously.

search_finish(result)¶

Parameters:: result (Gio.AsyncResult) – asynchronous result passed to callback
Raises:: GLib.Error
Returns:: a list of items that matched the search
Return type:: [Secret.Item]

Complete asynchronous operation to search for items in a collection.

search_sync(schema, attributes, flags, cancellable)¶

Parameters:

schema (Secret.Schema or None) – the schema for the attributes
attributes ({str: str}) – search for items matching these attributes
flags (Secret.SearchFlags) – search option flags
cancellable (Gio.Cancellable or None) – optional cancellation object

Raises:

GLib.Error

Returns:

a list of items that matched the search

Return type:

[Secret.Item]

Search for items matching the attributes in the collection. The attributes should be a table of string keys and string values.

If Secret.SearchFlags.ALL is set in flags, then all the items matching the search will be returned. Otherwise only the first item will be returned. This is almost always the unlocked item that was most recently stored.

If Secret.SearchFlags.UNLOCK is set in flags, then items will be unlocked if necessary. In either case, locked and unlocked items will match the search and be returned. If the unlock fails, the search does not fail.

If Secret.SearchFlags.LOAD_SECRETS is set in flags, then the items will have their secret values loaded and available via [method`Item`.get_secret].

This function may block indefinitely. Use the asynchronous version in user interface threads.

set_label(label, cancellable, callback, *user_data)¶

Parameters:

label (str) – a new label
cancellable (Gio.Cancellable or None) – optional cancellation object
callback (Gio.AsyncReadyCallback or None) – called when the operation completes
user_data (object or None) – data to pass to the callback

Set the label of this collection.

This function returns immediately and completes asynchronously.

set_label_finish(result)¶

Parameters:: result (Gio.AsyncResult) – asynchronous result passed to callback
Raises:: GLib.Error
Returns:: whether the change was successful or not
Return type:: bool

Complete asynchronous operation to set the label of this collection.

set_label_sync(label, cancellable)¶

Parameters:

label (str) – a new label
cancellable (Gio.Cancellable or None) – optional cancellation object

Raises:

GLib.Error

Returns:

whether the change was successful or not

Return type:

bool

Set the label of this collection.

This function may block indefinitely. Use the asynchronous version in user interface threads.

Property Details¶

Secret.Collection.props.created¶

Name:: created
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The date and time (in seconds since the UNIX epoch) that this collection was created.

Secret.Collection.props.flags¶

Name:: flags
Type:: Secret.CollectionFlags
Default Value:: Secret.CollectionFlags.NONE
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

A set of flags describing which parts of the secret collection have been initialized.

Secret.Collection.props.label¶

Name:: label
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The human readable label for the collection.

Setting this property will result in the label of the collection being set asynchronously. To properly track the changing of the label use the [method`Collection`.set_label] function.

Secret.Collection.props.locked¶

Name:: locked
Type:: bool
Default Value:: True
Flags:: READABLE

Whether the collection is locked or not.

To lock or unlock a collection use the [method`Service`.lock] or [method`Service`.unlock] functions.

Secret.Collection.props.modified¶

Name:: modified
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The date and time (in seconds since the UNIX epoch) that this collection was last modified.

Secret.Collection.props.service¶

Name:: service
Type:: Secret.Service
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The [class`Service`] object that this collection is associated with and uses to interact with the actual D-Bus Secret Service.