webchanges.reporters module

Reporters.

class webchanges.reporters.XMPP(sender, recipient, insecure_password=None)

Bases: object

Parameters:

• sender (str)

• recipient (str)

• insecure_password (str | None)

async send(chunk)

Parameters:

chunk (str)

Return type:

None

class webchanges.reporters.BetweenLinesFilter(state)

Bases: FilterBase

Filter to extract lines between two patterns.

Parameters:

state (JobState) – the JobState.

filter(data, mime_type, subfilter)

Filter lines between start and end patterns.

Parameters:

• data (str | bytes)

• mime_type (str)

• subfilter (dict[str, Any])

Return type:

tuple[str | bytes, str]

classmethod auto_process(state, data, mime_type)

Processes all automatic filters (those with “MATCH” set) in JobState.Job over the data.

Parameters:

• state (JobState) – The JobState object.

• data (str | bytes) – The data to be processed (filtered).

• mime_type (str)

Returns:

The output from the chain of filters (filtered data).

Return type:

tuple[str | bytes, str]

classmethod filter_chain_needs_bytes(filter_name)

Checks whether the first filter requires data in bytes (not Unicode).

Parameters:

filter_name (str | list[str | dict[str, Any]] | None) – The filter.

Returns:

True if the first filter requires data in bytes.

Return type:

bool

classmethod filter_documentation()

Generates simple filter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

classmethod is_bytes_filter_kind(filter_kind)

Checks whether the filter requires data in bytes (not Unicode).

Parameters:

filter_kind (str) – The filter name.

Returns:

True if the filter requires data in bytes.

Return type:

bool

match()

Method used by automatch filters.

Returns:

True if an automatch filter.

Return type:

bool

classmethod normalize_filter_list(filter_spec, job_index_number=None)

Generates a list of filters that has been checked for its validity.

Parameters:

• filter_spec (str | list[str | dict[str, Any]] | None) – A list of either filter_kind, subfilter (where subfilter is a dict) or a legacy string-based filter list specification.

• job_index_number (int | None) – The job index number.

Returns:

Iterator of filter_kind, subfilter (where subfilter is a dict).

Return type:

Iterator[tuple[str, dict[str, Any]]]

classmethod process(filter_kind, subfilter, job_state, data, mime_type)

Process the filter.

Parameters:

• filter_kind (str) – The name of the filter.

• subfilter (dict[str, Any]) – The subfilter information.

• job_state (JobState) – The JobState object (containing the Job).

• data (str | bytes) – The data upon which to apply the filter.

• mime_type (str)

Returns:

The data and media type (fka MIME type) of the data after the filter has been applied.

Return type:

tuple[str | bytes, str]

raise_import_error(package_name, filter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• filter_name (str) – The name of the filter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

method: str

class webchanges.reporters.BrowserReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: HtmlReporter

Display HTML summary using the default web browser.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

submit()

Submit a job to generate the report.

Returns:

The content of the HTML report.

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

static markdown_to_html(text, markdown_padded_tables=None)

Return an html representation of a markdown string.

Parameters:

• text (str)

• markdown_padded_tables (bool | None)

Return type:

str

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

re_htags = re.compile('<(/?)h\\d>')

re_ptags = re.compile('^<p>|</p>$')

re_tagend = re.compile('<(?!.*<).*>+$')

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.DiscordReporter(*args, **kwargs)

Bases: TextReporter

Send a message to a Discord channel using a discord webhook.

Parameters:

• report – The Report object containing information about the report.

• config – The configuration of the run (typically from config.yaml).

• job_states – The list of JobState objects containing the information about the jobs that were retrieved.

• duration – The duration of the retrieval of jobs.

• jobs_files – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config – The default configuration of differs (typically from config.yaml).

• args (Any)

• kwargs (Any)

config: _ConfigReportDiscord

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

Response | None

submit_to_discord(webhook_url, text)

Parameters:

• webhook_url (str)

• text (str)

Return type:

Response

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.EMailReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Send summary via email (including SMTP).

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportEmail

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.GitHubIssueReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: MarkdownReporter

Reporter that submits reports as issues to a GitHub repository.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportGithubIssue

submit(max_length=None, **kwargs)

Submit the report to GitHub as an issue.

Parameters:

• max_length (int | None)

• kwargs (Any)

Return type:

Iterable[str]

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.GotifyReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: MarkdownReporter

Send a message to a gotify server (https://gotify.net/)

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

MAX_LENGTH = 16384

config: _ConfigReportGotify

submit(max_length=None, **kwargs)

Submit a job to generate the report in Markdown format. We use the CommonMark spec: https://spec.commonmark.org/

Parameters:

• max_length (int | None) – The maximum length of the report. Unlimited if not specified.

• kwargs (Any)

Returns:

The content of the Markdown report.

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.HtmlReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: ReporterBase

The base class for all reports using HTML.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

re_ptags = re.compile('^<p>|</p>$')

re_htags = re.compile('<(/?)h\\d>')

re_tagend = re.compile('<(?!.*<).*>+$')

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the HTML report.

Parameters:

kwargs (Any)

Return type:

Iterable[str]

static markdown_to_html(text, markdown_padded_tables=None)

Return an html representation of a markdown string.

Parameters:

• text (str)

• markdown_padded_tables (bool | None)

Return type:

str

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.IFTTTReport(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Send summary via IFTTT.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportIfttt

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.MailgunReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Send email via the Mailgun service.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportMailgun

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

str | None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.MarkdownReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: ReporterBase

The base class for all reports using Markdown.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

submit(max_length=None, **kwargs)

Submit a job to generate the report in Markdown format. We use the CommonMark spec: https://spec.commonmark.org/

Parameters:

• max_length (int | None) – The maximum length of the report. Unlimited if not specified.

• kwargs (Any)

Returns:

The content of the Markdown report.

Return type:

Iterable[str]

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.MatrixReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: MarkdownReporter

Send a message to a room using the Matrix protocol.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportMatrix

MAX_LENGTH = 16384

submit(max_length=None, **kwargs)

Submit a job to generate the report in Markdown format. We use the CommonMark spec: https://spec.commonmark.org/

Parameters:

• max_length (int | None) – The maximum length of the report. Unlimited if not specified.

• kwargs (Any)

Returns:

The content of the Markdown report.

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.NtfyReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Send messages to a ntfy server.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

config: _ConfigReportNtfy

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

class webchanges.reporters.ProwlReporter(*args, **kwargs)

Bases: TextReporter

Send a detailed notification via prowlapp.com.

Parameters:

• report – The Report object containing information about the report.

• config – The configuration of the run (typically from config.yaml).

• job_states – The list of JobState objects containing the information about the jobs that were retrieved.

• duration – The duration of the retrieval of jobs.

• jobs_files – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config – The default configuration of differs (typically from config.yaml).

• args (Any)

• kwargs (Any)

config: _ConfigReportProwl

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.PushbulletReport(report, config, job_states, duration, jobs_files, differ_config)

Bases: WebServiceReporter

Send summary via pushbullet.com.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportPushbullet

web_service_get()

Return type:

Any

web_service_submit(service, title, body)

Parameters:

• service (Any)

• title (str)

• body (str)

Return type:

None

MAX_LENGTH = 1024

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.PushoverReport(report, config, job_states, duration, jobs_files, differ_config)

Bases: WebServiceReporter

Send summary via pushover.net.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportPushover

web_service_get()

Return type:

chump.User

web_service_submit(service, title, body)

Parameters:

• service (chump.User)

• title (str)

• body (str)

Return type:

None

MAX_LENGTH = 1024

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.ReporterBase(report, config, job_states, duration, jobs_files, differ_config)

Bases: object

Base class for reporting.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

submit(**kwargs)

For the ReporterBase subclass, submit a job to generate the report.

Returns:

The content of the report.

Parameters:

kwargs (Any)

Return type:

Iterable[str]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

class webchanges.reporters.RunCommandReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Run a command.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportRunCommand

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.ShellReporter(*args, **kwargs)

Bases: WebhookReporter

Deprecated; use run_command instead.

Parameters:

• report – The Report object containing information about the report.

• config – The configuration of the run (typically from config.yaml).

• job_states – The list of JobState objects containing the information about the jobs that were retrieved.

• duration – The duration of the retrieval of jobs.

• jobs_files – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config – The default configuration of differs (typically from config.yaml).

• args (Any)

• kwargs (Any)

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

prepare_post_data(text)

Parameters:

text (str)

Return type:

dict[str, str | list[dict[str, str | list[dict[str, str | list[dict[str, str]]]]]]]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

Response | None

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

submit_to_webhook(webhook_url, text)

Parameters:

• webhook_url (str)

• text (str)

Return type:

Response

config: _ConfigReportWebhook

class webchanges.reporters.SlackReporter(*args, **kwargs)

Bases: WebhookReporter

Deprecated; use webhook instead.

Parameters:

• report – The Report object containing information about the report.

• config – The configuration of the run (typically from config.yaml).

• job_states – The list of JobState objects containing the information about the jobs that were retrieved.

• duration – The duration of the retrieval of jobs.

• jobs_files – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config – The default configuration of differs (typically from config.yaml).

• args (Any)

• kwargs (Any)

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

prepare_post_data(text)

Parameters:

text (str)

Return type:

dict[str, str | list[dict[str, str | list[dict[str, str | list[dict[str, str]]]]]]]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

Response | None

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

submit_to_webhook(webhook_url, text)

Parameters:

• webhook_url (str)

• text (str)

Return type:

Response

config: _ConfigReportWebhook

class webchanges.reporters.StdoutReporter(*args, **kwargs)

Bases: TextReporter

Print summary on stdout (the console).

Parameters:

• report – The Report object containing information about the report.

• config – The configuration of the run (typically from config.yaml).

• job_states – The list of JobState objects containing the information about the jobs that were retrieved.

• duration – The duration of the retrieval of jobs.

• jobs_files – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config – The default configuration of differs (typically from config.yaml).

• args (Any)

• kwargs (Any)

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.TelegramReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: MarkdownReporter

Send a Markdown message using Telegram.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportTelegram

submit(max_length=4096, **kwargs)

Submit report.

Parameters:

• max_length (int)

• kwargs (Any)

Return type:

None

submit_to_telegram(bot_token, chat_id, text)

Submit to Telegram.

Parameters:

• bot_token (str)

• chat_id (int | str)

• text (str)

Return type:

Response

static telegram_escape_markdown(text, version=2, entity_type=None)

Helper function to escape telegram markup symbols. See https://core.telegram.org/bots/api#formatting-options

Inspired by https://github.com/python-telegram-bot/python-telegram-bot/blob/master/telegram/utils/helpers.py v13.5 30-Apr-21

Parameters:

• text (str) – The text.

• version (int) – Use to specify the version of telegrams Markdown. Either 1 or 2. Defaults to 2.

• entity_type (str | None) – For the entity types pre, code and the link part of text_links, only certain characters need to be escaped in MarkdownV2. See the official API documentation for details. Only valid in combination with version=2, will be ignored otherwise.

Returns:

The escaped text.

Return type:

str

telegram_chunk_by_line(text, max_length)

Chunk-ify by line while escaping markdown as required by Telegram.

Parameters:

• text (str)

• max_length (int)

Return type:

list[str]

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.TextReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: ReporterBase

The base class for all reports using plain text.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

Iterable[str]

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.WebServiceReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Base class for other reporters, such as Pushover and Pushbullet.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

MAX_LENGTH = 1024

web_service_get()

Return type:

str | chump.User

web_service_submit(service, title, body)

Parameters:

• service (str | chump.User)

• title (str)

• body (str)

Return type:

None

submit(**kwargs)

Submit a job to generate the report.

Returns:

The content of the plain text report.

Parameters:

kwargs (Any)

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.WebhookReporter(*args, **kwargs)

Bases: TextReporter

Send a text message to a webhook such as Slack or Mattermost. For Mattermost, set ‘markdown’ to true.

Parameters:

• report – The Report object containing information about the report.

• config – The configuration of the run (typically from config.yaml).

• job_states – The list of JobState objects containing the information about the jobs that were retrieved.

• duration – The duration of the retrieval of jobs.

• jobs_files – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config – The default configuration of differs (typically from config.yaml).

• args (Any)

• kwargs (Any)

config: _ConfigReportWebhook

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

Response | None

submit_to_webhook(webhook_url, text)

Parameters:

• webhook_url (str)

• text (str)

Return type:

Response

prepare_post_data(text)

Parameters:

text (str)

Return type:

dict[str, str | list[dict[str, str | list[dict[str, str | list[dict[str, str]]]]]]]

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

class webchanges.reporters.XMPPReporter(report, config, job_states, duration, jobs_files, differ_config)

Bases: TextReporter

Send a message using the XMPP Protocol.

Parameters:

• report (Report) – The Report object containing information about the report.

• config (_ConfigReportersList) – The configuration of the run (typically from config.yaml).

• job_states (list[JobState]) – The list of JobState objects containing the information about the jobs that were retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The list of paths to the files containing the list of jobs (optional, used in footers).

• differ_config (_ConfigDifferDefaults) – The default configuration of differs (typically from config.yaml).

config: _ConfigReportXmpp

MAX_LENGTH = 262144

submit()

Submit a job to generate the report.

Returns:

The content of the plain text report.

Return type:

None

convert(othercls)

Convert self to a different ReporterBase class (object typecasting).

Parameters:

othercls (type[ReporterBase]) – The ReporterBase class to be cast into.

Returns:

The typecasted object.

Return type:

ReporterBase

classmethod get_base_config(report)

Gets the configuration of the base of the report (e.g. for stdout, it will be text)

Parameters:

report (Report)

Return type:

dict[str, Any]

raise_import_error(package_name, reporter_name, error_message)

Raise ImportError for missing package.

Parameters:

• package_name (str) – The name of the module/package that could not be imported.

• reporter_name (str) – The name of the reporter that needs the package.

• error_message (str) – The error message from ImportError.

Raises:

ImportError.

Return type:

None

classmethod reporter_documentation()

Generates simple reporter documentation for use in the –features command line argument.

Returns:

A string to display.

Return type:

str

subject_with_args(filtered_job_states, subject='')

Parameters:

• filtered_job_states (list[JobState])

• subject (str)

Return type:

str

classmethod submit_all(report, job_states, duration, jobs_files)

Run all (enabled) reports.

Parameters:

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

Return type:

None

classmethod submit_one(name, report, job_states, duration, jobs_files, check_enabled=True)

Run a single named report.

Parameters:

• name (str) – The name of report to run.

• report (Report) – The Report object with the information of all the reports.

• job_states (list[JobState]) – The list of JobState objects containing the information about each job retrieved.

• duration (float) – The duration of the retrieval of jobs.

• jobs_files (list[Path]) – The path(s) to the file(s) containing the list of jobs (optional, used in footers).

• check_enabled (bool | None) – Whether to check if the report is marked “enabled” in the configuration (used for testing)

Return type:

None

webchanges.reporters.get_lines_between(lines, start_pattern=None, end_pattern=None)

Yield lines between start and end patterns.

Parameters:

• lines (Sequence[str])

• start_pattern (str | None)

• end_pattern (str | None)

Return type:

Generator[str, None, None]

webchanges.reporters.xmpp_have_password(sender)

Parameters:

sender (str)

Return type:

bool

webchanges.reporters.xmpp_set_password(sender)

Set the keyring password for the XMPP connection. Interactive.

Parameters:

sender (str)

Return type:

None