pyaud

Framework for writing Python package audits.

pyaud.main() → int[source]

Main function for package.

Returns:

Exit status.

pyaud.pyaud(module: str, audit: list[str] | None = None, exclude: str | None = None, fix: bool = False, no_cache: bool = False) → int[source]

Module entry point.

Parse commandline arguments and run the selected choice from the dictionary of functions which matches the key.

Parameters:
module: str

Choice of module: [modules] to list all.

audit: list[str] | None = None

List of plugins for audit.

exclude: str | None = None

Regex of paths to ignore.

fix: bool = False

Suppress and fix all fixable issues.

no_cache: bool = False

Disable file caching.

Returns:

Exit status.

pyaud.exceptions

Exceptions for use within the module.

All exceptions made public for if they need to be reraised or excepted.

Exceptions are already built into the architecture but can be used in new plugins as well.

exception pyaud.exceptions.NameConflictError(plugin: str, name: str)[source]

Bases: Exception

Raise if adding plugin whose name is not unique.

Parameters:
plugin: str

Plugin which could not be registered.

name: str

Name which clashes with another.

pyaud.messages

pyaud.plugins

Main module used for public API.

class pyaud.plugins.Action(name: str)[source]

Bases: Plugin

Blueprint for writing generic plugins.

Called within context of defined environment variables. If no environment variables are defined nothing will change.

Raises:

  • CalledProcessError – Will always be raised if something fails that is not to do with the action condition. Will be excepted and reraised as AuditError if the action fails.

  • AuditError – Raised from CalledProcessError if action fails.

Returns:

Any value and type can be returned.

abstract action(*args: str, **kwargs: Any) → int[source]

All logic to be written within this method.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

Any value and type can be returned.

class pyaud.plugins.Audit(name: str)[source]

Bases: Plugin

Blueprint for writing audit-only plugins.

Audit will be called from here.

Run within context of defined environment variables. If no environment variables are defined nothing will change.

Raises:

  • CalledProcessError – Will always be raised if something fails that is not to do with the audit condition. Will be excepted and reraised as AuditError if the audit fails.

  • AuditError – Raised from CalledProcessError if audit fails.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify call whether process has succeeded or failed. No value will actually return from __call__ as it will be passed to the decorator.

abstract audit(*args: str, **kwargs: Any) → int[source]

All audit logic to be written within this method.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify call whether process has succeeded or failed.

class pyaud.plugins.BaseFix(name: str)[source]

Bases: Audit

Blueprint for writing audit and fix plugins.

Audit will be called from here.

Called within context of defined environment variables. If no environment variables are defined nothing will change.

If audit fails and the -f/--fix flag is passed to the commandline the fix method will be called within the CalledProcessError try-except block.

If -f/--fix and the audit fails the user is running the audit only and will raise an AuditError.

Raises:

  • CalledProcessError – Will always be raised if something fails that is not to do with the audit condition. Will be excepted and reraised as AuditError if the audit fails and -f/--fix is not passed to the commandline.

  • AuditError – Raised from CalledProcessError if audit fails and -f/--fix flag if not passed to the commandline.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify call whether process has succeeded or failed. No value will actually return from __call__ as it will be passed to the decorator.

abstract audit(*args: str, **kwargs: Any) → int[source]

All audit logic to be written within this method.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify __call__ whether process has succeeded or failed. If non-zero exist is returned and -f/--fix has been passed to the commandline run the fix method, otherwise raise AuditError.

abstract fix(*args: str, **kwargs: Any) → int[source]

Run if audit fails but only if running a fix.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify __call__ whether process has succeeded or failed.

class pyaud.plugins.BasePlugin[source]

Bases: ABC

Base type for all plugins.

cache = False

If set to True then indexed files will be monitored for change.

cache_all = False

Only matters if cache is set to True. If False (default) then audit will cache on a file-by-file basis. If True, then no changes can be made to any file for a cache-hit to be valid.

cache_file : str | _Path | None = None

set a single cache file for plugin subclass.

class pyaud.plugins.Fix(name: str)[source]

Bases: BaseFix

Blueprint for writing audit and fix plugins for single files.

Announce file status.

Raises:

  • CalledProcessError – Will always be raised if something fails that is not to do with the audit condition. Will be excepted and reraised as AuditError if the audit fails and -f/--fix is not passed to the commandline.

  • AuditError – Raised from CalledProcessError if audit fails and -f/--fix flag if not passed to the commandline.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify call whether process has succeeded or failed. No value will actually return from __call__ as it will be passed to the decorator.

abstract audit(*args: str, **kwargs: Any) → int[source]

All audit logic to be written within this method.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify __call__ whether process has succeeded or failed. If non-zero exist is returned and -f/--fix has been passed to the commandline run the fix method, otherwise raise AuditError.

abstract fix(*args: str, **kwargs: Any) → int[source]

Run if audit fails but only if running a fix.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify __call__ whether process has succeeded or failed.

class pyaud.plugins.FixAll(name: str)[source]

Bases: BaseFix

Blueprint for writing audit and fix plugins for Python files.

Announce Python file status.

Raises:

  • CalledProcessError – Will always be raised if something fails that is not to do with the audit condition. Will be excepted and reraised as AuditError if the audit fails and -f/--fix is not passed to the commandline.

  • AuditError – Raised from CalledProcessError if audit fails and -f/--fix flag if not passed to the commandline.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify call whether process has succeeded or failed. No value will actually return from __call__ as it will be passed to the decorator.

abstract audit(*args: str, **kwargs: Any) → int[source]

All audit logic to be written within this method.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify __call__ whether process has succeeded or failed. If non-zero exist is returned and -f/--fix has been passed to the commandline run the fix method, otherwise raise AuditError.

abstract fix(*args: str, **kwargs: Any) → int[source]

Run if audit fails but only if running a fix.

Parameters:
*args: str

Args that can be passed from other plugins.

**kwargs: Any

Boolean flags for subprocesses.

Returns:

If any error has not been raised for any reason int object must be returned, from subprocess or written, to notify __call__ whether process has succeeded or failed.

class pyaud.plugins.Parametrize(name: str)[source]

Bases: Plugin

Define a list of strings to call multiple plugins.

Raises:

  • CalledProcessError – Will always be raised if something fails that is not to do with the called plugin’s condition. Will be excepted and reraised as AuditError if the called plugin fails and the called plugin does not specify a fix method or the -f/--fix flag is not passed to the commandline.

  • AuditError – Raised from CalledProcessError if called plugin fails and no fix method is specified or the -f/--fix flag is not passed to the commandline.

abstract plugins() → list[str][source]

List of plugin names to run.

Returns:

List of plugin names, as defined in @register.

class pyaud.plugins.Plugin(name: str)[source]

Bases: BasePlugin

Base class of all plugins.

Raises TypeError if registered directly.

Contains the name attribute assigned upon registration.

Subprocesses are stored in the subprocess dict object

Parameters:
name: str

Name assigned to plugin via @register decorator.

property name : str

Name of the plugin.

class pyaud.plugins.Plugins[source]

Bases: Dict[str, Plugin]

Holds registered plugins.

Instantiate plugin on running __setitem__.

Raises:

  • NameConflictError – If name of registered plugin is not unique.

  • TypeError – If non plugin type registered.

pyaud.plugins.get(name: str) → Plugin[source]

Get plugins by name.

Parameters:
name: str

Unique name of plugin.

Returns:

Callable plugin instance.

pyaud.plugins.load() → None[source]

Import all package prefixed with pyaud[-_].

pyaud.plugins.mapping() → dict[str, Plugin][source]

Get dict of named keys and their corresponding plugin values.

Returns:

Mapping of plugins and their unique names.

pyaud.plugins.register(name: str | None = None) → _t.Callable[[PluginType], PluginType][source]

Register subclassed plugin to collection.

If name is not provided a name will be assigned automatically.

Parameters:
name: str | None = None

Name to register plugin as.

Returns:

Return registered plugin to call.

pyaud.plugins.registered() → list[str][source]

Get list of registered plugins.

Returns:

List of registered plugins.