[RFC] API Deprecation and Removal

[mufeili]

🚀 Feature

Remove deprecated or replaced APIs.

Motivation

To continuously improve the user experience, DGL has evolved a lot over time. This involves deprecating old APIs and replacing them with new APIs. Meanwhile, the latest version of DGL still keeps many deprecated APIs. As of v1.0, we plan to completely remove the majority of these deprecated APIs for the following reasons.

• The deprecated APIs are no longer well maintained.
• They can yield poor performance or unexpected errors.
• Users can be confused between the deprecated APIs and the latest ones.

Pitch

While we consider it safe to remove APIs that have been deprecated a long time ago like since v0.5, we are uncertain about the rest and would like to learn more from your feedback. Depending on the collective feedback, we will choose from the following options for each candidate API.

• Keeping the API
• Deprecating the API and planning for removal in the future
• Removing the API

API Candidates with Uncertainty

We organize the API candidates based on their namespace. Unless otherwise mentioned, the full path of an API or a file Y under namespace dgl.X will be dgl.X.Y. It’s possible that a deprecated API is replaced with a new API with the same name in a different namespace.

dgl.contrib

file	Description
dis_kvstore.py	@zheng-da said that this is no longer used by distributed training.
graph_store.py	Same as above
unified_tensor.py	Deprecated upon discussion with @BarclayII , @yaox12

dgl.data

API	Description
num_labels attribute of QM7bDataset, QM9EdgeDataset, QM9Dataset, LegacyTUDataset, TUDataset	It has been replaced with num_tasks.

dgl._dataloading

• @BarclayII said that the TGN example depends on it.
• @Rhett-Ying said that DistDGL depends on it with the use of NodeCollator and EdgeCollator. The solution is to fully turn to dgl.dataloading.

dgl.dataloading

API	Description
EdgeDataLoader	This has been deprecated since v0.8. Users can combine DataLoader and as_edge_prediction_sampler instead.
NodeDataLoader	This has been deprecated since v0.8 and replaced with DataLoader.

dgl._deprecate

file	Description
runtime folder, frame.py, kernel.py, nodeflow.py, udf.py, view.py	These are no longer used.

dgl.distributed

API	Description
reshuffle argument of partition_graph	According to a comment two years ago, "This has been deprecated and will be removed in the next release. For heterogeneous graphs, reshuffle must be enabled."
BasicPartitionBook	@Rhett-Ying suggested that we can deprecate it.

dgl.readout

API	Description
Support of 1D tensor in broadcast_edges	Previously broadcast_edges supported 1D tensor for a graph of batch size 1 and 2D tensor of shape (B, D) for an arbitrary graph, B being the batch size. We recently deprecated this and want to drop the support in the future.
Support of 1D tensor in broadcast_nodes	Previously broadcast_nodes supported 1D tensor for a graph of batch size 1 and 2D tensor of shape (B, D) for an arbitrary graph, B being the batch size. We recently deprecated this and want to drop the support in the future.