REL: add module install.py

MANIFEST.in

@@ -5,6 +5,7 @@ include CHANGES.md
 include AUTHORS
 include requirements.txt
 include download.py
+include install.py
 include tests/README.md
 include tests/pytest.ini
 include tests/inspect_cython_signatures.py

install.py

@@ -0,0 +1,145 @@
+"""Install `dd`, including C extensions wrapping CUDD.
+
+Running this file will attempt to download
+the source code of CUDD from the internet.
+
+To run this file:
+
+```shell
+python install.py
+```
+
+This script is a shorthand for defining environment
+variables when running `pip install .` for the
+source code of the package `dd`.
+"""
+import argparse as _arg
+import os
+import re
+import shlex as _sh
+import subprocess as _sbp
+import tempfile as _tmp
+
+try:
+ import cython
+except ImportError as error:
+ cython = None
+ _cython_error = error
+
+
+def _main(
+ ) -> None:
+ """Entry point."""
+ args, unknown_args = _parse_args()
+ _assert_cython()
+ if not _ask_about_downloading(args):
+ print('Exiting without installing.')
+ return
+ with _tmp.NamedTemporaryFile('wt') as fd:
+ _install_using_pip(fd, unknown_args)
+
+
+def _install_using_pip(
+ fd,
+ unknown_args:
+ list[str]
+ ) -> None:
+ """Install `dd` using `pip`.
+
+ The installation includes `dd.cudd`.
+
+ Writes a temporary file to
+ the file system, used as requirements
+ file for `pip`.
+ """
+ env = dict(os.environ)
+ env.update(dict(
+ DD_FETCH='1',
+ DD_CUDD='1',
+ DD_CUDD_ZDD='1',
+ DD_CUDD_ADD='1'))
+ cmd_line = f'''
+ pip install
+ .
+ -vvv
+ --use-pep517
+ --no-build-isolation
+ '''
+ cmd = _sh.split(cmd_line)
+ cmd.extend(unknown_args)
+ _sbp.run(cmd, env=env)
+
+
+def _parse_args(
+ ) -> tuple[
+ _arg.Namespace,
+ list[str]]:
+ """Return command-line arguments."""
+ parser = _arg.ArgumentParser(description='''
+ Install package `dd` from its source,
+ including the modules `dd.cudd`, `dd.cudd_zdd`,
+ and `dd.cudd_add` (which are C extensions
+ that need `cython` and `gcc` to be compiled).
+
+ Attempts to download the source code of
+ CUDD from the internet.
+
+ Unknown arguments are passed to `pip install`.
+ ''')
+ parser.add_argument(
+ '-y', '--yes',
+ action='store_true',
+ help='go ahead and download CUDD '
+ 'source code tarball '
+ '(checking its SHA hash) '
+ 'without stopping and '
+ 'prompting the user '
+ 'for whether to do so.')
+ args, unknown_args = parser.parse_known_args()
+ return args, unknown_args
+
+
+def _assert_cython(
+ ) -> None:
+ """Assert that `cython` is installed.
+
+ Raise `ImportError` if not.
+ """
+ if cython is not None:
+ return
+ raise ImportError(
+ 'Installing `dd.cudd` requires the '
+ 'Python package `cython`, which can '
+ 'be installed from '
+ 'the Python Package Index (PyPI) '
+ 'by running `pip install cython`. '
+ 'For installing `dd` with only '
+ 'its pure-Python modules, '
+ 'running `pip install .` suffices, '
+ 'no need to run `python install.py`.'
+ ) from _cython_error
+
+
+def _ask_about_downloading(
+ args:
+ _arg.Namespace
+ ) -> bool:
+ """Ask whether to download CUDD tarball."""
+ if args.yes:
+ return True
+ choice = input(
+ 'This script downloads '
+ 'CUDD sources from the internet '
+ '(details in the file `download.py`).\n'
+ 'Proceed?\n'
+ '(answers: yes / no)\n')
+ match choice:
+ case 'yes' | 'no':
+ return (choice == 'yes')
+ raise ValueError(
+ 'Expected `yes` or '
+ '`no` as input.')
+
+
+if __name__ == '__main__':
+ _main()