Utils

Module Documentation

doctor.utils.DESCRIPTION_END_RE = re.compile(':(arg|param|returns|throws)', re.IGNORECASE)

Used to identify the end of the description block, and the beginning of the parameters. This assumes that the parameters and such will always occur at the end of the docstring.

class doctor.utils.Params(all, required, optional, logic)

Bases: object

Represents parameters for a request.

Parameters:

• all (List[str]) – A list of all paramter names for a request.
• required (List[str]) – A list of all required parameter names for a request.
• optional (List[str]) – A list of all optional parameter names for a request.
• logic (List[str]) – A list of all parameter names that are part ofthe logic function signature.

class doctor.utils.RequestParamAnnotation(name, annotation, required=False)

Bases: object

Represents a new request parameter annotation.

Parameters:

• name (str) – The name of the parameter.
• annotation (A doctor type that should subclass SuperType.) – The annotation type of the parameter.
• required (bool) – Indicates if the parameter is required or not.

doctor.utils.add_param_annotations(logic, params)

Adds parameter annotations to a logic function.

This adds additional required and/or optional parameters to the logic function that are not part of it’s signature. It’s intended to be used by decorators decorating logic functions or middleware.

Parameters:

• logic (Callable) – The logic function to add the parameter annotations to.
• params (List[RequestParamAnnotation]) – The list of RequestParamAnnotations to add to the logic func.

Return type:

Callable

Returns:

The logic func with updated parameter annotations.

doctor.utils.get_description_lines(docstring)

Extract the description from the given docstring.

This grabs everything up to the first occurrence of something that looks like a parameter description. The docstring will be dedented and cleaned up using the standard Sphinx methods.

Parameters:docstring (str) – The source docstring. Returns:list

doctor.utils.get_module_attr(module_filename, module_attr, namespace=None)

Get an attribute from a module.

This uses exec to load the module with a private namespace, and then plucks and returns the given attribute from that module’s namespace.

Note that, while this method doesn’t have any explicit unit tests, it is tested implicitly by the doctor’s own documentation. The Sphinx build process will fail to generate docs if this does not work.

Parameters:

• module_filename (str) – Path to the module to execute (e.g. “../src/app.py”).
• module_attr (str) – Attribute to pluck from the module’s namespace. (e.g. “app”).
• namespace (dict) – Optional namespace. If one is not passed, an empty dict will be used instead. Note that this function mutates the passed namespace, so you can inspect a passed dict after calling this method to see how the module changed it.

Returns:

The attribute from the module.

Raises:

KeyError – if the module doesn’t have the given attribute.

doctor.utils.get_params_from_func(func, signature=None)

Gets all parameters from a function signature.

Parameters:

• func (Callable) – The function to inspect.
• signature (Optional[Signature]) – An inspect.Signature instance.

Return type:

Params

Returns:

A named tuple containing information about all, optional, required and logic function parameters.

doctor.utils.get_valid_class_name(s)

Return the given string converted so that it can be used for a class name

Remove leading and trailing spaces; removes spaces and capitalizes each word; and remove anything that is not alphanumeric. Returns a pep8 compatible class name.

Parameters:s (str) – The string to convert. Return type:str Returns:The updated string.