Browser (pydent.browser)

New in version 0.1: Browser class created

Browser class for searching and cacheing results.

class pydent.browser.Browser(session, inherit_models=False)[source]

Bases: pydent.interfaces.QueryInterfaceABC

A class for browsing models and Aquarium inventory.

Instantiates a new browser from a AqSession instance.

Changed in version 0.1.5a7: ‘inherit_models’ argument will inherit the sessions model_cache (default: False)

Parameters

  • session (SessionABC) – a session instance

  • inherit_models (bool) – if True, the browser will inherit the cache in the provided session’s browser model_cache

INTERFACE_CLASS

alias of pydent.interfaces.QueryInterface

_Browser__query_helper(fname, query, model_class, sample_type=None, opts=None, params=None, as_single=False)

Builds a custom query for the browser.

Parameters

  • fname (basestring) – the function name

  • query (dict) – the query

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

  • sample_type (basestring) – optional sample_type name

  • opts (dict) – options to send to the function

  • params (dict) – additionaly keyword arguments to send to the function

  • as_single (bool) – if True, will return the first model of the array or None if array is empty

Returns

Aquarium model or list of Aquarium models

Return type

ModelBase | list

static _group_by_attribute(models, attribute)[source]

Group models by the given attribute.

static _match_query(query, model_dict)[source]

Matches a query against a model dictionary.

Parameters

  • query (dict) – query dictionary

  • model_dict (dict) – model dictionary (e.g. model.__dict__)

Returns

whether the model matches the query

Return type

bool

_retrieve_has_many_or_has_one(models, relationship_name, relation=None, strict=True)[source]

Performs exactly 1 query to fullfill some relationship for a list of models.

_retrieve_has_many_through(models, relationship_name, strict=True)[source]

Performs exactly 2 queries to establish a HasManyThrough relationship.

_update_model_cache_helper(modelname, modeldict)[source]

Updates the browser’s model cache with models from the provided model dict.

Return type

List[ModelBase]

all(model_class=None, opts=None)[source]

Return all models of a model_class.

Parameters

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

  • opts –

Returns

Return type

clear()[source]

Clears the model cache.

close_matches(pattern, sample_type=None, **query)[source]

Finds samples whose names closely match the pattern.

Parameters

  • pattern (basestring) – regular expression pattern

  • sample_type (basestring) – sample_type_name to filter samples (optional)

  • query (dict) – additional query parameters to filter by

Returns

list of samples

Return type

list

export_samples_to_csv(samples, out)[source]

Exports the samples to a csv (for Aquarium import)

Parameters

  • samples (list) – list of samples

  • out (basestring) – output path of csv file

Returns

pandas dataframe used for the csv

Return type

pandas.DataFrame

find(model_id, model_class=None)[source]

Finds a model by id. Will returned cached model if possible.

Parameters

  • model_id (int) – model_id

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

Returns

Return type

find_by_name(name, model_class=None, primary_key='id')[source]

Find model by name. Will return cached model if possible.

Parameters

  • name – name of the model

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

  • primary_key –

Returns

first(num=1, model_class=None, sample_type=None, query=None)[source]

Finds first models. Will NOT return cached models.

Parameters

  • num (int) – number of models to return

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

  • sample_type (basestring) – optional sample_type name

  • query (dict) – additional query to filter models

Returns

Return type

get(models, relations=None, query=None, strict=True, force_refresh=False)[source]
Parameters

  • models (List[ModelBase]) –

  • relations (Optional[List[BaseRelationship]]) –

  • query (Optional[dict]) –

  • strict (bool) –

  • force_refresh (bool) –

Return type

Union[Dict[str, List[ModelBase]], List[ModelBase]]

Returns

interface(model_class=None)[source]

Returns a new model query interface.

Parameters

model_class (basestring) –

Returns

Interface

Return type

QueryInterface

last(num=1, model_class=None, sample_type=None, query=None)[source]

Finds last models. Will NOT return cached models.

Parameters

  • num (int) – number of models to return

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

  • sample_type (basestring) – optional sample_type name

  • query (dict) – additional query to filter models

Returns

Return type

list_field_values(model_ids, **query)[source]

Lists sample field values.

May supply an additional query to filter FieldValue.

property model_name

Alias for self.model.__name__

one(model_class=None, sample_type=None, query=None, opts=None)[source]

Finds one instance of a model (or returns None)

Parameters

  • model_class (basestring) – the name of the model class (e.g. “Sample”)

  • sample_type (basestring) – optional sample_type name

  • query (dict) – additional query to filter models

  • opts (dict) – additional options

Returns

Return type

recursive_retrieve(models, relations, strict=True, force_refresh=False)[source]

Efficiently retrieve a model relationship recursively from an iterable. The relations_dict iterable may be either a list or a dictionary. For example, the following will collect all of the field_values and their incoming and outgoing wires, the connecting field_values, and finally those FieldValues’ operations.

relation_dict = {
    "field_values": {
        "wires_as_dest": {
            "source": "operation",
            "destination": "operation"
        },
        "wires_as_source": {
            "source": "operation",
            "destination": "operation"
        },
    }
}
browser.retrieve(operations, relation_dict)
Parameters

  • models (list) – models to retrieve from

  • relations (list|dict|basestring) – the relation to retrieve. May be a string (by attribute name), a list, or a dict.

  • strict (bool) – wither to ignore database inconsistencies

  • force_refresh (bool) –

Returns

dictionary of all models retrieved grouped by the attribute name that retrieved them.

Return type

dictionary

classmethod relationship_network(models, get_models, cache_func=None, key_func=None, reverse=False, g=None, strict_cache=True)[source]

Build a DAG of related models based on some relationships. By default are built from a model using (model.__class__.__name__, model._primary_key)

New in version 0.1.5a7: method added

See also

Usage example sample_network

Parameters

  • models (List[ModelBase]) – list of models

  • get_models (Callable) – A function that takes in a single instance of a Model and returns an iterable of Tuples of (model, data), which is used to build edges.

  • key_func (Optional[Callable]) – An optional function that takes in a single instance of a Model and returns a key and some node data

  • cache_func (Optional[Callable]) – A function that takes in a list of models and caches some results.

  • g (Optional[DiGraph]) – optional nx.DiGraph

  • reverse (bool) – whether to reverse the edge list

  • strict_cache (bool) – if True, if a request occurs after the cache step, a ForbiddenRequestException will be raised.

Returns

the relationship graph

retrieve(models, relationship_name, relation=None, strict=True, force_refresh=False)[source]

Retrieves a model relationship for the list of models. Compared to a for loop, retrieve is >10X faster for most queries.

# FAST code example
samples = browser.search(".*mCherry.*")
items = browser.retrieve(samples, 'items')
for s in samples:
    sample_items = s.items
    # do something with items

# very SLOW code example. DO NOT USE.
samples = browser.search(".*mCherry.*")
for s in samples:
    sample_items = s.items
    # do something with itmes
Parameters

  • models (list) – list of models to retrieve the attribute

  • relationship_name (basestring) – name of the attribute to retrieve

  • relation (pydent.relationships.Relation) – the relation to retrieve (operational)

  • strict (bool) – wither to ignore database inconsistencies

Returns

list of models retrieved

Return type

list

sample_list(sample_type_id=None)[source]

Returns a sample list.

classmethod sample_network(samples, reverse=False, g=None, get_models=None, cache_func=None, key_func=None)[source]

Build a DAG of Samples from their.

FieldValues.

New in version 0.1.5a7: method added

Changed in version 0.1.5a16: added optional get_models, cache_func, key_func arguments

Parameters

  • samples (List[Sample]) – list of samples

  • reverse (bool) – whether to reverse the edges of the final graph

  • g (Optional[DiGraph]) – the graph

Return type

DiGraph

Returns

samples_to_rows(samples, sample_resolver=None)[source]

Return row of dictionaries containing sample information and their properties. Can be imported into a pandas DataFrame:

import pandas

df = pandas.DataFrame(samples_to_rows(samples))
Parameters

  • samples (list) – samples, all of same sample type

  • sample_resolver (callable) – callable to resolve a sample object if the field value property contains a sample. Defaults to return the sample name.

Returns

list of dictionaries containing sample info and properties

Return type

list

search(pattern, ignore_case=True, sample_type=None, **query)[source]

Performs a regular expression search of Samples.

Parameters

  • pattern (basestring) – regular expression pattern

  • ignore_case (bool) – whether to ignore case for regex search (default: True)

  • sample_type (basestring) – sample_type_name to filter samples (optional)

  • query (dict) – additional query parameters to filter by

Returns

list of samples

Return type

list

search_description(pattern, samples=None, sample_type=None, ignore_case=True)[source]

Search samples by their description.

Parameters

  • pattern (basestring) – regex pattern

  • samples (list) – samples to search. If left blank, a search to find samples will be performed

  • sample_type (name) – restrict to a particular sample type

  • ignore_case (bool) – ignore case for regular pattern search (default True)

Returns

list of samples

Return type

list

set_model(model_name)[source]

Sets the default model of this browser.

update_cache(models, recursive=True, update_session=False)[source]

Update the browser’s model cache from a list of models.

Changed in version 0.1.5a8: Added ‘update_session’ kwarg which will change the model’s session to the browser’s session.

Warning

If update_session=True, the model’s session will change and this may have unintended consequences.

Parameters

  • models (List[ModelBase]) – list of models

  • recursive (bool) – if True, recursively collect all models contained in the relationships and use those to update the cache as well.

  • update_session (bool) – if True, attach the browser’s session to the models

Return type

Dict[str, List[ModelBase]]

Returns

the updated dictionary broken down by model class name

where(query, model_class=None, primary_key='id', sample_type=None, methods=None, opts=None, page_size=None, include=None)[source]

Perform a ‘where’ query. If models are found in the browser cache, those are returned, else new http queries are made to find the models.

Parameters

  • query – query as a dictionary

  • model_class – model class to use (str)

  • primary_key – which primary key to use (default: ‘id’)

  • sample_type – optional sample_type short cut for finding samples

  • kwargs – other kwargs

Returns

returned model list

exception pydent.browser.BrowserException[source]

Bases: pydent.exceptions.TridentBaseException

Generic browser exception.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.