Merge pull request #3 from pomponchik/develop

0.0.3

Author: pomponchik

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: pomponchik
+
+---
+
+## Short description
+
+Replace this text with a short description of the error and the behavior that you expected to see instead.
+
+
+## Describe the bug in detail
+
+Please add this test in such a way that it reproduces the bug you found and does not pass:
+
+```python
+def test_your_bug():
+    ...
+```
+
+Writing the test, please keep compatibility with the [`pytest`](https://docs.pytest.org/) framework.
+
+If for some reason you cannot describe the error in the test format, describe here the steps to reproduce it.
+
+
+## Environment
+ - OS: ...
+ - Python version (the output of the `python --version` command): ...
+ - Version of this package: ...

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,26 @@
+---
+name: Documentation fix
+about: Add something to the documentation, delete it, or change it
+title: ''
+labels: documentation
+assignees: pomponchik
+---
+
+## It's cool that you're here!
+
+Documentation is an important part of the project, we strive to make it high-quality and keep it up to date. Please adjust this template by outlining your proposal.
+
+
+## Type of action
+
+What do you want to do: remove something, add it, or change it?
+
+
+## Where?
+
+Specify which part of the documentation you want to make a change to? For example, the name of an existing documentation section or the line number in a file `README.md`.
+
+
+## The essence
+
+Please describe the essence of the proposed change

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: pomponchik
+
+---
+
+## Short description
+
+What do you propose and why do you consider it important?
+
+
+## Some details
+
+If you can, provide code examples that will show how your proposal will work. Also, if you can, indicate which alternatives to this behavior you have considered. And finally, how do you propose to test the correctness of the implementation of your idea, if at all possible?

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,12 @@
+---
+name: Question or consultation
+about: Ask anything about this project
+title: ''
+labels: guestion
+assignees: pomponchik
+
+---
+
+## Your question
+
+Here you can freely describe your question about the project. Please, before doing this, read the documentation provided, and ask the question only if the necessary answer is not there. In addition, please keep in mind that this is a free non-commercial project and user support is optional for its author. The response time is not guaranteed in any way.

.github/workflows/tests_and_coverage.yml

@@ -32,7 +32,7 @@ jobs:
       run: pip list
 
     - name: Run tests and show coverage on the command line
-      run: coverage run --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m
+      run: coverage run --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m --fail-under=100
 
     - name: Upload reports to codecov
       env:
@@ -45,4 +45,4 @@ jobs:
         ./codecov -t ${CODECOV_TOKEN}
 
     - name: Run tests and show the branch coverage on the command line
-      run: coverage run --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m
+      run: coverage run --branch --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m --fail-under=100

.github/workflows/tests_and_coverage_old.yml

@@ -32,7 +32,7 @@ jobs:
       run: pip list
 
     - name: Run tests and show coverage on the command line
-      run: coverage run --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m
+      run: coverage run --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m --fail-under=100
 
     - name: Upload reports to codecov
       env:
@@ -45,4 +45,4 @@ jobs:
         ./codecov -t ${CODECOV_TOKEN}
 
     - name: Run tests and show the branch coverage on the command line
-      run: coverage run --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m
+      run: coverage run --branch --source=suby --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m --fail-under=100

README.md

@@ -52,25 +52,33 @@ suby('python', '-c', 'print("hello, world!")')
 
 ## Run subprocess and look at the result
 
-The `suby` function returns an object of the `SubprocessResult` class. It contains the following required fields:
+The `suby` module is a callable object and can be imported like this:
 
-- **id** - a unique string that allows you to distinguish one result of calling the same command from another.
-- **stdout** - a string containing the entire buffered output of the command being run.
-- **stderr** - a string containing the entire buffered stderr of the command being run.
-- **returncode** - an integer indicating the return code of the subprocess. `0` means that the process was completed successfully, the other options usually indicate something bad.
-- **killed_by_token** - a boolean flag indicating whether the subprocess was killed due to [token](https://cantok.readthedocs.io/en/latest/the_pattern/) cancellation.
+```python
+import suby
+```
 
-The simplest example of what it might look like:
+If you use static type checking and get an error that it is impossible to call the module, use a more detailed import form - functionally, these two import ways are identical:
 
 ```python
-import suby
+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:
 
+```python
 result = suby('python', '-c', 'print("hello, world!")')
 print(result)
 # > SubprocessResult(id='e9f2d29acb4011ee8957320319d7541c', stdout='hello, world!\n', stderr='', returncode=0, killed_by_token=False)
 ```
 
-You can use strings or [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects as positional arguments for `suby`.
+We can see that it returns an object of the `SubprocessResult` class. It contains the following required fields:
+
+- **id** - a unique string that allows you to distinguish one result of calling the same command from another.
+- **stdout** - a string containing the entire buffered output of the command being run.
+- **stderr** - a string containing the entire buffered stderr of the command being run.
+- **returncode** - an integer indicating the return code of the subprocess. `0` means that the process was completed successfully, the other options usually indicate something bad.
+- **killed_by_token** - a boolean flag indicating whether the subprocess was killed due to [token](https://cantok.readthedocs.io/en/latest/the_pattern/) cancellation.
 
 
 ## Output

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "suby"
-version = "0.0.2"
+version = "0.0.3"
 authors = [
   { name="Evgeniy Blinov", email="zheni-b@yandex.ru" },
 ]
@@ -13,7 +13,7 @@ readme = "README.md"
 requires-python = ">=3.7"
 dependencies = [
     'emptylog>=0.0.7',
-    'cantok>=0.0.18',
+    'cantok>=0.0.24',
 ]
 classifiers = [
     "Operating System :: OS Independent",
@@ -32,6 +32,11 @@ classifiers = [
     'Intended Audience :: Developers',
     'Topic :: Software Development :: Libraries',
 ]
+keywords = [
+    'subprocesses',
+    'subprocesses wrapper',
+    'execute commands',
+]
 
 [tool.setuptools.package-data]
 "suby" = ["py.typed"]

suby/proxy_module.py

@@ -4,9 +4,10 @@
 from subprocess import Popen, PIPE
 from typing import List, Tuple, Callable, Union, Optional, Any
 from pathlib import Path
+from types import ModuleType
 
 from emptylog import EmptyLogger, LoggerProtocol
-from cantok import AbstractToken, TimeoutToken, CancellationError
+from cantok import AbstractToken, TimeoutToken, DefaultToken, CancellationError
 
 from suby.errors import RunningCommandError
 from suby.subprocess_result import SubprocessResult
@@ -23,15 +24,15 @@ def __call__(
         stdout_callback: Callable[[str], Any] = stdout_with_flush,
         stderr_callback: Callable[[str], Any] = stderr_with_flush,
         timeout: Optional[Union[int, float]] = None,
-        token: Optional[AbstractToken] = None,
+        token: AbstractToken = DefaultToken(),
     ) -> SubprocessResult:
         """
         About reading from strout and stderr: https://stackoverflow.com/a/28319191/14522393
         """
-        if timeout is not None and token is None:
+        if timeout is not None and isinstance(token, DefaultToken):
             token = TimeoutToken(timeout)
         elif timeout is not None:
-            token += TimeoutToken(timeout)  # type: ignore[operator]
+            token += TimeoutToken(timeout)
 
         converted_arguments = self.convert_arguments(arguments)
         arguments_string_representation = ' '.join([argument if ' ' not in argument else f'"{argument}"' for argument in converted_arguments])
@@ -44,7 +45,7 @@ def __call__(
 
         with Popen(list(converted_arguments), stdout=PIPE, stderr=PIPE, bufsize=1, universal_newlines=True) as process:
             stderr_reading_thread = self.run_stderr_thread(process, stderr_buffer, result, catch_output, stderr_callback)
-            if token is not None:
+            if not isinstance(token, DefaultToken):
                 killing_thread = self.run_killing_thread(process, token, result)
 
             for line in process.stdout:  # type: ignore[union-attr]
@@ -53,7 +54,7 @@ def __call__(
                     stdout_callback(line)
 
             stderr_reading_thread.join()
-            if token is not None:
+            if not isinstance(token, DefaultToken):
                 killing_thread.join()
 
         self.fill_result(stdout_buffer, stderr_buffer, process.returncode, result)
@@ -63,7 +64,7 @@ def __call__(
                 if result.killed_by_token:
                     logger.error(f'The execution of the "{arguments_string_representation}" command was canceled using a cancellation token.')
                     try:
-                        token.check()  # type: ignore[union-attr]
+                        token.check()
                     except CancellationError as e:
                         e.result = result  # type: ignore[attr-defined]
                         raise e
@@ -129,3 +130,7 @@ def fill_result(stdout_buffer: List[str], stderr_buffer: List[str], returncode:
         result.stdout = ''.join(stdout_buffer)
         result.stderr = ''.join(stderr_buffer)
         result.returncode = returncode
+
+    @property
+    def suby(self) -> ModuleType:
+        return self

tests/test_proxy_module.py

@@ -331,3 +331,13 @@ def test_use_path_object_as_first_positional_argument():
     assert result.stdout == 'kek\n'
     assert result.stderr == ''
     assert result.returncode == 0
+
+
+def test_suby_as_attribute_of_suby():
+    assert suby.suby is suby
+
+
+def test_full_import_form():
+    from suby import suby as local_suby
+
+    assert suby is local_suby