René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"The great API cleanup","articleBody":"As discussed in the last call, technically public (i.e. not flagged as private with an underscore), but semantically internal API makes it hard to change anything in Matplotlib.\r\n\r\nI propose to set a focus on reducing the API footprint for 3.3. With our current deprecation policy, we could remove that stuff from master once 3.4 is out, which should be towards the end of this year.\r\n\r\nIn particular:\r\n\r\n- Turn most parameters into keyword-only arguments. Depending on the function 0 to maybe 4 positional parameters should stay. Deprecations will be handled via `@cbook._make_keyword_only()`. This needs one of the approaches #14130 or #15254 to go in so that deprecations on Axes methods are also warned about in the pyplot wrappers.\r\n\r\n- Make more functions and methods private\r\n\r\n- Make more modules private. e.g. (not necessary complete):\r\n  - [x] `afm`\r\n  - [X] `blocking_input`\r\n  - [x] `docstring`\r\n  - [ ] `dviread`\r\n  - [ ] \u003cs\u003e`font_manager`\u003c/s\u003e\r\n  - [x] `fontconfig_pattern`\r\n  - [ ] \u003cs\u003e`hatch`\u003c/s\u003e\r\n  - [ ] \u003cs\u003e`legend_handler`\u003c/s\u003e\r\n  - [x] `mathtext`\r\n  - [ ] `texmanager`\r\n  - [x] `tight_bbox`\r\n  - [x] `tight_layout`\r\n  - [x] `type1font`\r\n\r\n- Mechanism to deprecate whole modules:\r\n\r\n  1. Move the exising module `git mv my_module.py _my_module.py` and put this into a commit.\r\n  2. Create a new `my_module.py` with the content:\r\n    ```\r\n    from matplotlib._my_module import *\r\n    from matplotlib import _api\r\n    _api.warn_deprecated(\"3.3\", f\"The module {__name__} is deprecated\")\r\n    ```\r\n   and add this in a second commit.\r\n\r\n   It is important to have the move in a separate commit to maintain the history of that code. If put together in one commit, git thinks we added `_my_module.py` and modified `my_module.py`. Then, we could not go back in history for the moved code.\r\n\r\n- [DONE] Move all the internal `cbook` functions to (a/multiple) private module(s).\r\n  ```\r\n  from matplotlib import _api\r\n\r\n  @_api.deprecated(\"3.2\")\r\n  def compare_versions(a, b):\r\n  ```\r\n  reads better than the current\r\n  ```\r\n  from matplotlib import cbook\r\n\r\n  @cbook._deprecated(\"3.2\")\r\n  def compare_versions(a, b):\r\n  ```\r\n  and it does not pollute the namespace with the public package name.\r\n\r\n- Rename `camelCase` to `camel_case` (when not too public; e.g. `rcParams` must stay).\r\n\r\n- Internally use `import mpl` and `mpl.rcParams` instead of `from matplotlib import rcParams` and `rcParams`. - Partially addressed in #16406.\r\n\r\n- remove the obscure function `pyplot.plotting()`, which is used as a container for the pyplot docstring.","author":{"url":"https://github.com/timhoffm","@type":"Person","name":"timhoffm"},"datePublished":"2020-01-11T00:35:20.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":12},"url":"https://github.com/16181/matplotlib/issues/16181"}