add install command (#108)

* add install command

* improve usage without import docs

* fix linting, tweak __main__.py

Author: samuelcolvin

README.md

@@ -61,14 +61,8 @@ outputs:
 
 ## Usage without Import
 
-modify `/usr/lib/python3.8/sitecustomize.py` making `debug` available in any python 3.8 code
+devtools can be used without `from devtools import debug` if you add `debug` into `__builtins__`
+in `sitecustomize.py`.
 
-```py
-# add devtools debug to builtins
-try:
-    from devtools import debug
-except ImportError:
-    pass
-else:
-    __builtins__['debug'] = debug
-```
+For instructions on adding `debug` to `__builtins__`, 
+see the [installation docs](https://python-devtools.helpmanual.io/usage/#usage-without-import).

devtools/__main__.py

@@ -0,0 +1,64 @@
+import os
+import sys
+from pathlib import Path
+
+from .version import VERSION
+
+# language=python
+install_code = """
+# add devtools `debug` function to builtins
+try:
+    from devtools import debug
+except ImportError:
+    pass
+else:
+    __builtins__['debug'] = debug
+"""
+
+
+def print_code() -> int:
+    print(install_code)
+    return 0
+
+
+def install() -> int:
+    print('[WARNING: this command is experimental, report issues at github.com/samuelcolvin/python-devtools]\n')
+
+    if 'debug' in __builtins__.__dict__:
+        print('Looks like devtools is already installed.')
+        return 0
+
+    try:
+        import sitecustomize  # type: ignore
+    except ImportError:
+        paths = [Path(p) for p in sys.path]
+        try:
+            path = next(p for p in paths if p.is_dir() and p.name == 'site-packages')
+        except StopIteration:
+            # what else makes sense to try?
+            print(f'unable to file a suitable path to save `sitecustomize.py` to from sys.path: {paths}')
+            return 1
+        else:
+            install_path = path / 'sitecustomize.py'
+    else:
+        install_path = Path(sitecustomize.__file__)
+
+    print(f'Found path "{install_path}" to install devtools into __builtins__')
+    print('To install devtools, run the following command:\n')
+    if os.access(install_path, os.W_OK):
+        print(f'    python -m devtools print-code >> {install_path}\n')
+    else:
+        print(f'    python -m devtools print-code | sudo tee -a {install_path} > /dev/null\n')
+        print('Note: "sudo" is required because the path is not writable by the current user.')
+
+    return 0
+
+
+if __name__ == '__main__':
+    if 'install' in sys.argv:
+        sys.exit(install())
+    elif 'print-code' in sys.argv:
+        sys.exit(print_code())
+    else:
+        print(f'python-devtools v{VERSION}, CLI usage: python -m devtools [install|print-code]')
+        sys.exit(1)

docs/examples/sitecustomize.py

@@ -39,7 +39,9 @@ def build_history():
     history = re.sub(r'#(\d+)', r'[#\1](https://github.com/samuelcolvin/python-devtools/issues/\1)', history)
     history = re.sub(r'( +)@([\w\-]+)', r'\1[@\2](https://github.com/\2)', history, flags=re.I)
     history = re.sub('@@', '@', history)
-    (THIS_DIR / '.history.md').write_text(history)
+    output_file = THIS_DIR / '.history.md'
+    if not output_file.exists() or history != output_file.read_text():
+        (THIS_DIR / '.history.md').write_text(history)
 
 
 def gen_example_html(markdown: str):
@@ -71,10 +73,12 @@ def set_version(markdown: str, page: Page) -> str:
 def remove_files(files: Files) -> Files:
     to_remove = []
     for file in files:
-        if file.src_path in {'plugins.py', 'requirements.txt'}:
+        if file.src_path == 'requirements.txt':
             to_remove.append(file)
         elif file.src_path.startswith('__pycache__/'):
             to_remove.append(file)
+        elif file.src_path.endswith('.py'):
+            to_remove.append(file)
 
     logger.debug('removing files: %s', [f.src_path for f in to_remove])
     for f in to_remove:

docs/plugins.py

@@ -83,19 +83,43 @@ For more details on prettier printing, see
 For more details on ansi colours, see
 [ansi.py](https://github.com/samuelcolvin/python-devtools/blob/main/devtools/ansi.py).
 
-## Usage without import
+## Usage without Import
 
 We all know the annoyance of running code only to discover a missing import, this can be particularly
 frustrating when the function you're using isn't used except during development.
 
-You can setup your environment to make `debug` available at all times by editing `sitecustomize.py`,
-with ubuntu and python3.8 this file can be found at `/usr/lib/python3.8/sitecustomize.py` but you might
-need to look elsewhere depending on your OS/python version.
+devtool's `debug` function can be used without import if you add `debug` to `__builtins__`
+in `sitecustomize.py`.
 
-Add the following to `sitecustomize.py`
+Two ways to do this:
+
+### Automatic install
+
+!!! warning
+    This is experimental, please [create an issue](https://github.com/samuelcolvin/python-devtools/issues) 
+    if you encounter any problems.
+
+To install `debug` into `__builtins__` automatically, run:
+
+```bash
+python -m devtools install
+```
+
+This command won't write to any files, but it should print a command for you to run to add/edit `sitecustomize.py`.
+
+### Manual install
+
+To manually add `debug` to `__builtins__`, add the following to `sitecustomize.py` or any code
+which is always imported.
 
 ```py
-{!examples/sitecustomize.py!}
+# add devtools `debug` function to builtins
+try:
+    from devtools import debug
+except ImportError:
+    pass
+else:
+    __builtins__['debug'] = debug
 ```
 
 The `ImportError` exception is important since you'll want python to run fine even if *devtools* isn't installed.

docs/usage.md

@@ -54,6 +54,7 @@ filterwarnings = 'error'
 [tool.coverage.run]
 source = ['devtools']
 branch = true
+omit = ['devtools/__main__.py']
 
 [tool.coverage.report]
 precision = 2