1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
|
.. _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!
|
