0.8

.github/workflows/run_tox.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        python-version: ['3.8', '3.9', '3.10']
 
     steps:
     - uses: actions/checkout@v1

doc/conf.py

@@ -37,7 +37,7 @@
 ]
 
 exec_code_working_dir = '../src'
-exec_code_folders = ['../src']
+exec_code_source_folders = ['../src', '../src', ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/configuration.rst

@@ -37,7 +37,7 @@ The following configuration parameters are available:
      - ``Path`` or ``str``
      - The working directory where the code will be executed.
 
-   * - ``exec_code_folders``
+   * - ``exec_code_source_folders``
      - | ``List`` of
        | ``Path`` or ``str``
      - | Additional folders that will be added to PYTHONPATH.
@@ -48,10 +48,10 @@ The following configuration parameters are available:
      - | The directory that is used to create the path to the
        | example files. Defaults to the parent folder of the ``conf.py``.
 
-   * - ``exec_code_stdout_encoding``
-     - ``str``
-     - | Encoding used to decode stdout.
-       | The default depends on the operating system but should be ``utf-8``.
+   * - ``exec_code_set_utf8_encoding``
+     - ``True`` or ``False``
+     - | True enforces utf-8 encoding (can fix encoding errors).
+       | Default is ``False`` except on Windows where it is ``True``.
 
 
 If it's a relative path it will be resolved relative to the parent folder of the ``conf.py``
@@ -61,7 +61,7 @@ Example:
 .. code-block:: python
 
    exec_code_working_dir = '..'
-   exec_code_folders = ['../my_src']
+   exec_code_source_folders = ['../my_src']
    exec_code_example_dir = '.'
 
 If you are unsure what the values are you can run Sphinx build in verbose mode with ``-v -v``.
@@ -72,6 +72,6 @@ Log output for Example:
 .. code-block:: text
 
    [exec-code] Working dir: C:\Python\sphinx-exec-code
-   [exec-code] Folders: C:\Python\sphinx-exec-code\my_src
+   [exec-code] Source folders: C:\Python\sphinx-exec-code\my_src
    [exec-code] Example dir: C:\Python\sphinx-exec-code\doc
-   [exec-code] Stdout encoding: utf-8
+   [exec-code] Set utf8 encoding: True

readme.md

@@ -36,9 +36,15 @@ This code will be executed
 ```
 
 # Changelog
+#### 0.8 (18.07.2022)
+- Renamed ``exec_code_folders`` to ``exec_code_source_folders``
+- Changed type of parameter to specify stdout to a flag
+- Changed default for config parameter that sets encoding
+- Dropped support for Python 3.7
+
 #### 0.7 (15.07.2022)
 - Added config parameter to specify stdout encoding
-- Only empty lines of the output get trimmed 
+- Only empty lines of the output get trimmed
 
 #### 0.6 (04.04.2022)
 - Fixed an issue where the line numbers for error messages were not correct

setup.py

@@ -52,7 +52,6 @@ def load_version() -> str:
         "License :: OSI Approved :: Apache Software License",
         "Natural Language :: English",
         "Operating System :: OS Independent",
-        "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",

src/sphinx_exec_code/__version__.py

@@ -1 +1 @@
-__version__ = '0.7'
+__version__ = '0.8'

src/sphinx_exec_code/code_exec.py

@@ -3,40 +3,32 @@
 import sys
 from itertools import dropwhile
 from pathlib import Path
-from typing import Iterable, Optional
-
-from sphinx.errors import ConfigError
 
 from sphinx_exec_code.code_exec_error import CodeException
-
-WORKING_DIR: Optional[str] = None
-ADDITIONAL_FOLDERS: Optional[Iterable[str]] = None
-STDOUT_ENCODING: str = sys.stdout.encoding
-
-
-def setup_code_env(cwd: Path, folders: Iterable[Path], encoding: str):
-    global WORKING_DIR, ADDITIONAL_FOLDERS, STDOUT_ENCODING
-    WORKING_DIR = str(cwd)
-    ADDITIONAL_FOLDERS = tuple(map(str, folders))
-    STDOUT_ENCODING = encoding
+from sphinx_exec_code.configuration import PYTHONPATH_FOLDERS, SET_UTF8_ENCODING, WORKING_DIR
 
 
 def execute_code(code: str, file: Path, first_loc: int) -> str:
-    if WORKING_DIR is None or ADDITIONAL_FOLDERS is None:
-        raise ConfigError('Working dir or additional folders are not set!')
+    cwd: Path = WORKING_DIR.value
+    encoding = 'utf-8' if SET_UTF8_ENCODING.value else None
+    python_folders = PYTHONPATH_FOLDERS.value
 
     env = os.environ.copy()
-    try:
-        env['PYTHONPATH'] = os.pathsep.join(ADDITIONAL_FOLDERS) + os.pathsep + env['PYTHONPATH']
-    except KeyError:
-        env['PYTHONPATH'] = os.pathsep.join(ADDITIONAL_FOLDERS)
 
-    run = subprocess.run([sys.executable, '-c', code], capture_output=True, cwd=WORKING_DIR, env=env)
+    if python_folders:
+        try:
+            env['PYTHONPATH'] = os.pathsep.join(python_folders) + os.pathsep + env['PYTHONPATH']
+        except KeyError:
+            env['PYTHONPATH'] = os.pathsep.join(python_folders)
+
+    run = subprocess.run([sys.executable, '-c', code.encode('utf-8')], capture_output=True, text=True,
+                         encoding=encoding, cwd=cwd, env=env)
+
     if run.returncode != 0:
-        raise CodeException(code, file, first_loc, run.returncode, run.stderr.decode()) from None
+        raise CodeException(code, file, first_loc, run.returncode, run.stderr) from None
 
     # decode output and drop tailing spaces
-    ret_str = (run.stdout.decode(encoding=STDOUT_ENCODING) + run.stderr.decode(encoding=STDOUT_ENCODING)).rstrip()
+    ret_str = (run.stdout if run.stdout is not None else '' + run.stderr if run.stderr is not None else '').rstrip()
 
     # drop leading empty lines
     ret_lines = list(dropwhile(lambda x: not x.strip(), ret_str.splitlines()))

src/sphinx_exec_code/code_format.py

@@ -1,4 +1,4 @@
-from typing import Iterable, Tuple
+from typing import Iterable, Tuple, List
 
 
 class VisibilityMarkerError(Exception):
@@ -16,7 +16,7 @@ def __init__(self, marker: str):
 
         self.do_add = True
         self.skip_empty = False
-        self.lines = []
+        self.lines: List[str] = []
 
     def is_marker(self, line: str) -> bool:
         if line == self.start:

src/sphinx_exec_code/configuration/__init__.py

@@ -0,0 +1 @@
+from .values import EXAMPLE_DIR, PYTHONPATH_FOLDERS, SET_UTF8_ENCODING, WORKING_DIR

src/sphinx_exec_code/configuration/base.py

@@ -0,0 +1,44 @@
+from typing import Any, Final, Generic, Optional, Tuple, Type, TypeVar, Union
+
+from sphinx.application import Sphinx as SphinxApp
+from sphinx.errors import ConfigError
+
+from sphinx_exec_code.__const__ import log
+
+TYPE_VALUE = TypeVar('TYPE_VALUE')
+
+
+class SphinxConfigValue(Generic[TYPE_VALUE]):
+    SPHINX_TYPE: Union[Tuple[Type[Any], ...], Type[Any]]
+
+    def __init__(self, sphinx_name: str, initial_value: Optional[TYPE_VALUE] = None):
+        self.sphinx_name: Final = sphinx_name
+        self._value: Optional[TYPE_VALUE] = initial_value
+
+    @property
+    def value(self) -> TYPE_VALUE:
+        if self._value is None:
+            raise ConfigError(f'{self.sphinx_name} is not set!')
+        return self._value
+
+    def transform_value(self, app: SphinxApp, value):
+        return value
+
+    def validate_value(self, value) -> TYPE_VALUE:
+        return value
+
+    def from_app(self, app: SphinxApp) -> TYPE_VALUE:
+        # load value
+        value = self.transform_value(app, getattr(app.config, self.sphinx_name))
+
+        # log transformed value
+        assert self.sphinx_name.startswith('exec_code_')
+        name = self.sphinx_name[10:].replace('_', ' ').capitalize()
+        log.debug(f'[exec-code] {name:s}: {value}')
+
+        # additional validation
+        self._value = self.validate_value(value)
+        return self._value
+
+    def add_config_value(self, app: SphinxApp, sphinx_default):
+        app.add_config_value(self.sphinx_name, sphinx_default, 'env', self.SPHINX_TYPE)

src/sphinx_exec_code/configuration/flag_config.py

@@ -0,0 +1,10 @@
+from sphinx.application import Sphinx as SphinxApp
+
+from sphinx_exec_code.configuration.base import SphinxConfigValue
+
+
+class SphinxConfigFlag(SphinxConfigValue[bool]):
+    SPHINX_TYPE = bool
+
+    def transform_value(self, app: SphinxApp, value) -> bool:
+        return bool(value)

src/sphinx_exec_code/configuration/path_config.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+from typing import Tuple
+
+from sphinx.application import Sphinx as SphinxApp
+
+from sphinx_exec_code.__const__ import log
+from sphinx_exec_code.configuration.base import SphinxConfigValue, TYPE_VALUE
+
+
+class SphinxConfigPath(SphinxConfigValue[TYPE_VALUE]):
+    SPHINX_TYPE = (str, Path)
+
+    def make_path(self, app: SphinxApp, value) -> Path:
+        try:
+            path = Path(value)
+        except Exception:
+            raise ValueError(f'Could not create Path from "{value}" (type {type(value).__name__}) '
+                             f'(configured by {self.sphinx_name:s})') from None
+
+        if not path.is_absolute():
+            path = (Path(app.confdir) / path).resolve()
+        return path
+
+    def check_folder_exists(self, folder: Path) -> Path:
+        if not folder.is_dir():
+            raise FileNotFoundError(f'Directory "{folder}" not found! (configured by {self.sphinx_name:s})')
+        return folder
+
+
+class SphinxConfigFolder(SphinxConfigPath[Path]):
+    def transform_value(self, app: SphinxApp, value) -> Path:
+        return self.make_path(app, value)
+
+    def validate_value(self, value: Path) -> Path:
+        return self.check_folder_exists(value)
+
+
+class SphinxConfigMultipleFolderStr(SphinxConfigPath[Tuple[str, ...]]):
+    SPHINX_TYPE = ()
+
+    def transform_value(self, app: SphinxApp, value) -> Tuple[Path, ...]:
+        return tuple(self.make_path(app, p) for p in value)
+
+    def validate_value(self, value: Tuple[Path, ...]) -> Tuple[str, ...]:
+        # check that folders exist
+        for f in value:
+            self.check_folder_exists(f)
+
+        # Search for a python package and print a warning if we find none
+        # since this is the only reason to specify additional folders
+        for f in value:
+            package_found = False
+            for _f in f.iterdir():
+                if not _f.is_dir():
+                    continue
+
+                # log warning if we don't find a python package
+                for file in _f.glob('__init__.py'):
+                    if file.name == '__init__.py':
+                        package_found = True
+                        break
+                if package_found:
+                    break
+
+            if not package_found:
+                log.warning(f'[exec-code] No Python packages found in {f}')
+
+        return tuple(map(str, value))

src/sphinx_exec_code/configuration/values.py

@@ -0,0 +1,9 @@
+from .flag_config import SphinxConfigFlag
+from .path_config import SphinxConfigFolder, SphinxConfigMultipleFolderStr
+
+EXAMPLE_DIR = SphinxConfigFolder('exec_code_example_dir')
+
+# Options for code execution
+WORKING_DIR = SphinxConfigFolder('exec_code_working_dir')
+PYTHONPATH_FOLDERS = SphinxConfigMultipleFolderStr('exec_code_source_folders')
+SET_UTF8_ENCODING = SphinxConfigFlag('exec_code_set_utf8_encoding')