Initial brownout README.md and implementation

Author: lesteve

README.md

@@ -1,8 +1,68 @@
-**Note:** `sklearn` package on PyPI exists to prevent bad actors to use the
-name. `scikit-learn` is the actual package name and should be used with pip,
-e.g. for:
+# Goal
+
+This repo implements brownout for the deprecated `sklearn` package on PyPI.
+
+# Brownout schedule
+
+The following table shows the dates and time window, where an exception will be
+raised if you attempt to install the `sklearn` package from PyPI.
+
+| Dates                             | Window(s)                      |
+|-----------------------------------|--------------------------------|
+| 2022 November 1st - December 30th | :00-:05 every hour             |
+| 2023 January 1st - February 28th  | :00-:10 every hour             |
+| 2023 March 1st - April 30th       | :00-:15 every hour             |
+| 2023 May 1st - June 30th          | :00-:10 and :30-:40 every hour |
+| 2023 July 1st - August 31st       | :00-:15 and :30-45 every hour  |
+| 2023 September 1st - October 30th | :00-:20 and :00-50 every hour  |
+| 2023 November 1st onwards         | always raise an exception      |
+
+# How to fix the error for the main use cases
+
+- use `pip install scikit-learn` rather than `pip install sklearn`
+- replace `sklearn` by `scikit-learn` in your pip requirements files
+  (`requirements.txt`, `setup.py,` `setup.cfg`, `Pipfile`, etc ...)
+- if the `sklearn` package is used by one of your dependencies
+  it would be great if you take some time to track which package uses
+  `sklearn` instead of `scikit-learn` and report it to their issue tracker
+- as last resort, set the environment variable ,
+  `SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True` to avoid this error
+
+# Reason for the deprecation
+
+`sklearn` package on PyPI exists to prevent malicious actors to use the
+`sklearn` package, since `sklearn` (the import name) and `scikit-learn` (the
+project name) are sometimes used interchangeably. `scikit-learn` is the actual
+package name and should be used with pip, e.g. for:
 - pip commands: `pip install scikit-learn`
-- pip `requirements.txt` files
+- pip requirement files (`requirements.txt`, `setup.py,` `setup.cfg`,
+  `Pipfile`, etc ...)
+
+At the time of writing (October 2022) `sklearn` downloads is about 1/5 of the
+`scikit-learn` downloads on PyPI so a lot of people are using it.
+
+There are some edge cases with the way the PyPI `sklearn` package is
+implemented:
+- `pip install sklearn==1.1.1` will say that the 1.1.1 version does not exist,
+  which is confusing. The only available version at the time of writing of
+  `sklearn` is 0.0.
+- `pip uninstall sklearn` will actually not uninstall `scikit-learn`, you can
+  still do `import sklearn` afterwards
+- it can be confusing to have both `sklearn` and `scikit-learn` in the `pip
+  list` output prompting questions like "why do I have scikit-learn 1.1.1 and
+  sklearn 0.0, and what does it even mean"?
+
+# Testing whether a package will be affected by the `sklearn` deprecation
+
+If you want to test whether a package has `sklearn` in its dependencies
+independently of the brownout schedule, you can do:
+
+```
+SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=False \
+    pip install package-to-test-goes-here
+```
 
-The aim of this repo is to implement the brownout of the `sklearn` package on
-PyPI.
+If you get an error that means that the package has `sklearn` in one of its
+dependencies. It would be greatly appreciated if you track which package it is,
+and if you report it to the appropriate project issue tracker to make them
+aware of the `sklearn` deprecation.

setup.cfg

@@ -1,20 +1,87 @@
-# encoding: utf8
-
+import os
+from datetime import datetime, MAXYEAR
+from dateutil.relativedelta import relativedelta
 from setuptools import setup
 
 
-setup(
-    author='UNKNOWN',
-    author_email="UNKNOWN\nblas_opt_info:\nblas_mkl_info:\n  FOUND:\n    libraries = ['mkl_intel_lp64', 'mkl_intel_thread', 'mkl_core', 'iomp5', 'pthread']\n    library_dirs = ['/Users/filo/anaconda/lib']\n    define_macros = [('SCIPY_MKL_H', None)]\n    include_dirs = ['/Users/filo/anaconda/include']\n\n  FOUND:\n    libraries = ['mkl_intel_lp64', 'mkl_intel_thread', 'mkl_core', 'iomp5', 'pthread']\n    library_dirs = ['/Users/filo/anaconda/lib']\n    define_macros = [('SCIPY_MKL_H', None)]\n    include_dirs = ['/Users/filo/anaconda/include']\n\nUNKNOWN",
-    description='A set of python modules for machine learning and data mining',
-    install_requires=['scikit-learn'],
-    long_description='''Use `scikit-learn <https://pypi.python.org/pypi/scikit-learn/>`_ instead.''',
-    maintainer='UNKNOWN',
-    maintainer_email="UNKNOWN\nblas_opt_info:\nblas_mkl_info:\n  FOUND:\n    libraries = ['mkl_intel_lp64', 'mkl_intel_thread', 'mkl_core', 'iomp5', 'pthread']\n    library_dirs = ['/Users/filo/anaconda/lib']\n    define_macros = [('SCIPY_MKL_H', None)]\n    include_dirs = ['/Users/filo/anaconda/include']\n\n  FOUND:\n    libraries = ['mkl_intel_lp64', 'mkl_intel_thread', 'mkl_core', 'iomp5', 'pthread']\n    library_dirs = ['/Users/filo/anaconda/lib']\n    define_macros = [('SCIPY_MKL_H', None)]\n    include_dirs = ['/Users/filo/anaconda/include']\n\nUNKNOWN",
-    name='sklearn',
-    platforms=['all'],
-    py_modules=['wheel-platform-tag-is-broken-on-empty-wheels-see-issue-141'],
-    url='https://pypi.python.org/pypi/scikit-learn/',
-    version="0.0",
-    zip_safe=False,
-)
+with open("README.md") as f:
+    LONG_DESCRIPTION = f.read()
+
+
+def maybe_raise_error(checked_datetime):
+    accept_deprecated_sklearn_package_install = os.environ.get(
+        "SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL", "use-brownout-schedule"
+    )
+    accept_deprecated_sklearn_package_install = (
+        accept_deprecated_sklearn_package_install.lower()
+    )
+
+    if accept_deprecated_sklearn_package_install == "true":
+        return
+
+    if accept_deprecated_sklearn_package_install == "false":
+        raise SystemExit(
+            "Refusing to install the deprecated sklearn package, "
+            "because SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=False is set"
+        )
+
+    start_date = datetime(2022, 11, 1)
+    all_start_dates = [start_date + relativedelta(months=2 * i) for i in range(7)]
+    date_in_the_far_future = datetime(MAXYEAR, 12, 31, 23, 59, 59)
+    all_end_dates = all_start_dates[1:] + [date_in_the_far_future]
+    all_check_functions = [
+        lambda dt: dt.minute < 5,
+        lambda dt: dt.minute < 10,
+        lambda dt: dt.minute < 15,
+        lambda dt: (dt.minute < 10) or (30 < dt.minute < 40),
+        lambda dt: (dt.minute < 15) or (30 < dt.minute < 45),
+        lambda dt: (dt.minute < 20) or (30 < dt.minute < 50),
+        lambda dt: True,
+    ]
+    brownout_schedule = zip(all_start_dates, all_end_dates, all_check_functions)
+
+    error_message = "\n".join(
+        [
+            "The 'sklearn' PyPI package is deprecated, use 'scikit-learn' ",
+            "rather than 'sklearn' for pip commands. ",
+            "",
+            "The brownout schedule for sklearn deprecation can be found at ",
+            "https://github.com/scikit-learn/sklearn-pypi-package#brownout-schedule",
+            "",
+            "Here is how to fix this error in the main use cases:",
+            "- use 'pip install scikit-learn' rather than 'pip install sklearn'",
+            "- replace sklearn by scikit-learn in your pip requirements files",
+            "  (requirements.txt, setup.py, setup.cfg, Pipfile, etc ...)",
+            "- if the sklearn package is used by one of your dependencies, ",
+            "  it would be great if you take some time to track which pakage uses ",
+            "  sklearn instead of scikit-learn and report it to their issue tracker",
+            "- as last resort, set the environment variable ",
+            "  SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True to avoid this error",
+            "",
+            "If the previous advice does not cover your use case, feel free to report it at:",
+            "https://github.com/scikit-learn/sklearn-pypi-package/issues/new",
+        ]
+    )
+    for start_date, end_date, check_function in brownout_schedule:
+        if (start_date <= checked_datetime < end_date) and check_function(
+            checked_datetime
+        ):
+            raise SystemExit(error_message)
+
+
+def main():
+    now = datetime.now()
+    now = datetime(2022, 11, 1)
+    maybe_raise_error(now)
+
+    setup(
+        description="deprecated sklearn package, use scikit-learn instead",
+        long_description=LONG_DESCRIPTION,
+        long_description_content_type="text/markdown",
+        name="sklearn",
+        version="0.1.0a1",
+    )
+
+
+if __name__ == "__main__":
+    main()