From 2fe9501bf38f9eeb02486f85060dfb253d126160 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Sun, 1 Dec 2024 18:47:38 +0100 Subject: [PATCH] [docs] Exclude common elements from components documentation. --- docs/source/conf.py | 3 ++- platypush/backend/__init__.py | 29 ++++++++++++++++++++++------- platypush/backend/http/__init__.py | 13 ++++++++----- platypush/message/__init__.py | 2 ++ platypush/plugins/__init__.py | 10 ++++++++++ 5 files changed, 44 insertions(+), 13 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c34efd82..60bdda07 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -199,7 +199,8 @@ intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} autodoc_default_options = { 'members': True, 'show-inheritance': True, - 'inherited-members': True, + # Skip these classes from the documented inheritance tree + 'inherited-members': 'threading.Thread', } sys.path.insert(0, os.path.abspath('../..')) diff --git a/platypush/backend/__init__.py b/platypush/backend/__init__.py index 4f6ec73f..8c13195e 100644 --- a/platypush/backend/__init__.py +++ b/platypush/backend/__init__.py @@ -52,11 +52,10 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): ): """ :param bus: Reference to the bus object to be used in the backend - :param poll_seconds: If the backend implements a ``loop`` method, this parameter expresses how often the - loop should run in seconds. + :param poll_seconds: If the backend implements a ``loop`` method, this + parameter expresses how often the loop should run in seconds. :param kwargs: Key-value configuration for the backend """ - self._thread_name = self.__class__.__name__ EventGenerator.__init__(self) ExtensionWithManifest.__init__(self) @@ -91,8 +90,11 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): It should be called by the derived classes whenever a new message should be processed. - :param msg: Received message. It can be either a key-value dictionary, a platypush.message.Message object, - or a string/byte UTF-8 encoded string + :param msg: Received message. It can be either a key-value dictionary, + a :class:`platypush.message.Message` object, or a string/byte UTF-8 + encoded string. + + :meta private: """ msg = Message.build(msg) @@ -292,10 +294,18 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): self.logger.info('Terminated backend %s', self.__class__.__name__) def on_stop(self): - """Callback invoked when the process stops""" + """ + Callback invoked when the process stops. + + :meta private: + """ def stop(self): - """Stops the backend thread by sending a STOP event on its bus""" + """ + Stops the backend thread by sending a STOP event on its bus. + + :meta private: + """ def _async_stop(): self._stop_event.set() @@ -310,6 +320,7 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): def should_stop(self): """ :return: True if the backend thread should be stopped, False otherwise. + :meta private: """ return self._stop_event.is_set() @@ -319,6 +330,7 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): :param timeout: The maximum time to wait for the backend thread to stop (default: None) :return: True if the backend thread has stopped, False otherwise. + :meta private: """ start = time.time() @@ -392,6 +404,7 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): "version": "{platypush_version}" } + :meta private: """ try: from zeroconf import ServiceInfo, Zeroconf @@ -447,6 +460,8 @@ class Backend(Thread, EventGenerator, ExtensionWithManifest): def unregister_service(self): """ Unregister the Zeroconf service configuration if available. + + :meta private: """ from redis import exceptions diff --git a/platypush/backend/http/__init__.py b/platypush/backend/http/__init__.py index bdc21fbf..e14eac3a 100644 --- a/platypush/backend/http/__init__.py +++ b/platypush/backend/http/__init__.py @@ -8,7 +8,7 @@ import threading from functools import partial from multiprocessing import Process from time import time -from typing import Mapping, Optional +from typing import Mapping, Optional, Union from tornado.httpserver import HTTPServer from tornado.netutil import bind_sockets, bind_unix_socket @@ -199,7 +199,7 @@ class HttpBackend(Backend): self, port: int = DEFAULT_HTTP_PORT, bind_address: Optional[str] = '0.0.0.0', - bind_socket: Optional[str] = None, + bind_socket: Optional[Union[str, bool]] = None, resource_dirs: Optional[Mapping[str, str]] = None, secret_key_file: Optional[str] = None, num_workers: Optional[int] = None, @@ -236,12 +236,11 @@ class HttpBackend(Backend): example, you are running the application on a small embedded device that doesn't support Tornado. """ - super().__init__(**kwargs) - assert ( bind_address or bind_socket ), 'Either bind_address or bind_socket must be set' + self.port = port self._server_proc: Optional[Process] = None self._service_registry_thread = None @@ -311,7 +310,11 @@ class HttpBackend(Backend): self.logger.info('HTTP server terminated') def notify_web_clients(self, event): - """Notify all the connected web clients (over websocket) of a new event""" + """ + Notify all the connected web clients (over websocket) of a new event. + + :meta private: + """ WSEventProxy.publish(event) # noqa: E1120 def _get_secret_key(self, _create=False): diff --git a/platypush/message/__init__.py b/platypush/message/__init__.py index 69c9673f..33471b37 100644 --- a/platypush/message/__init__.py +++ b/platypush/message/__init__.py @@ -33,6 +33,8 @@ class Message: """ JSON encoder that can serialize custom types commonly handled in Platypush messages. + + :meta private: """ @staticmethod diff --git a/platypush/plugins/__init__.py b/platypush/plugins/__init__.py index edb33fc5..914a5241 100644 --- a/platypush/plugins/__init__.py +++ b/platypush/plugins/__init__.py @@ -175,6 +175,8 @@ class RunnablePlugin(Plugin): def main(self): """ Implementation of the main loop of the plugin. + + :meta private: """ raise NotImplementedError() @@ -184,6 +186,8 @@ class RunnablePlugin(Plugin): def wait_stop(self, timeout=None): """ Wait until a stop event is received. + + :meta private: """ if self.disable_monitor: # Wait indefinitely if the monitor is disabled @@ -194,6 +198,8 @@ class RunnablePlugin(Plugin): def start(self): """ Start the plugin. + + :meta private: """ self._thread = threading.Thread( target=self._runner, name=self.__class__.__name__ @@ -203,6 +209,8 @@ class RunnablePlugin(Plugin): def stop(self): """ Stop the plugin. + + :meta private: """ self._should_stop.set() if ( @@ -273,6 +281,8 @@ class AsyncRunnablePlugin(RunnablePlugin, ABC): """ Main body of the async plugin. When it's called, the event loop should already be running and available over `self._loop`. + + :meta private: """ async def _listen(self):