Param method API plan for 2.0

[jbednar]

For Param 2.0, we have a chance to make API improvements that we've been building up to for some time. These were described in https://github.com/holoviz/param/issues/233 and issues linked to that, but this new issue will be focused on the changes we will actually make for 2.0, not just ones we think might be nice but won't get to. Here we'll focus specifically on what to do with the methods on Parameterized and on the param subobject of Parameterized, which dominate the namespace of a Parameterized object. Everything listed by dir(param.Parameterized()) and dir(param.Parameterized().param) is included below, along with a disposition using the following key:

Key:

• dunder: Pre-existing (though sometimes overridden) magic Python internal methods, that API is generally fixed and not up for discussion.
• private: Private API that should stay private. Might not be great API, but also not part of this discussion.
• delete: Deprecated API that should be deleted for v2.0.
• makeprivate: Rename to a private method
• makepublic: Rename to a public method
• rename: Rename on current object
• move: Move to a different object
• keep: Plan to keep as-is.
• add: Add new functionality (not actually in dir() currently)
• Options for Done: N/A (no action needed), deprecated (marked deprecated but not yet removed), PR# (where changed)

Done?	Disposition	name	Notes
N/A	dunder	.__class__
N/A	dunder	.__delattr__
N/A	dunder	.__dict__
N/A	dunder	.__dir__
N/A	dunder	.__doc__
N/A	dunder	.__eq__
N/A	dunder	.__format__
N/A	dunder	.__ge__
N/A	dunder	.__getattribute__
N/A	dunder	.__getstate__
N/A	dunder	.__gt__
N/A	dunder	.__hash__
N/A	dunder	.__init__
N/A	dunder	.__init_subclass__
N/A	dunder	.__le__
N/A	dunder	.__lt__
N/A	dunder	.__module__
N/A	dunder	.__ne__
N/A	dunder	.__new__
N/A	dunder	.__reduce__
N/A	dunder	.__reduce_ex__
N/A	dunder	.__repr__
N/A	dunder	.__setattr__
N/A	dunder	.__setstate__
N/A	dunder	.__sizeof__
N/A	dunder	.__str__
N/A	dunder	.__subclasshook__
N/A	dunder	.__weakref__
N/A	dunder	.param.__class__
N/A	dunder	.param.__contains__
N/A	dunder	.param.__delattr__
N/A	dunder	.param.__dict__
N/A	dunder	.param.__dir__
N/A	dunder	.param.__doc__
N/A	dunder	.param.__eq__
N/A	dunder	.param.__format__
N/A	dunder	.param.__ge__
N/A	dunder	.param.__getattr__
N/A	dunder	.param.__getattribute__
N/A	dunder	.param.__getitem__
N/A	dunder	.param.__gt__
N/A	dunder	.param.__hash__
N/A	dunder	.param.__init__
N/A	dunder	.param.__init_subclass__
N/A	dunder	.param.__iter__
N/A	dunder	.param.__le__
N/A	dunder	.param.__lt__
N/A	dunder	.param.__module__
N/A	dunder	.param.__ne__
N/A	dunder	.param.__new__
N/A	dunder	.param.__reduce__
N/A	dunder	.param.__reduce_ex__
N/A	dunder	.param.__repr__
N/A	dunder	.param.__setattr__
N/A	dunder	.param.__setstate__
N/A	dunder	.param.__sizeof__
N/A	dunder	.param.__str__
N/A	dunder	.param.__subclasshook__
N/A	dunder	.param.__weakref__
N/A	private	._Parameterized__db_print	Move some of these to .param?
N/A	private	._Parameterized__params
N/A	private	._instance__params
N/A	private	._name_param_value
N/A	private	._param
N/A	private	._param_watchers
N/A	private	._parameters_state
N/A	private	._set_name
N/A	private	.param._BATCH_WATCH
N/A	private	.param._Parameters__db_print
N/A	private	.param._TRIGGER
N/A	private	.param._batch_call_watchers
N/A	private	.param._call_watcher
N/A	private	.param._changed
N/A	private	.param._disable_stubs
N/A	private	.param._events
N/A	private	.param._execute_watcher
N/A	private	.param._generate_name
N/A	private	.param._instantiate_param
N/A	private	.param._set_name
N/A	private	.param._setup_params
N/A	private	.param._spec_to_obj
N/A	private	.param._update_event_type
N/A	private	.param._watch
N/A	keep	.name	This object's name Parameter
N/A	keep	.param	Parameters accessor
N/A	keep	.param.cls	Pointer to the owning Parameterized class
N/A	keep	.param.self	Pointer to the owning Parameterized instance, if any
N/A	keep	.param.self_or_cls	Pointer to .param.self if an instance, else .param.cls
N/A	keep	.param.deserialize_parameters
N/A	keep	.param.deserialize_value
N/A	keep	.param.serialize_parameters
N/A	keep	.param.serialize_value
N/A	keep	.param.schema
N/A	keep	.param.outputs
N/A	keep	.param.pprint
N/A	keep	.param.trigger
N/A	keep	.param.unwatch
N/A	keep	.param.watch
N/A	keep	.param.watch_values
N/A	keep	.param.objects
#559	keep	.param._watchers	Also made public as a read-only property .param.watchers
#556	keep	.param.warning	Keep as alias for .log(param.WARNING, ...), to support warnings module later
deprecated	delete	.param.debug	Use .param.log(param.DEBUG, ...) instead
deprecated	delete	.param.verbose	Use .param.log(param.VERBOSE, ...) instead
deprecated	delete	.param.message	Use .param.log(param.INFO, ...) instead
deprecated	delete	._add_parameter
deprecated	delete	.debug
deprecated	delete	.defaults
deprecated	delete	.force_new_dynamic_value
deprecated	delete	.get_param_values
deprecated	delete	.get_value_generator
deprecated	delete	.inspect_value
deprecated	delete	.message
deprecated	delete	.params
deprecated	delete	.print_param_defaults
deprecated	delete	.print_param_values
deprecated	delete	.set_default
deprecated	delete	.set_dynamic_time_fn
deprecated	delete	.set_param
deprecated	delete	.verbose
deprecated	delete	.warning
deprecated	delete	.script_repr
#559	delete	.param.defaults	Used once in HoloViews
#559	delete	.param.deprecate
#559	delete	.param.print_param_defaults
#559	delete	.param.print_param_values
#559	delete	.param.set_default
#559	delete	.param.params
#559	makepublic	.param._add_parameter	Rename to .param.add_parameter
#559	rename	.param.params_depended_on	Rename .param.method_dependencies
#558	rename	.param.set_param	Rename to .param.update ; match Python semantics ; Add note: # PARAM2_DEPRECATION: Remove backwards hack
#559	rename	.param.get_param_values	Replaced with .param.values (same but returns dict); get_param_values deprecated but used extensively in Panel and HoloViews and shouldn't warn until those usages are deleted.
#558	add	.values	Dictionary accessor for name:value pairs, accepting onlychanged=True option to see only changed
#556	add	.param.log	Add .log and recommend for new code instead of .debug, .verbose, .message
#559	add	.param.watchers	Read-only property for .param._watchers
#559	makeprivate	.pprint	Rename to _pprint and deprecate pprint
	makeprivate	.state_pop
	makeprivate	.state_push
	makeprivate	.initialized	Rename ._initialized (make private)
	move	.param.force_new_dynamic_value	Move to Parameter, not Parameterized
	move	.param.get_value_generator	Move to Parameter, not Parameterized
	move	.param.inspect_value	Move to Parameter, not Parameterized
	move	.param.set_dynamic_time_fn	Move to Parameter, not Parameterized

[philippjfr]

Just two notes to ensure a smooth transition since various users may in fact be using the private API for these:

1. For .param._add_parameter I'd go through a deprecation cycle (i.e. keep the private version but warn that it was made public)
2. For .param._watchers I'd keep the private attribute and just expose it as a public .param.watchers property

[maximlt]

Could we obfuscate more _param under param.Parameterized? Even if it's private API it seems to be the one that would most likely clash with user code.

It would actually be nice if the private API under param.Parameterized would follow the same convention, e.g. _Parameterized__xxx.

[jbednar]

1. For .param._add_parameter I'd go through a deprecation cycle (i.e. keep the private version but warn that it was made public)

I'm leaning towards just doing _add_parameter = add_parameter so that no one will get a warning for now, but then to have it as a to-do item to update the HoloViz projects that might use _add_parameter. Once those are done and released we could start warning.

Sounds good.

It would actually be nice if the private API under param.Parameterized would follow the same convention, e.g. _Parameterized__xxx.

Sounds like a good idea, with the goal of namespace cleanup. Formally not part of this group of tasks, but I guess may as well be done at the same time, so people only have to update code once (if indeed they are relying on private API).

[jbednar]

Looking the behavior of param main right now (v1.13.0-17-gaa484c4), there still seems to be work left to achieve the dispositions stated above (ignoring dunder and private attributes so I don't go insane):

Done?	Disposition	name	Notes
#559	makeprivate	.pprint	Rename to _pprint and deprecate pprint
deprecated	delete	.script_repr
	makeprivate	.state_pop
	makeprivate	.state_push
#745	makeprivate	.initialized	Rename ._initialized (make private)
deprecated	delete	.param.debug	Use .param.log(param.DEBUG, ...) instead
deprecated	delete	.param.verbose	Use .param.log(param.VERBOSE, ...) instead
deprecated	delete	.param.message	Use .param.log(param.INFO, ...) instead
#559	delete	.param.defaults	Used once in HoloViews
#559	delete	.param.print_param_defaults
#559	delete	.param.print_param_values
#559	delete	.param.set_default
#559	delete	.param.params
#559	rename	.param.params_depended_on	Rename .param.method_dependencies
#558	rename	.param.set_param	Rename to .param.update ; match Python semantics ; Add note: # PARAM2_DEPRECATION: Remove backwards hack
#559	rename	.param.get_param_values	Replaced with .param.values (same but returns dict); get_param_values deprecated but used extensively in Panel and HoloViews and shouldn't warn until those usages are deleted.
	move	.param.force_new_dynamic_value	Move to Parameter, not Parameterized
	move	.param.get_value_generator	Move to Parameter, not Parameterized
	move	.param.inspect_value	Move to Parameter, not Parameterized
	move	.param.set_dynamic_time_fn	Move to Parameter, not Parameterized

Presumably we need to merge #745 or something like it, plus remove, move, or make the others private as indicated. Or are some of these meant to be deprecated for 2.0 and then deleted in 2.1?

[maximlt]

@jbednar I have updated your table, adding a first column with my comments and actions:

• Priority 1 was to clean up the Parameterized namespace to avoid name clashes, this is on going work in #766 and #767. I looked through all the holoviz repos + examples for usage of .pprint or ._pprint and found none, so I decided to remove them all together, using .param.pprint() was the recommendation in the Version 1.12.0 release notes. The same search showed no usage of .script_repr that will be deleted. Instead of just deleting .state_pop in favor of ._state_pop, I decided to move it (and .state_push) to .param._state_pop. Finally .initialized should move under a private namespace.
• Priority 2 was not to break users that didn't realize many methods of the .param namespace were planned for removal. Unfortunately we found out recently that despite .param methods being deprecated for a long time, some deprecated methods were still in use in the HoloViz code sources. We can easily expect other Param users not to have updated their code. As such we decided not to remove them but to deprecate them first programmatically. They will be removed in a future version, that was suggested to be Param 3.0, but I think that it could happen before as the deprecation were announced (in the release notes) in Param 1.x (that's what a lawyer would say I guess!). The feedback on this all is: deprecating an API needs to be accompanied with a programmatic message.
• No action was taken yet for methods like .param.force_new_dynamic_value, .param.get_value_generator, etc. as they haven't even yet been deprecated in previous release notes and are still documented. Because of that it seems to me moving this API is no longer tied to the release of Param 2.0.

MLT	Done?	Disposition	name	Notes
.pprint and ._pprint will be deleted in #767	#559	makeprivate	.pprint	Rename to _pprint and deprecate pprint
Will be deleted in #767	deprecated	delete	.script_repr
Will be moved to .param._state_pop in #767		makeprivate	.state_pop
Will be moved to ._param._state_push in #767		makeprivate	.state_push
Will be moved to private namespace in #766	#745	makeprivate	.initialized	Rename ._initialized (make private)
deprecated programmatically in #734, will be removed in version X	deprecated	delete	.param.debug	Use .param.log(param.DEBUG, ...) instead
deprecated programmatically in #734, will be removed in a future version	deprecated	delete	.param.verbose	Use .param.log(param.VERBOSE, ...) instead
deprecated programmatically in #734, will be removed in a future version	deprecated	delete	.param.message	Use .param.log(param.INFO, ...) instead
deprecated programmatically in #734, will be removed in version X	#559	delete	.param.defaults	Used once in HoloViews
deprecated programmatically in #734, will be removed in version X	#559	delete	.param.print_param_defaults
deprecated programmatically in #734, will be removed in version X	#559	delete	.param.print_param_values
deprecated programmatically in #734, will be removed in version X	#559	delete	.param.set_default
deprecated programmatically in #734, will be removed in version X	#559	delete	.param.params
deprecated programmatically in #734, will be removed in version X	#559	rename	.param.params_depended_on	Rename .param.method_dependencies
deprecated programmatically in #734, will be removed in version X	#558	rename	.param.set_param	Rename to .param.update ; match Python semantics ; Add note: # PARAM2_DEPRECATION: Remove backwards hack
deprecated programmatically in #734, will be removed in version X	#559	rename	.param.get_param_values	Replaced with .param.values (same but returns dict); get_param_values deprecated but used extensively in Panel and HoloViews and shouldn't warn until those usages are deleted.
not even deprecated in previous release notes, still documented => can wait for post param 2.0		move	.param.force_new_dynamic_value	Move to Parameter, not Parameterized
not even deprecated in previous release notes, still documented => can wait for post param 2.0		move	.param.get_value_generator	Move to Parameter, not Parameterized
not even deprecated in previous release notes, still documented => can wait for post param 2.0		move	.param.inspect_value	Move to Parameter, not Parameterized
not even deprecated in previous release notes, still documented => can wait for post param 2.0		move	.param.set_dynamic_time_fn	Move to Parameter, not Parameterized

[jbednar]

Ok, that all sounds good to me. Thanks!

[maximlt]

I believe that this issue can be closed for now, all the removals that were reasonable enough were made. Many deprecation warnings are now in place, we will need to decide when exactly they should happen, that's for future discussion.