From dee21ee9a071216a7cc4a4e4b536daf0973d501c Mon Sep 17 00:00:00 2001 From: Chris Mayo Date: Sat, 25 Jul 2020 16:35:48 +0100 Subject: [PATCH] Fix formatting and typos in docstrings --- linkcheck/__init__.py | 2 +- linkcheck/ansicolor.py | 2 +- linkcheck/bookmarks/firefox.py | 2 +- linkcheck/checker/__init__.py | 7 ++++--- linkcheck/checker/dnsurl.py | 2 +- linkcheck/checker/httpurl.py | 3 ++- linkcheck/checker/mailtourl.py | 3 ++- linkcheck/checker/urlbase.py | 9 +++++---- linkcheck/configuration/__init__.py | 6 ++++-- linkcheck/decorators.py | 26 +++++++++++++------------- linkcheck/director/__init__.py | 1 + linkcheck/director/interrupt.py | 3 ++- linkcheck/director/status.py | 7 ++++--- linkcheck/httputil.py | 1 + linkcheck/lc_cgi.py | 3 ++- linkcheck/loader.py | 12 ++++++++---- linkcheck/lock.py | 8 +++++--- linkcheck/logger/__init__.py | 3 ++- linkcheck/memoryutil.py | 1 + linkcheck/network/iputil.py | 3 ++- linkcheck/plugins/viruscheck.py | 5 +++-- linkcheck/url.py | 4 ++-- 22 files changed, 67 insertions(+), 46 deletions(-) diff --git a/linkcheck/__init__.py b/linkcheck/__init__.py index 9d8a3f13..ff90a465 100644 --- a/linkcheck/__init__.py +++ b/linkcheck/__init__.py @@ -14,7 +14,7 @@ # with this program; if not, write to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """ -Main function module for link checking. +Main package for link checking. """ # version checks diff --git a/linkcheck/ansicolor.py b/linkcheck/ansicolor.py index d096842c..beb1c840 100644 --- a/linkcheck/ansicolor.py +++ b/linkcheck/ansicolor.py @@ -20,7 +20,7 @@ uses ctypes and Windows DLLs to generate colored output. From Term::ANSIColor, applies also to this module: The codes output by this module are standard terminal control codes, -complying with ECMA-48 and ISO 6429 (generally referred to as ``ANSI color'' +complying with ECMA-48 and ISO 6429 (generally referred to as "ANSI color" for the color codes). The non-color control codes (bold, dark, italic, underline, and reverse) are part of the earlier ANSI X3.64 standard for control sequences for video terminals and peripherals. diff --git a/linkcheck/bookmarks/firefox.py b/linkcheck/bookmarks/firefox.py index 5d18ffff..ef70d63b 100644 --- a/linkcheck/bookmarks/firefox.py +++ b/linkcheck/bookmarks/firefox.py @@ -13,7 +13,7 @@ # You should have received a copy of the GNU General Public License along # with this program; if not, write to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. -"""Parser for FireFox bookmark file.""" +"""Parser for Firefox bookmark file.""" import re diff --git a/linkcheck/checker/__init__.py b/linkcheck/checker/__init__.py index b3c2164e..cf08f73b 100644 --- a/linkcheck/checker/__init__.py +++ b/linkcheck/checker/__init__.py @@ -28,10 +28,11 @@ MAX_FILESIZE = 1024 * 1024 * 10 # 10MB def guess_url(url): """Guess if URL is a http or ftp URL. + @param url: the URL to check - @ptype url: unicode + @type url: unicode @return: url with http:// or ftp:// prepended if it's detected as - a http respective ftp URL. + a http respective ftp URL. @rtype: unicode """ if url.lower().startswith("www."): @@ -90,7 +91,7 @@ def get_url_from( @param parent_url: parent url @type parent_url: string or None @param base_ref: base url from tag - @type base_ref string or None + @type base_ref: string or None @param line: line number @type line: number @param column: column number diff --git a/linkcheck/checker/dnsurl.py b/linkcheck/checker/dnsurl.py index 87ac8621..0921fe62 100644 --- a/linkcheck/checker/dnsurl.py +++ b/linkcheck/checker/dnsurl.py @@ -14,7 +14,7 @@ # with this program; if not, write to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """ -Handle for dns: links. +Handler for dns: links. """ import socket diff --git a/linkcheck/checker/httpurl.py b/linkcheck/checker/httpurl.py index 9984e3ef..1fde71c5 100644 --- a/linkcheck/checker/httpurl.py +++ b/linkcheck/checker/httpurl.py @@ -123,9 +123,10 @@ class HttpUrl(internpaturl.InternPatternUrl, proxysupport.ProxySupport): The first digit of the Status-Code defines the class of response. The last two digits do not have any categorization role. There are 5 values for the first digit: + - 1xx: Informational - Not used, but reserved for future use - 2xx: Success - The action was successfully received, - understood, and accepted. + understood, and accepted - 3xx: Redirection - Further action must be taken in order to complete the request - 4xx: Client Error - The request contains bad syntax or cannot diff --git a/linkcheck/checker/mailtourl.py b/linkcheck/checker/mailtourl.py index fd527f2e..512935b9 100644 --- a/linkcheck/checker/mailtourl.py +++ b/linkcheck/checker/mailtourl.py @@ -14,7 +14,7 @@ # with this program; if not, write to the Free Software Foundation, Inc., # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """ -Handle for mailto: links. +Handler for mailto: links. """ import re @@ -136,6 +136,7 @@ class MailtoUrl(urlbase.UrlBase): def check_email_syntax(self, mail): """Check email syntax. The relevant RFCs: + - How to check names (memo): https://tools.ietf.org/html/rfc3696 - Email address syntax diff --git a/linkcheck/checker/urlbase.py b/linkcheck/checker/urlbase.py index daa3135c..e52db1b5 100644 --- a/linkcheck/checker/urlbase.py +++ b/linkcheck/checker/urlbase.py @@ -61,7 +61,7 @@ def urljoin(parent, url): """ If url is relative, join parent and url. Else leave url as-is. - @return joined url + @return: joined url """ if urlutil.url_is_absolute(url): return url @@ -794,9 +794,9 @@ class UrlBase: """Get pattern for intern URL matching. @param url: the URL to set intern pattern for, else self.url - @ptype url: unicode or None - @return non-empty regex pattern or None - @rtype String or None + @type url: unicode or None + @return: non-empty regex pattern or None + @rtype: String or None """ return None @@ -843,6 +843,7 @@ class UrlBase: """Return a simplified transport object for logging and caching. The transport object must contain these attributes: + - url_data.valid: bool Indicates if URL is valid - url_data.result: unicode diff --git a/linkcheck/configuration/__init__.py b/linkcheck/configuration/__init__.py index 70a10b98..f9f1e705 100644 --- a/linkcheck/configuration/__init__.py +++ b/linkcheck/configuration/__init__.py @@ -99,10 +99,11 @@ def get_share_dir(): def get_share_file(filename, devel_dir=None): """Return a filename in the share directory. + @param devel_dir: directory to search when developing - @ptype devel_dir: string + @type devel_dir: string @param filename: filename to search for - @ptype filename: string + @type filename: string @return: the found filename or None @rtype: string @raises: ValueError if not found @@ -135,6 +136,7 @@ def get_system_cert_file(): def get_certifi_file(): """Get the SSL certifications installed by the certifi package. + @return: the filename to the cert file @rtype: string @raises: ImportError when certifi is not installed or ValueError when diff --git a/linkcheck/decorators.py b/linkcheck/decorators.py index 797c624a..399d8b85 100644 --- a/linkcheck/decorators.py +++ b/linkcheck/decorators.py @@ -16,22 +16,22 @@ """ Simple decorators (usable in Python >= 2.4). -Example: +Example:: -@synchronized(thread.allocate_lock()) -def f(): - "Synchronized function" - print("i am synchronized:", f, f.__doc__) + @synchronized(thread.allocate_lock()) + def f(): + "Synchronized function" + print("i am synchronized:", f, f.__doc__) -@deprecated -def g(): - "this function is deprecated" - pass + @deprecated + def g(): + "this function is deprecated" + pass -@notimplemented -def h(): - "todo" - pass + @notimplemented + def h(): + "todo" + pass """ import warnings diff --git a/linkcheck/director/__init__.py b/linkcheck/director/__init__.py index 342d7652..5f560007 100644 --- a/linkcheck/director/__init__.py +++ b/linkcheck/director/__init__.py @@ -27,6 +27,7 @@ from . import aggregator, console def check_urls(aggregate): """Main check function; checks all configured URLs until interrupted with Ctrl-C. + @return: None """ try: diff --git a/linkcheck/director/interrupt.py b/linkcheck/director/interrupt.py index c7e832f7..64c4edfb 100644 --- a/linkcheck/director/interrupt.py +++ b/linkcheck/director/interrupt.py @@ -29,8 +29,9 @@ class Interrupt(task.CheckedTask): def __init__(self, duration): """Initialize the task. + @param duration: raise KeyboardInterrupt after given number of seconds - @ptype duration: int + @type duration: int """ super().__init__() self.duration = duration diff --git a/linkcheck/director/status.py b/linkcheck/director/status.py index 11414dc1..7c66396b 100644 --- a/linkcheck/director/status.py +++ b/linkcheck/director/status.py @@ -23,12 +23,13 @@ class Status(task.LoggedCheckedTask): def __init__(self, aggregator, wait_seconds): """Initialize the status logger task. + @param urlqueue: the URL queue - @ptype urlqueue: Urlqueue + @type urlqueue: Urlqueue @param logger: the logger object to inform about status - @ptype logger: console.StatusLogger + @type logger: console.StatusLogger @param wait_seconds: interval in seconds to report status - @ptype wait_seconds: int + @type wait_seconds: int """ logger = aggregator.config.status_logger super().__init__(logger) diff --git a/linkcheck/httputil.py b/linkcheck/httputil.py index b4704ddf..191ed4ed 100644 --- a/linkcheck/httputil.py +++ b/linkcheck/httputil.py @@ -51,6 +51,7 @@ def asn1_generaltime_to_seconds(timestr): YYYYMMDDhhmmssZ YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm + @return: a datetime object or None on error """ res = None diff --git a/linkcheck/lc_cgi.py b/linkcheck/lc_cgi.py index 6b6857d4..a49ef4a4 100644 --- a/linkcheck/lc_cgi.py +++ b/linkcheck/lc_cgi.py @@ -254,8 +254,9 @@ def dump(env, form): def format_error(why): """Format standard error page. + @param why: error message - @ptype why: unicode + @type why: unicode @return: HTML page content @rtype: unicode """ diff --git a/linkcheck/loader.py b/linkcheck/loader.py index 75e2ab51..a140df77 100644 --- a/linkcheck/loader.py +++ b/linkcheck/loader.py @@ -2,7 +2,8 @@ """ Functions to load plugin modules. -Example usage: +Example usage:: + modules = loader.get_package_modules('plugins') plugins = loader.get_plugins(modules, PluginClass) """ @@ -33,6 +34,7 @@ def get_package_modules(packagename): """Find all valid modules in the given package which must be a folder in the same directory as this loader.py module. A valid module has a .py extension, and is importable. + @return: all loaded valid modules @rtype: iterator of module """ @@ -75,7 +77,8 @@ def get_folder_modules(folder, parentpackage): def get_importable_files(folder): """Find all module files in the given folder that end with '.py' and don't start with an underscore. - @return module names + + @return: module names @rtype: iterator of string """ for fname in os.listdir(folder): @@ -92,10 +95,11 @@ def get_importable_files(folder): def get_plugins(modules, classes): """Find all given (sub-)classes in all modules. + @param modules: the modules to search - @ptype modules: iterator of modules + @type modules: iterator of modules @return: found classes - @rytpe: iterator of class objects + @rtype: iterator of class objects """ for module in modules: for plugin in get_module_plugins(module, classes): diff --git a/linkcheck/lock.py b/linkcheck/lock.py index 80963cf5..1f17ca14 100644 --- a/linkcheck/lock.py +++ b/linkcheck/lock.py @@ -22,8 +22,9 @@ from . import log, LOG_THREAD def get_lock(name, debug=False): """Get a new lock. + @param debug: if True, acquire() and release() will have debug messages - @ptype debug: boolean, default is False + @type debug: boolean, default is False @return: a lock object @rtype: threading.Lock or DebugLock """ @@ -58,10 +59,11 @@ class DebugLock: def get_semaphore(name, value=None, debug=False): """Get a new semaphore. + @param value: if not None, a BoundedSemaphore will be used - @ptype debug: int or None + @type debug: int or None @param debug: if True, acquire() and release() will have debug messages - @ptype debug: boolean, default is False + @type debug: boolean, default is False @return: a semaphore object @rtype: threading.Semaphore or threading.BoundedSemaphore or DebugLock """ diff --git a/linkcheck/logger/__init__.py b/linkcheck/logger/__init__.py index c00d5e34..6fe43492 100644 --- a/linkcheck/logger/__init__.py +++ b/linkcheck/logger/__init__.py @@ -446,8 +446,9 @@ class _Logger(abc.ABC): def format_modified(self, modified, sep=" "): """Format modification date in UTC if it's not None. + @param modified: modification date in UTC - @ptype modified: datetime or None + @type modified: datetime or None @return: formatted date or empty string @rtype: unicode """ diff --git a/linkcheck/memoryutil.py b/linkcheck/memoryutil.py index e86bb588..43df45dc 100644 --- a/linkcheck/memoryutil.py +++ b/linkcheck/memoryutil.py @@ -29,6 +29,7 @@ MemoryDebugMsg = strformat.format_feature_warning( def write_memory_dump(): """Dump memory to a temporary filename with the meliae package. + @return: JSON filename where memory dump has been written to @rtype: string """ diff --git a/linkcheck/network/iputil.py b/linkcheck/network/iputil.py index fd4fa583..16386fbe 100644 --- a/linkcheck/network/iputil.py +++ b/linkcheck/network/iputil.py @@ -36,8 +36,9 @@ def is_valid_ip(ip): def resolve_host(host): """ - @host: hostname or IP address Return list of ip numbers for given host. + + @param host: hostname or IP address """ ips = [] try: diff --git a/linkcheck/plugins/viruscheck.py b/linkcheck/plugins/viruscheck.py index 60be7439..d034f555 100644 --- a/linkcheck/plugins/viruscheck.py +++ b/linkcheck/plugins/viruscheck.py @@ -219,8 +219,9 @@ class ClamavConfig(dict): def scan(data, clamconf): """Scan data for viruses. - @return (infection msgs, errors) - @rtype ([], []) + + @return: (infection msgs, errors) + @rtype: ([], []) """ try: scanner = ClamdScanner(clamconf) diff --git a/linkcheck/url.py b/linkcheck/url.py index eb8fc171..7b3884c1 100644 --- a/linkcheck/url.py +++ b/linkcheck/url.py @@ -493,9 +493,9 @@ def splitport(host, port=0): the given default port is returned. @param host: host name - @ptype host: string + @type host: string @param port: the port number (default 0) - @ptype port: int + @type port: int @return: tuple of (host, port) @rtype: tuple of (string, int)