Parcels API review

[VeckoTheGecko]

In Python, modules, variables, and methods are marked as private by pre-pending an underscore. This is particularly useful for within classes to communicate what's part of the (stable) public API and the (unstable) internal API.

Parcels however hasn't adopted this convention across the codebase, meaning that the public API is implicitly the items that are mentioned in the tutorials.

I propose for us to clarify the private API by:

• Reviewing the codebase (variables, class attributes, class methods, functions) noting actions:
  • nothing: take no action
  • read_only: make the attribute read only (this means users can't overwrite the value naively by doing class.name = 2. This is important when the value has sideeffects - for example during initialisation)
  • make_private: make the variable private and add a deprecation notice
  • remove: remove storing of the variable (+ deprecation notice)
• Implementing the actions

This will help users - clarifying what is supported and what isn't - as well as help developers as they can make large changes to the internal API.

All deprecations/privatisations will be done transparently using warnings.

---

The API changes have now taken affect in v3.1.0, with deprecation warnings being raised. See the linked PRs below for information on exact changes.

If you rely on a method or attribute directly that is now raising a deprecation warning, please comment below