From 60588c8e1a97275db8de5a1c76fd7b099f9915de Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Mon, 8 Apr 2024 14:21:42 -0700 Subject: [PATCH 1/8] Add setup-py-to-pyproject-toml.md to address use case where a project's existing setup.py can be migrated to a pyproject.toml using Hatch. Update tutorials/installable-code.md to add a note about this specific use case for Hatch. Update tutorials/intro.md to add setup-py-to-pyproject-toml.md to toctree. --- tutorials/get-to-know-hatch.md | 3 +- tutorials/installable-code.md | 11 +++ tutorials/intro.md | 1 + tutorials/setup-py-to-pyproject-toml.md | 91 +++++++++++++++++++++++++ 4 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 tutorials/setup-py-to-pyproject-toml.md diff --git a/tutorials/get-to-know-hatch.md b/tutorials/get-to-know-hatch.md index 8d56b821f..d8e14e860 100644 --- a/tutorials/get-to-know-hatch.md +++ b/tutorials/get-to-know-hatch.md @@ -120,7 +120,8 @@ and maintaining your Python package easier. A few features that hatch offers -1. it will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you. While we have not extensively tested this feature yet, please let us know if you try it! +1. it will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you (see [Migrating setup.py to pyproject.toml using Hatch](setup-py-to-pyproject-toml.md +)) 2. It will help you by storing configuration information for publishing to PyPI after you've entered it once. Use `hatch -h` to see all of the available commands. diff --git a/tutorials/installable-code.md b/tutorials/installable-code.md index 6c25d42bd..f4e4cbd77 100644 --- a/tutorials/installable-code.md +++ b/tutorials/installable-code.md @@ -147,6 +147,17 @@ Neither 'setup.py' nor 'pyproject.toml' found. ::: +:::{admonition} Note about `setup.py` +:class: tip + +If your project already defines a `setup.py` file, Hatch can be used to automatically create the `pyproject.toml`. +* See [Using Hatch to Migrate setup.py to a pyproject.toml +](setup-py-to-pyproject-toml.md) + +::: + + + ## Time to create your Python package! Now that you understand the basics of the Python package directory structure, and associated key files (`__init__.py` and `pyproject.toml`), it's time to create your Python package! diff --git a/tutorials/intro.md b/tutorials/intro.md index c324510c7..77dbbc1e0 100644 --- a/tutorials/intro.md +++ b/tutorials/intro.md @@ -29,6 +29,7 @@ understanding the steps involved in creating a Python package. :caption: Python Packaging Tutorial Setup Get to know Hatch +Migrate setup.py to a pyproject.toml using Hatch ::: :::{toctree} diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md new file mode 100644 index 000000000..7e85252e1 --- /dev/null +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -0,0 +1,91 @@ +# Using Hatch to Migrate setup.py to a pyproject.toml + +Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`. + + +:::{admonition} Note +:class: tip + +This step is not necessary and is only useful if your project already has a `setup.py` file defined. +* If your project does not already define a `setup.py` see [Make your Python code installable](installable-code.md) +::: + +:::{admonition} Learning Objectives +:class: tip + +In this lesson you will learn: + +1. The process of using Hatch to transition to using `pyproject.toml` for projects that already have a `setup.py` defined. +::: + +## What is Hatch? + +See [Get to know Hatch](get-to-know-hatch.md). + +## Prerequisites + +Before we begin, ensure that you have Hatch installed on your system. You can install it via pip: + +```bash +pip install hatch +``` + +## Sample Directory Tree + +Let's take a look at a sample directory tree structure before and after using `hatch init`: + +### Before `hatch init` + +``` +project/ +│ +├── src/ +│ └── my_package/ +│ ├── __init__.py +│ └── module.py +│ +├── tests/ +│ └── test_module.py +│ +└── setup.py +``` + +### After `hatch init` + +``` +project/ +│ +├── pyproject.toml +│ +├── src/ +│ └── my_package/ +│ ├── __init__.py +│ └── module.py +│ +├── tests/ +│ └── test_module.py +│ +└── setup.py +``` + +As you can see, the main change after running `hatch init` is the addition of the `pyproject.toml` file in the project directory. + +## Step-by-Step Guide + +Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file for your project. + +1. **Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to the directory where your Python project is located. + + ```bash + cd path/to/your/project + ``` + +2. **Initialize Hatch**: Run the following command to initialize Hatch in your project directory: + + ```bash + hatch new --init + ``` + +3. **Review and Customize**: After running the previous command, Hatch will automatically generate a `pyproject.toml` file based on your existing project configuration. Take some time to review the contents of the generated `pyproject.toml` file. You may want to customize certain settings or dependencies based on your project's requirements (see [pyproject.toml tutorial](pyproject-toml.md) for more information about the `pyproject.toml`). + +4. **Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct. From 905d5bf0ff4f5b20490d8cbadaf3bfc705123648 Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Mon, 8 Apr 2024 15:17:08 -0700 Subject: [PATCH 2/8] Remove trailing whitespace from tutorials/setup-py-to-pyproject-toml.md --- tutorials/setup-py-to-pyproject-toml.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index 7e85252e1..2e014fa46 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -2,11 +2,10 @@ Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`. - :::{admonition} Note :class: tip -This step is not necessary and is only useful if your project already has a `setup.py` file defined. +This step is not necessary and is only useful if your project already has a `setup.py` file defined. * If your project does not already define a `setup.py` see [Make your Python code installable](installable-code.md) ::: From a09daed3770b6abc33cacc877ecb90dc37ad2690 Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Wed, 10 Apr 2024 19:10:38 -0700 Subject: [PATCH 3/8] Update setup-py-to-pyproject-toml.md to use the pipx convention for this guide instead of pip install --- tutorials/setup-py-to-pyproject-toml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index 2e014fa46..de2789914 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -26,7 +26,7 @@ See [Get to know Hatch](get-to-know-hatch.md). Before we begin, ensure that you have Hatch installed on your system. You can install it via pip: ```bash -pip install hatch +pipx install hatch ``` ## Sample Directory Tree From 50c471a35ab324be34cc075e5954d35ef4be87e6 Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Wed, 10 Apr 2024 19:14:57 -0700 Subject: [PATCH 4/8] Add short description about what Hatch is in the What is hatch section. --- tutorials/setup-py-to-pyproject-toml.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index de2789914..230aafdc0 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -19,7 +19,14 @@ In this lesson you will learn: ## What is Hatch? -See [Get to know Hatch](get-to-know-hatch.md). +Hatch is a Python package manager designed to streamline the process of creating, managing, and distributing Python packages. It provides a convenient CLI (Command-Line Interface) for tasks such as creating new projects, managing dependencies, building distributions, and publishing packages to repositories like PyPI. + +:::{admonition} Get to know Hatch +:class: tip + +See [Get to know Hatch](get-to-know-hatch.md) for more information. + +::: ## Prerequisites From 2ca25b343fada488e4b0126206ae06863befe65c Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Wed, 10 Apr 2024 19:21:17 -0700 Subject: [PATCH 5/8] Add additional steps for deleting the setup.py, building with hatch, and running any preexisting tests. --- tutorials/setup-py-to-pyproject-toml.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index 230aafdc0..9bb2abd1d 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -95,3 +95,25 @@ Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file 3. **Review and Customize**: After running the previous command, Hatch will automatically generate a `pyproject.toml` file based on your existing project configuration. Take some time to review the contents of the generated `pyproject.toml` file. You may want to customize certain settings or dependencies based on your project's requirements (see [pyproject.toml tutorial](pyproject-toml.md) for more information about the `pyproject.toml`). 4. **Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct. + +### Step 5: Delete setup.py + +Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory. + +```bash +rm setup.py +``` + +### Step 6: Test Build + +Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project: + +```bash +hatch build +``` + +This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process. + +### Step 7: Test Existing Functionality + +After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected. \ No newline at end of file From 826fb582e9f5f8b24d582454f27e9ed5a7c93198 Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Thu, 11 Apr 2024 18:06:51 -0700 Subject: [PATCH 6/8] Update setup-py-to-pyproject-toml.md to use numbering consistently in the step-by-step guide and remove some of the more simple bash commands, only leaving the necessary ones. --- tutorials/setup-py-to-pyproject-toml.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index 9bb2abd1d..3c5f40e0c 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -82,10 +82,6 @@ Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file 1. **Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to the directory where your Python project is located. - ```bash - cd path/to/your/project - ``` - 2. **Initialize Hatch**: Run the following command to initialize Hatch in your project directory: ```bash @@ -96,17 +92,9 @@ Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file 4. **Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct. -### Step 5: Delete setup.py - -Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory. - -```bash -rm setup.py -``` - -### Step 6: Test Build +5. **Delete setup.py**: Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory. -Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project: +6. **Test Build**: Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project: ```bash hatch build @@ -114,6 +102,6 @@ hatch build This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process. -### Step 7: Test Existing Functionality +7. **Test Existing Functionality**: After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected. \ No newline at end of file From 06e170cf4f718c88250c5b5c2e5b0ccffa37d595 Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Thu, 11 Apr 2024 18:07:57 -0700 Subject: [PATCH 7/8] Add newline at the EOF --- tutorials/setup-py-to-pyproject-toml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index 3c5f40e0c..19d7a360d 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -104,4 +104,4 @@ This command will build your project based on the specifications in the `pyproje 7. **Test Existing Functionality**: -After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected. \ No newline at end of file +After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected. From 558b636be9a2d355113e69912d6b220d0a1ae4ea Mon Sep 17 00:00:00 2001 From: miguelalizo Date: Thu, 11 Apr 2024 18:11:44 -0700 Subject: [PATCH 8/8] Tweak formatting. --- tutorials/setup-py-to-pyproject-toml.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tutorials/setup-py-to-pyproject-toml.md b/tutorials/setup-py-to-pyproject-toml.md index 19d7a360d..c97a06490 100644 --- a/tutorials/setup-py-to-pyproject-toml.md +++ b/tutorials/setup-py-to-pyproject-toml.md @@ -102,6 +102,4 @@ hatch build This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process. -7. **Test Existing Functionality**: - -After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected. +7. **Test Existing Functionality**: After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected.