The RestPose client mirrors the resources provided by the RestPose server as Python objects.
Representation of a RestPose server.
Allows indexing, searching, status management, etc.
| Parameters: |
|
|---|
Type of waiting to use for calls which modify state. Possible options are:
- none: Try pushing tasks onto the queue once, and then return immediately, raising a RequestFailed exception if the queue is full.
- push: Push tasks onto the queue, blocking until the task is pushed onto the queue. Errors which occur in processing or indexing can be accessed using checkpoints.
- process: Push tasks onto the queue, blocking until the task has been processed. Errors which occur during processing will be returned; errors which occur during processing or indexing can be accessed using checkpoints.
- complete: Push tasks onto the queue, blocking until the task has been fully handled by processing and indexing. Errors which occur during processing or indexing will be returned, and can also be accessed using checkpoints.
Get server status.
Returns a dictionary holding the status as returned from the server. See the server documentation for details.
Get a list of existing collections.
Returns a list of collection names (as strings).
Access to a collection.
| Parameters: |
|
|---|---|
| Returns: | a Collection object which can be used to search and modify the contents of the Collection. |
Note
No request is performed directly by this method; a Collection object is simply created which will make requests when needed. For this reason, no error will be reported at this stage even if the collection does not exist, or if a collection name containing invalid characters is used.
Object for creating searches on a field.
| Parameters: |
|
|---|
The target that will be used when creating Query objects. Defaults to None.
An object which generates queries for a specific field.
| Parameters: |
|
|---|
Create a query for fields which exactly match the given values.
A document will match if at least one of the stored values for the field exactly matches at least one of the given values.
This query type is currently available only for “exact”, “id” and “cat” field types.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “tag” field has a value of “edam”, “cheddar” or “leicester”. >>> query = coll.field.tag.is_in(['edam', 'cheddar', 'leicester'])
Search for documents in which the “tag” field has a value of “edam”. >>> query = coll.field.tag.is_in('edam')
|
Create a query for field values which are categories which are descendants of one of the given categories.
A document will match if at least one of the stored values for the field exactly matches a descendant of the given categories.
This query type is available only for “cat” field types.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “tag” field is a descendant of a value of “cheese” >>> query = coll.field.tag.is_descendant('cheese')
or, equivalently: >>> query = coll.field.tag.is_descendant(['cheese'])
|
Create a query for field values which are categories which are descendants of one of the given categories.
A document will match if at least one of the stored values for the field exactly matches a descendant of the given categories.
This query type is available only for “cat” field types.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “tag” field has a value of “cheese”, or has a value which is a descendant of “cheese”. >>> query = coll.field.tag.is_or_is_descendant('cheese')
or, equivalently: >>> query = coll.field.tag.is_or_is_descendant(['cheese'])
|
Create a query for fields which exactly match the given value.
Matches documents in which the supplied value exactly matches the stored value.
This query type is currently available only for “exact”, “id” and “cat” field types.
This query type may be constructed using the == operator, or the equals method.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “tag” field has a value of “edam”. >>> query = coll.field.tag.equals('edam')
Or, equivalently (but less conveniently for chained calls) >>> query = (coll.field.tag == 'edam')
|
Create a query for field values in a given range.
Matches documents in which one of the stored values in the field are in the specified range, including both the begin and end values.
This type is currently available only for “double”, “date” and “timestamp” field types.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “num” field has a value in the range 0 to 10 (including the endpoints). >>> query = coll.field.num.range(0, 10)
|
Create a query for geospatial field values based on distance.
Matches documents in which one of the stored values in the field is within the specified range of the center point (in meters on the surface of the earth).
This type is currently available only for “lonlat” field types.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “num” field has a value in the range 0 to 10 (including the endpoints). >>> query = coll.field.latlon.distscore([0.0, 0.0], 1609.344)
|
Create a query for a piece of text in the field.
This is a simple search for a matching sequences of words (subject to whatever processing has been performed on the field to conflate variant forms of words, such as stemming or word splitting for CJK text).
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “text” field contains text matching the phrase “Hello world”. >>> query = coll.field.text.text("Hello world")
|
Parse a structured query, searching the field.
Unlike text, this allows various operators to be used in the query; for example, parentheses may be used, and operators such as “AND” may be used
Todo
Document the operators permitted.
Beware that the parser is unable to make sense of some query strings (eg, those with mismatched parentheses). If such a query string is used, an error will be returned by the server when the search is performed.
| Parameters: |
|
|---|---|
| Example : | Search for documents in which the “text” field contains both “Hello” and “world”, but not “big”. >>> query = coll.field.text.text("Hello world -big")
|
Search for documents in which the field exists.
This type may be used to search across all fields.
| Example : | Search for documents in which the “text” field exists. >>> query = coll.field.text.exists()
Search for documents in which any field exists. >>> query = coll.any_field.exists()
|
|---|
Search for documents in which the field has a non-empty value.
This type may be used to search across all fields.
| Example : | Search for documents in which the “text” field has a non-empty value. >>> query = coll.field.text.nonempty()
Search for documents in which any field has a non-empty value. >>> query = coll.any_field.nonempty()
|
|---|
Search for documents in which the field has an empty value.
This type may be used to search across all fields.
| Example : | Search for documents in which the “text” field has an empty value. >>> query = coll.field.text.empty()
Search for documents in which any field has an empty value. >>> query = coll.any_field.empty()
|
|---|
Search for documents in which the field produced errors when parsing.
This type may be used to search across all fields.
| Example : | Search for documents in which the “text” field had an error when parsing. >>> query = coll.field.text.has_error()
Search for documents in which any field had an error when parsing. >>> query = coll.any_field.has_error()
|
|---|
An object which can be used to make and run queries.
Factory for field-specific queries.
Pseudo field for making queries across all fields.
Apply a Query to this QueryTarget.
| Parameters: |
|
|---|
The name of the document type
Add a document to the collection.
| Parameters: |
|
|---|
The name of the collection
Add a document to the collection.
| Parameters: |
|
|---|
Delete a document from the collection.
| Parameters: |
|
|---|
Set a checkpoint on the collection.
This creates a resource on the server which can be queried to detect whether indexing has reached the checkpoint yet. All updates sent before the checkpoint will be processed before indexing reaches the checkpoint, and no updates sent after the checkpoint will be processed before indexing reaches the checkpoint.
| Parameters: |
|
|---|
A checkpoint, used to check the progress of indexing.
Create a CheckPoint object.
| Parameters: |
|
|---|
Return true if the checkpoint has been reached.
May contact the server to check the current state.
Raises CheckPointExpiredError if the checkpoint expired before the state was checked.
Return the list of errors associated with the CheckPoint.
Note that if there are many errors, only the first few will be returned.
Returns None if the checkpoint hasn’t been reached yet.
Raises CheckPointExpiredError if the checkpoint expired before the state was checked.
Return the total count of errors associated with the CheckPoint.
This may be larger than len(self.errors), if there were more errors than the CheckPoint is able to hold.
Returns None if the checkpoint hasn’t been reached yet.
Raises CheckPointExpiredError if the checkpoint expired before the state was checked.
Wait for the checkpoint to be reached.
This will contact the server, and wait until the checkpoint has been reached.
If the checkpoint expires (before or during the call), a CheckPointExpiredError will be raised. Otherwise, this will return the checkpoint, so that further methods can be chained on it.
A taxnonmy; a hierarchy of category relationships.
A collection may have many taxonomies, each identified by a name. Each taxonomy contains a set of categories, and a tree of parent-child relationships (or, to use the correct mathematical terminology, a forest. ie, there may be many disjoint trees of parent-child relationships).
This class allows the relationships in a taxonomy to be obtained and modified.
The name of the taxonomy
Get details about the entire set of categories in the taxonomy.
This returns a dict, keyed by category ID, in which each each value is a list of parent category IDs.
Raises ResourceNotFound if the collection or taxonomy are not found.
Get the top-level category names in the taxonomy.
This returns a dict representing the categories in the taxonomy which have no parents. The keys are the category IDs, and the values are objects with the following properties:
- child_count: The number of direct child categories of this category.
- descendant_count: The number of descendants of this category.
Raises ResourceNotFound if the collection or taxonomy are not found.
Get the details of a category in the taxonomy.
This returns an object with the following properties:
- “parents”: A list of the category IDs of any direct parents of the category.
- “ancestors”: A list of the category IDs of any ancestors of the category.
- “children”: A list of the category IDs of any direct children of the category.
- “descendants”: A list of the category IDs of any descendants of the category.
Raises ResourceNotFound if the collection, taxonomy or category are not found.
Add a category.
Creates the collection, taxononmy and category if they don’t already exist.
| Parameters: |
|
|---|
Remove a category.
Creates the collection and taxononmy if they don’t already exist.
| Parameters: |
|
|---|
Add a parent to a category.
Creates the collection, taxononmy, category and the parent, if necessary.
| Parameters: |
|
|---|
Queries in RestPose.
An object which can be sliced or iterated to perform a query.
Create a new Searchable.
target is the object that the search will be performed on. For example, a restpose.Collection or restpose.DocumentType object.
Number of results to get in each request, if size is not explicitly set.
Set the function to get objects associated with results.
Overrides the default realiser for the query target.
Return a searchable, with the target set.
If the target was already set to the same value, returns self. Otherwise, returns a copy of target.
Explicitly force a search for this query to be performed.
This ignores any cached results, and always makes a call to the server.
The query should usually be sliced before calling this method. If the slice does not specify an endpoint, the server will use its internal limit on the number of results, so only a small number of results will be returned unless a larger number is explictly set by slicing.
| Returns: | The results of the search. |
|---|
Return the requested size of the result set.
This returns None if no limit has been placed on the size of the result set to return.
True if the value returned by matches_estimated is exact, False if it isn’t (or at least, isn’t guaranteed to be).
Return True if there are more results after the current slice.
If a limit has been placed on the size of the result set, returns True if there are more results after this limit, and False otherwise.
If no limit has been placed on the size of the result set, returns False.
Get a subset of the result set, based on the position of a particular base document.
| Parameters: |
|
|---|
Set the check_at_least value.
This is the minimum number of documents to try and check when running the search - useful mainly when you want reasonably accurate counts of matching documents, but don’t want to retrieve all matches.
Returns a new Search, with the check_at_least value to use when performing the search set to the specified value.
Set the sort order.
| Parameters: |
|
|---|
This may be called multiple times to order by multiple keys. Alternatively, the order_by_multiple method may be used to do this.
In detail: if this is called when a sort order has already been set, the previous sort order will be applied before the new one (ie, any items which compare equal in the new order will be returned in the order determined by the previously set sort order).
Set the sort order, using multiple keys.
| Parameters: |
|
|---|
Any existing sort order is removed.
Get facet counts for the given field in the matching documents.
Causes the search results to contain counts for each facet value seen in the field, in decreasing order of occurrence. The count entries are of the form: [value, occurrence count].
| Parameters: |
|
|---|
Note; all types being searched which contain the field must have been configured to store facet values in the same slot. The default configuration will guarantee this, but if custom configuration results in this constraint not being satisfied, an error will be returned.
Get occurrence counts of terms in the matching documents.
Warning - fairly slow.
Causes the search results to contain counts for each term seen, in decreasing order of occurrence. The count entries are of the form: [suffix, occurrence count] or [suffix, occurrence count, termfreq] if get_termfreqs was true.
| Parameters: |
|
|---|
Note; if group is specified as an empty string, this can be used to count occurrences of terms in all fields. In this case, terms will be represented by the group name, followed by a tab, followed by the normal term.
Get cooccurrence counts of terms in the matching documents.
Warning - fairly slow (and O(L*L), where L is the average document length).
Causes the search results to contain counts for each pair of terms seen, in decreasing order of cooccurrence. The count entries are of the form: [suffix1, suffix2, co-occurrence count] or [suffix1, suffix2, co-occurrence count, termfreq of suffix1, termfreq of suffix2] if get_termfreqs was true.
| Parameters: |
|
|---|
Note; if group is specified as an empty string, this can be used to count occurrences of terms in all fields. In this case, terms will be represented by the group name, followed by a tab, followed by the normal term.
Base class of all queries.
All query subclasses should have a property called “_query”, containing the query as a structure ready to be converted to JSON and sent to the server.
Return the results of this query filtered by another query.
This returns only documents which match both the original and the filter query, but uses only the weights from the original query.
| Parameters: |
|
|---|---|
| Example : | A query returning documents in which the tag field contains the value 'foo', filtered to only include documents in which the tag field also contains the value 'bar'. >>> query = Field('tag').equals('foo').filter(Field('tag').equals('bar'))
|
Return the results of this query, with additional weights from another query.
This returns exactly the documents which match the original query, but adds the weight from corresponding matches to the other query.
| Parameters: |
|
|---|---|
| Example : | A query returning documents in which the tag field contains the value 'foo', but with additional weights for any matches containing the value 'bar'. >>> query = Field('tag').equals('foo').and_maybe(Field('tag').equals('bar'))
|
A query in a particular field.
A query for meta information (about field presence, errors, etc).
Base class of Queries which are combinations of a sequence of queries.
Subclasses must define self._op, the operator to use to combine queries.
A query which matches only the documents matched by all subqueries.
The weights are the sum of the weights in the subqueries.
| Example : | A query returning documents in which the tag field contains both the value 'foo' and the value 'bar'. >>> query = And(Field('tag').equals('foo'),
... Field('tag').equals('bar'))
|
|---|
A query which matches the documents matched by any subquery.
The weights are the sum of the weights in the subqueries which match.
| Example : | A query returning documents in which the tag field contains at least one of the value 'foo' or the value 'bar'. >>> query = Or(Field('tag').equals('foo'),
... Field('tag').equals('bar'))
|
|---|
A query which matches the documents matched by an odd number of subqueries.
The weights are the sum of the weights in the subqueries which match.
| Example : | A query returning documents in which the tag field contains exactly one of the value 'foo' or the value 'bar'. >>> query = Xor(Field('tag').equals('foo'),
... Field('tag').equals('bar'))
|
|---|
A query which matches the documents matched by the first subquery, but not any of the other subqueries.
The weights returned are the weights in the first subquery.
| Example : | A query returning documents in which the tag field contains the value 'foo' but not the value 'bar'. >>> query = AndNot(Field('tag').equals('foo'),
... Field('tag').equals('bar'))
|
|---|
A query which matches the documents matched by all the subqueries, but only returns weights from the first subquery.
| Example : | A query returning documents in which the tag field contains the value 'foo', with weights from this match, but only where the tag field also contains the value 'bar'. >>> query = Filter(Field('tag').equals('foo'),
... Field('tag').equals('bar'))
|
|---|
A query which matches the documents matched by the first subquery, but adds additional weights from the other subqueries.
The weights are the sum of the weights in the subqueries.
| Example : | A query returning documents in which the tag field contains the value 'foo', with weights from this match, but with additional weights for any of these documents in which the tag field contains the value 'bar'. >>> query = AndMaybe(Field('tag').equals('foo'),
... Field('tag').equals('bar'))
|
|---|
A query which matches all the documents matched by another query, but with the weights multiplied by a factor.
| Example : | A query returning documents in which the tag field contains the value 'foo', with weights multiplied by 2.5. >>> query = MultWeight(Field('tag').equals('foo'), 2.5)
|
|---|
Build a query in which the weights are multiplied by a factor.
A Query which has had offsets or additional search options set.
This is produced from a Query when additional search options are set. It can’t be combined with other Query objects, since the semantics of doing so would be confusing.
The results returned from the server when performing a search.
The total number of documents searched.
The offset of the first result item.
The requested size.
The requested check_at_least value.
A lower bound on the number of matches.
An estimate of the number of matches.
An upper bound on the number of matches.
Set the function to get objects associated with results.
This function will be passed two lists of result items:
- first, a list of result items which must be given objects to associate with them.
- second, a list of result items which it is desirable to associate an object with; this can be used to perform bulk lookups.
And should assign the object to the object property of each of these.
Errors specific to RestPose.
Resources for RestPose.
This module provides a convenient interface to the resources exposed via HTTP by the RestPose server.
A response from the RestPose server.
In addition to the properties exposed by restkit:restkit.Response, this exposes a json property, to decode JSON responses automatically.
Get the response body as JSON.
| Returns: | The response body as a python object, decoded from JSON, if the response Content-Type was application/json. |
|---|---|
| Raises : | an exception if the Content-Type is not application/json, or the body is not valid JSON. |
| Raises : | RestPoseError if the status code returned is not one of the supplied status codes. |
A resource providing access to a RestPose server.
This may be subclassed and provided to restpose.Server, to allow requests to be monitored or modified. For example, a logging subclass could be used to record requests and their responses.
Initialise the resource.
| Parameters: |
|
|---|
The user agent to send when making requests.
Perform a request.
| Parameters: |
|
|---|