From 7bdb9bedc86730b174300490144446f72db3b391 Mon Sep 17 00:00:00 2001 From: JB Lovland <jlov@equinor.com> Date: Fri, 17 Nov 2023 14:14:37 +0100 Subject: [PATCH] DOC: Update type hints section --- docs/contributing.rst | 42 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index dcec4ff57..2c9dc11ba 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -205,43 +205,39 @@ Standard acronyms to start the commit message with are: TST: addition or modification of tests REL: related to releasing xtgeo -Type hints +Type Hints ---------- -xtgeo strongly encourages (from year 2021) the use of PEP 484 style type hints. -New development should contain type hints and pull requests to annotate existing -code are accepted as well! +As of 2023, xtgeo requires the use of type annotations in all new feature +developments, incorporating Python 3.10's enhanced syntax for type hints. +This facilitates a more concise and readable style. -Style guidelines +Style Guidelines ~~~~~~~~~~~~~~~~ -Types imports should follow the from typing import ... convention. So rather than +- For Python versions prior to 3.10, include the following import for compatibility: + + .. code-block:: python -.. code-block:: python - - import typing - - primes: typing.List[int] = [] - -You should write + from __future__ import annotations -.. code-block:: python - - from typing import List, Optional, Union +- Use Python's built-in generics (e.g., `list`, `tuple`) directly. This approach is +preferred over importing types like `List` or `Tuple` from the `typing` module. - primes: List[int] = [] +- Apply the new union type syntax using the pipe (`|`) for clarity and simplicity. For example: -Optional should be used where applicable, so instead of + .. code-block:: python -.. code-block:: python + primes: list[int] = [] - maybe_primes: List[Union[int, None]] = [] +- For optional types, use `None` with the pipe (`|`) instead of `Optional`. For instance: -You should write + .. code-block:: python -.. code-block:: python + maybe_primes: list[int | None] = [] - maybe_primes: List[Optional[int]] = [] +Note: These guidelines align with PEP 604 and are preferred for all new code submissions and when +updating existing code. Pull Request Guidelines