Add migration and compare script

[blink1073]

Add scripts to migrate a Jupyter or Jupyter extension project from setuptools to hatch.
The script handles most of the migration automatically, but prints prompts for the user on recommended follow up actions.
There is also a comparison script to ensure that all assets remain the same in the produced dist files.
Adds a unit test that starts from a setuptools-based cookiecutter extension and verifies all aspects of migration.

[agoose77]

I've been moving one of my projects to use this plugin, and noticed that there's currently no "nice" way to get the version. If you use the code pathway, it will fail for cookiecutter-extension derivatives if the build has not yet been run because package.json won't have been bundled.

I thought about this, and I think the most elegant solution is, rather than modifying the cookiecutter to look in the parent directory 🤮, to create a version plugin that knows about package.json.

I wrote https://github.com/agoose77/hatch-nodejs-version for this, and I'd be interested to hear your thoughts on whether it's a good fit for the problem.

You'd then want to use importlib.resources (or the backport importlib_resources for python<3.8) to retrieve the version from the install metadata instead of package.json (to ensure the two agree). I think this is a good change, but recognise some people might prefer not to use that.

[blink1073]

ooh, I like that approach, thank you!

[blink1073]

Actually, thinking about this more: I think we should use tbump to keep these versions in sync, so we don't have to depend on importlib_resources at runtime. We could then use a static version in pyproject.toml itself, as we do in jupyter_server.

Once we have the simplified workflow for jupyter-releaser done, we could update the cookiecutter to use releaser by default (or as an option).

[blink1073]

Current output from migrating an extension made with jupyterlab/extension-cookiecutter-ts:

[build-system]
requires = [
    "hatchling>=1.3.1",
]
build-backend = "hatchling.build"

[project]
name = "myextension"
description = "A JupyterLab extension."
readme = "README.md"
license = "BSD-3-Clause"
requires-python = ">=3.7"
authors = [
    { name = "me", email = "me@me.com" },
]
keywords = [
    "Jupyter",
    "JupyterLab",
    "JupyterLab3",
]
classifiers = [
    "Framework :: Jupyter",
    "Framework :: Jupyter :: JupyterLab",
    "Framework :: Jupyter :: JupyterLab :: 3",
    "Framework :: Jupyter :: JupyterLab :: Extensions",
    "Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt",
    "License :: OSI Approved :: BSD License",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.7",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
]
dependencies = []
version = "0.1.0"

[project.urls]
Homepage = "https://github.com/github_username/myextension"

[tool.hatch.version]
path = "myextension/__init__.py"

[tool.hatch.build]
artifacts = [
    "myextension/labextension",
]

[tool.hatch.build.targets.wheel.shared-data]
"myextension/labextension/static" = "share/jupyter/labextensions/myextension/static"
"install.json" = "share/jupyter/labextensions/myextension/install.json"
"myextension/labextension/package.json" = "share/jupyter/labextensions/myextension/package.json"

[tool.hatch.build.targets.sdist]
exclude = [
    ".github",
]

[tool.hatch.build.hooks.jupyter-builder]
dependencies = [
    "hatch-jupyter-builder>=0.3.3",
]
build-function = "hatch_jupyter_builder.npm_builder"
ensured-targets = [
    "myextension/labextension/static/style.js",
    "myextension/labextension/package.json",
]
skip-if-exists = [
    "myextension/labextension/static/style.js",
]

[tool.hatch.build.hooks.jupyter-builder.build-kwargs]
build_cmd = "build:prod"
npm = [
    "jlpm",
]

[tool.hatch.build.hooks.jupyter-builder.editable-build-kwargs]
build_cmd = "install:extension"
source_dir = "src"
build_dir = "!!! needs manual input !!!"

[tool.tbump]
field = [
    { name = "channel", default = "" },
    { name = "release", default = "" },
]
file = [
    { src = "pyproject.toml" },
    { src = "myextension/_version.py" },
]

[tool.tbump.version]
current = "0.1.0"
regex = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<channel>a|b|rc|.dev)(?P<release>\\d+))?"

[tool.tbump.git]
message_template = "Bump to {new_version}"
tag_template = "v{new_version}"

[blink1073]

Sketch for testing:

• Include a current cookiecutter folder as a test asset
• Add an expected pyproject.toml test asset
• Migrate the current cookiecutter folder in a temp folder
• Ensure the pyproject.toml files match
• Run the compare script and ensure the sdists and wheels match
• Run twine check --strict on the resulting sdists
• Make the test only run on a marker - and run it as a separate test on CI

[blink1073]

cc @jtpio. I'm going to merge and iterate on this.

[jtpio]

Nice thanks @blink1073 👍