API Reference

tidypy.execute_tools(config, path, progress=None)

Executes the suite of TidyPy tools upon the project and returns the issues that are found.

Parameters:
  • config (dict) – the TidyPy configuration to use
  • path (str) – that path to the project to analyze
  • progress (tidypy.Progress) – the progress reporter object that will receive callbacks during the execution of the tool suite. If not specified, not progress notifications will occur.
Return type:

tidypy.Collector

tidypy.execute_reports(config, path, collector, on_report_finish=None, output_file=None)

Executes the configured suite of issue reports.

Parameters:
  • config (dict) – the TidyPy configuration to use
  • path (str) – that path to the project that was analyzed
  • collector (tidypy.Collector) – the issues to report
tidypy.get_tools()

Retrieves the TidyPy tools that are available in the current Python environment.

The returned dictionary has keys that are the tool names and values are the tool classes.

Return type:dict
tidypy.get_reports()

Retrieves the TidyPy issue reports that are available in the current Python environment.

The returned dictionary has keys are the report names and values are the report classes.

Return type:dict
tidypy.get_extenders()

Retrieves the TidyPy configuration extenders that are available in the current Python environment.

The returned dictionary has keys are the extender names and values are the extender classes.

Return type:dict
tidypy.get_default_config()

Produces a stock/out-of-the-box TidyPy configuration.

Return type:dict
tidypy.get_user_config(project_path, use_cache=True)

Produces a TidyPy configuration that incorporates the configuration files stored in the current user’s home directory.

Parameters:
  • project_path (str) – the path to the project that is going to be analyzed
  • use_cache (bool) – whether or not to use cached versions of any remote/referenced TidyPy configurations. If not specified, defaults to True.
Return type:

dict

tidypy.get_local_config(project_path, use_cache=True)

Produces a TidyPy configuration using the pyproject.toml in the project’s directory.

Parameters:
  • project_path (str) – the path to the project that is going to be analyzed
  • use_cache (bool) – whether or not to use cached versions of any remote/referenced TidyPy configurations. If not specified, defaults to True.
Return type:

dict

tidypy.get_project_config(project_path, use_cache=True)

Produces the Tidypy configuration to use for the specified project.

If a pyproject.toml exists, the configuration will be based on that. If not, the TidyPy configuration in the user’s home directory will be used. If one does not exist, the default configuration will be used.

Parameters:
  • project_path (str) – the path to the project that is going to be analyzed
  • use_cache (bool) – whether or not to use cached versions of any remote/referenced TidyPy configurations. If not specified, defaults to True.
Return type:

dict

tidypy.purge_config_cache(location=None)

Clears out the cache of TidyPy configurations that were retrieved from outside the normal locations.

class tidypy.Tool(config)

The base class for TidyPy tools.

Parameters:config (dict) – the tool configuration to use during execution
classmethod can_be_used()

Indicates whether or not this tool can be executed now. Useful when you need to check for certain environmental conditions (e.g., Python version, dependency availability, etc).

Unless overridden, always returns True.

Return type:bool
config = None

The tool’s configuration to use during its execution.

execute(finder)

Analyzes the project and generates a list of issues found during that analysis.

Must be implemented by concrete classes.

Parameters:finder (tidypy.Finder) – the Finder class that should be used to identify the files or directories that the tool will analyze.
Return type:list(tidypy.Issue)
classmethod get_all_codes()

Produces a sequence of all the issue codes this tool is capable of generating. Elements in this sequence must all be 2-element tuples, where the first element is the code, and the second is a textual description of what the code means.

Must be implemented by concrete classes.

Returns:tuple of tuples containing two strings each
classmethod get_default_config()

Produces a tool configuration stanza that acts as the base/default for this tool.

rtype: dict

class tidypy.PythonTool(config)

A convenience abstract class that automatically sets the filters in the tool configuration to target Python source files.

Parameters:config (dict) – the tool configuration to use during execution
classmethod get_default_config()

Produces a tool configuration stanza that acts as the base/default for this tool.

rtype: dict

class tidypy.Issue(code=None, message=None, filename=None, line=None, character=None)

A class that encapsulates an issue found during the analysis of a project.

character = None

The character number within the line of the file where the issue was found (if known). The first column in a line is notated as 1 (not zero).

code = None

A string containing a code that identifies the type of issue found.

filename = None

A string containing the full path to the file where the issue was found.

line = None

The line number within the file where the issue was found (if known). The first line in a file is notated as 1 (not zero).

message = None

A string containing a description of the issue.

pylint_type = 'E'

A character indicating the comparable pylint category this issue would fall into: E=error, W=warning, R=refactor, C=convention

tool = None

A string containing name of the tool that found the issue.

class tidypy.TidyPyIssue(code=None, message=None, filename=None, line=None, character=None)

The base class for all TidyPy application issues that are produced.

class tidypy.UnknownIssue(exc, filename)

A completely unanticipated exception/problem was encountered during the execution of a tool.

class tidypy.AccessIssue(exc, filename)

An issue indicating that a file/directory cannot be accessed (typically due to permissions).

class tidypy.ParseIssue(exc, filename, line=None, character=None)

An issue indicating that a file could not be parsed as expected (e.g., a Python source file with invalid syntax).

class tidypy.ToolIssue(message, project_path, details=None, failure=False)

An issue indicating that a tool completely crashed/failed during its execution.

class tidypy.Finder(base_path, config)

A class that encapsulates the logic of finding files in a project that will be analyzed.

Parameters:
  • base_path (str) – the path to the base of the project
  • config (dict) – the configuration to use when searching the project
directories(filters=None, containing=None)

A generator that produces a sequence of paths to directories in the project that matches the specified filters.

Parameters:
  • filters (list(str)) – the regular expressions to use when finding directories in the project. If not specified, all directories are returned.
  • containing (list(str)) – if a directory passes through the specified filters, it is checked for the presence of a file that matches one of the regular expressions in this parameter.
files(filters=None)

A generator that produces a sequence of paths to files in the project that matches the specified filters.

Parameters:filters (list(str)) – the regular expressions to use when finding files in the project. If not specified, all files are returned.
is_excluded(path)

Determines whether or not the specified file is excluded by the project’s configuration.

Parameters:path (pathlib.Path) – the path to check
Return type:bool
is_excluded_dir(path)

Determines whether or not the specified directory is excluded by the project’s configuration.

Parameters:path (pathlib.Path) – the path to check
Return type:bool
modules(filters=None)

A generator that produces a sequence of paths to files that look to be Python modules (e.g., *.py).

Parameters:filters (list(str)) – the regular expressions to use when finding files in the project. If not specified, all files are returned.
packages(filters=None)

A generator that produces a sequence of paths to directories that look to be Python packages (e.g., they contain an __init__.py).

Parameters:filters (list(str)) – the regular expressions to use when finding directories in the project. If not specified, all directories are returned.
project_path

The path to the project that this Finder is operating from.

read_file(filepath)

Retrieves the contents of the specified file.

This function performs simple caching so that the same file isn’t read more than once per process.

Parameters:filepath (str) – the file to read.
Return type:str
relative_to_project(filepath)

Reformats a file path to be relative to this Finder’s project path.

Parameters:filepath (str or pathlib.Path) – the path to reformat
Return type:str
sys_paths(filters=None)

Produces a list of paths that would be suitable to use in sys.path in order to access the Python modules/packages found in this project.

Parameters:filters (list(str)) – the regular expressions to use when finding files in the project. If not specified, all files are returned.
class tidypy.Collector(config)

A class that contains all the issues found during an execution of the TidyPy tool suite.

Parameters:config (dict) – the configuration used to during the analysis of the project
add_issues(issues)

Adds an issue to the collection.

Parameters:issues (tidypy.Issue or list(tidypy.Issue)) – the issue(s) to add
get_grouped_issues(keyfunc=None, sortby=None)

Retrieves the issues in the collection grouped into buckets according to the key generated by the keyfunc.

Parameters:
  • keyfunc (func) – a function that will be used to generate the key that identifies the group that an issue will be assigned to. This function receives a single tidypy.Issue argument and must return a string. If not specified, the filename of the issue will be used.
  • sortby (list(str)) – the properties to sort the issues by
Return type:

OrderedDict

get_issues(sortby=None)

Retrieves the issues in the collection.

Parameters:sortby (list(str)) – the properties to sort the issues by
Return type:list(tidypy.Issue)
issue_count(include_unclean=False)

Returns the number of issues in the collection.

Parameters:include_unclean (bool) – whether or not to include issues that are being ignored due to being a duplicate, excluded, etc.
Return type:int
class tidypy.Report(config, base_path, output_file=None)

The base class for TidyPy issue reporters.

Parameters:
  • config (dict) – the configuration used during the analysis of the project
  • base_path (str) – the path to the project base directory
execute(collector)

Produces the contents of the report.

Must be implemented by concrete classes.

Parameters:collector (tidypy.Collector) – the collection of issues to report on
output(msg, newline=True)

Writes the specified string to the output target of the report.

Parameters:
  • msg (str) – the message to output.
  • newline (str) – whether or not to append a newline to the end of the message
relative_filename(filename)

Generates a path for the specified filename that is relative to the project path.

Parameters:filename (str) – the filename to generate the path for
Return type:str
class tidypy.Extender

The base class for TidyPy configuration extenders.

classmethod can_handle(location)

Indicates whether or not this Extender is capable of retrieving the specified location.

Parameters:location (str) – a URI indicating where to retrieve the TidyPy configuration from
Return type:bool
classmethod parse(content, is_pyproject=False)

A convenience method for parsing a TOML-serialized configuration.

Parameters:
  • content (str) – a TOML string containing a TidyPy configuration
  • is_pyproject (bool) – whether or not the content is (or resembles) a pyproject.toml file, where the TidyPy configuration is located within a key named tool.
Return type:

dict

classmethod retrieve(location, project_path)

Retrieves a TidyPy configuration from the specified location.

Parameters:
  • location (str) – a URI indicating where to retrieve the TidyPy configuration from
  • project_path (str) – the full path to the project’s base
Return type:

dict

exception tidypy.ExtenderError

The base class for all exceptions raised by an Extender during its operation.

exception tidypy.DoesNotExistError

An exception indicating that the specified Extender does not exist in the current environment.

class tidypy.Progress

An interface for receiving events that occur during the execution of the TidyPy tool suite.

on_finish()

Called after all tools in the suite have completed.

on_start()

Called when the execution of the TidyPy tool suite begins.

on_tool_finish(tool)

Called when an individual tool completes execution.

Parameters:tool (str) – the name of the tool that completed
on_tool_start(tool)

Called when an individual tool begins execution.

Parameters:tool (str) – the name of the tool that is starting
class tidypy.QuietProgress

An implementation of tidypy.Progress that produces no output.

class tidypy.ConsoleProgress(config)

An implementation of tidypy.Progress that outputs a progress bar to the console.

on_finish()

Called after all tools in the suite have completed.

on_start()

Called when the execution of the TidyPy tool suite begins.

on_tool_finish(tool)

Called when an individual tool completes execution.

Parameters:tool (str) – the name of the tool that completed
on_tool_start(tool)

Called when an individual tool begins execution.

Parameters:tool (str) – the name of the tool that is starting