#11934

pending completion

Build # #11934

Build Type

push

travis-ci

Committed by

web-flow

Commit Message

<a href="https://github.com/datajoint/datajoint-python/commit/<a class=hub.com/datajoint/datajoint-python/commit/08fb99fe7a53b58a806709b7e36e69b017169f37">08fb99fe7<a href="https://github.com/datajoint/datajoint-python/commit/08fb99fe7a53b58a806709b7e36e69b017169f37">">Merge </a><a class="double-link" href="https://github.com/datajoint/datajoint-python/commit/<a class="double-link" href="https://github.com/datajoint/datajoint-python/commit/6784770fd23b6bcce490d06c1ced98d9ce3e341d">6784770fd</a>">6784770fd</a><a href="https://github.com/datajoint/datajoint-python/commit/08fb99fe7a53b58a806709b7e36e69b017169f37"> into 413e2f90d">413e2f90d</a>

Run Details

801 of 801 new or added lines in 25 files covered. (100.0%)

2988 of 3313 relevant lines covered (90.19%)

0.9 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.21

/datajoint/fetch.py

from functools import partial
from pathlib import Path
import warnings
import pandas
import itertools
import re
import numpy as np
import uuid
import numbers
from . import blob, hash
from .errors import DataJointError
from .settings import config
from .utils import safe_write


class key:
    """
    object that allows requesting the primary key as an argument in expression.fetch()
    The string "KEY" can be used instead of the class key
    """

    pass


def is_key(attr):
    return attr is key or attr == "KEY"


def to_dicts(recarray):
    """convert record array to a dictionaries"""
    for rec in recarray:
        yield dict(zip(recarray.dtype.names, rec.tolist()))


def _get(connection, attr, data, squeeze, download_path):
    """
    This function is called for every attribute

    :param connection: a dj.Connection object
    :param attr: attribute name from the table's heading
    :param data: literal value fetched from the table
    :param squeeze: if True squeeze blobs
    :param download_path: for fetches that download data, e.g. attachments
    :return: unpacked data
    """
    if data is None:
        return

    extern = (
        connection.schemas[attr.database].external[attr.store]
        if attr.is_external
        else None
    )

    # apply attribute adapter if present
    adapt = attr.adapter.get if attr.adapter else lambda x: x

    if attr.is_filepath:
        return adapt(extern.download_filepath(uuid.UUID(bytes=data))[0])

    if attr.is_attachment:
        # Steps:
        # 1. get the attachment filename
        # 2. check if the file already exists at download_path, verify checksum
        # 3. if exists and checksum passes then return the local filepath
        # 4. Otherwise, download the remote file and return the new filepath
        _uuid = uuid.UUID(bytes=data) if attr.is_external else None
        attachment_name = (
            extern.get_attachment_name(_uuid)
            if attr.is_external
            else data.split(b"\0", 1)[0].decode()
        )
        local_filepath = Path(download_path) / attachment_name
        if local_filepath.is_file():
            attachment_checksum = (
                _uuid if attr.is_external else hash.uuid_from_buffer(data)
            )
            if attachment_checksum == hash.uuid_from_file(
                local_filepath, init_string=attachment_name + "\0"
            ):
                return adapt(
                    str(local_filepath)
                )  # checksum passed, no need to download again
            # generate the next available alias filename
            for n in itertools.count():
                f = local_filepath.parent / (
                    local_filepath.stem + "_%04x" % n + local_filepath.suffix
                )
                if not f.is_file():
                    local_filepath = f
                    break
                if attachment_checksum == hash.uuid_from_file(
                    f, init_string=attachment_name + "\0"
                ):
                    return adapt(str(f))  # checksum passed, no need to download again
        # Save attachment
        if attr.is_external:
            extern.download_attachment(_uuid, attachment_name, local_filepath)
        else:
            # write from buffer
            safe_write(local_filepath, data.split(b"\0", 1)[1])
        return adapt(str(local_filepath))  # download file from remote store

    return adapt(
        uuid.UUID(bytes=data)
        if attr.uuid
        else (
            blob.unpack(
                extern.get(uuid.UUID(bytes=data)) if attr.is_external else data,
                squeeze=squeeze,
            )
            if attr.is_blob
            else data
        )
    )


def _flatten_attribute_list(primary_key, attrs):
    """
    :param primary_key: list of attributes in primary key
    :param attrs: list of attribute names, which may include "KEY", "KEY DESC" or "KEY ASC"
    :return: generator of attributes where "KEY" is replaces with its component attributes
    """
    for a in attrs:
        if re.match(r"^\s*KEY(\s+[aA][Ss][Cc])?\s*$", a):
            yield from primary_key
        elif re.match(r"^\s*KEY\s+[Dd][Ee][Ss][Cc]\s*$", a):
            yield from (q + " DESC" for q in primary_key)
        else:
            yield a


class Fetch:
    """
    A fetch object that handles retrieving elements from the table expression.
    :param expression: the QueryExpression object to fetch from.
    """

    def __init__(self, expression):
        self._expression = expression

    def __call__(
        self,
        *attrs,
        offset=None,
        limit=None,
        order_by=None,
        format=None,
        as_dict=None,
        squeeze=False,
        download_path="."
    ):
        """
        Fetches the expression results from the database into an np.array or list of dictionaries and
        unpacks blob attributes.
        :param attrs: zero or more attributes to fetch. If not provided, the call will return
        all attributes of this relation. If provided, returns tuples with an entry for each attribute.
        :param offset: the number of tuples to skip in the returned result
        :param limit: the maximum number of tuples to return
        :param order_by: a single attribute or the list of attributes to order the results.
                No ordering should be assumed if order_by=None.
                To reverse the order, add DESC to the attribute name or names: e.g. ("age DESC", "frequency")
                To order by primary key, use "KEY" or "KEY DESC"
        :param format: Effective when as_dict=None and when attrs is empty
                None: default from config['fetch_format'] or 'array' if not configured
                "array": use numpy.key_array
                "frame": output pandas.DataFrame. .
        :param as_dict: returns a list of dictionaries instead of a record array.
                Defaults to False for .fetch() and to True for .fetch('KEY')
        :param squeeze:  if True, remove extra dimensions from arrays
        :param download_path: for fetches that download data, e.g. attachments
        :return: the contents of the relation in the form of a structured numpy.array or a dict list
        """
        if order_by is not None:
            # if 'order_by' passed in a string, make into list
            if isinstance(order_by, str):
                order_by = [order_by]
            # expand "KEY" or "KEY DESC"
            order_by = list(
                _flatten_attribute_list(self._expression.primary_key, order_by)
            )

        attrs_as_dict = as_dict and attrs
        if attrs_as_dict:
            # absorb KEY into attrs and prepare to return attributes as dict (issue #595)
            if any(is_key(k) for k in attrs):
                attrs = list(self._expression.primary_key) + [
                    a for a in attrs if a not in self._expression.primary_key
                ]
        if as_dict is None:
            as_dict = bool(attrs)  # default to True for "KEY" and False otherwise
        # format should not be specified with attrs or is_dict=True
        if format is not None and (as_dict or attrs):
            raise DataJointError(
                "Cannot specify output format when as_dict=True or "
                "when attributes are selected to be fetched separately."
            )
        if format not in {None, "array", "frame"}:
            raise DataJointError(
                "Fetch output format must be in "
                '{{"array", "frame"}} but "{}" was given'.format(format)
            )

        if not (attrs or as_dict) and format is None:
            format = config["fetch_format"]  # default to array
            if format not in {"array", "frame"}:
                raise DataJointError(
                    'Invalid entry "{}" in datajoint.config["fetch_format"]: '
                    'use "array" or "frame"'.format(format)
                )

        if limit is None and offset is not None:
            warnings.warn(
                "Offset set, but no limit. Setting limit to a large number. "
                "Consider setting a limit explicitly."
            )
            limit = 8000000000  # just a very large number to effect no limit

        get = partial(
            _get,
            self._expression.connection,
            squeeze=squeeze,
            download_path=download_path,
        )
        if attrs:  # a list of attributes provided
            attributes = [a for a in attrs if not is_key(a)]
            ret = self._expression.proj(*attributes)
            ret = ret.fetch(
                offset=offset,
                limit=limit,
                order_by=order_by,
                as_dict=False,
                squeeze=squeeze,
                download_path=download_path,
                format="array",
            )
            if attrs_as_dict:
                ret = [
                    {k: v for k, v in zip(ret.dtype.names, x) if k in attrs}
                    for x in ret
                ]
            else:
                return_values = [
                    list(
                        (to_dicts if as_dict else lambda x: x)(
                            ret[self._expression.primary_key]
                        )
                    )
                    if is_key(attribute)
                    else ret[attribute]
                    for attribute in attrs
                ]
                ret = return_values[0] if len(attrs) == 1 else return_values
        else:  # fetch all attributes as a numpy.record_array or pandas.DataFrame
            cur = self._expression.cursor(
                as_dict=as_dict, limit=limit, offset=offset, order_by=order_by
            )
            heading = self._expression.heading
            if as_dict:
                ret = [
                    dict((name, get(heading[name], d[name])) for name in heading.names)
                    for d in cur
                ]
            else:
                ret = list(cur.fetchall())
                record_type = (
                    heading.as_dtype
                    if not ret
                    else np.dtype(
                        [
                            (
                                name,
                                type(value),
                            )  # use the first element to determine blob type
                            if heading[name].is_blob
                            and isinstance(value, numbers.Number)
                            else (name, heading.as_dtype[name])
                            for value, name in zip(ret[0], heading.as_dtype.names)
                        ]
                    )
                )
                try:
                    ret = np.array(ret, dtype=record_type)
                except Exception as e:
                    raise e
                for name in heading:
                    # unpack blobs and externals
                    ret[name] = list(map(partial(get, heading[name]), ret[name]))
                if format == "frame":
                    ret = pandas.DataFrame(ret).set_index(heading.primary_key)
        return ret


class Fetch1:
    """
    Fetch object for fetching the result of a query yielding one row.
    :param expression: a query expression to fetch from.
    """

    def __init__(self, expression):
        self._expression = expression

    def __call__(self, *attrs, squeeze=False, download_path="."):
        """
        Fetches the result of a query expression that yields one entry.

        If no attributes are specified, returns the result as a dict.
        If attributes are specified returns the corresponding results as a tuple.

        Examples:
        d = rel.fetch1()   # as a dictionary
        a, b = rel.fetch1('a', 'b')   # as a tuple

        :params *attrs: attributes to return when expanding into a tuple.
                 If attrs is empty, the return result is a dict
        :param squeeze:  When true, remove extra dimensions from arrays in attributes
        :param download_path: for fetches that download data, e.g. attachments
        :return: the one tuple in the relation in the form of a dict
        """
        heading = self._expression.heading

        if not attrs:  # fetch all attributes, return as ordered dict
            cur = self._expression.cursor(as_dict=True)
            ret = cur.fetchone()
            if not ret or cur.fetchone():
                raise DataJointError(
                    "fetch1 requires exactly one tuple in the input set."
                )
            ret = dict(
                (
                    name,
                    _get(
                        self._expression.connection,
                        heading[name],
                        ret[name],
                        squeeze=squeeze,
                        download_path=download_path,
                    ),
                )
                for name in heading.names
            )
        else:  # fetch some attributes, return as tuple
            attributes = [a for a in attrs if not is_key(a)]
            result = self._expression.proj(*attributes).fetch(
                squeeze=squeeze, download_path=download_path, format="array"
            )
            if len(result) != 1:
                raise DataJointError(
                    "fetch1 should only return one tuple. %d tuples found" % len(result)
                )
            return_values = tuple(
                next(to_dicts(result[self._expression.primary_key]))
                if is_key(attribute)
                else result[attribute][0]
                for attribute in attrs
            )
            ret = return_values[0] if len(attrs) == 1 else return_values
        return ret

1	from functools import partial	1✔
2	from pathlib import Path	1✔
3	import warnings	1✔
4	import pandas	1✔
5	import itertools	1✔
6	import re	1✔
7	import numpy as np	1✔
8	import uuid	1✔
9	import numbers	1✔
10	from . import blob, hash	1✔
11	from .errors import DataJointError	1✔
12	from .settings import config	1✔
13	from .utils import safe_write	1✔
14
15
16	class key:	1✔
17	"""
18	object that allows requesting the primary key as an argument in expression.fetch()
19	The string "KEY" can be used instead of the class key
20	"""
21
22	pass	1✔
23
24
25	def is_key(attr):	1✔
26	return attr is key or attr == "KEY"	1✔
27
28
29	def to_dicts(recarray):	1✔
30	"""convert record array to a dictionaries"""
31	for rec in recarray:	1✔
32	yield dict(zip(recarray.dtype.names, rec.tolist()))	1✔
33
34
35	def _get(connection, attr, data, squeeze, download_path):	1✔
36	"""
37	This function is called for every attribute
38
39	:param connection: a dj.Connection object
40	:param attr: attribute name from the table's heading
41	:param data: literal value fetched from the table
42	:param squeeze: if True squeeze blobs
43	:param download_path: for fetches that download data, e.g. attachments
44	:return: unpacked data
45	"""
46	if data is None:	1✔
47	return	1✔
48
49	extern = (	1✔
50	connection.schemas[attr.database].external[attr.store]
51	if attr.is_external
52	else None
53	)
54
55	# apply attribute adapter if present
56	adapt = attr.adapter.get if attr.adapter else lambda x: x	1✔
57
58	if attr.is_filepath:	1✔
59	return adapt(extern.download_filepath(uuid.UUID(bytes=data))[0])	1✔
60
61	if attr.is_attachment:	1✔
62	# Steps:
63	# 1. get the attachment filename
64	# 2. check if the file already exists at download_path, verify checksum
65	# 3. if exists and checksum passes then return the local filepath
66	# 4. Otherwise, download the remote file and return the new filepath
67	_uuid = uuid.UUID(bytes=data) if attr.is_external else None	1✔
68	attachment_name = (	1✔
69	extern.get_attachment_name(_uuid)
70	if attr.is_external
71	else data.split(b"\0", 1)[0].decode()
72	)
73	local_filepath = Path(download_path) / attachment_name	1✔
74	if local_filepath.is_file():	1✔
75	attachment_checksum = (	1✔
76	_uuid if attr.is_external else hash.uuid_from_buffer(data)
77	)
78	if attachment_checksum == hash.uuid_from_file(	1✔
79	local_filepath, init_string=attachment_name + "\0"
80	):
81	return adapt(	1✔
82	str(local_filepath)
83	) # checksum passed, no need to download again
84	# generate the next available alias filename
85	for n in itertools.count():	1✔
86	f = local_filepath.parent / (	1✔
87	local_filepath.stem + "_%04x" % n + local_filepath.suffix
88	)
89	if not f.is_file():	1✔
90	local_filepath = f	1✔
91	break	1✔
92	if attachment_checksum == hash.uuid_from_file(	1✔
93	f, init_string=attachment_name + "\0"
94	):
95	return adapt(str(f)) # checksum passed, no need to download again	×
96	# Save attachment
97	if attr.is_external:	1✔
98	extern.download_attachment(_uuid, attachment_name, local_filepath)	1✔
99	else:
100	# write from buffer
101	safe_write(local_filepath, data.split(b"\0", 1)[1])	1✔
102	return adapt(str(local_filepath)) # download file from remote store	1✔
103
104	return adapt(	1✔
105	uuid.UUID(bytes=data)
106	if attr.uuid
107	else (
108	blob.unpack(
109	extern.get(uuid.UUID(bytes=data)) if attr.is_external else data,
110	squeeze=squeeze,
111	)
112	if attr.is_blob
113	else data
114	)
115	)
116
117
118	def _flatten_attribute_list(primary_key, attrs):	1✔
119	"""
120	:param primary_key: list of attributes in primary key
121	:param attrs: list of attribute names, which may include "KEY", "KEY DESC" or "KEY ASC"
122	:return: generator of attributes where "KEY" is replaces with its component attributes
123	"""
124	for a in attrs:	1✔
125	if re.match(r"^\sKEY(\s+[aA][Ss][Cc])?\s$", a):	1✔
126	yield from primary_key	1✔
127	elif re.match(r"^\sKEY\s+[Dd][Ee][Ss][Cc]\s$", a):	1✔
128	yield from (q + " DESC" for q in primary_key)	1✔
129	else:
130	yield a	1✔
131
132
133	class Fetch:	1✔
134	"""
135	A fetch object that handles retrieving elements from the table expression.
136	:param expression: the QueryExpression object to fetch from.
137	"""
138
139	def __init__(self, expression):	1✔
140	self._expression = expression	1✔
141
142	def __call__(	1✔
143	self,
144	*attrs,
145	offset=None,
146	limit=None,
147	order_by=None,
148	format=None,
149	as_dict=None,
150	squeeze=False,
151	download_path="."
152	):
153	"""
154	Fetches the expression results from the database into an np.array or list of dictionaries and
155	unpacks blob attributes.
156	:param attrs: zero or more attributes to fetch. If not provided, the call will return
157	all attributes of this relation. If provided, returns tuples with an entry for each attribute.
158	:param offset: the number of tuples to skip in the returned result
159	:param limit: the maximum number of tuples to return
160	:param order_by: a single attribute or the list of attributes to order the results.
161	No ordering should be assumed if order_by=None.
162	To reverse the order, add DESC to the attribute name or names: e.g. ("age DESC", "frequency")
163	To order by primary key, use "KEY" or "KEY DESC"
164	:param format: Effective when as_dict=None and when attrs is empty
165	None: default from config['fetch_format'] or 'array' if not configured
166	"array": use numpy.key_array
167	"frame": output pandas.DataFrame. .
168	:param as_dict: returns a list of dictionaries instead of a record array.
169	Defaults to False for .fetch() and to True for .fetch('KEY')
170	:param squeeze: if True, remove extra dimensions from arrays
171	:param download_path: for fetches that download data, e.g. attachments
172	:return: the contents of the relation in the form of a structured numpy.array or a dict list
173	"""
174	if order_by is not None:	1✔
175	# if 'order_by' passed in a string, make into list
176	if isinstance(order_by, str):	1✔
177	order_by = [order_by]	1✔
178	# expand "KEY" or "KEY DESC"
179	order_by = list(	1✔
180	_flatten_attribute_list(self._expression.primary_key, order_by)
181	)
182
183	attrs_as_dict = as_dict and attrs	1✔
184	if attrs_as_dict:	1✔
185	# absorb KEY into attrs and prepare to return attributes as dict (issue #595)
186	if any(is_key(k) for k in attrs):	1✔
187	attrs = list(self._expression.primary_key) + [	×
188	a for a in attrs if a not in self._expression.primary_key
189	]
190	if as_dict is None:	1✔
191	as_dict = bool(attrs) # default to True for "KEY" and False otherwise	1✔
192	# format should not be specified with attrs or is_dict=True
193	if format is not None and (as_dict or attrs):	1✔
194	raise DataJointError(	×
195	"Cannot specify output format when as_dict=True or "
196	"when attributes are selected to be fetched separately."
197	)
198	if format not in {None, "array", "frame"}:	1✔
199	raise DataJointError(	×
200	"Fetch output format must be in "
201	'{{"array", "frame"}} but "{}" was given'.format(format)
202	)
203
204	if not (attrs or as_dict) and format is None:	1✔
205	format = config["fetch_format"] # default to array	1✔
206	if format not in {"array", "frame"}:	1✔
207	raise DataJointError(	×
208	'Invalid entry "{}" in datajoint.config["fetch_format"]: '
209	'use "array" or "frame"'.format(format)
210	)
211
212	if limit is None and offset is not None:	1✔
213	warnings.warn(	1✔
214	"Offset set, but no limit. Setting limit to a large number. "
215	"Consider setting a limit explicitly."
216	)
217	limit = 8000000000 # just a very large number to effect no limit	1✔
218
219	get = partial(	1✔
220	_get,
221	self._expression.connection,
222	squeeze=squeeze,
223	download_path=download_path,
224	)
225	if attrs: # a list of attributes provided	1✔
226	attributes = [a for a in attrs if not is_key(a)]	1✔
227	ret = self._expression.proj(*attributes)	1✔
228	ret = ret.fetch(	1✔
229	offset=offset,
230	limit=limit,
231	order_by=order_by,
232	as_dict=False,
233	squeeze=squeeze,
234	download_path=download_path,
235	format="array",
236	)
237	if attrs_as_dict:	1✔
238	ret = [	1✔
239	{k: v for k, v in zip(ret.dtype.names, x) if k in attrs}
240	for x in ret
241	]
242	else:
243	return_values = [	1✔
244	list(
245	(to_dicts if as_dict else lambda x: x)(
246	ret[self._expression.primary_key]
247	)
248	)
249	if is_key(attribute)
250	else ret[attribute]
251	for attribute in attrs
252	]
253	ret = return_values[0] if len(attrs) == 1 else return_values	1✔
254	else: # fetch all attributes as a numpy.record_array or pandas.DataFrame
255	cur = self._expression.cursor(	1✔
256	as_dict=as_dict, limit=limit, offset=offset, order_by=order_by
257	)
258	heading = self._expression.heading	1✔
259	if as_dict:	1✔
260	ret = [	1✔
261	dict((name, get(heading[name], d[name])) for name in heading.names)
262	for d in cur
263	]
264	else:
265	ret = list(cur.fetchall())	1✔
266	record_type = (	1✔
267	heading.as_dtype
268	if not ret
269	else np.dtype(
270	[
271	(
272	name,
273	type(value),
274	) # use the first element to determine blob type
275	if heading[name].is_blob
276	and isinstance(value, numbers.Number)
277	else (name, heading.as_dtype[name])
278	for value, name in zip(ret[0], heading.as_dtype.names)
279	]
280	)
281	)
282	try:	1✔
283	ret = np.array(ret, dtype=record_type)	1✔
284	except Exception as e:	×
285	raise e	×
286	for name in heading:	1✔
287	# unpack blobs and externals
288	ret[name] = list(map(partial(get, heading[name]), ret[name]))	1✔
289	if format == "frame":	1✔
290	ret = pandas.DataFrame(ret).set_index(heading.primary_key)	1✔
291	return ret	1✔
292
293
294	class Fetch1:	1✔
295	"""
296	Fetch object for fetching the result of a query yielding one row.
297	:param expression: a query expression to fetch from.
298	"""
299
300	def __init__(self, expression):	1✔
301	self._expression = expression	1✔
302
303	def __call__(self, *attrs, squeeze=False, download_path="."):	1✔
304	"""
305	Fetches the result of a query expression that yields one entry.
306
307	If no attributes are specified, returns the result as a dict.
308	If attributes are specified returns the corresponding results as a tuple.
309
310	Examples:
311	d = rel.fetch1() # as a dictionary
312	a, b = rel.fetch1('a', 'b') # as a tuple
313
314	:params *attrs: attributes to return when expanding into a tuple.
315	If attrs is empty, the return result is a dict
316	:param squeeze: When true, remove extra dimensions from arrays in attributes
317	:param download_path: for fetches that download data, e.g. attachments
318	:return: the one tuple in the relation in the form of a dict
319	"""
320	heading = self._expression.heading	1✔
321
322	if not attrs: # fetch all attributes, return as ordered dict	1✔
323	cur = self._expression.cursor(as_dict=True)	1✔
324	ret = cur.fetchone()	1✔
325	if not ret or cur.fetchone():	1✔
326	raise DataJointError(	1✔
327	"fetch1 requires exactly one tuple in the input set."
328	)
329	ret = dict(	1✔
330	(
331	name,
332	_get(
333	self._expression.connection,
334	heading[name],
335	ret[name],
336	squeeze=squeeze,
337	download_path=download_path,
338	),
339	)
340	for name in heading.names
341	)
342	else: # fetch some attributes, return as tuple
343	attributes = [a for a in attrs if not is_key(a)]	1✔
344	result = self._expression.proj(*attributes).fetch(	1✔
345	squeeze=squeeze, download_path=download_path, format="array"
346	)
347	if len(result) != 1:	1✔
348	raise DataJointError(	1✔
349	"fetch1 should only return one tuple. %d tuples found" % len(result)
350	)
351	return_values = tuple(	1✔
352	next(to_dicts(result[self._expression.primary_key]))
353	if is_key(attribute)
354	else result[attribute][0]
355	for attribute in attrs
356	)
357	ret = return_values[0] if len(attrs) == 1 else return_values	1✔
358	return ret	1✔

datajoint / datajoint-python / #11934

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous