pydent.aqsession.Browser¶

class pydent.aqsession.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

__init__(session, inherit_models=False)[source]¶

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

Methods

`__init__`(session[, inherit_models])	Instantiates a new browser from a AqSession instance.
`all`([model_class, opts])	Return all models of a model_class.
`cached_find`(model_class, id)
`cached_where`(query, model[, primary_key, …])
`clear`()	Clears the model cache.
`close_matches`(pattern[, sample_type])	Finds samples whose names closely match the pattern.
`export_samples_to_csv`(samples, out)	Exports the samples to a csv (for Aquarium import)
`find`(model_id[, model_class])	Finds a model by id.
`find_by_name`(name[, model_class, primary_key])	Find model by name.
`first`([num, model_class, sample_type, query])	Finds first models.
`get`(models[, relations, query, strict, …])	type models `List`[`ModelBase`]
`inspect`(model, header, attributes)
`interface`([model_class])	Returns a new model query interface.
`last`([num, model_class, sample_type, query])	Finds last models.
`list_field_values`(model_ids, **query)	Lists sample field values.
`list_models`(args, *kwargs)
`new_sample`(sample_type, name, description, …)
`one`([model_class, sample_type, query, opts])	Finds one instance of a model (or returns None)
`recursive_retrieve`(models, relations[, …])	Efficiently retrieve a model relationship recursively from an iterable.
`retrieve`(models, relationship_name[, …])	Retrieves a model relationship for the list of models.
`sample_list`([sample_type_id])	Returns a sample list.
`Browser.samples_to_df`
`samples_to_rows`(samples[, sample_resolver])	Return row of dictionaries containing sample information and their properties.
`search`(pattern[, ignore_case, sample_type])	Performs a regular expression search of Samples.
`search_description`(pattern[, samples, …])	Search samples by their description.
`set_model`(model_name)	Sets the default model of this browser.
`update_cache`(models[, recursive, update_session])	Update the browser’s model cache from a list of models.
`where`(query[, model_class, primary_key, …])	Perform a ‘where’ query.

Attributes

`ACCEPTED_GET_RELATION_TYPES`
`model_name`	Alias for self.model.__name__
`models`

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