Auditors Module

Django Agents Auditor Module.

This module provides comprehensive auditing capabilities for Django projects, including code quality analysis, security checks, and best practices validation.

The auditor system consists of: - AuditReport: Report generation and formatting - BaseAuditor: Base class for all auditors - Various specialized auditors for different aspects of Django projects

Example

Basic usage of the auditor system:

from django_agents.auditors import AuditReport, CodebaseAuditor

report = AuditReport(output_format='markdown')
auditor = CodebaseAuditor()
result = auditor.audit()
report.add_section('Codebase Analysis', result)
print(report.generate())

class django_agents.auditors.AuditReport(output_format='text')

Bases: object

Manages audit report generation and formatting.

This class collects audit results from multiple auditors and generates formatted reports in various output formats (text, markdown, JSON, HTML).

Parameters:

output_format (str) – Output format for the report. Options: ‘text’, ‘markdown’, ‘json’, ‘html’. Defaults to ‘text’.

format

The output format for the report.

Type:

str

sections

List of report sections containing audit results.

Type:

list

total_issues

Total count of critical issues found.

Type:

int

total_warnings

Total count of warnings found.

Type:

int

total_suggestions

Total count of suggestions provided.

Type:

int

Example

>>> report = AuditReport(output_format='markdown')
>>> report.add_section('Security', {'critical': ['Issue 1']})
>>> print(report.generate())

__init__(output_format='text')

Initialize the audit report.

Parameters:

output_format (str, optional) – Format for output generation. Defaults to ‘text’.

add_section(title, content)

Add a section to the report.

Parameters:

• title (str) – Section title.

• content (dict) – Section content containing audit results with keys: - critical (list): Critical issues - warnings (list): Warnings - suggestions (list): Suggestions - good_practices (list): Detected best practices

generate()

Generate the final audit report in the specified format.

Returns:

Formatted report content.

Return type:

str

Note

The format is determined by the output_format parameter passed during initialization.

get_summary()

Return a summary of the audit report.

Returns:

Summary containing counts of issues, warnings, and suggestions.

Return type:

str

class django_agents.auditors.BaseAuditor

Bases: object

Base class for all auditor implementations.

This abstract class provides the foundation for creating specialized auditors that analyze different aspects of Django projects.

critical

List of critical issues found during audit.

Type:

list

warnings

List of warnings identified.

Type:

list

suggestions

List of improvement suggestions.

Type:

list

good_practices

List of detected best practices.

Type:

list

Note

Subclasses must implement the audit() method to perform specific audit operations.

__init__()

Initialize the auditor with empty result lists.

audit()

Perform the audit operation.

This method must be implemented by subclasses to perform specific audit checks.

Returns:

Audit results from get_result().

Return type:

dict

Raises:

NotImplementedError – If not implemented by subclass.

get_result()

Return the aggregated audit results.

Returns:

Dictionary containing:

• critical (list): Critical issues

• warnings (list): Warnings

• suggestions (list): Suggestions

• good_practices (list): Best practices

• critical_issues (int): Count of critical issues

Return type:

dict

class django_agents.auditors.CodebaseAuditor

Bases: BaseAuditor

Auditor for analyzing project codebase structure and quality.

Performs comprehensive analysis of Python files, project structure, dependencies, and documentation.

Checks include:

• Project structure validation

• Python file analysis (docstrings, function complexity)

• Dependency management

• Documentation presence

audit()

Run the codebase audit.

Returns:

Audit results containing identified issues and recommendations.

Return type:

dict

class django_agents.auditors.TestsAuditor

Bases: BaseAuditor

Auditor for analyzing test coverage and quality.

Examines test files, test functions, and testing frameworks to ensure adequate test coverage.

Checks include:

• Presence of test files

• Number of test functions

• Testing framework configuration (pytest, unittest)

• Coverage tool installation

audit()

Run the tests audit.

Returns:

Audit results with test coverage analysis.

Return type:

dict

class django_agents.auditors.AppsAuditor

Bases: BaseAuditor

Auditor for analyzing Django app structure and organization.

Validates Django app configurations and checks for proper modular organization.

Checks include:

• Installed apps analysis

• App structure validation

• Required files in apps

• Agent integration

audit()

Run the Django apps audit.

Returns:

Audit results with app structure analysis.

Return type:

dict

class django_agents.auditors.SettingsAuditor

Bases: BaseAuditor

Auditor for analyzing Django settings and security configuration.

Performs security-focused analysis of Django settings including DEBUG mode, SECRET_KEY, security middleware, and database configuration.

Checks include:

• DEBUG mode status

• SECRET_KEY security

• ALLOWED_HOSTS configuration

• Security middleware presence

• Database configuration

• Static/media files setup

audit()

Run the Django settings audit.

Returns:

Audit results with security and configuration analysis.

Return type:

dict

class django_agents.auditors.ProductionAuditor

Bases: BaseAuditor

Auditor for production deployment readiness.

Analyzes the project for production deployment requirements including HTTPS configuration, deployment files, and security settings.

Checks include:

• DEBUG mode verification

• Deployment configuration files

• HTTPS/SSL settings

• HSTS configuration

• Logging configuration

• Environment variable templates

audit()

Run the production readiness audit.

Returns:

Audit results with production readiness analysis.

Return type:

dict

class django_agents.auditors.DatabaseAuditor

Bases: BaseAuditor

Auditor for database models and migrations.

Analyzes Django models, migrations, and database optimization.

Checks include:

• Model count and structure

• __str__ method presence

• Migrations existence

• Database indexes

audit()

Run the database audit.

Returns:

Audit results with database analysis.

Return type:

dict

class django_agents.auditors.ServerAuditor

Bases: BaseAuditor

Auditor for server and deployment configuration.

Analyzes server setup including WSGI/ASGI, web servers, and caching configuration.

Checks include:

• WSGI/ASGI file presence

• Gunicorn installation

• Static file serving (WhiteNoise)

• Server configuration files

• Cache configuration

audit()

Run the server audit.

Returns:

Audit results with server configuration analysis.

Return type:

dict

AuditReport

class django_agents.auditors.AuditReport(output_format='text')

Bases: object

Manages audit report generation and formatting.

This class collects audit results from multiple auditors and generates formatted reports in various output formats (text, markdown, JSON, HTML).

Parameters:

output_format (str) – Output format for the report. Options: ‘text’, ‘markdown’, ‘json’, ‘html’. Defaults to ‘text’.

format

The output format for the report.

Type:

str

sections

List of report sections containing audit results.

Type:

list

total_issues

Total count of critical issues found.

Type:

int

total_warnings

Total count of warnings found.

Type:

int

total_suggestions

Total count of suggestions provided.

Type:

int

Example

>>> report = AuditReport(output_format='markdown')
>>> report.add_section('Security', {'critical': ['Issue 1']})
>>> print(report.generate())

__init__(output_format='text')

Initialize the audit report.

Parameters:

output_format (str, optional) – Format for output generation. Defaults to ‘text’.

add_section(title, content)

Add a section to the report.

Parameters:

• title (str) – Section title.

• content (dict) – Section content containing audit results with keys: - critical (list): Critical issues - warnings (list): Warnings - suggestions (list): Suggestions - good_practices (list): Detected best practices

generate()

Generate the final audit report in the specified format.

Returns:

Formatted report content.

Return type:

str

Note

The format is determined by the output_format parameter passed during initialization.

get_summary()

Return a summary of the audit report.

Returns:

Summary containing counts of issues, warnings, and suggestions.

Return type:

str

BaseAuditor

class django_agents.auditors.BaseAuditor

Bases: object

Base class for all auditor implementations.

This abstract class provides the foundation for creating specialized auditors that analyze different aspects of Django projects.

critical

List of critical issues found during audit.

Type:

list

warnings

List of warnings identified.

Type:

list

suggestions

List of improvement suggestions.

Type:

list

good_practices

List of detected best practices.

Type:

list

Note

Subclasses must implement the audit() method to perform specific audit operations.

__init__()

Initialize the auditor with empty result lists.

audit()

Perform the audit operation.

This method must be implemented by subclasses to perform specific audit checks.

Returns:

Audit results from get_result().

Return type:

dict

Raises:

NotImplementedError – If not implemented by subclass.

get_result()

Return the aggregated audit results.

Returns:

Dictionary containing:

• critical (list): Critical issues

• warnings (list): Warnings

• suggestions (list): Suggestions

• good_practices (list): Best practices

• critical_issues (int): Count of critical issues

Return type:

dict

Specialized Auditors

CodebaseAuditor

class django_agents.auditors.CodebaseAuditor

Bases: BaseAuditor

Auditor for analyzing project codebase structure and quality.

Performs comprehensive analysis of Python files, project structure, dependencies, and documentation.

Checks include:

• Project structure validation

• Python file analysis (docstrings, function complexity)

• Dependency management

• Documentation presence

audit()

Run the codebase audit.

Returns:

Audit results containing identified issues and recommendations.

Return type:

dict

TestsAuditor

class django_agents.auditors.TestsAuditor

Bases: BaseAuditor

Auditor for analyzing test coverage and quality.

Examines test files, test functions, and testing frameworks to ensure adequate test coverage.

Checks include:

• Presence of test files

• Number of test functions

• Testing framework configuration (pytest, unittest)

• Coverage tool installation

audit()

Run the tests audit.

Returns:

Audit results with test coverage analysis.

Return type:

dict

AppsAuditor

class django_agents.auditors.AppsAuditor

Bases: BaseAuditor

Auditor for analyzing Django app structure and organization.

Validates Django app configurations and checks for proper modular organization.

Checks include:

• Installed apps analysis

• App structure validation

• Required files in apps

• Agent integration

audit()

Run the Django apps audit.

Returns:

Audit results with app structure analysis.

Return type:

dict

SettingsAuditor

class django_agents.auditors.SettingsAuditor

Bases: BaseAuditor

Auditor for analyzing Django settings and security configuration.

Performs security-focused analysis of Django settings including DEBUG mode, SECRET_KEY, security middleware, and database configuration.

Checks include:

• DEBUG mode status

• SECRET_KEY security

• ALLOWED_HOSTS configuration

• Security middleware presence

• Database configuration

• Static/media files setup

audit()

Run the Django settings audit.

Returns:

Audit results with security and configuration analysis.

Return type:

dict

ProductionAuditor

class django_agents.auditors.ProductionAuditor

Bases: BaseAuditor

Auditor for production deployment readiness.

Analyzes the project for production deployment requirements including HTTPS configuration, deployment files, and security settings.

Checks include:

• DEBUG mode verification

• Deployment configuration files

• HTTPS/SSL settings

• HSTS configuration

• Logging configuration

• Environment variable templates

audit()

Run the production readiness audit.

Returns:

Audit results with production readiness analysis.

Return type:

dict

DatabaseAuditor

class django_agents.auditors.DatabaseAuditor

Bases: BaseAuditor

Auditor for database models and migrations.

Analyzes Django models, migrations, and database optimization.

Checks include:

• Model count and structure

• __str__ method presence

• Migrations existence

• Database indexes

audit()

Run the database audit.

Returns:

Audit results with database analysis.

Return type:

dict

ServerAuditor

class django_agents.auditors.ServerAuditor

Bases: BaseAuditor

Auditor for server and deployment configuration.

Analyzes server setup including WSGI/ASGI, web servers, and caching configuration.

Checks include:

• WSGI/ASGI file presence

• Gunicorn installation

• Static file serving (WhiteNoise)

• Server configuration files

• Cache configuration

audit()

Run the server audit.

Returns:

Audit results with server configuration analysis.

Return type:

dict

Usage Example

from django_agents.auditors import AuditReport, CodebaseAuditor, SettingsAuditor

# Create report
report = AuditReport(output_format='markdown')

# Run auditors
codebase_auditor = CodebaseAuditor()
report.add_section('Codebase Analysis', codebase_auditor.audit())

settings_auditor = SettingsAuditor()
report.add_section('Settings & Security', settings_auditor.audit())

# Generate report
print(report.generate())

# Get summary
print(report.get_summary())