679 Change of attributes for added individuals

[kysrpex]

See the linked issue for more details on the problem. The new behaviour will be the following for the next stable release that will be released from this hotfix branch.

rdflib 5.0.0

>>> from osp.core.namespaces import city, cuba
... from osp.core.utils import pretty_print
... import osp.core.warnings as warning_settings
... freiburg = city.City(name="Freiburg")
... industrial_area = city.Neighborhood(name = 'Industrie Gebiet', coordinates=[1, 8])
... print(industrial_area.coordinates)
... industrial_area.coordinates[0] = 98
... print(industrial_area.coordinates)
... industrial_area.coordinates = [98, 8]
... print(industrial_area.coordinates)
WARNING 2021-08-26 12:56:09,333 [osp.core]: Attribute city.coordinates references the mutable object [1 8] of type <class 'numpy.ndarray'>. Please note that if you modify this object in-place, the changes will not be reflected on the cuds object's attribute. 
For example, executing `fr = city.City(name='Freiburg', coordinates=[1, 2]); fr.coordinates[0]=98; fr.coordinates` would yield `array([1, 2])` instead of `array([98, 2])`, as you could expect. Use `fr.coordinates = [98, 2]` instead, or save the attribute to a different variable, i.e. `value = fr.coordinates; value[0] = 98, fr.coordinates = value`.
You will not see this kind of warning again during this session. You can turn off the warning by running `import osp.core.warnings as warning_settings; warning_settings.attributes_cannot_modify_in_place = False`.
[1 8]
[1 8]
[98  8]

A slightly different version of the warning will be merged to dev, since on dev you can upgrade to rdflib 6.0.0 given that you have the proper Python version installed.

rdflib 5.0.0

WARNING 2021-08-26 12:56:09,333 [osp.core]: Attribute city.coordinates references the mutable object [1 8] of type <class 'numpy.ndarray'>. Please note that because you have `rdflib < 6.0.0` installed,  if you modify this object in-place, the changes will not be reflected on the cuds object's attribute. 
For example, executing `fr = city.City(name='Freiburg', coordinates=[1, 2]); fr.coordinates[0]=98; fr.coordinates` would yield `array([1, 2])` instead of `array([98, 2])`, as you could expect. Use `fr.coordinates = [98, 2]` instead, or save the attribute to a different variable, i.e. `value = fr.coordinates; value[0] = 98, fr.coordinates = value`.
You will not see this kind of warning again during this session. You can turn off the warning by running `import osp.core.warnings as warning_settings; warning_settings.attributes_cannot_modify_in_place = False`.

On dev the dev branch, and with rdflib >= 6.0.0 installed, the user will see no warning, and in-place modification will work.

>>> from osp.core.namespaces import city, cuba
... from osp.core.utils import pretty_print
... import osp.core.warnings as warning_settings
... freiburg = city.City(name="Freiburg")
... industrial_area = city.Neighborhood(name = 'Industrie Gebiet', coordinates=[1, 8])
... print(industrial_area.coordinates)
... industrial_area.coordinates[0] = 98
... print(industrial_area.coordinates)
... industrial_area.coordinates = [98, 8]
... print(industrial_area.coordinates)
[1 8]
[98  8]
[98  8]

---

Upsides:

• No bug.

Downsides:

• Old code will not produce the same results, since it could be modifying things in-place. That's the reason behind the warning.

It's thus tricky to decide whether to define this as an incompatible API change (major version increase) or an error correction (patch version increase), as the in-place modification was a grey area. Maybe let's go for the error correction, given that the warning is there and makes it easy for the user to fix behaviour reliant on in-place modifications.

Edit: actually, the changes introduced to dev should increase the minor version number, we are promoting in-place modification from a grey area to an authorized feature, in a backwards-compatible way.

---

Closes #679. Merge first to master, merge also to dev (change the contents of setup.py to the appropriate ones after merging to master, restore the dev warning after merging to master). Since this is a critical fix, the package version was bumped.

[kysrpex]

@pablo-de-andres @yoavnash You are seeing now what will be merged to master. After one of you approves, I'll merge to master. Then I will push commits for the dev version of this, request your review again, and merge to dev.

[yoavnash]

Move detailed warning to web page and refer to it by link.

[kysrpex]

Move detailed warning to web page and refer to it by link.

I started to do this and it fits in the CUDS API tutorial. However, the problem is that our readthedocs deployment does seem to render all docs versions. Thus, if somebody is using an old version of OSP-core, they will be linked to the latest version of the docs, which may show a different text.

I think fixing this aspect of readthedocs maybe is too much for an issue that is critical. We can do it later when this deployment thing is sorted out.

[kysrpex]

I already merged this to master and released the hotfix. For dev, we can try to take the extra time.