Skip to content

POC: Showcases for support type hints #2793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed

POC: Showcases for support type hints #2793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b827ddf
Add type hints to for dataset loading functions
seisman Nov 2, 2023
a0eeca4
Improve the doc style
seisman Nov 3, 2023
6f7d261
Autocompletion of parameter in vscode
seisman Nov 3, 2023
966537f
Another way to support autocompletion
seisman Nov 3, 2023
12c5a2e
Autocompletion for dict keys
seisman Nov 3, 2023
515d1de
Fix a typo
seisman Nov 24, 2023
ac10335
Merge branch 'main' into typehints/datasets
seisman Nov 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@
"sphinx_gallery.gen_gallery",
]

# Autodoc configurations
autodoc_typehints = "description"

# Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
autosummary_generate = []

Expand Down
13 changes: 8 additions & 5 deletions pygmt/datasets/earth_relief.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

The grids are available in various resolutions.
"""
from collections.abc import Sequence
from typing import Literal, Union

from pygmt.datasets.load_remote_dataset import _load_remote_dataset
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import kwargs_to_strings
Expand All @@ -13,11 +16,11 @@

@kwargs_to_strings(region="sequence")
def load_earth_relief(
resolution="01d",
region=None,
registration=None,
data_source="igpp",
use_srtm=False,
resolution: str = "01d",
region: Union[str, Sequence, None] = None,
registration: Literal["gridline", "pixel", None] = None,
data_source: Literal["igpp", "gebco", "gebcosi", "synbath"] = "igpp",
use_srtm: bool = False,
):
r"""
Load the Earth relief datasets (topography and bathymetry) in various
Expand Down
21 changes: 20 additions & 1 deletion pygmt/src/basemap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,29 @@
basemap - Plot base maps and frames for the figure.
"""

from typing import Any, TypedDict, Unpack

from pygmt.clib import Session
from pygmt.helpers import build_arg_string, fmt_docstring, kwargs_to_strings, use_alias


class Parameters(TypedDict):
region: Any
projection: Any
zscale: Any
zsize: Any
frame: Any
map_scale: Any
box: Any
rose: Any
compass: Any
verbose: bool
panel: Any
coltypes: Any
perspective: Any
transparency: Any


@fmt_docstring
@use_alias(
R="region",
Expand All @@ -24,7 +43,7 @@
t="transparency",
)
@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
def basemap(self, **kwargs):
def basemap(self, **kwargs: Unpack[Parameters]):
r"""
Plot base maps and frames for the figure.

Expand Down
22 changes: 21 additions & 1 deletion pygmt/src/coast.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""
coast - Plot land and water.
"""
from typing import Any, Literal

from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
Expand Down Expand Up @@ -36,7 +37,26 @@
t="transparency",
)
@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
def coast(self, **kwargs):
def coast(
self,
region: Any = None,
projection: Any = None,
area_thresh: Any = None,
frame: Any = None,
resolution: Literal["f", "h", "i", "l", "c", "a", None] = None,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think if we could get this to show up in the Sphinx docs too at https://pygmt-dev--2793.org.readthedocs.build/en/2793/api/generated/pygmt.Figure.coast.html? Currently we're following GMT and it might be a bit confusing for new users on what | means

image

One way is to use something like https://github.com/tox-dev/sphinx-autodoc-typehints. See example at https://pyproject-api.readthedocs.io/en/latest/#pyproject_api.Frontend.metadata_from_built on how it could look like:

image

But of course, this is the simple case. There are other cases where we can combine letters, and we'll need to think about that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's worth a try.

land: Any = None,
water: Any = None,
rivers: Any = None,
borders: Any = None,
lakes: Any = None,
map_scale: Any = None,
dcw: Any = None,
shorelines: Any = None,
perspective: Any = None,
transparency: Any = None,
verbose: Any = None,
**kwargs,
):
r"""
Plot continents, shorelines, rivers, and borders on maps.

Expand Down
10 changes: 10 additions & 0 deletions pygmt/src/text.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
"""
text - Plot text on a figure.
"""
from typing import TypedDict

import numpy as np
from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
Expand All @@ -15,6 +17,12 @@
)


class Paragraph(TypedDict):
linewidth: str
width: str
justify: str


@fmt_docstring
@use_alias(
R="region",
Expand All @@ -23,6 +31,7 @@
C="clearance",
D="offset",
G="fill",
M="paragraph",
N="no_clip",
V="verbose",
W="pen",
Expand Down Expand Up @@ -52,6 +61,7 @@ def text_( # noqa: PLR0912
angle=None,
font=None,
justify=None,
paragraph: Paragraph = None,
**kwargs,
):
r"""
Expand Down