Document the deprecation policy and add the deprecate_parameter decorator to deprecate parameters #1160

seisman · 2021-04-02T04:23:03Z

Description of proposed changes

This is a draft implementation to deprecate a parameter but keep backward compatibility.

For example, the Figure.plot() function has the sizes parameter, but we want to rename it to size, and keep backward compatibility. We can add the deprecate_parameter decorator to the Figure.plot() method:

@deprecate_parameter("sizes", "size", "v0.4.0", "v0.6.0")
def plot():
   ...

It means the old parameter name sizes is deprecated since v0.4.0, and will be removed in v0.6.0.
The new parameter name is size.

When users use sizes, a warning will be raised.

References:

Related to #1120.

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

pygmt/helpers/decorators.py

weiji14 · 2021-04-04T03:12:45Z

pygmt/src/plot.py

@@ -43,7 +44,8 @@
    t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
+@deprecate_parameter("sizes", "size", "v0.4.0", "v0.6.0")


I would use the keyword name here, make it easier to regex match when the time comes to deprecate something. Also, do we want to deprecate this at v0.6.0 or v0.5.0?

Suggested change

@deprecate_parameter("sizes", "size", "v0.4.0", "v0.6.0")

@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")

Also, do we want to deprecate this at v0.6.0 or v0.5.0?

As sizes is heavily used, I'd like to give users more time to change the old names to new names.

pygmt/helpers/decorators.py

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

seisman · 2021-04-06T05:34:08Z

/format

pygmt/src/plot.py

weiji14

Looks good, I would add a note about our deprecation policy (and how to use @deprecate_parameter) in the maintainer docs, maybe after #1185 is completed.

pygmt/helpers/decorators.py

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

Bumps [conda-incubator/setup-miniconda](https://github.com/conda-incubator/setup-miniconda) from v2.1.0 to v2.1.1. - [Release notes](https://github.com/conda-incubator/setup-miniconda/releases) - [Changelog](https://github.com/conda-incubator/setup-miniconda/blob/master/CHANGELOG.md) - [Commits](conda-incubator/setup-miniconda@v2.1.0...35d1405) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Bumps [codecov/codecov-action](https://github.com/codecov/codecov-action) from v1.3.1 to v1.3.2. - [Release notes](https://github.com/codecov/codecov-action/releases) - [Changelog](https://github.com/codecov/codecov-action/blob/master/CHANGELOG.md) - [Commits](codecov/codecov-action@v1.3.1...9b0b9bb) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

seisman · 2021-04-13T01:57:17Z

Ping @GenericMappingTools/pygmt-contributors for reviews and comments on this PR.

weiji14

Just some proofread edits. No outstanding issues on the @deprecate_parameter function.

doc/maintenance.md

pygmt/helpers/decorators.py

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

pygmt/helpers/decorators.py

core-man · 2021-04-13T03:30:48Z

Woow~ Looks great 😄 Only some minor suggestions.

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> Co-authored-by: Yao Jiayuan <coreman.seism@gmail.com>

pygmt/helpers/decorators.py

…rator to deprecate parameters (GenericMappingTools#1160) * Add the deprecate_parameter decorator to deprecate parameters * Use FutureWarning instead of DeprecationWarning * Document the deprecation policy Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> Co-authored-by: Meghan Jones <meghanj@hawaii.edu> Co-authored-by: Yao Jiayuan <coreman.seism@gmail.com>

Add the deprecate_parameter decorator to deprecate parameters

35466a2

seisman force-pushed the deprecate-decorator branch from 6ea6150 to 35466a2 Compare April 3, 2021 18:19

vercel bot temporarily deployed to Preview April 3, 2021 18:19 Inactive

weiji14 reviewed Apr 4, 2021

View reviewed changes

pygmt/helpers/decorators.py Outdated Show resolved Hide resolved

Apply suggestions from code review

0d12dfc

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

vercel bot temporarily deployed to Preview April 4, 2021 03:45 Inactive

weiji14 added the deprecation Deprecating a feature label Apr 5, 2021

Improve the docstrings and doctests

93f721b

vercel bot temporarily deployed to Preview April 6, 2021 05:07 Inactive

Improve the doctest to catch the warnings

98ea6eb

vercel bot temporarily deployed to Preview April 6, 2021 05:23 Inactive

Merge branch 'master' into deprecate-decorator

5104bfc

vercel bot temporarily deployed to Preview April 6, 2021 05:31 Inactive

[format-command] fixes

b4a79b7

vercel bot temporarily deployed to Preview April 6, 2021 05:38 Inactive

Use FutureWarning instead of DeprecationWarning

e8eda6c

seisman commented Apr 6, 2021

View reviewed changes

pygmt/src/plot.py Outdated Show resolved Hide resolved

seisman changed the title ~~WIP: Add the deprecate_parameter decorator to deprecate parameters~~ Add the deprecate_parameter decorator to deprecate parameters Apr 6, 2021

seisman added this to the 0.4.0 milestone Apr 6, 2021

seisman marked this pull request as ready for review April 6, 2021 06:10

weiji14 reviewed Apr 6, 2021

View reviewed changes

pygmt/helpers/decorators.py Show resolved Hide resolved

Add extra notes for the decorator

d491846

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

vercel bot temporarily deployed to Preview April 6, 2021 06:23 Inactive

seisman and others added 5 commits April 6, 2021 02:31

Revert the changes in plot.py

59450ff

Merge branch 'master' into deprecate-decorator

65146bd

format the docstrings

a3f63c7

vercel bot temporarily deployed to Preview April 12, 2021 17:15 Inactive

seisman added 2 commits April 12, 2021 21:43

Merge branch 'master' into deprecate-decorator

3e04397

Fix 'sizes' to 'size' in the example

5d993cc

vercel bot temporarily deployed to Preview April 13, 2021 01:44 Inactive

weiji14 reviewed Apr 13, 2021

View reviewed changes

doc/maintenance.md Outdated Show resolved Hide resolved

doc/maintenance.md Outdated Show resolved Hide resolved

doc/maintenance.md Outdated Show resolved Hide resolved

doc/maintenance.md Outdated Show resolved Hide resolved

pygmt/helpers/decorators.py Outdated Show resolved Hide resolved

Apply suggestions from code review

1055725

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

vercel bot temporarily deployed to Preview April 13, 2021 02:39 Inactive

core-man reviewed Apr 13, 2021

View reviewed changes

pygmt/helpers/decorators.py Outdated Show resolved Hide resolved

core-man reviewed Apr 13, 2021

View reviewed changes

pygmt/helpers/decorators.py Outdated Show resolved Hide resolved

Apply suggestions from code review

82dfb90

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> Co-authored-by: Yao Jiayuan <coreman.seism@gmail.com>

vercel bot temporarily deployed to Preview April 15, 2021 18:36 Inactive

core-man reviewed Apr 16, 2021

View reviewed changes

pygmt/helpers/decorators.py Show resolved Hide resolved

Add a test for co-existence of old and new parameter names

c73b80b

core-man approved these changes Apr 16, 2021

View reviewed changes

seisman added 2 commits April 16, 2021 15:10

Merge branch 'master' into deprecate-decorator

5018133

Format

15f3b71

vercel bot temporarily deployed to Preview April 16, 2021 19:11 Inactive

seisman added the final review call This PR requires final review and approval from a second reviewer label Apr 16, 2021

weiji14 approved these changes Apr 18, 2021

View reviewed changes

Merge branch 'master' into deprecate-decorator

3280bf5

vercel bot temporarily deployed to Preview April 19, 2021 03:58 Inactive

seisman removed the final review call This PR requires final review and approval from a second reviewer label Apr 19, 2021

seisman changed the title ~~Add the deprecate_parameter decorator to deprecate parameters~~ Document the deprecation policy and addd the deprecate_parameter decorator to deprecate parameters Apr 19, 2021

seisman merged commit 3469dfe into master Apr 19, 2021

seisman deleted the deprecate-decorator branch April 19, 2021 04:21

weiji14 changed the title ~~Document the deprecation policy and addd the deprecate_parameter decorator to deprecate parameters~~ Document the deprecation policy and add the deprecate_parameter decorator to deprecate parameters Oct 19, 2021

weiji14 mentioned this pull request Oct 19, 2021

PyGMT: A Python interface for the Generic Mapping Tools pyOpenSci/software-submission#43

Closed

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the deprecation policy and add the deprecate_parameter decorator to deprecate parameters #1160

Document the deprecation policy and add the deprecate_parameter decorator to deprecate parameters #1160

seisman commented Apr 2, 2021 •

edited

Loading

weiji14 Apr 4, 2021

seisman Apr 4, 2021

seisman commented Apr 6, 2021

weiji14 left a comment

seisman commented Apr 13, 2021

weiji14 left a comment

core-man commented Apr 13, 2021

	@deprecate_parameter("sizes", "size", "v0.4.0", "v0.6.0")
	@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")

Document the deprecation policy and add the deprecate_parameter decorator to deprecate parameters #1160

Document the deprecation policy and add the deprecate_parameter decorator to deprecate parameters #1160

Conversation

seisman commented Apr 2, 2021 • edited Loading

weiji14 Apr 4, 2021

Choose a reason for hiding this comment

seisman Apr 4, 2021

Choose a reason for hiding this comment

seisman commented Apr 6, 2021

weiji14 left a comment

Choose a reason for hiding this comment

seisman commented Apr 13, 2021

weiji14 left a comment

Choose a reason for hiding this comment

core-man commented Apr 13, 2021

seisman commented Apr 2, 2021 •

edited

Loading