consistent ignore keys + make private

[stas00]

This PR addresses #7258

(the proposal has evolved a bit since the initial PR, this comments reflects the current state)

• renames optional model attributes:

  - authorized_missing_keys    => _keys_to_ignore_on_load_missing
  - authorized_unexpected_keys => _keys_to_ignore_on_load_unexpected
  - keys_to_never_save         => _keys_to_ignore_on_save

to (1) make them consistent (2) make them private

• removes these from public API docstring (documents them privately as comments in place)

This is a breaking change.

Fixes #7258

@LysandreJik, @sgugger

p.s. if we want to postpone it for v5, this PR was a quick one liner:

find . -type d -name ".git" -prune -o -type f -exec perl -pi -e 's|authorized_missing_keys|_keys_to_ignore_on_load_missing|g; s|authorized_unexpected_keys|_keys_to_ignore_on_load_unexpected|g'; s|keys_to_never_save|_keys_to_ignore_on_save|g' {} \;

and then manually adjusting the docs.

[sgugger]

Way cleaner, thanks! Just some doc nits on the side.

[LysandreJik]

This is great, thanks for being so fast @stas00!

[stas00]

oh, boy, there is also authorized_unexpected_keys

transformers/src/transformers/modeling_tf_utils.py

Lines 346 to 354 in 49759c0

	- **authorized_missing_keys** (:obj:`List[str]`, `optional`) -- A list of re pattern of tensor names to ignore
	from the model when loading the model weights (and avoid unnecessary warnings).
	- **authorized_unexpected_keys** (:obj:`List[str]`, `optional`) -- A list of re pattern of tensor names to
	ignore from the weights when loading the model weights (and avoid unnecessary warnings).
	"""
	config_class = None
	base_model_prefix = ""
	authorized_missing_keys = None
	authorized_unexpected_keys = None

[LysandreJik]

Indeed, very nice catch! How should we rename that one?

[stas00]

Current authorized_missing_keys and authorized_unexpected_keys do the same thing overall, just 2 different categories.

perhaps?

  - authorized_missing_keys    => _keys_to_ignore_on_load_missing
  - authorized_unexpected_keys => _keys_to_ignore_on_load_unexpected
  - keys_to_never_save         => _keys_to_ignore_on_save

[sgugger]

For me authorized_unexpected_keys should be the _keys_to_ignore_on_load: they are in the state dict but we ignore them.
The authorized_missing_keys should have another name such as _keys_missing_to_ignore_on_load or just _keys_missing_to_ignore.

Re- documentation. We usually document private stuff in comments in the code, so I think we should remove the public documentation and change it in comments.

[sgugger]

We were writing at the same time @stas00 , your names are better than mine. Go ahead!

[LysandreJik]

I really like the new comments.

[LysandreJik]

You can safely ignore the failed connections. It's been happening since the change to git-based repos. We're looking into fixing it with @julien-c, it happens very often.

[stas00]

@LysandreJik, I trust you will document this breaking change - I just don't know where I'd do that...

[LysandreJik]

Yes, I'm currently documenting all breaking changes in the release notes.