webchanges.util module

A few utilities used elsewhere.

webchanges.util.lazy_import(fullname)

Lazily imports a module. See https://stackoverflow.com/questions/42703908.

To identify loading time, run $ python -X importtime webchanges –help

Parameters:

fullname (str)

Return type:

ModuleType | None

class webchanges.util.TrackSubClasses(name, bases, namespace, **kwargs)

Bases: type

A metaclass that stores subclass name-to-class mappings in the base class.

_summary_. # TODO.

Parameters:

  • name (str) – _description_. # TODO.

  • bases (tuple[type, ...]) – _description_. # TODO.

  • namespace (dict[str, Any]) – _description_. # TODO.

  • kwargs (Any)

job_states: list[JobState]
sorted_by_kind()

Generates a list of all members of a class sorted by the value of their __kind__ attribute.

Useful for documentation.

Parameters:

cls (TrackSubClasses) – The class.

Returns:

The sorted list of class members.

Return type:

list[TrackSubClasses]

mro()

Return a type’s method resolution order.

webchanges.util.edit_file(filename)

Opens the editor to edit a file.

Parameters:

filename (str | bytes | PathLike) – The filename.

Return type:

None

webchanges.util.import_module_from_source(module_name, source_path)

Loads a module and executes it in its own namespace.

Parameters:

  • module_name (str) – The name of the module to import.

  • source_path (str | bytes | PathLike) – The path where the module is located.

Returns:

A ModuleType object.

Return type:

ModuleType

webchanges.util.chunk_string(text, length, numbering=False)

Chunks a string.

Parameters:

  • text (str) – The text to be chunked.

  • length (int) – The length of the chunked text.

  • numbering (bool) – Whether to number each chunk on the left if more than one chunk is generated.

Returns:

a list of chunked strings

Return type:

list[str]

webchanges.util.linkify(text, shorten=False, extra_params='', require_protocol=False, permitted_protocols=('http', 'https', 'mailto'))

Converts plain text into HTML with links.

For example linkify(“Hello http://tornadoweb.org!”) would return ‘Hello <a href=”http://tornadoweb.org”>http://tornadoweb.org</a>!’.

We are using a regex from tornado library https://github.com/tornadoweb/tornado/blob/master/tornado/escape.py. This regex should avoid character entities other than &amp; so that we won’t pick up &quot;, etc., but it is vulnerable to Regular expression Denial of Service (ReDoS), which would divert computational resources to an expensive regex match. The risk in this application is limited.

In the future, consider using linkify from the bleach project instead (requires importing another package).

Parameters:

  • text (str) – The text to linkify.

  • shorten (bool) – Long urls will be shortened for display.

  • extra_params (str | Callable[[str], str]) – Extra text to include in the link tag, or a callable taking the link as an argument and returning the extra text, e.g. linkify(text, extra_params=’rel=”nofollow” class=”external”’).

  • require_protocol (bool) – Only linkify urls which include a protocol; if this is False, urls such as www.facebook.com will also be linkified.

  • permitted_protocols (tuple[str, ...]) – Protocols which should be linkified, e.g. linkify(text, permitted_protocols=(‘http’, ‘ftp’, ‘mailto’)); it is very unsafe to include protocols such as javascript.

  • text

  • shorten

  • extra_params

  • require_protocol

  • permitted_protocols

Return type:

str

webchanges.util.get_new_version_number(timeout=None)

Check PyPi for newer version of project.

Parameters:

  • timeout (float | None) – Timeout in seconds after which empty string is returned.

  • timeout

Returns:

The new version number if a newer version of project is found on PyPi, empty string otherwise, False if error retrieving the new version number is encountered.

Return type:

str | bool

webchanges.util.dur_text(duration)

Returns a formatted string optimized to the number of seconds for use in footers.

Parameters:

  • duration (float) – The duration in seconds.

  • duration

Returns:

The formatted string.

Return type:

str

webchanges.util.file_ownership_checks(filename)

Check security of file and its directory.

Ensures that they belong to the current UID or root and only the owner can write to them. Return list of errors if any. Linux only.

Returns:

List of errors encountered (if any).

Parameters:

filename (Path)

Return type:

list[str]

webchanges.util.mark_to_html(text, markdown_padded_tables=False, extras=None)

Converts a line of Markdown (e.g. as generated by html2text filter) to html.

Parameters:

  • text (str) – The text in Markdown format.

  • markdown_padded_tables (bool | None) – If true, monospace the tables for alignment.

  • extras (Iterable[str] | None) – Additional extras for Markdown.

Returns:

The text in html format.

Return type:

str

webchanges.util.import_optional_dependency(name, extra='')

Import an optional dependency.

If a dependency is missing an ImportError with a nice message will be raised.

Parameters:

  • name (str) – The module name.

  • extra (str) – Additional text to include in the ImportError message.

Returns maybe_module:

The imported module, when found and the version is correct. None is returned when the package is not found.

Return type:

ModuleType