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

willingc commented 10 months ago

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

Create the pyproject.toml with hatch new --init
Try a hatch build to see what errors
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)
Try hatch build and see the sdist and wheel in the dist directory.
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 commented 10 months ago

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 commented 9 months ago

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

pypa / hatch