Docs improvements #155
Docs improvements #155
Conversation
to simplify starting with this library, let's help users by providing a simple command to list all docs of the aexpect objects. Signed-off-by: Lukáš Doktor <[email protected]>
|
@AClon314 would this work for you or would you prefer another formulation? |
Yep, this works well for me. Appreciate the thoughtfulness! |
pevogam
left a comment
pevogam
left a comment
There was a problem hiding this comment.
I left a quick review about this
| we do keep our docstrings updated. To get details about all `aexpect.client` | ||
| objects simply run `python -c "import aexpect; [print(f'\n{name}\n{len(name) | ||
| * '='}', func.__doc__) for name, func in aexpect.__dict__.items() if | ||
| hasattr(func, '__doc__')]"` |
There was a problem hiding this comment.
Seems a bit far fetched but good it is a one-liner.
aexpect/client.py
Outdated
| ): | ||
| """ | ||
| Run a subprocess in the background and collect its output and exit status. | ||
| Runs the command, awaits for it to finish up to timeout and returns the |
There was a problem hiding this comment.
The default for docstrings is to use imperative form just like commit message. So I think Run is still better than Runs.
There was a problem hiding this comment.
In fact it would even be better as "Run a command" instead of "Run the command" since the argument is a detail of the function and not the other way around.
There was a problem hiding this comment.
Run a command then wait for it to finish up to a given timeout...
| """ | ||
| Run a subprocess in the background and collect its output and exit status. | ||
| Runs the command, awaits for it to finish up to timeout and returns the | ||
| Expect object (alive or dead, allows interaction). |
There was a problem hiding this comment.
Same as above - of course nice clarification too, perhaps we should take it out of the brackets as it is not secondary clarification but a major piece of information to separate the two functions.
There was a problem hiding this comment.
ok, not sure how to formulate that better without adding long sentences, so let's just go with the brackets form for now...
the first line should cover the main differences, let's add them there. Signed-off-by: Lukáš Doktor <[email protected]>
|
|
||
| To get more information use the python `help()` command on various objects, | ||
| we do keep our docstrings updated. To get details about all `aexpect.client` | ||
| objects simply run `python -c "import aexpect; [print(f'\n{name}\n{len(name) |
There was a problem hiding this comment.
Hi @ldoktor ! do you expect it to describe internal objects such as __name__? Maybe they aren't so relevant and can be filtered out? If too much a work then ignore that comment.
Ran locally just fine:
$ python -c "import aexpect; [print(f'\n{name}\n{len(name)
* '='}', func.__doc__) for name, func in aexpect.__dict__.items() if
hasattr(func, '__doc__')]"
__name__
======== str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to 'utf-8'.
errors defaults to 'strict'.
<snip>
remote
======
Functions and classes used for logging into guests and transferring files.
Example usage:
::
import aexpect
import aexpect.remote
with aexpect.ShellSession("sh") as b:
b.cmd("echo asdf > /tmp/bbb")
with aexpect.remote.remote_login("ssh", "127.0.0.1", 5000, "root", "123456",
aexpect.remote.PROMPT_LINUX) as a:
a.cmd("rm /tmp/aaa -Rf")
aexpect.remote.scp_to_session(a, "/tmp/bbb", "/tmp/aaa")
aexpect.remote.scp_from_session(a, "/tmp/aaa", "/tmp/ccc")
.. warning:: Some of this API is freshly migrated and might still be experimental.There was a problem hiding this comment.
TBH I don't think it'd be worth complicating the command (as it's suppose to be executed by users so they should understand that before running it)
4 participants
Few docs changes inspired by #154