Extension_yt_frontend.md

This is a personal note on the migration process to port a yt frontend into its own extension package so that it can be developed outside the main code base.

Steps

A working repo structure

The following structure isn't the only possible one, but it's designed to make migration to the core yt codebase easiest once the frontend is mature and battle tested.

I'll use dummy as a fake frontend name here, just replace it with whatever fits yours. Note that the source directory has to be named yt_<something> to comply with yt's extensions importing rules.

yt_dummy/
    __init__.py
    tests/
setup.py
setup.cfg                # recommended
pyproject.toml           # recommended
.pre-commit-config.yaml  # recommended
LICENSE                  # recommended
README.md                # recommended

Then copy all files from yt/frontends/<dummy> within your yt_dummy folder to boostrap the frontend.

The __init__.py file should contain the following line:

from .data_structures import DummyDataset

It is recommended to copy setup.cfg, pyproject.toml and .pre-commit-config.yaml from yt's main repo and then edit these files to remove the yt-specific stuff and adjust metadata to your project.

If your frontend is pure Python, setup.py can be as simple as

from setuptools import setup

setup()

Some rules to keep in mind as you develop a frontend separate from the core code base

1. identify and highlight frontend-exclusive dependencies within the code
   1. within frontend/, import statements for sharing objects with sibling modules should be writen in the relative style, e.g.,

   from .data_structures import DummyDataset

   as opposed to absolute, e.g.

   from yt_dummy.frontend.data_structure import DummyDataset

2. within frontend/, import statements for sharing objects with sibling modules should be writen in the relative style, e.g., ```pythonfrom .data_structures import DummyDataset, as opposed to absolute, e.g. from yt_dummy.frontend.data_structure import DummyDataset`)
3. within frontend/, import statements for sharing objects with sibling modules should be writen in the relative style, e.g., ```pythonfrom .data_structures import DummyDataset, as opposed to absolute, e.g. from yt_dummy.frontend.data_structure import DummyDataset`)
4. regarding code style, you don't have to comply to rules followed by the main repo, though it is advisable you do it anyway to minimize the edits you'll need to make if you want to migrate you frontend to the main code base later. See https://yt-project.org/docs/dev/developing/developing.html#coding-style-guide
5. regarding fundamental dependencies: There are two viable approaches.
   1. In case you intend to propose your frontend for inclusion in the main repo at some point in the future:
   • it is strongly advisable to set the same lower limit than yt regarding supported Python versions (see setup.cfg, e.g install_requires python >= 3.6 as of the yt 4.0.x series)
   • it is advised to set boundaries to your supported yt version (e.g. install_requires=yt>=4.0.1,<5.0)
   • ideally, you should have a daily continuous integration job running against the dev version of yt, so you'll be automatically notified if something breaks your extension upstream, and you can report on the issue tracker so we can work out a solution before the next release is rolled out. This helps tremendously in guaranteeing that your extension stays compatible with future versions of yt before it gets integrated
   2. On the contrary, if you wish to keep your frontend isolated for ever, you can just hard pin the required yt version that you know works with your extension and maybe upgrade it later if that seems relevant.