Skip to content

Commit 873120d

Browse files
thiellthiell
committed
setup.py: improvements for pip install and venv
- remove root exception handling - include man pages as data_files - check for config files in sys.prefix/etc/clustershell - if $CLUSTERSHELL_CFGDIR is defined, always try it first This allows clustershell to be installed as user in a venv using pip install or using pip install --user with man pages. Root installation using pip is now discouraged. If done, /usr/local is likely to be used as the install prefix. Fixes #389.
1 parent 98761ce commit 873120d

File tree

6 files changed

+106
-84
lines changed

6 files changed

+106
-84
lines changed

‎clustershell.spec.in‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1+
%if 0%{?rhel} < 9
12
%{!?python_sitelib: %global python_sitelib %(%{__python} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())")}
23
%{!?python2_sitelib: %global python2_sitelib %{python_sitelib}}
34
%{!?__python: %global __python python}
45
%{!?__python2: %global __python2 %{__python}}
6+
%endif
57

68
%if 0%{?fedora} >= 22
79
%{!?python2_pkgversion: %global python2_pkgversion 2}
@@ -134,15 +136,6 @@ popd
134136
ln -s conf/groups.d/local.cfg %{buildroot}/%{_sysconfdir}/clustershell/groups
135137
%endif
136138

137-
# man pages
138-
install -d %{buildroot}/%{_mandir}/{man1,man5}
139-
install -p -m 0644 doc/man/man1/clubak.1 %{buildroot}/%{_mandir}/man1/
140-
install -p -m 0644 doc/man/man1/cluset.1 %{buildroot}/%{_mandir}/man1/
141-
install -p -m 0644 doc/man/man1/clush.1 %{buildroot}/%{_mandir}/man1/
142-
install -p -m 0644 doc/man/man1/nodeset.1 %{buildroot}/%{_mandir}/man1/
143-
install -p -m 0644 doc/man/man5/clush.conf.5 %{buildroot}/%{_mandir}/man5/
144-
install -p -m 0644 doc/man/man5/groups.conf.5 %{buildroot}/%{_mandir}/man5/
145-
146139
# vim addons
147140
%if 0%{?suse_version}
148141
%define vimdatadir %{_datadir}/vim/site

‎doc/sphinx/config.rst‎

Lines changed: 49 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,30 @@ clush
1111
clush.conf
1212
^^^^^^^^^^
1313

14-
The following configuration file defines global default values for
15-
several *clush* tool parameters::
14+
The following configuration file defines system-wide default values for
15+
several ``clush`` tool parameters::
1616

17-
$CLUSTERSHELL_CFGDIR/clush.conf
18-
19-
If *$CLUSTERSHELL_CFGDIR* is not defined, */etc/clustershell/clush.conf* will
20-
be used,
17+
/etc/clustershell/clush.conf
2118

22-
*clush* settings might then be overridden (globally, or per user) if one of the
23-
following files is found, in priority order::
19+
``clush`` settings might then be overridden (globally, or per user) if one of
20+
the following files is found, in priority order::
2421

2522
$XDG_CONFIG_HOME/clustershell/clush.conf
2623
$HOME/.config/clustershell/clush.conf (only if $XDG_CONFIG_HOME is not defined)
24+
{sys.prefix}/etc/clustershell/clush.conf
2725
$HOME/.local/etc/clustershell/clush.conf
2826
$HOME/.clush.conf (deprecated, for 1.6 compatibility only)
2927

30-
The following table describes available *clush* config file settings.
28+
.. note:: The path using `sys.prefix`_ was added in version 1.9.1 and is
29+
useful for Python virtual environments.
30+
31+
In addition, if the environment variable ``$CLUSTERSHELL_CFGDIR`` is defined and
32+
valid, it will used instead. In such case, the following configuration file
33+
will be tried first for ``clush``::
34+
35+
$CLUSTERSHELL_CFGDIR/clush.conf
36+
37+
The following table describes available ``clush`` config file settings.
3138

3239
+-----------------+----------------------------------------------------+
3340
| Key | Value |
@@ -36,10 +43,10 @@ The following table describes available *clush* config file settings.
3643
| | number of *ssh(1)* allowed to run at the same |
3744
| | time). |
3845
+-----------------+----------------------------------------------------+
39-
| confdir | Optional list of directory paths where *clush* |
46+
| confdir | Optional list of directory paths where ``clush`` |
4047
| | should look for **.conf** files which define |
4148
| | :ref:`run modes <clushmode-config>` that can then |
42-
| | be activated with `--mode`. All other *clush* |
49+
| | be activated with `--mode`. All other ``clush`` |
4350
| | config file settings defined in this table might |
4451
| | be overriden in a run mode. Each mode section |
4552
| | should have a name prefixed by "mode:" to clearly |
@@ -80,25 +87,25 @@ The following table describes available *clush* config file settings.
8087
| | stderr, and cannot be modified. |
8188
+-----------------+----------------------------------------------------+
8289
| fd_max | Maximum number of open file descriptors |
83-
| | permitted per *clush* process (soft resource limit |
84-
| | for open files). This limit can never exceed the |
85-
| | system (hard) limit. The *fd_max* (soft) and |
90+
| | permitted per ``clush`` process (soft resource |
91+
| | limit for open files). This limit can never exceed |
92+
| | the system (hard) limit. The *fd_max* (soft) and |
8693
| | system (hard) limits should be high enough to |
87-
| | run *clush*, although their values depend on |
94+
| | run ``clush``, although their values depend on |
8895
| | your fanout value. |
8996
+-----------------+----------------------------------------------------+
9097
| history_size | Set the maximum number of history entries saved in |
9198
| | the GNU readline history list. Negative values |
9299
| | imply unlimited history file size. |
93100
+-----------------+----------------------------------------------------+
94-
| node_count | Should *clush* display additional (node count) |
101+
| node_count | Should ``clush`` display additional (node count) |
95102
| | information in buffer header? (yes/no) |
96103
+-----------------+----------------------------------------------------+
97-
| maxrc | Should *clush* return the largest of command |
104+
| maxrc | Should ``clush`` return the largest of command |
98105
| | return codes? (yes/no) |
99-
| | If set to no (the default), *clush* exit status |
106+
| | If set to no (the default), ``clush`` exit status |
100107
| | gives no information about command return codes, |
101-
| | but rather reports on *clush* execution itself |
108+
| | but rather reports on ``clush`` execution itself |
102109
| | (zero indicating a successful run). |
103110
+-----------------+----------------------------------------------------+
104111
| password_prompt | Enable password prompt and password forwarding to |
@@ -143,7 +150,7 @@ The following table describes available *clush* config file settings.
143150
Run modes
144151
^^^^^^^^^
145152

146-
Since version 1.9, *clush* has support for run modes, which are special
153+
Since version 1.9, ``clush`` has support for run modes, which are special
147154
:ref:`clush-config` settings with a given name. Two run modes are provided in
148155
example configuration files that can be copied and modified. They implement
149156
password-based authentication with *sshpass(1)* and support of interactive
@@ -152,7 +159,7 @@ password-based authentication with *sshpass(1)* and support of interactive
152159
To use a run mode with ``clush --mode``, install a configuration file in one
153160
of :ref:`clush-config`'s ``confdir`` (usually ``clush.conf.d``). Only
154161
configuration files ending in **.conf** are scanned. If the user running
155-
*clush* doesn't have read access to a configuration file, is it ignored.
162+
``clush`` doesn't have read access to a configuration file, it is ignored.
156163
When ``--mode`` is specified, you can display all available run modes for
157164
the current user by enabling debug mode (``-d``).
158165

@@ -189,21 +196,28 @@ ClusterShell loads *groups.conf* configuration files that define how to
189196
obtain node groups configuration, ie. the way the library should access
190197
file-based or external node group **sources**.
191198

192-
The following configuration file defines global default values for
199+
The following configuration file defines system-wide default values for
193200
*groups.conf*::
194201

195-
$CLUSTERSHELL_CFGDIR/groups.conf
196-
197-
If *$CLUSTERSHELL_CFGDIR* is not defined, */etc/clustershell/groups.conf* will
198-
be used,
202+
/etc/clustershell/groups.conf
199203

200204
*groups.conf* settings might then be overridden (globally, or per user) if one
201205
of the following files is found, in priority order::
202206

203207
$XDG_CONFIG_HOME/clustershell/groups.conf
204208
$HOME/.config/clustershell/groups.conf (only if $XDG_CONFIG_HOME is not defined)
209+
{sys.prefix}/etc/clustershell/groups.conf
205210
$HOME/.local/etc/clustershell/groups.conf
206211

212+
.. note:: The path using `sys.prefix`_ was added in version 1.9.1 and is
213+
useful for Python virtual environments.
214+
215+
In addition, if the environment variable ``$CLUSTERSHELL_CFGDIR`` is defined and
216+
valid, it will used instead. In such case, the following configuration file
217+
will be tried first for *groups.conf*::
218+
219+
$CLUSTERSHELL_CFGDIR/groups.conf
220+
207221
This makes possible for an user to have its own *node groups* configuration.
208222
If no readable configuration file is found, group support will be disabled but
209223
other node set operations will still work.
@@ -611,18 +625,22 @@ in *defaults.conf*.
611625

612626
The following configuration file defines ClusterShell system-wide defaults::
613627

614-
$CLUSTERSHELL_CFGDIR/defaults.conf
615-
616-
If *$CLUSTERSHELL_CFGDIR* is not defined, */etc/clustershell/defaults.conf*
617-
will be used,
628+
/etc/clustershell/defaults.conf
618629

619630
*defaults.conf* settings might then be overridden (globally, or per user) if
620631
one of the following files is found, in priority order::
621632

622633
$XDG_CONFIG_HOME/clustershell/defaults.conf
623634
$HOME/.config/clustershell/defaults.conf (only if $XDG_CONFIG_HOME is not defined)
635+
{sys.prefix}/etc/clustershell/defaults.conf
624636
$HOME/.local/etc/clustershell/defaults.conf
625637

638+
In addition, if the environment variable ``$CLUSTERSHELL_CFGDIR`` is defined and
639+
valid, it will used instead. In such case, the following configuration file
640+
will be tried first for ClusterShell defaults::
641+
642+
$CLUSTERSHELL_CFGDIR/defaults.conf
643+
626644
Use case: rsh
627645
^^^^^^^^^^^^^^
628646

@@ -660,3 +678,4 @@ without error.
660678

661679
.. _ConfigParser: http://docs.python.org/library/configparser.html
662680
.. _nodeset: https://xcat-docs.readthedocs.io/en/stable/guides/admin-guides/references/man8/nodeset.8.html
681+
.. _sys.prefix: https://docs.python.org/3/library/sys.html#sys.prefix

‎doc/sphinx/install.rst‎

Lines changed: 27 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -231,45 +231,53 @@ ClusterShell is available since "Natty" release (11.04):
231231
* http://packages.ubuntu.com/clustershell
232232

233233

234-
Installing ClusterShell using PIP
235-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
236-
237-
Installing ClusterShell as root using PIP
238-
"""""""""""""""""""""""""""""""""""""""""
239-
240-
To install ClusterShell as a standard Python package using PIP [#]_ as root::
241-
242-
$ pip install ClusterShell
243-
244-
Or alternatively, using the source tarball::
245-
246-
$ pip install ClusterShell-1.x.tar.gz
234+
Installing ClusterShell the Python way
235+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
247236

237+
.. warning:: Installing ClusterShell as root using pip [#]_ is discouraged and
238+
can result in conflicting behaviour with the system package manager. Use
239+
packages provided by your OS instead to install ClusterShell system-wide.
248240

249241
.. _install-pip-user:
250242

251-
Installing ClusterShell as user using PIP
243+
Installing ClusterShell as user using pip
252244
"""""""""""""""""""""""""""""""""""""""""
253245

254-
To install ClusterShell as a standard Python package using PIP as an user::
246+
To install ClusterShell as a standard Python package using pip as an user::
255247

256248
$ pip install --user ClusterShell
257249

258250
Or alternatively, using the source tarball::
259251

260252
$ pip install --user ClusterShell-1.x.tar.gz
261253

262-
Then, you just need to update your ``PYTHONPATH`` environment variable to be
263-
able to import the library and ``PATH`` to easily use the :ref:`tools`::
254+
Then, you might need to update your ``PATH`` to easily use the :ref:`tools`,
255+
and possibly set the ``PYTHONPATH`` environment variable to be able to import
256+
the library, and finally ``MANPATH`` for the man pages::
264257

265-
$ export PYTHONPATH=$PYTHONPATH:~/.local/lib
266258
$ export PATH=$PATH:~/.local/bin
259+
$
260+
$ # Might also be needed:
261+
$ export PYTHONPATH=$PYTHONPATH:~/.local/lib
262+
$ export MANPATH=$MANPATH:$HOME/.local/share/man
267263

268264
Configuration files are installed in ``~/.local/etc/clustershell`` and are
269265
automatically loaded before system-wide ones (for more info about supported
270266
user config files, please see the :ref:`clush-config` or :ref:`groups-config`
271267
config sections).
272268

269+
.. _install-venv-pip:
270+
271+
Isolated environment using virtualenv and pip
272+
"""""""""""""""""""""""""""""""""""""""""""""
273+
274+
It is possible to use virtual env (`venv`_) and pip to install ClusterShell
275+
in an isolated environment::
276+
277+
$ python3 -m venv venv
278+
$ source venv/bin/activate
279+
$ pip install ClusterShell
280+
273281
.. _install-source:
274282

275283
Source
@@ -291,3 +299,4 @@ the latest development version from the repository::
291299
.. _EPEL: http://fedoraproject.org/wiki/EPEL
292300
.. _Alma Linux: https://almalinux.org/
293301
.. _Rocky Linux: https://rockylinux.org/
302+
.. _venv: https://docs.python.org/3/tutorial/venv.html

‎lib/ClusterShell/Defaults.py‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -91,15 +91,22 @@ def _distant_workerclass(defaults):
9191

9292
def config_paths(config_name):
9393
"""Return default path list for a ClusterShell config file name."""
94-
return [os.path.join(os.environ.get('CLUSTERSHELL_CFGDIR',
95-
'/etc/clustershell'),
96-
config_name), # global config file
97-
# default pip --user config file
98-
os.path.expanduser('~/.local/etc/clustershell/%s' % config_name),
99-
# per-user config (top override)
100-
os.path.join(os.environ.get('XDG_CONFIG_HOME',
101-
os.path.expanduser('~/.config')),
102-
'clustershell', config_name)]
94+
95+
paths = [os.path.join('/etc/clustershell', config_name), # system-wide
96+
# default pip --user config file
97+
os.path.expanduser('~/.local/etc/clustershell/%s' % config_name),
98+
# Python installation prefix (for venv)
99+
os.path.join(sys.prefix, 'etc/clustershell', config_name),
100+
# per-user config (XDG Base Directory Specification)
101+
os.path.join(os.environ.get('XDG_CONFIG_HOME',
102+
os.path.expanduser('~/.config')),
103+
'clustershell', config_name)]
104+
105+
# $CLUSTERSHELL_CFGDIR has precedence over any other config paths
106+
if 'CLUSTERSHELL_CFGDIR' in os.environ:
107+
paths.append(os.path.join(os.environ['CLUSTERSHELL_CFGDIR'],
108+
config_name))
109+
return paths
103110

104111
def _converter_integer_tuple(value):
105112
"""ConfigParser converter for tuple of integers"""

‎setup.py‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,8 @@
2525

2626
VERSION = '1.9'
2727

28-
# Default CFGDIR: in-prefix config install (rpmbuild or pip as user)
2928
CFGDIR = 'etc/clustershell'
30-
31-
# Use system-wide CFGDIR instead when installing as root on Unix
32-
try:
33-
if os.geteuid() == 0:
34-
CFGDIR = '/etc/clustershell'
35-
except AttributeError: # Windows?
36-
pass
29+
MANDIR = 'share/man'
3730

3831
# Dependencies (for pip install)
3932
REQUIRES = ['PyYAML']
@@ -57,7 +50,16 @@
5750
(os.path.join(CFGDIR, 'groups.d'),
5851
['conf/groups.d/cluster.yaml.example',
5952
'conf/groups.d/local.cfg',
60-
'conf/groups.d/README'])],
53+
'conf/groups.d/README']),
54+
(os.path.join(MANDIR, 'man1'),
55+
['doc/man/man1/clubak.1',
56+
'doc/man/man1/cluset.1',
57+
'doc/man/man1/clush.1',
58+
'doc/man/man1/nodeset.1']),
59+
(os.path.join(MANDIR, 'man5'),
60+
['doc/man/man5/clush.conf.5',
61+
'doc/man/man5/groups.conf.5']),
62+
],
6163
entry_points={'console_scripts':
6264
['clubak=ClusterShell.CLI.Clubak:main',
6365
'cluset=ClusterShell.CLI.Nodeset:main',

‎tests/CLIConfigTest.py‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -320,8 +320,7 @@ def testClushConfigWithInstalledConfig(self):
320320
config = ClushConfig(options)
321321

322322
def testClushConfigCustomGlobal(self):
323-
"""test CLI.Config.ClushConfig (CLUSTERSHELL_CFGDIR global custom
324-
config)
323+
"""test CLI.Config.ClushConfig (CLUSTERSHELL_CFGDIR global custom config)
325324
"""
326325

327326
# Save existing environment variable, if it's defined
@@ -375,13 +374,6 @@ def testClushConfigCustomGlobal(self):
375374
def testClushConfigUserOverride(self):
376375
"""test CLI.Config.ClushConfig (XDG_CONFIG_HOME user config)"""
377376

378-
# XXX Test should be improved when CLUSTERSHELL_CONFIG is available
379-
# Improvement: override CLUSTERSHELL_CONFIG and set a sys clush config
380-
# then verify that user config overrides CLUSTERSHELL_CONFIG as
381-
# expected...
382-
# For now, it has been tested manually. This test only really only
383-
# ensures that user config is taken into account.
384-
385377
xdg_config_home_save = os.environ.get('XDG_CONFIG_HOME')
386378

387379
# Create fake XDG_CONFIG_HOME

0 commit comments

Comments
 (0)