Reserve the `_trait*` namespace for Traits internal use

[mdickinson]

I suggest that we document the _trait* portion of the namespace of a HasTraits object as reserved for use by Traits itself: that is, users should avoid methods or traits whose name starts with "_trait".

To some extent this already happens, but if there's agreement on this, it would be good to document this clearly.

[mdickinson]

This came up in #842. Let's aim to get this agreed (or not) and documented for Traits 6.1.0.

[mdickinson]

See also #983. Possibly we want to reserve trait* as well as _trait*.

[mdickinson]

We may also want to consider warning on trait names that shadow method names.

[kitchoi]

traits_view is still advertised by traits: https://github.com/enthought/traits/blob/046e68acd939c04a4567a939b1ea0a5036ad219d/traits/has_traits.py#L1638-L1639

This contradicts with the fact that subclass should not define traits named trait*. We should probably at least remove this recommendation in the docstring as part of the requirement for closing this issue.

[kitchoi]

We should probably at least remove this recommendation in the docstring as part of the requirement for closing this issue.

Even better, replace this sentence with a mention of the default_traits_view method, which is expected to be overridden by subclasses.

[kitchoi]

Hmmm I just realized that this issue is not in 6.1 milestone but PR #1008 has gone in. Should this issue be moved to 6.1 milestone so we make sure to update the documentation before the next release?

[mdickinson]

Re-opening: see #1050.

[kitchoi]

See attempt to fix the warning in traitsui: https://github.com/enthought/traitsui/pull/796

Perhaps we want to reserve trait_, traits_, _trait_ and _traits_, with the "_" at the end. This would allow traitsui to have its own reserved prefix too.

[mdickinson]

Perhaps we want to reserve trait_, traits_, _trait_ and _traits_, with the "_" at the end.

That sounds reasonable to me. We'd also want to reserve plain old trait and traits (and for consistency we might as well also reserve _trait and _traits).

So the appropriate regex would be something like ^_?traits?($|_).

[mdickinson]

While we're here, there's another part to this: because of the way that CTrait handles metadata (allowing metadata values to be retrieved via attribute access), we may also want to to introduce naming rules there, too.