GData.Query¶

Subclasses:: GData.CalendarQuery, GData.ContactsQuery, GData.DocumentsDriveQuery, GData.DocumentsQuery, GData.FreebaseQuery, GData.FreebaseSearchQuery, GData.FreebaseTopicQuery, GData.PicasaWebQuery, GData.TasksQuery, GData.YouTubeQuery

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (q)
class	`new_with_limits` (q, start_index, max_results)
	`get_author` ()
	`get_categories` ()
	`get_etag` ()
	`get_max_results` ()
	`get_published_max` ()
	`get_published_min` ()
	`get_q` ()
	`get_query_uri` (feed_uri)
	`get_start_index` ()
	`get_updated_max` ()
	`get_updated_min` ()
	`is_strict` ()
	`next_page` ()
	`previous_page` ()
	`set_author` (author)
	`set_categories` (categories)
	`set_etag` (etag)
	`set_is_strict` (is_strict)
	`set_max_results` (max_results)
	`set_published_max` (published_max)
	`set_published_min` (published_min)
	`set_q` (q)
	`set_start_index` (start_index)
	`set_updated_max` (updated_max)
	`set_updated_min` (updated_min)

Virtual Methods¶

Inherited:: GObject.Object (7)

do_get_query_uri (feed_uri, query_uri, params_started)

Properties¶

Name	Type	Flags	Short Description
`author`	`str`	r/w	Author search string.
`categories`	`str`	r/w	Category search string.
`etag`	`str`	r/w	An ETag against which to check.
`is-strict`	`bool`	r/w	Should the server be strict about the query?
`max-results`	`int`	r/w	The maximum number of entries to return.
`published-max`	`int`	r/w	Maximum date for returned entries to be published.
`published-min`	`int`	r/w	Minimum date for returned entries to be published.
`q`	`str`	r/w	Query terms for which to search.
`start-index`	`int`	r/w	One-based result start index.
`updated-max`	`int`	r/w	Maximum date for updates on returned entries.
`updated-min`	`int`	r/w	Minimum date for updates on returned entries.

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class GData.Query(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: GData.QueryClass

All the fields in the GData.Query structure are private and should never be accessed directly.

classmethod new(q)¶

Parameters:: q (str or None) – a query string, or None
Returns:: a new GData.Query
Return type:: GData.Query

Creates a new GData.Query with its GData.Query :q property set to q.

classmethod new_with_limits(q, start_index, max_results)¶

Parameters:

q (str or None) – a query string, or None
start_index (int) – a one-based start index for the results, or 0
max_results (int) – the maximum number of results to return, or 0

Returns:

a new GData.Query

Return type:

GData.Query

Creates a new GData.Query with its GData.Query :q property set to q, and the limits start_index and max_results applied.

get_author()¶

Returns:: the author property, or None if it is unset
Return type:: str

Gets the GData.Query :author property.

get_categories()¶

Returns:: the categories property, or None if it is unset
Return type:: str

Gets the GData.Query :categories property.

get_etag()¶

Returns:: the ETag property, or None if it is unset
Return type:: str

Gets the GData.Query :etag property.

New in version 0.2.0.

get_max_results()¶

Returns:: the maximum results property, or 0 if it is unset
Return type:: int

Gets the GData.Query :max-results property.

get_published_max()¶

Returns:: the published-max property, or -1
Return type:: int

Gets the GData.Query :published-max property. If the property is unset, -1 will be returned.

get_published_min()¶

Returns:: the published-min property, or -1
Return type:: int

Gets the GData.Query :published-min property. If the property is unset, -1 will be returned.

get_q()¶

Returns:: the q property, or None if it is unset
Return type:: str

Gets the GData.Query :q property.

get_query_uri(feed_uri)¶

Parameters:: feed_uri (str) – the feed URI on which to build the query URI
Returns:: a query URI; free with GLib.free()
Return type:: str

Builds a query URI from the given base feed URI, using the properties of the GData.Query. This function will take care of all necessary URI escaping, so it should not be done beforehand.

The query URI is what functions like GData.Service.query() use to query the online service.

get_start_index()¶

Returns:: the start index property, or 0 if it is unset
Return type:: int

Gets the GData.Query :start-index property.

get_updated_max()¶

Returns:: the updated-max property, or -1
Return type:: int

Gets the GData.Query :updated-max property. If the property is unset, -1 will be returned.

get_updated_min()¶

Returns:: the updated-min property, or -1
Return type:: int

Gets the GData.Query :updated-min property. If the property is unset, -1 will be returned.

is_strict()¶

Returns:: the strict property
Return type:: bool

Gets the GData.Query :is-strict property.

New in version 0.2.0.

next_page()¶

Changes the state of the GData.Query such that when GData.Query.get_query_uri() is next called, it will build the query URI for the next page in the result set.

Ideally, the URI of the next page is retrieved from a feed automatically when GData.Service.query() is called, but GData.Query.next_page() will fall back to using GData.Query :start-index to emulate true pagination if this fails.

You should not implement pagination manually using GData.Query :start-index.

previous_page()¶

Returns:: True if there is a previous page and it has been switched to, False otherwise
Return type:: bool

Changes the state of the GData.Query such that when GData.Query.get_query_uri() is next called, it will build the query URI for the previous page in the result set.

See the documentation for GData.Query.next_page() for an explanation of how query URIs from the feeds are used to this end.

set_author(author)¶

Parameters:: author (str or None) – the new author string, or None

Sets the GData.Query :author property of the GData.Query to the new author string, author.

Set author to None to unset the property in the query URI.

set_categories(categories)¶

Parameters:: categories (str or None) – the new category string, or None

Sets the GData.Query :categories property of the GData.Query to the new category string, categories.

Set categories to None to unset the property in the query URI.

set_etag(etag)¶

Parameters:: etag (str or None) – the new ETag, or None

Sets the GData.Query :etag property of the GData.Query to the new ETag, etag.

Set etag to None to not check against the server-side ETag.

New in version 0.2.0.

set_is_strict(is_strict)¶

Parameters:: is_strict (bool) – the new strict value

Sets the GData.Query :is-strict property of the GData.Query to the new strict value, is_strict.

New in version 0.2.0.

set_max_results(max_results)¶

Parameters:: max_results (int) – the new maximum results value, or 0

Sets the GData.Query :max-results property of the GData.Query to the new maximum results value, max_results.

Set max_results to 0 to unset the property in the query URI.

set_published_max(published_max)¶

Parameters:: published_max (int) – the new maximum publish time, or -1

Sets the GData.Query :published-max property of the GData.Query to the new maximum publish time, published_max.

Set published_max to -1 to unset the property in the query URI.

set_published_min(published_min)¶

Parameters:: published_min (int) – the new minimum publish time, or -1

Sets the GData.Query :published-min property of the GData.Query to the new minimum publish time, published_min.

Set published_min to -1 to unset the property in the query URI.

set_q(q)¶

Parameters:: q (str or None) – a new query string, or None

Sets the GData.Query :q property of the GData.Query to the new query string, q.

Set q to None to unset the property in the query URI.

set_start_index(start_index)¶

Parameters:: start_index (int) – the new start index, or 0

Sets the GData.Query :start-index property of the GData.Query to the new one-based start index, start_index.

Set start_index to 0 to unset the property in the query URI.

set_updated_max(updated_max)¶

Parameters:: updated_max (int) – the new maximum update time, or -1

Sets the GData.Query :updated-max property of the GData.Query to the new maximum update time, updated_max.

Set updated_max to -1 to unset the property in the query URI.

set_updated_min(updated_min)¶

Parameters:: updated_min (int) – the new minimum update time, or -1

Sets the GData.Query :updated-min property of the GData.Query to the new minimum update time, updated_min.

Set updated_min to -1 to unset the property in the query URI.

do_get_query_uri(feed_uri, query_uri, params_started) virtual¶

Parameters:

feed_uri (str) –
query_uri (GLib.String) –
params_started (bool) –

Property Details¶

GData.Query.props.author¶

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

An entry author. The service returns entries where the author name and/or e-mail address match your query string.

GData.Query.props.categories¶

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

A category filter.

You can query on multiple categories by listing multiple categories separated by slashes. The service returns all entries that match all of the categories (like using AND between terms). For example: Fritz/Laurie returns entries that match both categories (“Fritz” and “Laurie”).

To do an OR between terms, use a pipe character (|). For example: Fritz\%7CLaurie returns entries that match either category.

An entry matches a specified category if the entry is in a category that has a matching term or label, as defined in the Atom specification. (Roughly, the “term” is the internal string used by the software to identify the category, while the “label” is the human-readable string presented to a user in a user interface.)

To exclude entries that match a given category, use the form -categoryname.

To query for a category that has a scheme – such as <category scheme="urn:google.com" term="public"/> – you must place the scheme in curly braces before the category name. For example: {urn:google.com}public. To match a category that has no scheme, use an empty pair of curly braces. If you don’t specify curly braces, then categories in any scheme will match.

The above features can be combined. For example: A|-{urn:google.com}B/-C means (A OR (NOT B)) AND (NOT C).

GData.Query.props.etag¶

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

The ETag against which to check for updates. If the server-side ETag matches this one, the requested feed hasn’t changed, and is not returned unnecessarily.

Setting any of the other query properties will unset the ETag, as ETags match against entire queries. If the ETag should be used in a query, it must be set again using GData.Query.set_etag() after setting any other properties.

New in version 0.2.0.

GData.Query.props.is_strict¶

Name:: is-strict
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Strict query parameter checking. If this is enabled, an error will be returned by the online service if a parameter is not recognised.

New in version 0.2.0.

GData.Query.props.max_results¶

Name:: max-results
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

Maximum number of results to be retrieved. Most services have a default GData.Query :max-results size imposed by the server; if you wish to receive the entire feed, specify a large number such as GObject.G_MAXUINT for this property.

Use 0 to not specify a maximum number of results.

GData.Query.props.published_max¶

Name:: published-max
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE

Upper bound on the entry publish date, exclusive.

GData.Query.props.published_min¶

Name:: published-min
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE

Lower bound on the entry publish date, inclusive.

GData.Query.props.q¶

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

A full-text query string.

When creating a query, list search terms separated by spaces, in the form term1 term2 term3. (As with all of the query parameter values, the spaces must be URL encoded.) The service returns all entries that match all of the search terms (like using AND between terms). Like Google’s web search, a service searches on complete words (and related words with the same stem), not substrings.

To search for an exact phrase, enclose the phrase in quotation marks: “exact phrase”.

To exclude entries that match a given term, use the form -term.

The search is case-insensitive.

Example: to search for all entries that contain the exact phrase “Elizabeth Bennet” and the word “Darcy” but don’t contain the word “Austen”, use the following query: “Elizabeth Bennet” Darcy -Austen.

GData.Query.props.start_index¶

Name:: start-index
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The one-based index of the first result to be retrieved. Use GData.Query.next_page() and GData.Query.previous_page() to implement pagination, rather than manually changing GData.Query :start-index.

Use 0 to not specify a start index.

GData.Query.props.updated_max¶

Name:: updated-max
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE

Upper bound on the entry update date, exclusive.

GData.Query.props.updated_min¶

Name:: updated-min
Type:: int
Default Value:: -1
Flags:: READABLE, WRITABLE

Lower bound on the entry update date, inclusive.