Create a tutorial or "how to" migrate an existing setuptools and tox project to Hatch/Hatchling

[willingc]

Hi @ofek, I've been playing around this week with migrating nteract's papermill project to using hatch as a replacement for setuptools and tox. I really think hatch would simplify the dev experience by removing tox and some of the tool config files. I've been walking through these steps:

pyproject.toml creation

1. Create the pyproject.toml with hatch new --init
2. Try a hatch build to see what errors
3. Correct pyproject.toml fields for version location, license SPDX, dependency that had an inline comment (remove the comment which came over as part of the dependency string), dependency (remove -r ../requirements.txt)
4. Try hatch build and see the sdist and wheel in the dist directory.
5. Test pip installing the wheel

Migrate tox config to hatch scripts

Update ci to use hatch scripts

---

One challenge that I am running across is the best practice for specifying optional dependencies and environments as well as the purpose of templates.

s3_reqs = read_reqs('s3.txt', folder='requirements')
azure_reqs = read_reqs('azure.txt', folder='requirements')
gcs_reqs = read_reqs('gcs.txt', folder='requirements')
hdfs_reqs = read_reqs('hdfs.txt', folder='requirements')
github_reqs = read_reqs('github.txt', folder='requirements')
docs_only_reqs = read_reqs('docs.txt', folder='requirements')
black_reqs = ['black >= 19.3b0']
all_reqs = s3_reqs + azure_reqs + gcs_reqs + hdfs_reqs + github_reqs + black_reqs
docs_reqs = all_reqs + docs_only_reqs
# Temporarily remove hdfs_reqs from dev deps until the pyarrow package is available for Python 3.12
dev_reqs = (
    read_reqs('dev.txt', folder='requirements') + s3_reqs + azure_reqs + gcs_reqs + black_reqs
)  # all_reqs
extras_require = {
    "test": dev_reqs,
    "dev": dev_reqs,
    "all": all_reqs,
    "s3": s3_reqs,
    "azure": azure_reqs,
    "gcs": gcs_reqs,
    "hdfs": hdfs_reqs,
    "github": github_reqs,
    "black": black_reqs,
    "docs": docs_reqs,
}

Happy to turn this into a how to doc once we fully migrate.

[ofek]

I would love assistance with such a how-to document!

best practice for specifying optional dependencies and environments

https://hatch.pypa.io/latest/config/environment/overview/#features

the purpose of templates

Environment templates just make it easy to have a base environment that you can change in minor ways. For example, locally you would most likely want to use editable installs whereas in CI you might like to test a real installation like a user would experience. In this case you can have a separate environment that just disables dev mode.

[holmboe]

There is also https://hatch.pypa.io/latest/meta/faq/#tool-migration