|
| 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 Python |
| 123 | +package, run the following: |
| 124 | + |
| 125 | +``` bash |
| 126 | +just install-precommit |
| 127 | +``` |
| 128 | + |
| 129 | +This sets up the pre-commit hooks to run standard checks on your |
| 130 | +repository whenever you commit files to the history. |
| 131 | + |
| 132 | +If you are using the template to create a Python package for the Seedcase |
| 133 | +Project, run: |
| 134 | + |
| 135 | +``` bash |
| 136 | +just update-quarto-theme |
| 137 | +``` |
| 138 | + |
| 139 | +This adds the `seedcase-theme` Quarto theme to the website, which |
| 140 | +provides a consistent look and feel across all Seedcase Project |
| 141 | +websites, including for Python package websites. |
| 142 | +It's called `update-quarto-theme` here since you can use this |
| 143 | +command to keep the theme updated. |
| 144 | + |
| 145 | +Next, install [`spaid`](https://github.com/seedcase-project/spaid) and |
| 146 | +use the following commands to run the next setup steps: |
| 147 | + |
| 148 | +``` bash |
| 149 | +spaid_gh_create_repo_from_local -h |
| 150 | +spaid_gh_set_repo_settings -h |
| 151 | +spaid_gh_ruleset_basic_protect_main -h |
| 152 | +``` |
| 153 | + |
| 154 | +Some configuration is needed after copying this template to a new |
| 155 | +repository, including configuration external to the repository. Some |
| 156 | +GitHub workflows require installing GitHub Apps, for greater security |
| 157 | +purposes and easier administration when managing multiple repositories. |
| 158 | +The [security |
| 159 | +section](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens) |
| 160 | +in our [Guidebook](https://guidebook.seedcase-project.org/) provides |
| 161 | +instructions on how to set up GitHub Apps, secrets, and variables. |
| 162 | +Ideally the secrets and variables should be set up in the organization |
| 163 | +settings. The specific workflows in this template that require this |
| 164 | +additional setup are: |
| 165 | + |
| 166 | +- The workflow `.github/workflows/release-package.yml` requires the |
| 167 | + [auto-release-token](https://github.com/apps/auto-release-token) |
| 168 | + GitHub App as well as a creating a GitHub secret called |
| 169 | + `UPDATE_VERSION_TOKEN` and a variable called `UPDATE_VERSION_APP_ID` |
| 170 | + that has the App ID. |
| 171 | +- The workflow `.github/workflows/add-to-project.yml` requires the |
| 172 | + [add-to-board-token](https://github.com/apps/add-to-board-token) |
| 173 | + GitHub App, along with the `ADD_TO_BOARD_TOKEN` secret and the |
| 174 | + `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. |
| 175 | + |
| 176 | +If you use Netlify, you will also need to add a `NETLIFY_AUTH_TOKEN` secret |
| 177 | +of your Netlify Token. |
![pre-commit-ci[bot]](https://avatars.githubusercontent.com/in/68672?v=4&size=40){kind=avatar}
0 commit comments