From: Scott Gasch Date: Wed, 1 Jun 2022 01:00:09 +0000 (-0700) Subject: More docs cleanup. X-Git-Url: https://wannabe.guru.org/gitweb/?a=commitdiff_plain;h=ec7c26dad2c26e4e4c33a69252654e3b1155bc7b;p=python_utils.git More docs cleanup. --- diff --git a/parallelize.py b/parallelize.py index 52eb4d1..5f1de2b 100644 --- a/parallelize.py +++ b/parallelize.py @@ -33,7 +33,7 @@ def parallelize( @parallelize(method=Method.PROCESS) def my_other_function(d, e, f) -> str: - ...do more really expensice work, e.g., a network read + ...do more really expensive work, e.g., a network read @parallelize(method=Method.REMOTE) def my_other_other_function(g, h) -> int: diff --git a/persistent.py b/persistent.py index 808f955..5801460 100644 --- a/persistent.py +++ b/persistent.py @@ -2,8 +2,8 @@ # © Copyright 2021-2022, Scott Gasch -"""A :class:Persistent is just a class with a load and save method. This -module defines the :class:Persistent base and a decorator that can be used to +"""A :class:`Persistent` is just a class with a load and save method. This +module defines the :class:`Persistent` base and a decorator that can be used to create a persistent singleton that autoloads and autosaves.""" import atexit @@ -60,7 +60,7 @@ class Persistent(ABC): def was_file_written_today(filename: str) -> bool: - """Convenience wrapper around was_file_written_within_n_seconds. + """Convenience wrapper around :meth:`was_file_written_within_n_seconds`. Args: filename: filename to check @@ -136,13 +136,13 @@ class PersistAtShutdown(enum.Enum): """ An enum to describe the conditions under which state is persisted to disk. This is passed as an argument to the decorator below and - is used to indicate when to call :meth:save on a :class:Persistent + is used to indicate when to call :meth:`save` on a :class:`Persistent` subclass. - * NEVER: never call :meth:save - * IF_NOT_LOADED: call :meth:save as long as we did not successfully - :meth:load its state. - * ALWAYS: always call :meth:save + * NEVER: never call :meth:`save` + * IF_NOT_LOADED: call :meth:`save` as long as we did not successfully + :meth:`load` its state. + * ALWAYS: always call :meth:`save` """ NEVER = (0,) @@ -151,27 +151,27 @@ class PersistAtShutdown(enum.Enum): class persistent_autoloaded_singleton(object): - """A decorator that can be applied to a :class:Persistent subclass - (i.e. a class with :meth:save and :meth:load methods. The + """A decorator that can be applied to a :class:`Persistent` subclass + (i.e. a class with :meth:`save` and :meth:`load` methods. The decorator will intercept attempts to instantiate the class via - it's c'tor and, instead, invoke the class' :meth:load to give it a + it's c'tor and, instead, invoke the class' :meth:`load` to give it a chance to read state from somewhere persistent (disk, db, whatever). Subsequent calls to construt instances of the wrapped class will return a single, global instance (i.e. the wrapped class is a singleton). - If :meth:load fails (returns None), the c'tor is invoked with the + If :meth:`load` fails (returns None), the c'tor is invoked with the original args as a fallback. Based upon the value of the optional argument :code:`persist_at_shutdown` argument, (NEVER, IF_NOT_LOADED, - ALWAYS), the :meth:save method of the class will be invoked just + ALWAYS), the :meth:`save` method of the class will be invoked just before program shutdown to give the class a chance to save its state somewhere. .. note:: - The implementations of :meth:save and :meth:load and where the - class persists its state are details left to the :class:Persistent + The implementations of :meth:`save` and :meth:`load` and where the + class persists its state are details left to the :class:`Persistent` implementation. Essentially this decorator just handles the plumbing of calling your save/load and appropriate times and creates a transparent global singleton whose state can be diff --git a/site_config.py b/site_config.py index 5604de6..eb7d884 100644 --- a/site_config.py +++ b/site_config.py @@ -34,17 +34,36 @@ class SiteConfig(object): """The set of information specific to where the program is running.""" location_name: str + """Either "HOUSE" or "CABIN" depending on where we're running""" + location: Location + """Same as above but as an enum value instead of a string""" + network: str + """The local network specification, e.g. 192.168.0.0/24.""" + network_netmask: str + """The netmask of the local network, e.g. 255.255.255.0.""" + network_router_ip: str + """The IP address of the local router, e.g. 192.168.0.1.""" + presence_location: Location + """Same as location, above.""" + is_anyone_present: Callable + """Returns a callable which, when invoked, will tell you if it detects + any person in your location by auditing network device MAC addresses.""" + arper_minimum_device_count: int + """How many MAC addresses do we need to see for it to be considered a + successful scan?""" + arper_cache_file: str + """The location of the persisted IP-MAC address mappings.""" -def get_location_name(): +def get_location_name() -> str: """ Where are we? @@ -56,7 +75,7 @@ def get_location_name(): return get_config().location_name -def get_location(): +def get_location() -> Location: """ Returns location as an enum instead of a string. @@ -69,7 +88,7 @@ def get_location(): return get_config().location -def is_anyone_present_wrapper(location: Location): +def _is_anyone_present_wrapper(location: Location): import base_presence p = base_presence.PresenceDetection() @@ -164,7 +183,7 @@ def get_config(location_override: Optional[str] = None): network_netmask='255.255.255.0', network_router_ip='10.0.0.1', presence_location=Location.HOUSE, - is_anyone_present=lambda x=Location.HOUSE: is_anyone_present_wrapper(x), + is_anyone_present=lambda x=Location.HOUSE: _is_anyone_present_wrapper(x), arper_minimum_device_count=50, arper_cache_file='/home/scott/cache/.arp_table_cache_house', ) @@ -176,7 +195,7 @@ def get_config(location_override: Optional[str] = None): network_netmask='255.255.255.0', network_router_ip='192.168.0.1', presence_location=Location.CABIN, - is_anyone_present=lambda x=Location.CABIN: is_anyone_present_wrapper(x), + is_anyone_present=lambda x=Location.CABIN: _is_anyone_present_wrapper(x), arper_minimum_device_count=15, arper_cache_file='/home/scott/cache/.arp_table_cache_cabin', ) diff --git a/smart_future.py b/smart_future.py index dbce432..c0fce3a 100644 --- a/smart_future.py +++ b/smart_future.py @@ -2,7 +2,7 @@ # © Copyright 2021-2022, Scott Gasch -"""A :class:Future that can be treated as a substutute for the result +"""A :class:`Future` that can be treated as a substutute for the result that it contains and will not block until it is used. At that point, if the underlying value is not yet available yet, it will block until the internal result actually becomes available. diff --git a/state_tracker.py b/state_tracker.py index 3e2060f..0476d1a 100644 --- a/state_tracker.py +++ b/state_tracker.py @@ -3,9 +3,9 @@ # © Copyright 2021-2022, Scott Gasch """Several helpers to keep track of internal state via periodic -polling. :class:StateTracker expects to be invoked periodically to -maintain state whereas the others (:class:AutomaticStateTracker and -:class:WaitableAutomaticStateTracker) automatically update themselves +polling. :class:`StateTracker` expects to be invoked periodically to +maintain state whereas the others (:class:`AutomaticStateTracker` and +:class:`WaitableAutomaticStateTracker`) automatically update themselves and, optionally, expose an event for client code to wait on state changes. """ @@ -73,7 +73,7 @@ class StateTracker(ABC): Args: update_id: the string you passed to the c'tor as a key in - the update_ids_to_update_secs dict. :meth:update will + the update_ids_to_update_secs dict. :meth:`update` will only be invoked on the shoulder, at most, every update_secs seconds. @@ -87,7 +87,7 @@ class StateTracker(ABC): def heartbeat(self, *, force_all_updates_to_run: bool = False) -> None: """Invoke this method to cause the StateTracker instance to identify and invoke any overdue updates based on the schedule passed to - the c'tor. In the base :class:StateTracker class, this method must + the c'tor. In the base :class:`StateTracker` class, this method must be invoked manually by a thread from external code. Other subclasses are available that create their own updater threads (see below). @@ -126,15 +126,15 @@ class StateTracker(ABC): class AutomaticStateTracker(StateTracker): - """Just like :class:StateTracker but you don't need to pump the - :meth:heartbeat method periodically because we create a background - thread that manages periodic calling. You must call :meth:shutdown, + """Just like :class:`StateTracker` but you don't need to pump the + :meth:`heartbeat` method periodically because we create a background + thread that manages periodic calling. You must call :meth:`shutdown`, though, in order to terminate the update thread. """ @background_thread def pace_maker(self, should_terminate: threading.Event) -> None: - """Entry point for a background thread to own calling :meth:heartbeat + """Entry point for a background thread to own calling :meth:`heartbeat` at regular intervals so that the main thread doesn't need to do so. """ @@ -170,7 +170,7 @@ class AutomaticStateTracker(StateTracker): override_sleep_delay: By default, this class determines how long the background thread should sleep between - automatic invocations to :meth:heartbeat based on the + automatic invocations to :meth:`heartbeat` based on the period of each update type in update_ids_to_update_secs. If this argument is non-None, it overrides this computation and uses this period as the sleep in the background thread. @@ -244,7 +244,7 @@ class WaitableAutomaticStateTracker(AutomaticStateTracker): override_sleep_delay: By default, this class determines how long the background thread should sleep between - automatic invocations to :meth:heartbeat based on the + automatic invocations to :meth:`heartbeat` based on the period of each update type in update_ids_to_update_secs. If this argument is non-None, it overrides this computation and uses this period as the sleep in the background thread. diff --git a/string_utils.py b/string_utils.py index 6ce4c50..4127079 100644 --- a/string_utils.py +++ b/string_utils.py @@ -1893,7 +1893,7 @@ def ngrams(txt: str, n: int): def ngrams_presplit(words: Sequence[str], n: int): """ - Same as :meth:ngrams but with the string pre-split. + Same as :meth:`ngrams` but with the string pre-split. """ return list_utils.ngrams(words, n) diff --git a/text_utils.py b/text_utils.py index 66c0d22..3b28968 100644 --- a/text_utils.py +++ b/text_utils.py @@ -352,7 +352,7 @@ def justify_text(text: str, *, width: int = 80, alignment: str = "c", indent_by: def generate_padded_columns(text: List[str]) -> Generator: - """Given a list of strings, break them into columns using :meth:split + """Given a list of strings, break them into columns using :meth:`split` and then compute the maximum width of each column. Finally, distribute the columular chunks into the output padding each to the proper width. diff --git a/thread_utils.py b/thread_utils.py index c4a2937..65f6037 100644 --- a/thread_utils.py +++ b/thread_utils.py @@ -133,11 +133,11 @@ def periodically_invoke( call forever Returns: - a :class:Thread object and an :class:Event that, when + a :class:`Thread` object and an :class:`Event` that, when signaled, will stop the invocations. .. note:: - It is possible to be invoked one time after the :class:Event + It is possible to be invoked one time after the :class:`Event` is set. This event can be used to stop infinite invocation style or finite invocation style decorations.