|
| 1 | +--- |
| 2 | +title: "Guide" |
| 3 | +--- |
| 4 | + |
| 5 | +This guide gives an overview of how to use this template for creating a |
| 6 | +new Python package. It includes instructions for using the template and |
| 7 | +post-creation tasks. |
| 8 | + |
| 9 | +## Installing |
| 10 | + |
| 11 | +In order to use this template, you need to install a few programs: |
| 12 | + |
| 13 | +- [Python](https://www.python.org/): Required by the template tool |
| 14 | + itself (copier) and for installing and using many of the tools in |
| 15 | + this template. |
| 16 | +- [Git](https://git-scm.com/): For version control and setting up Git |
| 17 | + to track the newly created package. |
| 18 | +- [copier](https://copier.readthedocs.io/en/stable/#quick-start): A |
| 19 | + template tool for making new projects in a standardised and |
| 20 | + structured way. |
| 21 | +- [uv](https://docs.astral.sh/uv/): A tool for managing Python |
| 22 | + environments and running commands. Some post-copy steps of this |
| 23 | + template use uv. |
| 24 | +- [just](https://just.systems/man/en/): A build management tool that |
| 25 | + helps with running common build and check tasks. |
| 26 | + |
| 27 | +You will need to install Python and Git yourself, but the other tools |
| 28 | +can be installed using |
| 29 | +[`pipx`](https://pipxproject.github.io/pipx/)---which we strongly |
| 30 | +recommend---with the following command: |
| 31 | + |
| 32 | +``` bash |
| 33 | +pipx install copier uv rust-just |
| 34 | +``` |
| 35 | + |
| 36 | +## Creating a new Python package |
| 37 | + |
| 38 | +You can use this template to create a new Python package with a standard |
| 39 | +set of files and folders, as well as all the features and configurations |
| 40 | +to make it easier to build your package more smoothly and effectively. |
| 41 | +First, open a Terminal and move into the directory where you want to |
| 42 | +create the new Python package. Then run the following command: |
| 43 | + |
| 44 | +``` bash |
| 45 | +# Copy into the current directory, which is the "." |
| 46 | +uvx copier copy --trust gh:seedcase-project/template-python-package . |
| 47 | +``` |
| 48 | + |
| 49 | +::: callout-caution |
| 50 | +This template runs some post-copy commands using your terminal. In order |
| 51 | +to run them, you need to use the `--trust` option. Review the |
| 52 | +[`copier.yml`](https://github.com/seedcase-project/template-python-package/blob/main/copier.yaml) |
| 53 | +file, under the `_tasks` key to see what commands will be run after |
| 54 | +copying the template, so you can know and trust what the commands are |
| 55 | +doing. Unfortunately, this template can't be used without the `--trust` |
| 56 | +option. |
| 57 | +::: |
| 58 | + |
| 59 | +## Applying the template to an existing Python package |
| 60 | + |
| 61 | +If you want to use this template on an existing Python package, you can |
| 62 | +use the `copy` command of `copier` just like above to apply the template |
| 63 | +to the existing package. This will add all the template's files and |
| 64 | +configurations to the existing package. |
| 65 | + |
| 66 | +``` bash |
| 67 | +uvx copier copy --trust gh:seedcase-project/template-python-package . |
| 68 | +``` |
| 69 | + |
| 70 | +It will go through a series of prompts, as in the case of creating a new |
| 71 | +Python package, including asking if you want to overwrite existing |
| 72 | +files. |
| 73 | + |
| 74 | +::: callout-note |
| 75 | +To use the `copy` command, the Python package needs to be tracked by Git |
| 76 | +and in a clean state (no changes). |
| 77 | +::: |
| 78 | + |
| 79 | +## Applying the latest template changes |
| 80 | + |
| 81 | +There are two ways to update an existing Python package with the latest |
| 82 | +changes from the template: `update` and `recopy`. |
| 83 | + |
| 84 | +Use `update` to apply template updates to your project without |
| 85 | +overwriting local changes. `update` will compare the version of the |
| 86 | +template you used when you first copied the template with the current |
| 87 | +version of the template, and then apply the changes that are different. |
| 88 | +This also means it won't overwrite any changes you made to files in your |
| 89 | +current Python package, for example, if you deleted a file that was in |
| 90 | +the template, it won't be copied back. |
| 91 | + |
| 92 | +Use `recopy` if you want to reapply the template from scratch, which |
| 93 | +will overwrite any changes you made to the files that were copied from |
| 94 | +the template. This is useful if you want to reset the Python package to |
| 95 | +the state of the template. For example, if you deleted a file but want |
| 96 | +it back from the template or are simply curious to see if there are any |
| 97 | +new changes that you might want to use. |
| 98 | + |
| 99 | +In both cases, the commands are very similar and also use many of the |
| 100 | +same options as the `copy` command. If you want to use the same answers |
| 101 | +as given when you first copied the template, you can use the |
| 102 | +`--defaults` option. Then it will only prompt you for the questions that |
| 103 | +have changed since the last time you copied the template. |
| 104 | + |
| 105 | +``` bash |
| 106 | +uvx copier update --trust --defaults |
| 107 | +# Or |
| 108 | +uvx copier recopy --trust --defaults |
| 109 | +``` |
| 110 | + |
| 111 | +As with the `copy` command, the Python package needs to be tracked by |
| 112 | +Git and must be in a clean state (no changes) for the `update` and |
| 113 | +`recopy` commands to work. |
| 114 | + |
| 115 | +## Post-creation setup |
| 116 | + |
| 117 | +These steps are mainly for us in the Seedcase Project to set up the |
| 118 | +repository with the settings we use, but you can follow them if you want |
| 119 | +to set up your Python package in a similar way. They are also included |
| 120 | +in a message after you've copied the template. |
| 121 | + |
| 122 | +After copying the template, while in the directory of the new Data |
| 123 | +Package, run the following: |
| 124 | + |
| 125 | +``` bash |
| 126 | +just install-precommit |
| 127 | +``` |
| 128 | + |
| 129 | +Next, install [`spaid`](https://github.com/seedcase-project/spaid) and |
| 130 | +use the following commands to run the next setup steps: |
| 131 | + |
| 132 | +``` bash |
| 133 | +spaid_gh_create_repo_from_local -h |
| 134 | +spaid_gh_set_repo_settings -h |
| 135 | +spaid_gh_ruleset_basic_protect_main -h |
| 136 | +``` |
| 137 | + |
| 138 | +Some configuration is needed after copying this template to a new |
| 139 | +repository, including configuration external to the repository. |
| 140 | + |
| 141 | +- The template file `.github/workflows/release-package.yml` requires |
| 142 | + the [auto-release-token](https://github.com/apps/auto-release-token) |
| 143 | + GitHub App to be installed. |
| 144 | +- The GitHub secrets `UPDATE_VERSION_TOKEN`, `ADD_TO_BOARD`, and |
| 145 | + `NETLIFY_AUTH_TOKEN` and variables `UPDATE_VERSION_APP_ID` and |
| 146 | + `ADD_TO_BOARD_APP_ID` have to be set up in the repository (or |
| 147 | + organization) settings. See this |
| 148 | + [guide](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens) |
| 149 | + for more details on how to configure this. |
0 commit comments