Changed period into abstract class and moved docstrings

financeager/period.py

@@ -5,6 +5,7 @@
 from dateutil import rrule
 from datetime import datetime as dt
 import re
+from abc import ABC, abstractmethod
 
 from tinydb import TinyDB, Query, storages
 from tinydb.database import Element
@@ -41,7 +42,7 @@ class RecurrentEntryValidationModel(BaseValidationModel):
  end = DateType(formats=("%Y-%m-%d", PERIOD_DATE_FORMAT))
 
 
-class Period:
+class Period(ABC):
  def __init__(self, name=None):
  """Create Period object. Its name defaults to the current year if not
  specified.
@@ -57,56 +58,92 @@ def year(self):
  """Return period year as integer."""
  return int(self._name)
 
-
-class PeriodException(Exception):
- pass
-
-
-class TinyDbPeriod(Period):
- def __init__(self, name=None, data_dir=None, **kwargs):
- """Create a period with a TinyDB database backend, identified by 'name'.
- If 'data_dir' is given, the database storage type is JSON (the storage
- filepath is derived from the Period's name). Otherwise the data is
- stored in memory.
- Keyword args are passed to the TinyDB constructor. See the respective
- docs for detailed information.
+ @abstractmethod
+ def add_entry(self, table_name=None, **kwargs):
+ """Add an entry (standard or recurrent) to the database.
+ If 'table_name' is not specified, the kwargs name, value[, category,
+ date] are used to insert a unique entry in the standard table.
+ With 'table_name' as 'recurrent', the kwargs name, value, frequency
+ [, start, end, category] are used to insert a template entry in the
+ recurrent table.
+ Two kwargs are mandatory:
+ :param name: entry name
+ :type name: str
+ :param value: entry value
+ :type value: float, int or str
+ The following kwarg is optional:
+ :param category: entry category. If not specified, the program
+ attempts to derive it from previous, eponymous entries. If this
+ fails, ``_DEFAULT_CATEGORY`` is assigned
+ :type category: str or None
+ The following kwarg is optional for standard entries:
+ :param date: entry date. Defaults to current date
+ :type date: str of ``PERIOD_DATE_FORMAT``
+ The following kwarg is mandatory for recurrent entries:
+ :param frequency: 'yearly', 'half-yearly', 'quarter-yearly',
+ 'bimonthly', 'monthly', 'weekly' or 'daily'
+ The following kwargs are optional for recurrent entries:
+ :param start: start date (defaults to current date)
+ :param end: end date (defaults to last day of the period's year)
+ :raise: PeriodException if validation failed or table name unknown
+ :return: ID of new entry (int)
  """
 
- super().__init__(name=name)
+ @abstractmethod
+ def remove_entry(self, eid, table_name=None):
+ """Remove an entry from the Period database given its ID. The category
+ cache is updated.
+ :param eid: ID of the entry to be deleted.
+ :type eid: int or str
+ :param table_name: name of the table that contains the entry.
+ Default: 'standard'
+ :type table_name: str
+ :raise: PeriodException if entry/ID not found.
+ :return: entry ID if removal was successful
+ """
 
- # evaluate args/kwargs for TinyDB constructor. This overwrites the
- # 'storage' kwarg if explicitly passed
- if data_dir is None:
- args = []
- kwargs["storage"] = storages.MemoryStorage
- else:
- args = [os.path.join(data_dir, "{}.json".format(self.name))]
- kwargs["storage"] = storages.JSONStorage
+ @abstractmethod
+ def update_entry(self, eid, table_name=None, **kwargs):
+ """Update one or more fields of a single entry of the Period.
+ :param eid: entry ID of the entry to be updated
+ :param table_name: table that the entry is stored in (default:
+ 'standard')
+ :param kwargs: 'date' for standard entries; any of 'frequency', 'start',
+ 'end' for recurrent entries; any of 'name', 'value', 'category' for
+ either entry type
+ :raise: PeriodException if entry not found
+ :return: ID of the updated entry
+ """
 
- self._db = TinyDB(*args, **kwargs)
- self._create_category_cache()
+ @abstractmethod
+ def get_entry(self, eid, table_name=None):
+ """Get entry specified by ``eid`` in the table ``table_name`` (defaults to
+ table 'standard').
+ :type eid: int or str
+ :raise: PeriodException if entry not found
+ :return: found entry
+ """
 
- def _create_category_cache(self):
- """The category cache assigns a counter for each element name in the
- database (excluding recurrent elements), keeping track of the
- categories the element was labeled with. This allows deriving the
- category of an element if not explicitly given."""
- self._category_cache = defaultdict(Counter)
- for element in self._db.all():
- self._category_cache[element["name"]].update([element["category"]])
+ @abstractmethod
+ def get_entries(self, filters=None):
+ """Get dict of standard and recurrent entries that match the items of
+ the filters dict, if specified. Constructs a condition from the given
+ filters and uses it to query all tables.
+ :return: dict{
+ DEFAULT_TABLE: dict{ int: entry },
+ "recurrent": dict{ int: list[entry] }
+ }
+ """
 
  def _preprocess_entry(self, raw_data=None, table_name=None, partial=False):
  """Perform preprocessing steps (validation, conversion, substitution) of
  raw entry fields prior to adding it to the database.
-
  :param raw_data: dict containing raw entry fields
  :param table_name: name of the table that the entry is passed to
  :param partial: indicates whether preprocessing is performed before
  adding (False) or updating (True) the database
-
  :raise: PeriodException if validation failed or table name unknown
  """
-
  table_name = table_name or DEFAULT_TABLE
  if table_name not in ["recurrent", DEFAULT_TABLE]:
  raise PeriodException("Unknown table name: {}".format(table_name))
@@ -130,7 +167,6 @@ def _remove_redundant_fields(table_name, raw_data):
  schematics validation ('Rogue field' error). This method removes
  redundant fields in `raw_data` in-place.
  """
-
  if table_name == "recurrent":
  redundant_fields = ["date"]
  else:
@@ -142,11 +178,9 @@ def _remove_redundant_fields(table_name, raw_data):
  @staticmethod
  def _validate_entry(raw_data, table_name, **model_kwargs):
  """Validate raw entry data acc. to ValidationModel.
-
  :return: primitive (type-correct) representation of fields
  :raise: PeriodException if validation failed
  """
-
  ValidationModel = RecurrentEntryValidationModel \
  if table_name == "recurrent" else StandardEntryValidationModel
 
@@ -165,27 +199,8 @@ def _validate_entry(raw_data, table_name, **model_kwargs):
  raise PeriodException("Invalid input data:\n{}".format(
  "\n".join(infos)))
 
- @staticmethod
- def _convert_fields(**fields):
- """Convert string field values to lowercase for storage. Fields with
- value None are discarded.
- """
-
- converted_fields = {}
-
- for k, v in fields.items():
- if v is None:
- continue
- try:
- converted_fields[k] = v.lower()
- except AttributeError:
- converted_fields[k] = v
-
- return converted_fields
-
  def _substitute_none_fields(self, table_name, **fields):
  """Substitute optional fields by defaults."""
-
  substituted_fields = fields.copy()
 
  # table_name is either of two values; verified in _preprocess_entry
@@ -222,19 +237,72 @@ def _substitute_none_fields(self, table_name, **fields):
 
  return substituted_fields
 
+ @staticmethod
+ def _convert_fields(**fields):
+ """Convert string field values to lowercase for storage. Fields with
+ value None are discarded.
+ """
+ converted_fields = {}
+
+ for k, v in fields.items():
+ if v is None:
+ continue
+ try:
+ converted_fields[k] = v.lower()
+ except AttributeError:
+ converted_fields[k] = v
+
+ return converted_fields
+
+
+class PeriodException(Exception):
+ pass
+
+
+class TinyDbPeriod(Period):
+ def __init__(self, name=None, data_dir=None, **kwargs):
+ """Create a period with a TinyDB database backend, identified by 'name'.
+ If 'data_dir' is given, the database storage type is JSON (the storage
+ filepath is derived from the Period's name). Otherwise the data is
+ stored in memory.
+ Keyword args are passed to the TinyDB constructor. See the respective
+ docs for detailed information.
+ """
+
+ super().__init__(name=name)
+
+ # evaluate args/kwargs for TinyDB constructor. This overwrites the
+ # 'storage' kwarg if explicitly passed
+ if data_dir is None:
+ args = []
+ kwargs["storage"] = storages.MemoryStorage
+ else:
+ args = [os.path.join(data_dir, "{}.json".format(self.name))]
+ kwargs["storage"] = storages.JSONStorage
+
+ self._db = TinyDB(*args, **kwargs)
+ self._create_category_cache()
+
+ def _create_category_cache(self):
+ """The category cache assigns a counter for each element name in the
+ database (excluding recurrent elements), keeping track of the
+ categories the element was labeled with. This allows deriving the
+ category of an element if not explicitly given."""
+ self._category_cache = defaultdict(Counter)
+ for element in self._db.all():
+ self._category_cache[element["name"]].update([element["category"]])
+
  def _update_category_cache(self,
  eid=None,
  table_name=None,
  removing=False,
  **fields):
  """Update the category cache when adding or updating an entry. The `eid`
  kwarg is used to distinguish the use cases.
-
  :param eid: element ID when updating
  :param table_name: table name when updating
  :param removing: indicate updating cache after removing an entry
  :param fields: preprossed entry fields to be inserted in the database
-
  :raise: PeriodException if element not found when updating
  """
 
@@ -260,41 +328,6 @@ def _update_category_cache(self,
  old_category] += 1
 
  def add_entry(self, table_name=None, **kwargs):
- """
- Add an entry (standard or recurrent) to the database.
- If 'table_name' is not specified, the kwargs name, value[, category,
- date] are used to insert a unique entry in the standard table.
- With 'table_name' as 'recurrent', the kwargs name, value, frequency
- [, start, end, category] are used to insert a template entry in the
- recurrent table.
-
- Two kwargs are mandatory:
- :param name: entry name
- :type name: str
- :param value: entry value
- :type value: float, int or str
-
- The following kwarg is optional:
- :param category: entry category. If not specified, the program
- attempts to derive it from previous, eponymous entries. If this
- fails, ``_DEFAULT_CATEGORY`` is assigned
- :type category: str or None
-
- The following kwarg is optional for standard entries:
- :param date: entry date. Defaults to current date
- :type date: str of ``PERIOD_DATE_FORMAT``
-
- The following kwarg is mandatory for recurrent entries:
- :param frequency: 'yearly', 'half-yearly', 'quarter-yearly',
- 'bimonthly', 'monthly', 'weekly' or 'daily'
-
- The following kwargs are optional for recurrent entries:
- :param start: start date (defaults to current date)
- :param end: end date (defaults to last day of the period's year)
-
- :raise: PeriodException if validation failed or table name unknown
- :return: TinyDB ID of new entry (int)
- """
 
  table_name = table_name or DEFAULT_TABLE
  fields = self._preprocess_entry(raw_data=kwargs, table_name=table_name)
@@ -306,15 +339,6 @@ def add_entry(self, table_name=None, **kwargs):
  return element_id
 
  def get_entry(self, eid, table_name=None):
- """
- Get entry specified by ``eid`` in the table ``table_name`` (defaults to
- table 'standard').
-
- :type eid: int or str
-
- :raise: PeriodException if element not found
- :return: found element (tinydb.Element)
- """
 
  table_name = table_name or DEFAULT_TABLE
  element = self._db.table(table_name).get(eid=int(eid))
@@ -324,17 +348,6 @@ def get_entry(self, eid, table_name=None):
  return element
 
  def update_entry(self, eid, table_name=None, **kwargs):
- """Update one or more fields of a single entry of the Period.
-
- :param eid: entry ID of the entry to be updated
- :param table_name: table that the entry is stored in (default:
- 'standard')
- :param kwargs: 'date' for standard entries; any of 'frequency', 'start',
- 'end' for recurrent entries; any of 'name', 'value', 'category' for
- either entry type
- :raise: PeriodException if element not found
- :return: ID of the updated entry
- """
 
  table_name = table_name or DEFAULT_TABLE
  fields = self._preprocess_entry(
@@ -350,17 +363,14 @@ def update_entry(self, eid, table_name=None, **kwargs):
  def _search_all_tables(self, query_impl=None):
  """Search both the standard table and the recurrent table for elements
  that satisfy the given condition.
-
  The elements' `eid` attribute is used as key in the returned subdicts
  because it is lost in the client-server communication protocol (on
  `financeager print`, the server calls Period.get_entries, yet the
  JSON response returned drops the Element.eid attribute s.t. it's not
  available when calling prettify on the client side).
-
  :param query_impl: condition for the search. If none (default), all
  elements are returned.
  :type query_impl: tinydb.queries.QueryImpl
-
  :return: dict
  """
 
@@ -445,18 +455,6 @@ def _create_recurrent_elements(self, element):
  date=date.strftime(PERIOD_DATE_FORMAT)))
 
  def remove_entry(self, eid, table_name=None):
- """Remove an entry from the Period database given its ID. The category
- cache is updated.
-
- :param eid: ID of the element to be deleted.
- :type eid: int or str
- :param table_name: name of the table that contains the element.
- Default: 'standard'
- :type table_name: str
-
- :raise: PeriodException if element/ID not found.
- :return: element ID if removal was successful
- """
 
  table_name = table_name or DEFAULT_TABLE
  # might raise PeriodException if ID not existing
@@ -518,10 +516,7 @@ def test(e):
  return condition
 
  def get_entries(self, filters=None):
- """Get dict of standard and recurrent entries that match the items of
- the filters dict, if specified. Constructs a condition from the given
- filters and uses it to query all tables.
-
+ """
  :return: dict{
  DEFAULT_TABLE: dict{ int: tinydb.Element },
  "recurrent": dict{ int: list[tinydb.Element] }