https://github.com/xonsh/xontrib-template
Full-featured template for building extension (xontrib) for the xonsh shell.
https://github.com/xonsh/xontrib-template
cli cookiecutter copier copier-python copier-template poetry poetry-python shell shell-extension terminal xonsh xonsh-dev xontrib
Last synced: 14 days ago
JSON representation
Full-featured template for building extension (xontrib) for the xonsh shell.
- Host: GitHub
- URL: https://github.com/xonsh/xontrib-template
- Owner: xonsh
- License: mit
- Created: 2017-06-28T21:22:55.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2025-01-09T10:09:46.000Z (over 1 year ago)
- Last Synced: 2025-01-09T11:23:39.089Z (over 1 year ago)
- Topics: cli, cookiecutter, copier, copier-python, copier-template, poetry, poetry-python, shell, shell-extension, terminal, xonsh, xonsh-dev, xontrib
- Language: Python
- Homepage:
- Size: 147 KB
- Stars: 48
- Watchers: 7
- Forks: 10
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
A template for creating the xonsh extensions called xontribs.
If you like the template click ⭐ on the repo.
[](https://asciinema.org/a/499605)
## Why use this template?
This template includes good pack of prebuilt files:
* `README` with the info and xontrib promotion instructions
* `pyproject.toml` file to make and install PyPi package easily — pick a build backend when prompted by `copier`:
* `setuptools` — classic [`PEP 621`](https://peps.python.org/pep-0621/) layout
* `poetry` — [Poetry](https://python-poetry.org/) project layout
* `uv` — [uv](https://docs.astral.sh/uv/)-managed project with `hatchling` backend and PEP 735 dependency groups
* `.gitattributes` file to enable Github syntax highlighting for `*.xsh` files
* `.gitignore` file with standard list of directories to ignore
* `.github/workflow/push-test.yml` to automatically test the code using Github Actions
* `.github/*_template.md` files to create Github templates for the text of issue and PR.
* `.github/FUNDING.yml` file with template for Github sponsorship button.
* `.pre-commit-config.yaml` file with [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks)
* `MANIFEST.in` file to make Conda feedstock easily
* `LICENSE` file with standard MIT license
* `tests/` with the test suite
## Create new xontrib
Install [copier](https://copier.readthedocs.io/en/stable/):
* From pip:
```xsh
pip install copier copier-templates-extensions
```
* From xonsh-env (xonsh mamba install):
```xsh
xpip install copier copier-templates-extensions
xbin-add copier
```
* From [uv](https://docs.astral.sh/uv/):
```xsh
# Start creating a xontrib using one liner:
uvx --with copier-templates-extensions copier copy --trust gh:xonsh/xontrib-template .
# or just install:
uv tool install --with copier-templates-extensions copier
```
* From [pipx](https://pypa.github.io/pipx/):
```xsh
pipx install copier>=9
pipx inject copier copier-templates-extensions
```
Then create your new xontrib:
```xsh
copier copy --trust gh:xonsh/xontrib-template .
```
## Advent of [PEP-621](https://peps.python.org/pep-0621/)
Older projects can use the following tools to upgrade their setup to use pyproject.toml
* https://github.com/asottile/setup-py-upgrade
* https://ini2toml.readthedocs.io/en/latest/setuptools_pep621.html
* https://validate-pyproject.readthedocs.io/
* https://github.com/denkiwakame/py-tiny-pkg
## If you have an idea for xontrib but have no time to implement
* [Create an issue with your idea](https://github.com/xonsh/xontrib-template/issues/new?assignees=&labels=idea&template=idea.md&title=Idea%3A+)
* [Top ideas](https://github.com/xonsh/xontrib-template/issues?q=is%3Aissue+is%3Aopen+label%3Aidea+sort%3Areactions-%2B1-desc)
## Development
- `copier` selects the latest tag when `--vcs-ref` option is not given. So it is important to tag the main branch after important template updates.
### How to fix [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks)
If you're using `.pre-commit-config.yaml` and have an error during testing you need fix the code i.e.:
```xsh
xpip install pre-commit-hooks
pre-commit run --all-files black # or isort, etc
```
## Links
* [Awesome Xontribs](https://github.com/xonsh/awesome-xontribs)
* [Xontribs on GitHub](https://github.com/topics/xontrib)