mirror of
https://github.com/xonsh/xonsh.git
synced 2025-03-04 08:24:40 +01:00
67 lines
2.4 KiB
ReStructuredText
67 lines
2.4 KiB
ReStructuredText
.. _tutorial_xonsh_projects:
|
|
|
|
************************************
|
|
Tutorial: Xonsh Projects
|
|
************************************
|
|
Bam! Suppose you want to get beyond scripting and write a whole
|
|
library, utility, or other big project in xonsh. Here is how you do
|
|
that. Spoiler alert: it is easy, powerful, and fun!
|
|
|
|
Overview
|
|
================================
|
|
Xonsh is fully interoperable with Python. Writing a xonsh library is
|
|
very similar to writing a Python library, using all of the same tooling
|
|
and infrastructure for packaging pure Python code.
|
|
|
|
Structure
|
|
==========
|
|
Xonsh modules are written in xonsh files (``*.xsh``), side-by-side with Python files
|
|
(``*.py``). Suppose we have a package called ``mypkg`` which uses xonsh files.
|
|
Here is a sample file system layout would be::
|
|
|
|
|- mypkg/
|
|
|- __init__.py # a regular package with an init file
|
|
|- other.py # not a xonsh file
|
|
|- show.py # "mypkg.show", full module name
|
|
|- tell.xsh # "mypkg.tell", full module name
|
|
|- subpkg/
|
|
|- __init__.py
|
|
|- a.py # "mypkg.subpkg.a", full module name
|
|
|- b.xsh # "mypkg.subpkg.b", full module name
|
|
|
|
To ensure that these files are installed, you need to provide the
|
|
appropriate information in ``setup.py`` file for your project.
|
|
For the above structure, this looks like the following.
|
|
|
|
**setup.py**::
|
|
|
|
setup(
|
|
packages=['mypkg', 'mypkg.subpkg'],
|
|
package_dir={'mypkg': 'mypkg', 'mypkg.subpkg': 'mypkg/subpkg'},
|
|
package_data={'mypkg': ['*.xsh'], 'mypkg.subpkg': ['*.xsh']},
|
|
)
|
|
|
|
With this, the xonsh code will be installed and included in any source
|
|
distribution you create!
|
|
|
|
Setting up xonsh sessions
|
|
=========================
|
|
Xonsh code requires a ``XonshSession`` to exist as ``builtins.__xonsh__`` and for
|
|
be that object to be setup correctly. This can be quite a bit of work and
|
|
the exact setup depends on the execution context. To simplify the process
|
|
of constructing the session properly, xonsh provides the ``xonsh.main.setup()``
|
|
function specifically for use in 3rd party packages.
|
|
|
|
While ``xonsh.main.setup()`` is safely re-entrant, it is a good idea to add the following
|
|
snippet to the root-level ``__init__.py`` of your project. With the ``mypkg`` example
|
|
above, the session setup is as follows:
|
|
|
|
``mypkg/__init__.py``
|
|
|
|
.. code-block:: python
|
|
|
|
from xonsh.main import setup
|
|
setup()
|
|
del setup
|
|
|
|
Enjoy!
|