0.0.4

README.md

@@ -25,6 +25,7 @@ Here is a small wrapper around the [subprocesses](https://docs.python.org/3/libr
 
 - [**Quick start**](#quick-start)
 - [**Run subprocess and look at the result**](#run-subprocess-and-look-at-the-result)
+- [**Command parsing**](#command-parsing)
 - [**Output**](#output)
 - [**Logging**](#logging)
 - [**Exceptions**](#exceptions)
@@ -45,10 +46,12 @@ And use:
 ```python
 import suby
 
-suby('python', '-c', 'print("hello, world!")')
+suby('python -c "print(\'hello, world!\')"')
 # > hello, world!
 ```
 
+You can also quickly try out this and other packages without having to install using [instld](https://github.com/pomponchik/instld).
+
 
 ## Run subprocess and look at the result
 
@@ -64,10 +67,10 @@ If you use static type checking and get an error that it is impossible to call t
 from suby import suby
 ```
 
-Let's try to call `suby`. You can use strings or [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects as positional arguments, but now we call it with only simple strings:
+Let's try to call `suby`:
 
 ```python
-result = suby('python', '-c', 'print("hello, world!")')
+result = suby('python -c "print(\'hello, world!\')"')
 print(result)
 # > SubprocessResult(id='e9f2d29acb4011ee8957320319d7541c', stdout='hello, world!\n', stderr='', returncode=0, killed_by_token=False)
 ```
@@ -81,28 +84,68 @@ We can see that it returns an object of the `SubprocessResult` class. It contain
 - **killed_by_token** - a boolean flag indicating whether the subprocess was killed due to [token](https://cantok.readthedocs.io/en/latest/the_pattern/) cancellation.
 
 
+## Command parsing
+
+Each command you use to call `suby` is passed to a special [system call](https://en.wikipedia.org/wiki/System_call). Which one exactly depends on the operating system you are using. But regardless of the specific operating system, this system call usually accepts not one whole line of input, but a list of substrings. This means that somewhere under the hood, `suby` should cut the string you passed. The rules for this cutting are usually also different for different operating systems and depend on the specific shell you prefer. `suby` uses the [CMD](https://en.wikipedia.org/wiki/Cmd.exe) as a standard for [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) and [POSIX](https://en.wikipedia.org/wiki/POSIX) for POSIX-compatible systems.
+
+In most cases, you will not notice any differences in the parsing rules. For example, the following line:
+
+```bash
+python -c "print('hello, world!')"
+```
+
+... on Windows should be escaped like here:
+
+```python
+suby('python -c "print^(\'hello,world^!\'^)"')
+```
+
+... and on other systems like here:
+
+```python
+suby('python -c "print(\'hello, world!\')"')
+```
+
+You can pass not only strings to suby, but also [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects:
+
+```python
+import sys
+from pathlib import Path
+
+suby(Path(sys.executable), '-c print(777)')
+# This will work too.
+```
+
+If for some reason you want to disable the automatic splitting of strings into parts, pass `split=False`:
+
+```python
+suby('python', '-c', 'print(777)', split=False)
+```
+
+Of course, in this case, you will have to cut the command by yourself.
+
+
 ## Output
 
 By default, the `stdout` and `stderr` of the subprocess are forwarded to the `stdout` and `stderr` of the current process. The reading from the subprocess is continuous, and the output is every time a full line is read. For continuous reading from `stderr`, a separate thread is created in the main process, so that `stdout` and `stderr` are read independently.
 
 You can override the output functions for `stdout` and `stderr`. To do this, you need to pass as arguments `stdout_callback` and `stderr_callback`, respectively, some functions that accept a string as an argument. For example, you can color the output (the code example uses the [`termcolor`](https://github.com/termcolor/termcolor) library):
 
 ```python
-import suby
 from termcolor import colored
 
 def my_new_stdout(string: str) -> None:
     print(colored(string, 'red'), end='')
 
-suby('python', '-c', 'print("hello, world!")', stdout_callback=my_new_stdout)
+suby('python -c "print(\'hello, world!\')"', stdout_callback=my_new_stdout)
 # > hello, world!
 # You can't see it here, but believe me, if you repeat the code at home, the output in the console will be red!
 ```
 
 You can also completely disable the output by passing `True` as the `catch_output` parameter:
 
 ```python
-suby('python', '-c', 'print("hello, world!")', catch_output=True)
+suby('python -c "print(\'hello, world!\')"', catch_output=True)
 # There's nothing here.
 ```
 
@@ -115,7 +158,6 @@ By default, `suby` does not log command execution. However, you can pass a logge
 
 ```python
 import logging
-import suby
 
 logging.basicConfig(
     level=logging.INFO,
@@ -125,15 +167,15 @@ logging.basicConfig(
     ]
 )
 
-suby('python', '-c', 'pass', logger=logging.getLogger('logger_name'))
+suby('python -c pass', logger=logging.getLogger('logger_name'))
 # > 2024-02-22 02:15:08,155 [INFO] The beginning of the execution of the command "python -c pass".
 # > 2024-02-22 02:15:08,190 [INFO] The command "python -c pass" has been successfully executed.
 ```
 
 The message about the start of the command execution is always done with the `INFO` [level](https://docs.python.org/3.8/library/logging.html#logging-levels). If the command is completed successfully, the end message will also be with the `INFO` level. And if not - `ERROR`:
 
 ```python
-suby('python', '-c', 'raise ValueError', logger=logging.getLogger('logger_name'), catch_exceptions=True, catch_output=True)
+suby('python -c "raise ValueError"', logger=logging.getLogger('logger_name'), catch_exceptions=True, catch_output=True)
 # > 2024-02-22 02:20:25,549 [INFO] The beginning of the execution of the command "python -c "raise ValueError"".
 # > 2024-02-22 02:20:25,590 [ERROR] Error when executing the command "python -c "raise ValueError"".
 ```
@@ -150,10 +192,8 @@ By default, `suby` raises exceptions in three cases:
 1. If the command you are calling ended with a return code not equal to `0`. In this case, you will see an exception `suby.RunningCommandError`:
 
 ```python
-import suby
-
 try:
-    suby('python', '-c', '1/0')
+    suby('python -c 1/0')
 except suby.RunningCommandError as e:
     print(e)
     # > Error when executing the command "python -c 1/0".
@@ -166,7 +206,7 @@ except suby.RunningCommandError as e:
 You can prevent `suby` from raising any exceptions. To do this, set the `catch_exceptions` parameter to `True`:
 
 ```python
-result = suby('python', '-c', 'import time; time.sleep(10_000)', timeout=1, catch_exceptions=True)
+result = suby('python -c "import time; time.sleep(10_000)"', timeout=1, catch_exceptions=True)
 print(result)
 # > SubprocessResult(id='c9125b90d03111ee9660320319d7541c', stdout='', stderr='', returncode=-9, killed_by_token=True)
 ```
@@ -175,7 +215,7 @@ Keep in mind that the full result of the subprocess call can also be found throu
 
 ```python
 try:
-    suby('python', '-c', 'import time; time.sleep(10_000)', timeout=1)
+    suby('python -c "import time; time.sleep(10_000)"', timeout=1)
 except suby.TimeoutCancellationError as e:
     print(e.result)
     # > SubprocessResult(id='a80dc26cd03211eea347320319d7541c', stdout='', stderr='', returncode=-9, killed_by_token=True)
@@ -192,19 +232,18 @@ So, you can pass your cancellation tokens to `suby`. By default, canceling a tok
 
 ```python
 from random import randint
-import suby
 from cantok import ConditionToken
 
 token = ConditionToken(lambda: randint(1, 1000) == 7)  # This token will be cancelled when a random unlikely event occurs.
-suby('python', '-c', 'import time; time.sleep(10_000)', token=token)
+suby('python -c "import time; time.sleep(10_000)"', token=token)
 # > cantok.errors.ConditionCancellationError: The cancellation condition was satisfied.
 ```
 
 However, if you pass the `catch_exceptions=True` argument, the exception [will not be raised](#exceptions). Instead, you will get the [usual result](#run-subprocess-and-look-at-the-result) of calling `suby` with the `killed_by_token=True` flag:
 
 ```python
 token = ConditionToken(lambda: randint(1, 1000) == 7)
-print(suby('python', '-c', 'import time; time.sleep(10_000)', token=token, catch_exceptions=True))
+print(suby('python -c "import time; time.sleep(10_000)"', token=token, catch_exceptions=True))
 # > SubprocessResult(id='e92ccd54d24b11ee8376320319d7541c', stdout='', stderr='', returncode=-9, killed_by_token=True)
 ```
 
@@ -215,9 +254,7 @@ print(suby('python', '-c', 'import time; time.sleep(10_000)', token=token, catch
 You can set a timeout for `suby`. It must be an integer greater than zero, which indicates the number of seconds that the subprocess can continue to run. If the timeout expires before the subprocess completes, an exception will be raised:
 
 ```python
-import suby
-
-suby('python', '-c', 'import time; time.sleep(10_000)', timeout=1)
+suby('python -c "import time; time.sleep(10_000)"', timeout=1)
 # > cantok.errors.TimeoutCancellationError: The timeout of 1 seconds has expired.
 ```
 
@@ -227,7 +264,7 @@ The exception corresponding to this token was be reimported to `suby`:
 
 ```python
 try:
-    suby('python', '-c', 'import time; time.sleep(10_000)', timeout=1)
+    suby('python -c "import time; time.sleep(10_000)"', timeout=1)
 except suby.TimeoutCancellationError as e:  # As you can see, TimeoutCancellationError is available in the suby module.
     print(e)
     # > The timeout of 1 seconds has expired.
@@ -236,6 +273,6 @@ except suby.TimeoutCancellationError as e:  # As you can see, TimeoutCancellatio
 Just as with [regular cancellation tokens](#working-with-cancellation-tokens), you can prevent exceptions from being raised using the `catch_exceptions=True` argument:
 
 ```python
-print(suby('python', '-c', 'import time; time.sleep(10_000)', timeout=1, catch_exceptions=True))
+print(suby('python -c "import time; time.sleep(10_000)"', timeout=1, catch_exceptions=True))
 # > SubprocessResult(id='ea88c518d25011eeb25e320319d7541c', stdout='', stderr='', returncode=-9, killed_by_token=True)
 ```

pyproject.toml

@@ -4,16 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "suby"
-version = "0.0.3"
+version = "0.0.4"
 authors = [
   { name="Evgeniy Blinov", email="zheni-b@yandex.ru" },
 ]
 description = 'Slightly simplified subprocesses'
 readme = "README.md"
 requires-python = ">=3.7"
 dependencies = [
-    'emptylog>=0.0.7',
-    'cantok>=0.0.24',
+    'emptylog>=0.0.8',
+    'cantok>=0.0.30',
+    'oslex>=0.1.3 ; platform_system == "Windows"',
 ]
 classifiers = [
     "Operating System :: OS Independent",

suby/__init__.py

@@ -1,7 +1,7 @@
 import sys
 
 from suby.proxy_module import ProxyModule as ProxyModule
-from suby.errors import RunningCommandError as RunningCommandError  # noqa: F401
+from suby.errors import RunningCommandError as RunningCommandError, WrongCommandError as WrongCommandError  # noqa: F401
 
 from cantok import TimeoutCancellationError as TimeoutCancellationError  # noqa: F401
 

suby/errors.py

@@ -5,3 +5,6 @@ class RunningCommandError(Exception):
     def __init__(self, message: str, subprocess_result: SubprocessResult) -> None:
         self.result = subprocess_result
         super().__init__(message)
+
+class WrongCommandError(Exception):
+    pass

suby/proxy_module.py

@@ -9,7 +9,12 @@
 from emptylog import EmptyLogger, LoggerProtocol
 from cantok import AbstractToken, TimeoutToken, DefaultToken, CancellationError
 
-from suby.errors import RunningCommandError
+try:
+    from oslex import split as shlex_split  # type: ignore[import, unused-ignore]
+except ImportError:  # pragma: no cover
+    from shlex import split as shlex_split  # pragma: no cover
+
+from suby.errors import RunningCommandError, WrongCommandError
 from suby.subprocess_result import SubprocessResult
 from suby.callbacks import stdout_with_flush, stderr_with_flush
 
@@ -24,6 +29,7 @@ def __call__(
         stdout_callback: Callable[[str], Any] = stdout_with_flush,
         stderr_callback: Callable[[str], Any] = stderr_with_flush,
         timeout: Optional[Union[int, float]] = None,
+        split: bool = True,
         token: AbstractToken = DefaultToken(),
     ) -> SubprocessResult:
         """
@@ -34,7 +40,8 @@ def __call__(
         elif timeout is not None:
             token += TimeoutToken(timeout)
 
-        converted_arguments = self.convert_arguments(arguments)
+        converted_arguments = self.convert_arguments(arguments, split)
+
         arguments_string_representation = ' '.join([argument if ' ' not in argument else f'"{argument}"' for argument in converted_arguments])
 
         stdout_buffer: List[str] = []
@@ -84,14 +91,21 @@ def __call__(
         return result
 
     @staticmethod
-    def convert_arguments(arguments: Tuple[Union[str, Path], ...]) -> List[str]:
+    def convert_arguments(arguments: Tuple[Union[str, Path], ...], split: bool) -> List[str]:
         converted_arguments = []
 
         for argument in arguments:
             if isinstance(argument, Path):
                 converted_arguments.append(str(argument))
             elif isinstance(argument, str):
-                converted_arguments.append(argument)
+                if split:
+                    try:
+                        for sub_argument in shlex_split(argument):
+                            converted_arguments.append(sub_argument)
+                    except Exception as e:  # pragma: no cover
+                        raise WrongCommandError(f'The expression "{argument}" cannot be parsed.') from e  # pragma: no cover
+                else:
+                    converted_arguments.append(argument)
             else:
                 raise TypeError(f'Only strings and pathlib.Path objects can be positional arguments when calling the suby function. You passed "{argument}" ({type(argument).__name__}).')
 

tests/documentation/__init__.py

@@ -0,0 +1 @@
+

tests/documentation/test_quick_start.py

@@ -0,0 +1,46 @@
+from io import StringIO
+import platform
+from contextlib import redirect_stdout, redirect_stderr
+
+import suby
+import pytest
+
+
+@pytest.mark.skipif(platform.system() == 'Windows', reason='Windows and not windows have different rules of escaping characters.')
+def test_run_hello_world_not_windows():
+    stderr_buffer = StringIO()
+    stdout_buffer = StringIO()
+
+    with redirect_stdout(stdout_buffer), redirect_stderr(stderr_buffer):
+        result = suby('python -c "print(\'hello, world!\')"')
+
+    assert stderr_buffer.getvalue() == ''
+    assert stdout_buffer.getvalue() == 'hello, world!\n'
+
+    assert result.stdout == 'hello, world!\n'
+    assert result.stderr == ''
+    assert result.returncode == 0
+    assert not result.killed_by_token
+
+
+@pytest.mark.skipif(platform.system() != 'Windows', reason='Windows and not windows have different rules of escaping characters.')
+def test_run_hello_world_windows():
+    stderr_buffer = StringIO()
+    stdout_buffer = StringIO()
+
+    with redirect_stdout(stdout_buffer), redirect_stderr(stderr_buffer):
+        #result = suby('python -c "print^(\'hello, world^!\'^)"', catch_exceptions=True)
+        result = suby('python -c "print(\'hello, world!\')"', catch_exceptions=True)
+        print(result)
+
+    print(result)
+
+    print(stderr_buffer.getvalue())
+
+    #assert stderr_buffer.getvalue() == ''
+    assert stdout_buffer.getvalue() == 'hello, world!\n'
+
+    assert result.stdout == 'hello, world!\n'
+    assert result.stderr == ''
+    assert result.returncode == 0
+    assert not result.killed_by_token