From 91550b37f78cb2db6590f591b3eeacd653fba9b4 Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Sat, 17 Apr 2021 10:20:30 -0700 Subject: [PATCH] DOC: Autoreformat all docstrings. This reformat all docstrings in ipykernel to conform to numpydoc. --- ipykernel/connect.py | 4 ++-- ipykernel/datapub.py | 2 -- ipykernel/embed.py | 3 +-- ipykernel/iostream.py | 5 ++--- ipykernel/jsonutil.py | 9 +++------ ipykernel/kernelapp.py | 8 ++++---- ipykernel/kernelspec.py | 25 ++++++++++--------------- ipykernel/parentpoller.py | 1 - ipykernel/pickleutil.py | 20 +++++++++----------- ipykernel/pylab/backend_inline.py | 13 ++++++------- ipykernel/serialize.py | 6 +----- ipykernel/zmqshell.py | 23 +++++++++++------------ 12 files changed, 49 insertions(+), 70 deletions(-) diff --git a/ipykernel/connect.py b/ipykernel/connect.py index 37b029207..08c374141 100644 --- a/ipykernel/connect.py +++ b/ipykernel/connect.py @@ -36,7 +36,7 @@ def get_connection_file(app=None): def find_connection_file(filename='kernel-*.json', profile=None): """DEPRECATED: find a connection file, and return its absolute path. - + THIS FUNCTION IS DEPRECATED. Use jupyter_client.find_connection_file instead. Parameters @@ -80,7 +80,7 @@ def find_connection_file(filename='kernel-*.json', profile=None): def _find_connection_file(connection_file, profile=None): """Return the absolute path for a connection file - + - If nothing specified, return current Kernel's connection file - If profile specified, show deprecation warning about finding connection files in profiles - Otherwise, call jupyter_client.find_connection_file diff --git a/ipykernel/datapub.py b/ipykernel/datapub.py index 19db14a6c..c124195cb 100644 --- a/ipykernel/datapub.py +++ b/ipykernel/datapub.py @@ -38,7 +38,6 @@ def publish_data(self, data): Parameters ---------- - data : dict The data to be published. Think of it as a namespace. """ @@ -60,7 +59,6 @@ def publish_data(data): Parameters ---------- - data : dict The data to be published. Think of it as a namespace. """ diff --git a/ipykernel/embed.py b/ipykernel/embed.py index 6641cd6e5..4334eb182 100644 --- a/ipykernel/embed.py +++ b/ipykernel/embed.py @@ -23,8 +23,7 @@ def embed_kernel(module=None, local_ns=None, **kwargs): The module to load into IPython globals (default: caller) local_ns : dict, optional The namespace to load into IPython user namespace (default: caller) - - kwargs : various, optional + **kwargs : various, optional Further keyword args are relayed to the IPKernelApp constructor, allowing configuration of the Kernel. Will only have an effect on the first embed_kernel call for a given process. diff --git a/ipykernel/iostream.py b/ipykernel/iostream.py index ab6a2f707..8fab38da4 100644 --- a/ipykernel/iostream.py +++ b/ipykernel/iostream.py @@ -50,10 +50,9 @@ def __init__(self, socket, pipe=False): Parameters ---------- - - socket: zmq.PUB Socket + socket : zmq.PUB Socket the socket on which messages will be sent. - pipe: bool + pipe : bool Whether this process should listen for IOPub messages piped from subprocesses. """ diff --git a/ipykernel/jsonutil.py b/ipykernel/jsonutil.py index 3029ad462..1218c8eae 100644 --- a/ipykernel/jsonutil.py +++ b/ipykernel/jsonutil.py @@ -50,13 +50,11 @@ def encode_images(format_dict): Parameters ---------- - format_dict : dict A dictionary of display data keyed by mime-type Returns ------- - format_dict : dict A copy of the same dictionary, but binary image data ('image/png', 'image/jpeg' or 'application/pdf') @@ -87,10 +85,9 @@ def json_clean(obj): Returns ------- out : object - - A version of the input which will not cause an encoding error when - encoded as JSON. Note that this function does not *encode* its inputs, - it simply sanitizes it so that there will be no encoding errors later. + A version of the input which will not cause an encoding error when + encoded as JSON. Note that this function does not *encode* its inputs, + it simply sanitizes it so that there will be no encoding errors later. """ # types that are 'atomic' and ok in json as-is. diff --git a/ipykernel/kernelapp.py b/ipykernel/kernelapp.py index ff2fdfd90..17fe183a7 100644 --- a/ipykernel/kernelapp.py +++ b/ipykernel/kernelapp.py @@ -527,10 +527,10 @@ def init_shell(self): def configure_tornado_logger(self): """ Configure the tornado logging.Logger. - Must set up the tornado logger or else tornado will call - basicConfig for the root logger which makes the root logger - go to the real sys.stderr instead of the capture streams. - This function mimics the setup of logging.basicConfig. + Must set up the tornado logger or else tornado will call + basicConfig for the root logger which makes the root logger + go to the real sys.stderr instead of the capture streams. + This function mimics the setup of logging.basicConfig. """ logger = logging.getLogger('tornado') handler = logging.StreamHandler() diff --git a/ipykernel/kernelspec.py b/ipykernel/kernelspec.py index 911df5f8b..9d43a8f71 100644 --- a/ipykernel/kernelspec.py +++ b/ipykernel/kernelspec.py @@ -28,16 +28,13 @@ def make_ipkernel_cmd(mod='ipykernel_launcher', executable=None, extra_arguments ---------- mod : str, optional (default 'ipykernel') A string of an IPython module whose __main__ starts an IPython kernel - executable : str, optional (default sys.executable) The Python executable to use for the kernel process. - extra_arguments : list, optional A list of extra arguments to pass when executing the launch code. Returns ------- - A Popen command list """ if executable is None: @@ -61,10 +58,10 @@ def get_kernel_dict(extra_arguments=None): def write_kernel_spec(path=None, overrides=None, extra_arguments=None): """Write a kernel spec directory to `path` - + If `path` is not specified, a temporary directory is created. If `overrides` is given, the kernelspec JSON is updated before writing. - + The path to the kernelspec is always returned. """ if path is None: @@ -92,33 +89,31 @@ def write_kernel_spec(path=None, overrides=None, extra_arguments=None): def install(kernel_spec_manager=None, user=False, kernel_name=KERNEL_NAME, display_name=None, prefix=None, profile=None, env=None): """Install the IPython kernelspec for Jupyter - + Parameters ---------- - - kernel_spec_manager: KernelSpecManager [optional] + kernel_spec_manager : KernelSpecManager [optional] A KernelSpecManager to use for installation. If none provided, a default instance will be created. - user: bool [default: False] + user : bool [default: False] Whether to do a user-only install, or system-wide. - kernel_name: str, optional + kernel_name : str, optional Specify a name for the kernelspec. This is needed for having multiple IPython kernels for different environments. - display_name: str, optional + display_name : str, optional Specify the display name for the kernelspec - profile: str, optional + profile : str, optional Specify a custom profile to be loaded by the kernel. - prefix: str, optional + prefix : str, optional Specify an install prefix for the kernelspec. This is needed to install into a non-default location, such as a conda/virtual-env. - env: dict, optional + env : dict, optional A dictionary of extra environment variables for the kernel. These will be added to the current environment variables before the kernel is started Returns ------- - The path where the kernelspec was installed. """ if kernel_spec_manager is None: diff --git a/ipykernel/parentpoller.py b/ipykernel/parentpoller.py index 38bf72e72..238a397c2 100644 --- a/ipykernel/parentpoller.py +++ b/ipykernel/parentpoller.py @@ -55,7 +55,6 @@ def __init__(self, interrupt_handle=None, parent_handle=None): interrupt_handle : HANDLE (int), optional If provided, the program will generate a Ctrl+C event when this handle is signaled. - parent_handle : HANDLE (int), optional If provided, the program will terminate immediately when this handle is signaled. diff --git a/ipykernel/pickleutil.py b/ipykernel/pickleutil.py index 651df1f3c..ea5ba715d 100644 --- a/ipykernel/pickleutil.py +++ b/ipykernel/pickleutil.py @@ -67,7 +67,7 @@ def interactive(f): def use_dill(): """use dill to expand serialization support - + adds support for object methods and closures to serialization. """ # import dill causes most of the magic @@ -91,7 +91,7 @@ def use_dill(): def use_cloudpickle(): """use cloudpickle to expand serialization support - + adds support for object methods and closures to serialization. """ import cloudpickle @@ -118,18 +118,16 @@ def use_cloudpickle(): class CannedObject(object): def __init__(self, obj, keys=[], hook=None): """can an object for safe pickling - + Parameters - ========== - - obj: + ---------- + obj The object to be canned - keys: list (optional) + keys : list (optional) list of attribute names that will be explicitly canned / uncanned - hook: callable (optional) + hook : callable (optional) An optional extra callable, which can do additional processing of the uncanned object. - large data may be offloaded into the buffers list, used for zero-copy transfers. """ @@ -304,7 +302,7 @@ class CannedMemoryView(CannedBytes): def _import_mapping(mapping, original=None): """import any string-keys in a type mapping - + """ log = get_logger() log.debug("Importing canning map") @@ -322,7 +320,7 @@ def _import_mapping(mapping, original=None): def istype(obj, check): """like isinstance(obj, check), but strict - + This won't catch subclasses. """ if isinstance(check, tuple): diff --git a/ipykernel/pylab/backend_inline.py b/ipykernel/pylab/backend_inline.py index f5333d517..36af62936 100644 --- a/ipykernel/pylab/backend_inline.py +++ b/ipykernel/pylab/backend_inline.py @@ -25,13 +25,13 @@ def show(close=None, block=None): Parameters ---------- close : bool, optional - If true, a ``plt.close('all')`` call is automatically issued after - sending all the figures. If this is set, the figures will entirely - removed from the internal list of figures. + If true, a ``plt.close('all')`` call is automatically issued after + sending all the figures. If this is set, the figures will entirely + removed from the internal list of figures. block : Not used. - The `block` parameter is a Matplotlib experimental parameter. - We accept it in the function signature for compatibility with other - backends. + The `block` parameter is a Matplotlib experimental parameter. + We accept it in the function signature for compatibility with other + backends. """ if close is None: close = InlineBackend.instance().close_figures @@ -158,7 +158,6 @@ def configure_inline_support(shell, backend): Parameters ---------- shell : InteractiveShell instance - backend : matplotlib backend """ # If using our svg payload backend, register the post-execution diff --git a/ipykernel/serialize.py b/ipykernel/serialize.py index a8558e80a..184a60ded 100644 --- a/ipykernel/serialize.py +++ b/ipykernel/serialize.py @@ -61,7 +61,6 @@ def serialize_object(obj, buffer_threshold=MAX_BYTES, item_threshold=MAX_ITEMS): Parameters ---------- - obj : object The object to be serialized buffer_threshold : int @@ -99,14 +98,11 @@ def deserialize_object(buffers, g=None): Parameters ---------- - - bufs : list of buffers/bytes - + buffers : list of buffers/bytes g : globals to be used when uncanning Returns ------- - (newobj, bufs) : unpacked object, and the list of remaining unused buffers. """ bufs = list(buffers) diff --git a/ipykernel/zmqshell.py b/ipykernel/zmqshell.py index 2dcb8b349..0f9eb8723 100644 --- a/ipykernel/zmqshell.py +++ b/ipykernel/zmqshell.py @@ -100,15 +100,15 @@ def publish(self, data, metadata=None, source=None, transient=None, Parameters ---------- - data: dict + data : dict A mime-bundle dict, keyed by mime-type. - metadata: dict, optional + metadata : dict, optional Metadata associated with the data. - transient: dict, optional, keyword-only + transient : dict, optional, keyword-only Transient data that may only be relevant during a live display, such as display_id. Transient data should not be persisted to documents. - update: bool, optional, keyword-only + update : bool, optional, keyword-only If True, send an update_display_data message instead of display_data. """ self._flush_streams() @@ -149,7 +149,7 @@ def clear_output(self, wait=False): Parameters ---------- - wait: bool (default: False) + wait : bool (default: False) If True, the output will not be cleared immediately, instead waiting for the next display before clearing. This reduces bounce during repeated clear & display loops. @@ -173,7 +173,6 @@ def register_hook(self, hook): Returns ------- Either a publishable message, or `None`. - The DisplayHook objects must return a message from the __call__ method if they still require the `session.send` method to be called after transformation. @@ -188,13 +187,13 @@ def unregister_hook(self, hook): Parameters ---------- - hook: Any callable object which has previously been - registered as a hook. + hook : Any callable object which has previously been + registered as a hook. Returns ------- bool - `True` if the hook was removed, `False` if it wasn't - found. + found. """ try: self._hooks.remove(hook) @@ -618,9 +617,9 @@ def system_piped(self, cmd): Parameters ---------- cmd : str - Command to execute (can not end in '&', as background processes are - not supported. Should not be a command that expects input - other than simple text. + Command to execute (can not end in '&', as background processes are + not supported. Should not be a command that expects input + other than simple text. """ if cmd.rstrip().endswith('&'): # this is *far* from a rigorous test