#12408

pending completion

Build # #12408

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/437315ef14fe6c8b9f94dc5a7dc663521ea53603">437315ef1<a href="https://github.com/datajoint/datajoint-python/commit/437315ef14fe6c8b9f94dc5a7dc663521ea53603">">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/dc96601ea845a325104f97044fea57928db6c5ab">dc96601ea</a>">dc96601ea</a><a href="https://github.com/datajoint/datajoint-python/commit/437315ef14fe6c8b9f94dc5a7dc663521ea53603"> into 0ff34f283">0ff34f283</a>

Run Details

58 of 58 new or added lines in 14 files covered. (100.0%)

3085 of 3421 relevant lines covered (90.18%)

0.9 hits per line

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

94.26

/datajoint/fetch.py

from functools import partial
from pathlib import Path
import logging
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

logger = logging.getLogger(__name__.split(".")[0])


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

datajoint / datajoint-python / #12408

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