Create a New Writer¤

When adding a new Writer to the repository the following steps should be performed. You will also need to Create a New Reader.

uv is used as the package and project manager for msl-io development, it is recommended to install it. mypy and basedpyright are used as type checkers, ruff is used as the formatter/linter and the documentation is built with MkDocs using the Material theme and the mkdocstrings-python plugin. Installation of these packages is automatically managed for you by uv. CSpell provides spell checking and can be installed by running npm install -g cspell@latest (which requires Node.js and npm to be installed).

Create a fork of the repository.

Create a new Writer by following this template. Save it in the src/msl/io/writers folder.

from __future__ import annotations

# It's a good idea to provide type annotations in your code
from typing import TYPE_CHECKING

# Import the necessary msl-io objects
from msl.io import Writer

if TYPE_CHECKING:
    from typing import Any

    from msl.io import Group
    from msl.io.types import PathLike, WriteLike


class MyWriter(Writer):
    """Name your class to be whatever you want, i.e., change MyWriter."""

    def write(
        self, file: PathLike | WriteLike | None = None, root: Group | None = None, **kwargs: Any
    ) -> None:
        """Implement your write method with the above signature.

        Args:
            file: The file to write to. If `None` then uses the value of
                `file` that was specified when `MyWriter` was instantiated.
            root: Write `root` to the file. If None then write the Groups
                and Datasets that were created using `MyWriter`.
            kwargs: Optional keyword arguments.
        """

Import your Writer in the src/msl/io/writers/__init__.py and src/msl/io/__init__.py modules. Follow what is done for the other Writers.
Add test cases to the tests directory to make sure that your Writer works as expected. It is recommended to try converting a Root object between your Writer and other Writers that are available to verify different file-format conversions. Also, look at the test modules that begin with test_writer for more examples. Run the tests using uv run pytest.
Lint uv run ruff check, format uv run ruff format and type check uv run basedpyright, uv run mypy . the code. These checks are also performed once you do Step 10. Type checking with mypy requires the MYPYPATH=src environment variable to be defined to fix the Source file found twice under different module names: "io" and "msl.io" issue.
Add the new Writer, alphabetically, to docs/writers/index.md. Follow what is done for the other Writers.
Update CHANGELOG.md stating that you added this new Writer.
Build the documentation uv run mkdocs serve and check that your Writer renders correctly.
Run the spell checker cspell .. Since this step requires Node.js and npm to be installed, you may skip it. This check is also performed once you do Step 10.
If running the tests pass and linting, formatting, type/spell checking and building the documentation do not show errors/warnings then create a pull request.