Coverage for pandalone/xleash/io/backend.py : 95%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
#!/usr/bin/env python # -*- coding: UTF-8 -*- # # Copyright 2014-2019European Commission (JRC); # Licensed under the EUPL (the 'Licence'); # You may not use this work except in compliance with the Licence. # You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl The manager and the base for all :term:`backends` fetching cells from actual workbooks and sheets.
Prefer accessing the public members from the parent module.
.. currentmodule:: pandalone.xleash """
"""A plugin for a :term:`backend` must implement and add instances into :data:`io_backends`."""
def bid(self, wb_url): """ Express the willingness to handle a workbook when deciding backends.
:param wb_url: a full-url of a workbook, local('file://) or remote('http://') :return: - an integer signifying willingness; bigger integers take precedence. - `None` signifies invalidness. """
def open_sheet(self, wb_url, sheet_id): """ Open a :class:`ABCSheet` subclass, if backend has won the bid.
:param wb_url: a full-url of a workbook, local('file://) or remote('http://') """
def list_sheetnames(self, wb_url): """Returns a list of sheet-names, if bids "decided" this backend."""
""" Asks :term:`backends` to bid for creating :class:`ABCSheet` instances - client should handle resources.
Backends are taken from :data:`io_backends` or specified during construction. """
""" :param backends: The list of :class:`backends` to consider when opening sheets. If it evaluates to false, :data:`io_backends` assumed. :typ backends: list or None """
""" :param ABCSheet base_sheet: The sheet used when unspecified `wb_url`. """ if sheet_id is None: sheet = base_sheet else: base_sheet.open_sibling_sheet(sheet_id) else: url = utils.path2url(wb_url) sheet = self._open_sheet(url, sheet_id)
assert sheet, (wb_url, sheet_id) return sheet
"""Asks all :attr:`backends` to :term:`bid` for handling a :term:`xl-ref`. """ "No suitable xleash-backend found for(%r)!" "\n Have you installed `xlrd` extra with this command?" "\n pip install pandalone[xlrd]" % wb_url )
raise ValueError("Backend(%s) found no sheet for(%r)!" % (be, url))
""" A caching-store of :class:`ABCSheet` instances, serving them based on (workbook, sheet) IDs, optionally creating them from backends.
:ivar dict _cached_sheets: A cache of all _Spreadsheets accessed so far, keyed by multiple keys generated by :meth:`_derive_sheet_keys`.
- To avoid opening non-trivial workbooks, use the :meth:`add_sheet()` to pre-populate this cache with them.
- It is a resource-manager for contained sheets, so it can be used wth a `with` statement.
"""
""" :param backends: The list of :class:`backends` to consider when opening sheets. If it evaluates to false, :data:`io_backends` assumed. :typ backends: list or None """
else:
""" Retuns the product of user-specified and sheet-internal keys.
:param wb_ids: a single or a sequence of extra workbook-ids (ie: file, url) :param sh_ids: a single or sequence of extra sheet-ids (ie: name, index, None) """
"""Closes all contained sheets and empties cache."""
""" Updates cache.
:param wb_ids: a single or sequence of extra workbook-ids (ie: file, url) :param sh_ids: a single or sequence of extra sheet-ids (ie: name, index, None) """
""" :param ABCSheet base_sheet: The sheet used when unspecified `wb_id`. """ else:
else: else:
""" Returns top-left/bottom-down margins of full cells from a :term:`state` matrix.
May be used by :meth:`ABCSheet.get_margin_coords()` if a backend does not report the sheet-margins internally.
:param np.ndarray states_matrix: A 2D-array with `False` wherever cell are blank or empty. Use :meth:`ABCSheet.get_states_matrix()` to derrive it. :return: the 2 coords of the top-left & bottom-right full cells :rtype: (Coords, Coords)
Examples:: >>> states_matrix = np.asarray([ ... [0, 0, 0], ... [0, 1, 0], ... [0, 1, 1], ... [0, 0, 1], ... ]) >>> margins = margin_coords_from_states_matrix(states_matrix) >>> margins (Coords(row=1, col=1), Coords(row=3, col=2))
Note that the botom-left cell is not the same as `states_matrix` matrix size::
>>> states_matrix = np.asarray([ ... [0, 0, 0, 0], ... [0, 1, 0, 0], ... [0, 1, 1, 0], ... [0, 0, 1, 0], ... [0, 0, 0, 0], ... ]) >>> margin_coords_from_states_matrix(states_matrix) == margins True
"""
# return indices.min(0), indices.max(0)
""" A delegating to backend factory and sheet-wrapper with utility methods.
:param np.ndarray _states_matrix: The :term:`states-matrix` cached, so recreate object to refresh it. :param dict _margin_coords: limits used by :func:`_resolve_cell`, cached, so recreate object to refresh it.
Resource management is outside of the scope of this class, and must happen in the backend workbook/sheet instance.
*xlrd* examples::
>>> import xlrd # doctest: +SKIP >>> with xlrd.open_workbook(self.tmp) as wb: # doctest: +SKIP ... sheet = xleash.xlrdSheet(wb.sheet_by_name('Sheet1')) ... ## Do whatever
*win32* examples::
>>> with dsgdsdsfsd as wb: # doctest: +SKIP ... sheet = xleash.win32Sheet(wb.sheet['Sheet1']) TODO: Win32 Sheet example """
""" Override it to release resources for this sheet."""
""" Override it to release resources this and all sibling sheets."""
def get_sheet_ids(self): """ :return: a 2-tuple of its wb-name and a sheet-ids of this sheet i.e. name & indx :rtype: SheetId or None """
def open_sibling_sheet(self, sheet_id): """Return a sibling sheet by the given index or name"""
def list_sheetnames(self): """Return a list of names"""
def _read_states_matrix(self): """ Read the :term:`states-matrix` of the wrapped sheet.
:return: A 2D-array with `False` wherever cell are blank or empty. :rtype: ndarray """
""" Read and cache the :term:`states-matrix` of the wrapped sheet.
:return: A 2D-array with `False` wherever cell are blank or empty. :rtype: ndarray :raise: EmptyCaptureException if sheet empty """
def read_rect(self, st, nd): """ Fecth the actual values from the backend Excel-sheet.
:param Coords st: the top-left edge, inclusive :param Coords, None nd: the bottom-right edge, inclusive(!); when `None`, must return a scalar value. :type nd: Coords, None :return: Depends on whether both coords are given: - If both given, 2D list-lists with the values of the rect, which might be empty if beyond limits. - If only 1st given, the scalar value, and if beyond margins, raise error!
:rtype: list :raise: EmptyCaptureException (optionally) if sheet empty """
""" Override if possible to read (any of the) limits directly from the sheet.
:return: the 2 coords of the top-left & bottom-right full cells; anyone coords can be None. By default returns ``(None, None)``. :rtype: (Coords, Coords) :raise: EmptyCaptureException if sheet empty """ return None, None # pragma: no cover
""" Extract (and cache) margins either internally or from :func:`margin_coords_from_states_matrix()`.
:return: the resolved top-left and bottom-right :class:`.xleash.Coords` :rtype: tuple :raise: EmptyCaptureException if sheet empty """
"""A sample :class:`ABCSheet` made out of 2D-list or numpy-arrays, for facilitating tests."""
raise NotImplementedError()
|