Add tf.deprecationWarn() and tf.disableDeprecationWarnings() (tensorflow#1539)

This adds an environment flag for whether deprecation warnings are enabled, and two methods, `deprecationWarn` which will warn the user about deprecated methods (turned off by the global environment flag) and `disableDeprecationWarnings` which will completely turn off all deprecation warnings.

FEATURE

Author: Nikhil Thorat

src/environment.ts

@@ -19,7 +19,7 @@ import * as device_util from './device_util';
 import {Engine, MemoryInfo, ProfileInfo, ScopeFn, TimingInfo} from './engine';
 import {Features, getFeaturesFromURL, getMaxTexturesInShader, getNumMBBeforePaging, getWebGLDisjointQueryTimerVersion, getWebGLMaxTextureSize, isChrome, isDownloadFloatTextureEnabled, isRenderToFloatTextureEnabled, isWebGLFenceEnabled, isWebGLVersionEnabled} from './environment_util';
 import {KernelBackend} from './kernels/backend';
-import {DataId, setTensorTracker, Tensor} from './tensor';
+import {DataId, setDeprecationWarningFn, setTensorTracker, Tensor} from './tensor';
 import {TensorContainer} from './tensor_types';
 import {getTensorsInContainer} from './tensor_util';
 
@@ -378,6 +378,8 @@ export class Environment {
       return false;
     } else if (feature === 'TENSORLIKE_CHECK_SHAPE_CONSISTENCY') {
       return !this.get('PROD');
+    } else if (feature === 'DEPRECATION_WARNINGS_ENABLED') {
+      return true;
     }
     throw new Error(`Unknown feature ${feature}.`);
   }
@@ -498,4 +500,20 @@ export function enableProdMode(): void {
   ENV.set('PROD', true);
 }
 
+/** Globally disables deprecation warnings */
+export function disableDeprecationWarnings(): void {
+  ENV.set('DEPRECATION_WARNINGS_ENABLED', false);
+  console.warn(`TensorFlow.js deprecation warnings have been disabled.`);
+}
+
+/** Warn users about deprecated functionality. */
+export function deprecationWarn(msg: string) {
+  if (ENV.get('DEPRECATION_WARNINGS_ENABLED')) {
+    console.warn(
+        msg + ' You can disable deprecation warnings with ' +
+        'tf.disableDeprecationWarnings().');
+  }
+}
+setDeprecationWarningFn(deprecationWarn);
+
 export let ENV = getOrMakeEnvironment();

src/environment_test.ts

@@ -218,3 +218,35 @@ describeWithFlags('WEBGL_SIZE_UPLOAD_UNIFORM', WEBGL_ENVS, () => {
     expect(env.get('WEBGL_SIZE_UPLOAD_UNIFORM')).toBeGreaterThan(0);
   });
 });
+
+describe('deprecation warnings', () => {
+  let oldWarn: (msg: string) => void;
+  beforeEach(() => {
+    oldWarn = console.warn;
+    spyOn(console, 'warn').and.callFake((msg: string): void => null);
+  });
+  afterEach(() => {
+    console.warn = oldWarn;
+  });
+
+  it('deprecationWarn warns', () => {
+    tf.deprecationWarn('xyz is deprecated.');
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    expect(console.warn)
+        .toHaveBeenCalledWith(
+            'xyz is deprecated. You can disable deprecation warnings with ' +
+            'tf.disableDeprecationWarnings().');
+  });
+
+  it('disableDeprecationWarnings called, deprecationWarn doesnt warn', () => {
+    tf.disableDeprecationWarnings();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    expect(console.warn)
+        .toHaveBeenCalledWith(
+            'TensorFlow.js deprecation warnings have been disabled.');
+
+    // deprecationWarn no longer warns.
+    tf.deprecationWarn('xyz is deprecated.');
+    expect(console.warn).toHaveBeenCalledTimes(1);
+  });
+});

src/environment_util.ts

@@ -92,6 +92,8 @@ export interface Features {
   // Whether to do sanity checks when inferring a shape from user-provided
   // values, used when creating a new tensor.
   'TENSORLIKE_CHECK_SHAPE_CONSISTENCY'?: boolean;
+  // Whether deprecation warnings are enabled.
+  'DEPRECATION_WARNINGS_ENABLED'?: boolean;
 }
 
 export enum Type {
@@ -126,6 +128,7 @@ export const URL_PROPERTIES: URLProperty[] = [
   {name: 'EPSILON', type: Type.NUMBER},
   {name: 'PROD', type: Type.BOOLEAN},
   {name: 'TENSORLIKE_CHECK_SHAPE_CONSISTENCY', type: Type.BOOLEAN},
+  {name: 'DEPRECATION_WARNINGS_ENABLED', type: Type.BOOLEAN},
 ];
 
 export interface URLProperty {

src/index.ts

@@ -23,7 +23,7 @@ import './kernels/backend_cpu';
 
 import {nextFrame} from './browser_util';
 import * as environment from './environment';
-import {enableProdMode, Environment} from './environment';
+import {deprecationWarn, disableDeprecationWarnings, enableProdMode, Environment} from './environment';
 // Serialization.
 import * as io from './io/io';
 import * as math from './math';
@@ -65,19 +65,11 @@ export const disposeVariables = Environment.disposeVariables;
 export const memory = Environment.memory;
 export {version as version_core};
 
-export {nextFrame};
+// Top-level method exports.
+export {nextFrame, enableProdMode, disableDeprecationWarnings, deprecationWarn};
 
 // Second level exports.
-export {
-  environment,
-  io,
-  math,
-  serialization,
-  test_util,
-  util,
-  webgl,
-  enableProdMode
-};
+export {environment, io, math, serialization, test_util, util, webgl};
 
 // Backend specific.
 export {KernelBackend, BackendTimingInfo, DataMover, DataStorage} from './kernels/backend';

src/tensor.ts

@@ -360,6 +360,12 @@ export interface OpHandler {
 let trackerFn: () => TensorTracker = null;
 // Used by chaining methods to call into ops.
 let opHandler: OpHandler = null;
+// Used to warn about deprecated methods.
+let deprecationWarningFn: (msg: string) => void = null;
+// This here so that we can use this method on dev branches and keep the
+// functionality at master.
+// tslint:disable-next-line:no-unused-expression
+[deprecationWarningFn];
 
 /**
  * An external consumer can register itself as the tensor tracker. This way
@@ -378,6 +384,14 @@ export function setOpHandler(handler: OpHandler) {
   opHandler = handler;
 }
 
+/**
+ * Sets the deprecation warning function to be used by this file. This way the
+ * Tensor class can be a leaf but still use the environment.
+ */
+export function setDeprecationWarningFn(fn: (msg: string) => void) {
+  deprecationWarningFn = fn;
+}
+
 /**
  * We wrap data id since we use weak map to avoid memory leaks.
  * Since we have our own memory management, we have a reference counter