Merge pull request #1119 from xcube-dev/forman-code_styling

New code styling

CHANGES.md

@@ -1,3 +1,13 @@
+## Changes in 1.8.3 (in development)
+
+### Other changes
+
+* Reformatted code base according to the default settings used by 
+  [isort](https://pycqa.github.io/isort/) and
+  [ruff](https://docs.astral.sh/ruff/). Updated development 
+  dependencies accordingly.
+* Updated copyright notices.
+
 ## Changes in 1.8.2
 
 * Bundled xcube Viewer 

CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+We are committed to providing a friendly, safe, and welcoming environment 
+for all, regardless of gender, sexual orientation, ability, ethnicity, 
+religion, or any other characteristic.
+
+We expect everyone to treat each other with respect and kindness. We do not 
+tolerate harassment or discrimination of any kind.
+
+If you witness or experience any behavior that violates this code of conduct, 
+please report it to the project maintainers immediately.
+
+Thank you for helping us create a welcoming community!

CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing Guidelines
+
+Thank you for your interest in contributing to **xcube**! 
+
+To ensure consistency and readability, please adhere to 
+the [xcube development guidelines](docs/source/devguide.md).
+Please make also sure that you respect our [code of conduct](CODE_OF_CONDUCT.md) 
+
+We appreciate your contributions — happy coding! 🚀
+

docker/install-xcube-plugin.sh

@@ -1,5 +1,11 @@
 #!/bin/env bash
 
+#
+# Copyright (c) 2018-2025 by xcube team and contributors
+# Permissions are hereby granted under the terms of the MIT License:
+# https://opensource.org/licenses/MIT.
+#
+
 PACKAGE=$1;
 PACKAGE_VERSION=$2;
 INSTALL_MODE=$3

docs/source/conf.py

@@ -1,3 +1,7 @@
+#  Copyright (c) 2018-2025 by xcube team and contributors
+#  Permissions are hereby granted under the terms of the MIT License:
+#  https://opensource.org/licenses/MIT.
+
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -13,11 +17,12 @@
 import os
 import sys
 
-src_root = os.path.abspath('../..')
+src_root = os.path.abspath("../..")
 sys.path.insert(0, src_root)
 
 # noinspection PyUnresolvedReferences
 import recommonmark
+
 # noinspection PyUnresolvedReferences
 import sphinx_rtd_theme
 
@@ -26,49 +31,49 @@
 # -- Project information -----------------------------------------------------
 
 
-project = 'xcube'
-copyright = '2018-2024, Brockmann Consult GmbH'
-author = 'Brockmann Consult GmbH'
+project = "xcube"
+copyright = "2018-2024, Brockmann Consult GmbH"
+author = "Brockmann Consult GmbH"
 
 # The full version, including alpha/beta/rc tags
 release = version
 
 # Title of the document
-doc_title = 'xcube Toolkit Documentation'
+doc_title = "xcube Toolkit Documentation"
 
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.7'
+needs_sphinx = "1.7"
 
 # The main toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The suffix(es) of source filenames.
-source_suffix = ['.rst', '.md']
+source_suffix = [".rst", ".md"]
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx_autodoc_annotation',
-    'sphinx_markdown_tables',
-    'sphinxarg.ext',
-    'recommonmark',
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_annotation",
+    "sphinx_markdown_tables",
+    "sphinxarg.ext",
+    "recommonmark",
 ]
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -77,61 +82,59 @@
 
 # Generate automatic links to the documentation of objects in other projects.
 intersphinx_mapping = {
-    'matplotlib': ('https://matplotlib.org/stable/', None),
-    'numpy': ('https://numpy.org/doc/stable/', None),
-    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
-    'geopandas': ('https://geopandas.org/en/stable/', None),
-    'python': ('https://docs.python.org/3/', None),
-    'xarray': ('https://docs.xarray.dev/en/stable/', None),
-    'zarr': ('https://zarr.readthedocs.io/en/stable/', None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
+    "geopandas": ("https://geopandas.org/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+    "zarr": ("https://zarr.readthedocs.io/en/stable/", None),
 }
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 html_theme_options = {
-
     # General options
-    'canonical_url': '',
+    "canonical_url": "",
     # 'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
-    'logo_only': False,
-    'display_version': True,
-    'prev_next_buttons_location': 'bottom',
-    'style_external_links': False,
-    'style_nav_header_background': 'white',
+    "logo_only": False,
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": False,
+    "style_nav_header_background": "white",
     #  WARNING: unsupported theme option 'vcs_pageview_mode' given
     # 'vcs_pageview_mode': '',
     #  WARNING: unsupported theme option 'github_url' given
     # 'github_url': 'https://github.com/dcs4cop/xcube',
-
     # Toc options
-    'collapse_navigation': True,
-    'sticky_navigation': True,
-    'navigation_depth': 4,
-    'includehidden': True,
-    'titles_only': False,
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = project + '-docs'
+htmlhelp_basename = project + "-docs"
 
-html_logo = '_static/logo.png'
+html_logo = "_static/logo.png"
 
 # -- Options for Autodoc output -------------------------------------------------
 
-autoclass_content = 'class'
-autodoc_member_order = 'bysource'
+autoclass_content = "class"
+autodoc_member_order = "bysource"
 autodoc_inherit_docstrings = True
-autodoc_typehints = 'signature'
+autodoc_typehints = "signature"
 
 # Align with requirements.txt
 # autodoc_mock_imports = [

docs/source/devguide.md

@@ -38,30 +38,50 @@ The current software version is in `xcube/version.py`.
 
 ## Coding Style
 
-We follow [PEP-8](https://www.python.org/dev/peps/pep-0008/), including
+We mainly follow conventions stated in 
+[PEP-8](https://www.python.org/dev/peps/pep-0008/), including
 its recommendation of [PEP-484](https://www.python.org/dev/peps/pep-0484/)
 syntax for type hints.
 
-### Updating code style in the existing codebase
+The code style of xcube equals the default settings 
+of [Black](https://black.readthedocs.io/) 
+which are also largely implemented by [Ruff](https://docs.astral.sh/ruff/). 
 
-A significant portion of the existing codebase does not adhere to our current
-code style guidelines. It is of course a goal to bring these parts into
-conformance with the style guide, but major style changes should not be
-bundled into pull requests focused on other improvements or bug fixes, because
-they obscure the significant code changes and make reviews difficult.
-Large-scale style and formatting updates should instead be made via dedicated
-pull requests.
+Both Black and Ruff are quite un-opinionated regarding the order of imports,
+therefore we use [isort](https://pycqa.github.io/isort/) with default setting 
+to automatically order them (see also section below).
+
+Given what has been stated above, the recommended way to automatically format 
+new xcube code is:
+
+```shell
+isort <path>
+ruff format <path>
+```
+
+### Order of Imports
+
+According to [isort](https://pycqa.github.io/isort/), we group and 
+sort imports statements as follows:
+
+1. Future imports
+1. Python standard library imports, e.g., `os`, `typing`, etc
+1. 3rd-party imports, e.g., `xarray`, `zarr`, etc
+1. 1st-party xcube module imports using absolute paths, 
+   e.g., `from xcube.a.b.c import d`. 
+1. 1st-party xcube module imports from local modules: 
+   Relative imports such as `from .c import d` are ok
+   while `from ..c import d` are not ok.
 
 ### Line length
 
-As recommended in PEP-8, all lines should be limited to a maximum of 79
-characters, including docstrings and comments.
+Unlike recommended in PEP-8, all code lines should not exceed 88 characters, 
+while docstrings and comments should not exceed 78 characters.
 
 ### Quotation marks for string literals
 
-In general, single quotation marks should always be used for string literals.
-Double quotation marks should only be used if there is a compelling reason to
-do so in a particular case.
+Double quotation marks should be used for string literals by default.
+
 
 ## Main Packages
 
@@ -214,7 +234,7 @@ by the class `xcube.core.xarray.DatasetAccessor`. This class is an
 that is used to reflect `xcube.core` functions and make it directly 
 applicable to the `xarray.Dataset` object.
 
-Therefore any xcube API shall be reflected in this extension class.
+Therefore, any xcube API shall be reflected in this extension class.
 
 
 ### Package `xcube.webapi`

environment.yml

@@ -48,11 +48,13 @@ dependencies:
   - pip
   - pip:
      - chartlets >=0.1.0
-  # Testing
+  # Development
   - flake8 >=3.7
+  - isort >=6
   - kerchunk
   - moto >=4
   - pytest >=4.4
   - pytest-cov >=2.6
   - requests-mock >=1.8
+  - ruff >=0.9
   - werkzeug

examples/notebooks/datastores/preload.ipynb

@@ -38,10 +38,10 @@
    "outputs": [],
    "source": [
     "data_ids = (\n",
-    "    \"tt-data/tinky-winky.nc\", \n",
-    "    \"tt-data/dipsy.zarr\", \n",
-    "    \"tt-data/laa-laa.tiff\", \n",
-    "    \"tt-data/po.zarr.zip\"\n",
+    "    \"tt-data/tinky-winky.nc\",\n",
+    "    \"tt-data/dipsy.zarr\",\n",
+    "    \"tt-data/laa-laa.tiff\",\n",
+    "    \"tt-data/po.zarr.zip\",\n",
     ")"
    ]
   },
@@ -53,8 +53,8 @@
    "outputs": [],
    "source": [
     "def preload_data(handle: PreloadHandle, data_id: str):\n",
-    "    duration = random.randint(5, 15) # seconds\n",
-    "    num_ticks = 100  \n",
+    "    duration = random.randint(5, 15)  # seconds\n",
+    "    num_ticks = 100\n",
     "    for i in range(num_ticks):\n",
     "        time.sleep(duration / num_ticks)\n",
     "        if handle.cancelled:\n",
@@ -166,7 +166,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "async_handle = ExecutorPreloadHandle(data_ids, blocking=False, preload_data=preload_data)"
+    "async_handle = ExecutorPreloadHandle(\n",
+    "    data_ids, blocking=False, preload_data=preload_data\n",
+    ")"
    ]
   },
   {