A template for creating the xonsh extensions called xontribs.

If you like the template click ⭐ on the repo.

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 layout
  • poetry — Poetry project layout
  • uv — 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
• MANIFEST.in file to make Conda feedstock easily
• LICENSE file with standard MIT license
• tests/ with the test suite

Create new xontrib

Install copier:

• From pip:

  pip install copier copier-templates-extensions
  

• From xonsh-env (xonsh mamba install):

  xpip install copier copier-templates-extensions
  xbin-add copier
  

• From uv:

  # 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:

  pipx install copier>=9
  pipx inject copier copier-templates-extensions
  

Then create your new xontrib:

copier copy --trust gh:xonsh/xontrib-template .

Advent of PEP-621

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
• Top ideas

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

If you're using .pre-commit-config.yaml and have an error during testing you need fix the code i.e.:

xpip install pre-commit-hooks
pre-commit run --all-files black  # or isort, etc

Links

• Awesome Xontribs
• Xontribs on GitHub