pygmt.params.Pattern: Set default pattern value to 1 plus extra validation checks

[weiji14]

Description of proposed changes

Set default pattern value as 1 to fix autodoc warning about AttributeError: type object 'Pattern' has no attribute 'pattern'. Add proper validation to ensure non-int and non-PathLike values will raise a GMTValueError.

Addresses #4100 (comment), patches #4020

Preview: https://pygmt-dev--4134.org.readthedocs.build/en/4134/api/generated/pygmt.params.Pattern.html

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 wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• 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 command is:

• /format: automatically format and lint the code

[weiji14]

Originally posted by @yvonnefroehlich in #4100

Looking at the failing docs for windwos I found this warning / error:

WARNING: autodoc: failed to import property 'Pattern.pattern' from module 'pygmt.params'; the following exception was raised:

Traceback (most recent call last):
  File "C:\Users\runneradmin\micromamba\envs\pygmt\Lib\site-packages\sphinx\util\inspect.py", line 461, in safe_getattr
    return getattr(obj, name, *defargs)
AttributeError: type object 'Pattern' has no attribute 'pattern'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "C:\Users\runneradmin\micromamba\envs\pygmt\Lib\site-packages\sphinx\ext\autodoc\importer.py", line 288, in import_object
    obj = attrgetter(obj, mangled_name)
  File "C:\Users\runneradmin\micromamba\envs\pygmt\Lib\site-packages\sphinx\ext\autodoc\__init__.py", line 384, in get_attr
    return autodoc_attrgetter(obj, name, *defargs, registry=self.env._registry)
  File "C:\Users\runneradmin\micromamba\envs\pygmt\Lib\site-packages\sphinx\ext\autodoc\__init__.py", line 3149, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
  File "C:\Users\runneradmin\micromamba\envs\pygmt\Lib\site-packages\sphinx\util\inspect.py", line 477, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: pattern
 [autodoc.import_object]

@yvonnefroehlich, I've fixed the AttributeError, but the Windows docs build still shows as failing at https://github.com/GenericMappingTools/pygmt/actions/runs/18149651674/job/51657848578#step:7:1735 with make: *** [Makefile:35: html] Error 2816, and there doesn't seem to be any other obvious warnings/errors in the logs. Could you maybe test locally on your Windows computer and see if it looks fine? That Docs test on Windows has been failing since May 2025 though, so could also just ignore it.

[seisman]

What about default to pattern 1?

[yvonnefroehlich]

@yvonnefroehlich, I've fixed the AttributeError, but the Windows docs build still shows as failing at https://github.com/GenericMappingTools/pygmt/actions/runs/18149651674/job/51657848578#step:7:1735 with make: *** [Makefile:35: html] Error 2816, and there doesn't seem to be any other obvious warnings/errors in the logs. Could you maybe test locally on your Windows computer and see if it looks fine? That Docs test on Windows has been failing since May 2025 though, so could also just ignore it.

Great, thanks 🙂!
Yes, these are two different things. Actually I wanted to look (again) on the failing docs for Windows, and there I found this new warning/error. I still do not know why the Windows docs are failing currently, and I think it's OK to ignore this.

[weiji14]

/format

[seisman]

OK to merge after the CI passes.

[weiji14]

/format

[weiji14]

/format

[yvonnefroehlich]

@yvonnefroehlich, I've fixed the AttributeError, but the Windows docs build still shows as failing at https://github.com/GenericMappingTools/pygmt/actions/runs/18149651674/job/51657848578#step:7:1735 with make: *** [Makefile:35: html] Error 2816, and there doesn't seem to be any other obvious warnings/errors in the logs. Could you maybe test locally on your Windows computer and see if it looks fine? That Docs test on Windows has been failing since May 2025 though, so could also just ignore it.

Great, thanks 🙂! Yes, these are two different things. Actually I wanted to look (again) on the failing docs for Windows, and there I found this new warning/error. I still do not know why the Windows docs are failing currently, and I think it's OK to ignore this.

Looks good! No warnings anymore 🙂.
Regarding the failing windows docs: As I do not face this issue locally, I still do not know what is going wrong here.