Package: knol
python-package-templateThis is a template repository for Python package projects.In this README :point_down:FeaturesUsageInitial setupCreating releasesProjects using this templateFAQContributingFeaturesThis template repository comes with all of the boilerplate needed for:⚙️ Robust (and free) CI withGitHub Actions:Unit tests ran withPyTestagainst multiple Python versions and operating systems.Type checking withmypy.Linting withruff.Formatting withisortandblack.🤖Dependabotconfiguration to keep your dependencies up-to-date.📄 Great looking API documentation built usingSphinx(runmake docsto preview).🚀 Automatic GitHub and PyPI releases. Just follow the steps inRELEASE_PROCESS.mdto trigger a new release.UsageInitial setupCreate a new repositoryfrom this template with the desired name of your project.Your project name (i.e. the name of the repository) and the name of the corresponding Python package don't necessarily need to match, but you might want to check onPyPIfirst to see if the package name you want is already taken.Create a Python 3.8 or newer virtual environment.If you're not sure how to create a suitable Python environment, the easiest way is usingMiniconda. On a Mac, for example, you can install Miniconda usingHomebrew:brew install minicondaThen you can create and activate a new Python environment by running:conda create -n my-package python=3.9
conda activate my-packageNow that you have a suitable Python environment, you're ready to personalize this repository. Just run:pip install -r setup-requirements.txt
python scripts/personalize.pyAnd then follow the prompts.:pencil:NOTE: This script will overwrite the README in your repository.Commit and push your changes, then make sure all GitHub Actions jobs pass.(Optional) If you plan on publishing your package to PyPI, add repository secrets forPYPI_USERNAMEandPYPI_PASSWORD. To add these, go to "Settings" > "Secrets" > "Actions", and then click "New repository secret".If you don't have PyPI account yet, you cancreate one for free.(Optional) If you want to deploy your API docs toreadthedocs.org, go to thereadthedocs dashboardand import your new project.Then click on the "Admin" button, navigate to "Automation Rules" in the sidebar, click "Add Rule", and then enter the following fields:Description:Publish new versions from tagsMatch:Custom MatchCustom match:v[vV]Version:TagAction:Activate versionThen hit "Save".After your first release, the docs will automatically be published toyour-project-name.readthedocs.io.Creating releasesCreating new GitHub and PyPI releases is easy. The GitHub Actions workflow that comes with this repository will handle all of that for you.
All you need to do is follow the instructions inRELEASE_PROCESS.md.Projects using this templateHere is an incomplete list of some projects that started off with this template:ai2-tangocached-pathbeaker-pygantryip-bot☝️Want your work featured here? Just open a pull request that adds the link.FAQShould I use this template even if I don't want to publish my package?Absolutely! If you don't want to publish your package, just delete thedocs/directory and thereleasejob in.github/workflows/main.yml.ContributingIf you find a bug :bug:, please open abug report.
If you have an idea for an improvement or new feature :rocket:, please open afeature request.