Skip to content

Break things up into smaller files, improve docs, various bugfixes#149

Merged
lukelbd merged 102 commits into
masterfrom
move-files
May 9, 2020
Merged

Break things up into smaller files, improve docs, various bugfixes#149
lukelbd merged 102 commits into
masterfrom
move-files

Conversation

@lukelbd
Copy link
Copy Markdown
Collaborator

@lukelbd lukelbd commented May 9, 2020

This really does too many things for just one PR, but I was kind of "in the zone" making these edits and only tried to break them up into smaller commits after the fact. This is the kind of enormous refactor PR that will become rarer once the project matures and the v1.0.0 milestone is reached and the project can become more community-driven.

The biggest change: this PR moves everything around into smaller files with more sensible grouping and more intuitive filenames, mimicking the matplotlib file structure, and adds an internals folder with internal utilities (e.g. tools for generating deprecation warnings)

This also stops syncing ipython notebooks directly and uses jupytext py:percent files instead, and makes some major documentation improvements.

Because I started to do additional work on top of the moved files, this PR also contains bugfixes and a couple feature additions that would otherwise have their own PRs. But I did manage to isolate these changes into meaningful commits, which are individually referenced in the CHANGELOG.rst.

This PR renames some classes and utility functions that users rarely interact with, but had not-very-sensible names (the old versions are still there, but a deprecation warning is issued when the function is called/class is instantiated). So far this consists of:

  • shade() --> scale_luminance() ("shade" has ambiguous meaning)
  • saturate() --> scale_saturation() (match the convention for scale_luminance)
  • GeoAxes() --> CartopyAxes()
  • ProjAxes() --> GeoAxes() (more obvious name as "base class" for the geographic axes classes specific to each package, CartopyAxes and BasemapAxes, and if/when basemap support is deprecated it will be easy to just get rid of the subclasses and simply move the CartopyAxes features onto GeoAxes)
  • BinNorm() --> DiscreteNorm() (the fact that its normalized output colors are non-continuous is its defining feature)
  • subplot_grid() --> SubplotsContainer() (match convention for class names)
  • inline_backend_fmt() --> config_inline_backend() (because it runs magic %config InlineBackend and does more than changing figure formats)
  • Colormap.concatenate() --> Colormap.append() (because "concatenate" implies a static method or separate function that concatenates input colormaps)
  • Colormap.truncated() --> Colormap.truncate() (prefer imperative tense)
  • Colormap.punched() --> Colormap.cut() (prefer imperative tense, much better name)
  • Colormap.updated() --> Colormap.copy() (prefer imperative tense)
  • ColorDict() --> ColorDatabase()
  • CmapDict() --> ColormapDatabase()

Finally, this removes the public attributes cmaps, cycles, colordict, locators, formatters, basemap_kwargs, cartopy_crs. Since these were just meant as a sort of documentation feature for users to check out registered names on-the-fly (had no intended/advertised practical functionality), they are removed without deprecation. It makes more sense for users to look at online documentation, the docstrings, or just try to retrieve a non-existing class with a constructor function (e.g. Formatter('foo')) and read the error message, which lists all the registered names.

@lukelbd lukelbd changed the title Break things up into smaller files / mimic matplotlib file structure Break things up into smaller files, improve docs, various bugfixes May 9, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant