Update documentation related to subclassing

[zks0002]

Description

I tried to subclass the FixedPoint class and ran into several issues.

• It seems that the context manager is used internally in several functions. For those functions, I can't use super() because the attributes added by the child class do not get saved.

• fixedpoint.functions only support fixedpoint.FixedPoint objects.

• property setters are used in the context manager exit, which apparently don't get inherited (given the examples below).

Steps to reproduce

>>> from fixedpoint import FixedPoint
>>> FixedPoint.enable_logging()
>>> class Hello(FixedPoint):
...     __slots__ = '_myattr',
...     def __init__(self, value, myattr):
...         super().__init__(value)
...         self._myattr = myattr
...     def myfunc(self):
...         with self:
...             self._myattr = 'modified!'
...             print(self._myattr)
...         print(self._myattr)
...
>>> x = Hello(42, 'original')
>>> print(x._myattr)
original
>>> x.myfunc()
modified!
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in myfunc
  File "C:\Python38\lib\site-packages\fixedpoint\fixedpoint.py", line 1104, in __exit__
    self.__class__.__dict__[attr].fset(self, value)
KeyError: 'str_base'

Expected Behavior

Update the documentation to provide specific steps for subclassing. An example would be nice.

As far as the code example, I'd expect this:

>>> x = Hello(42, 'original')
>>> print(x._myattr)
original
>>> x.myfunc()
modified!
original
>>> print(x._myattr)
original

Environment

• Operating System: Windows 10
• Python version (output of python -V): 3.8.0
• fixedpoint version (find in the output of pip list): 1.0.1

Logs

From the example code above:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEBUG: FP.1.__init__ LINE 261 (17 Jun 2020 @ 16:34:14.237
Deduced fractional length: 0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEBUG: FP.1.__init__ LINE 272 (17 Jun 2020 @ 16:34:14.238
Deduced integer length: 6
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEBUG: FP.1.__init__ LINE 299 (17 Jun 2020 @ 16:34:14.238
--------------------------------------------------------------------------------
intended: 42
Q format: UQ6.0
overflow: clamp
rounding: nearest
overflow_alert: error
mismatch_alert: warning
implicit_cast_alert: warning
str_base: 16
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEBUG: FP.1.from_int LINE 349 (17 Jun 2020 @ 16:34:14.238
MIN:  0
INT:  42
MAX:  63
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEBUG: FP.1.trim LINE 1264 (17 Jun 2020 @ 16:34:14.238
INTS:  True
FRACS: True
Trimming 0 fractional bits
Trimming 0 integer bits

[zks0002]

Seems like this is addressed somewhat here:
https://stackoverflow.com/questions/42763283/access-superclass-property-setter-in-subclass

Since fixedpoint does not define its properties and setters with other methods, they'd have to be overridden like so:

from fixedpoint.properties import StrBase
from fixedpoint.fixedpoint import FixedPointType
...
class Hello(FixedPoint):
    ...
    @property
    def str_base(self: FixedPointType) -> int:
        return int(self._str_base.value)
    @str_base.setter
    def str_base(self: FixedPointType, base: int) -> None:
        try:
            self._str_base = StrBase(base)
        except ValueError:
            raise ValueError(f"Invalid str_base setting: {base!r}.")

When I do this, I get the same exception as the code example above but for mismatch_alert. So I redo all the properties and setters (copied from fixedpoint.fixedpoint) and I get the following:

>>> x = Hello(42, 'original')
>>> print(x._myattr)
original
>>> x.myfunc()
modified!
modified!
>>> x = Hello(42, 'original')
>>> print(x._myattr)
original
>>> x.myfunc()
modified!
modified!
>>> print(x._myattr)
modified!

So that problem is solved but still need to address the first bullet point in the description of the original problem.