Style Guide#

The Earth2Studio style guide is a set of conventions we have adopted detailing how to write code for this project. A consistent style and process makes the package much easier to understand for users and ensures compliance requirements are met.

Code Formatting#

Earth2Studio uses black as the code formatter. All committed code is expected to be compliant with the version of black specified in the pyproject.toml. Pre-commit will format your code for you or you can run make format to run black on all files.

Additional code formatting principles:

  • File names are always lower case and use a shortened name for the component they contain

  • Class names are capitalized using Pascal case

  • Function names are lower case using snake case

Linting#

Linting is performed by ruff, which includes many processes to ensure code between files is as consistent as possible. Ruff is configured in the project’s pyproject.toml. Pre-commit will run linting for you or you can run make lint to run ruff on all files.

Type Hints#

Earth2Studio is a MyPy compliant package, meaning type hints are required for all functions (parameters and return type). MyPy is configured in the package’s pyproject.toml. On top of requiring type hints, the following guidelines should be used:

  • To help keep APIs concise, several of the common types used throughout the package are defined in earth2studio/utils/type.py, which should be used when applicable.

    from collections import OrderedDict
from datetime import timedelta

import numpy as np

FrameSchema = OrderedDict[str, np.ndarray]
CoordSystem = OrderedDict[str, np.ndarray]

# Specific dimension custom types
VariableArray = np.ndarray[str]
LeadTimeArray = np.ndarray[np.timedelta64]
TimeArray = np.ndarray[np.datetime64]
FieldArray = np.ndarray[str]

TimeTolerance = (
    timedelta
    | np.timedelta64
    | tuple[timedelta, timedelta]
    | tuple[np.timedelta64, np.timedelta64]
)

  • Earth2Studio is Python 3.10+, thus type hinting using generic objects should be used instead of the typing package. Refer to PEP 585 for details.

  • Earth2Studio is Python 3.10+, thus the | operator should be used instead of Union and Optional type operators. Refer to PEP 604 for details.

Note

The pre-commit hook PyUpgrade will enforce Python 3.10 type styles automatically.

Licensing Information#

All source code files must start with this paragraph:

# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES.
# SPDX-FileCopyrightText: All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Signing Your Work#

We require that all contributors “sign-off” on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license. Any contribution which contains commits that are not Signed-Off will not be accepted.

To sign off on a commit, use the --signoff (or -s) option when committing your changes:

git commit -s -m "Adding a cool feature."

This will append the following to your commit message:

Signed-off-by: Your Name <your@email.com>

Full text of the DCO

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this license
document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to
submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge,
is covered under an appropriate open source license and I have the right under that
license to submit that work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am permitted to submit under a
different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified
(a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and
that a record of the contribution (including all personal information I submit with
it, including my sign-off) is maintained indefinitely and may be redistributed
consistent with this project or the open source license(s) involved.