[tor-commits] [stem/master] Implement setting docstrings of `stem.control.Controller` methods

atagar at torproject.org atagar at torproject.org
Thu Jul 16 01:28:59 UTC 2020 

commit 26d2222480d6b10ef57097c9f40e44112408d1c1
Author: Illia Volochii <illia.volochii at gmail.com>
Date:   Sun May 17 20:10:22 2020 +0300

    Implement setting docstrings of `stem.control.Controller` methods
---
 stem/control.py | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 78 insertions(+), 2 deletions(-)

diff --git a/stem/control.py b/stem/control.py
index bdcdfb75..6e15c16c 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -3861,7 +3861,18 @@ class AsyncController(BaseController):
     return (set_events, failed_events)
 
 
+def _set_doc_from_async_controller(func: Callable) -> Callable:
+  func.__doc__ = getattr(AsyncController, func.__name__).__doc__
+  return func
+
+
 class Controller(_BaseControllerSocketMixin, stem.util.AsyncClassWrapper):
+  """
+  Connection with Tor's control socket. This wraps
+  :class:`~stem.control.AsyncController` to provide a synchronous
+  interface and for backwards compatibility.
+  """
+
   @classmethod
   def from_port(cls: Type, address: str = '127.0.0.1', port: Union[int, str] = 'default') -> 'stem.control.Controller':
     """
@@ -3915,198 +3926,263 @@ class Controller(_BaseControllerSocketMixin, stem.util.AsyncClassWrapper):
     self._wrapped_instance: AsyncController = self._init_async_class(AsyncController, control_socket, is_authenticated)
     self._socket = self._wrapped_instance._socket
 
+  @_set_doc_from_async_controller
   def msg(self, message: str) -> stem.response.ControlMessage:
     return self._execute_async_method('msg', message)
 
+  @_set_doc_from_async_controller
   def is_authenticated(self) -> bool:
     return self._wrapped_instance.is_authenticated()
 
+  @_set_doc_from_async_controller
   def connect(self) -> None:
     self._execute_async_method('connect')
 
+  @_set_doc_from_async_controller
   def reconnect(self, *args: Any, **kwargs: Any) -> None:
     self._execute_async_method('reconnect', *args, **kwargs)
 
+  @_set_doc_from_async_controller
   def close(self) -> None:
     self._execute_async_method('close')
 
+  @_set_doc_from_async_controller
   def get_latest_heartbeat(self) -> float:
     return self._wrapped_instance.get_latest_heartbeat()
 
+  @_set_doc_from_async_controller
   def add_status_listener(self, callback: Callable[['stem.control.BaseController', 'stem.control.State', float], None], spawn: bool = True) -> None:
     self._wrapped_instance.add_status_listener(callback, spawn)
 
+  @_set_doc_from_async_controller
   def remove_status_listener(self, callback: Callable[['stem.control.Controller', 'stem.control.State', float], None]) -> bool:
     self._wrapped_instance.remove_status_listener(callback)
 
+  @_set_doc_from_async_controller
   def authenticate(self, *args: Any, **kwargs: Any) -> None:
     self._execute_async_method('authenticate', *args, **kwargs)
 
+  @_set_doc_from_async_controller
   def get_info(self, params: Union[str, Sequence[str]], default: Any = UNDEFINED, get_bytes: bool = False) -> Union[str, Dict[str, str]]:
     return self._execute_async_method('get_info', params, default, get_bytes)
 
+  @_set_doc_from_async_controller
   def get_version(self, default: Any = UNDEFINED) -> stem.version.Version:
     return self._execute_async_method('get_version', default)
 
+  @_set_doc_from_async_controller
   def get_exit_policy(self, default: Any = UNDEFINED) -> stem.exit_policy.ExitPolicy:
     return self._execute_async_method('get_exit_policy', default)
 
+  @_set_doc_from_async_controller
   def get_ports(self, listener_type: 'stem.control.Listener', default: Any = UNDEFINED) -> Sequence[int]:
     return self._execute_async_method('get_ports', listener_type, default)
 
+  @_set_doc_from_async_controller
   def get_listeners(self, listener_type: 'stem.control.Listener', default: Any = UNDEFINED) -> Sequence[Tuple[str, int]]:
     return self._execute_async_method('get_listeners', listener_type, default)
 
+  @_set_doc_from_async_controller
   def get_accounting_stats(self, default: Any = UNDEFINED) -> 'stem.control.AccountingStats':
     return self._execute_async_method('get_accounting_stats', default)
 
+  @_set_doc_from_async_controller
   def get_protocolinfo(self, default: Any = UNDEFINED) -> stem.response.protocolinfo.ProtocolInfoResponse:
     return self._execute_async_method('get_protocolinfo', default)
 
+  @_set_doc_from_async_controller
   def get_user(self, default: Any = UNDEFINED) -> str:
     return self._execute_async_method('get_user', default)
 
+  @_set_doc_from_async_controller
   def get_pid(self, default: Any = UNDEFINED) -> int:
     return self._execute_async_method('get_pid', default)
 
+  @_set_doc_from_async_controller
   def get_start_time(self, default: Any = UNDEFINED) -> float:
     return self._execute_async_method('get_start_time', default)
 
+  @_set_doc_from_async_controller
   def get_uptime(self, default: Any = UNDEFINED) -> float:
     return self._execute_async_method('get_uptime', default)
 
+  @_set_doc_from_async_controller
   def is_user_traffic_allowed(self) -> 'stem.control.UserTrafficAllowed':
     return self._execute_async_method('is_user_traffic_allowed')
 
+  @_set_doc_from_async_controller
   def get_microdescriptor(self, relay: Optional[str] = None, default: Any = UNDEFINED) -> stem.descriptor.microdescriptor.Microdescriptor:
     return self._execute_async_method('get_microdescriptor', relay, default)
 
+  @_set_doc_from_async_controller
   def get_microdescriptors(self, default: Any = UNDEFINED) -> Iterator[stem.descriptor.microdescriptor.Microdescriptor]:
     return self._execute_async_generator_method('get_microdescriptors', default)
 
+  @_set_doc_from_async_controller
   def get_server_descriptor(self, relay: Optional[str] = None, default: Any = UNDEFINED) -> stem.descriptor.server_descriptor.RelayDescriptor:
     return self._execute_async_method('get_server_descriptor', relay, default)
 
+  @_set_doc_from_async_controller
   def get_server_descriptors(self, default: Any = UNDEFINED) -> Iterator[stem.descriptor.server_descriptor.RelayDescriptor]:
     return self._execute_async_generator_method('get_server_descriptors', default)
 
+  @_set_doc_from_async_controller
   def get_network_status(self, relay: Optional[str] = None, default: Any = UNDEFINED) -> stem.descriptor.router_status_entry.RouterStatusEntryV3:
     return self._execute_async_method('get_network_status', relay, default)
 
+  @_set_doc_from_async_controller
   def get_network_statuses(self, default: Any = UNDEFINED) -> Iterator[stem.descriptor.router_status_entry.RouterStatusEntryV3]:
     return self._execute_async_generator_method('get_network_statuses', default)
 
+  @_set_doc_from_async_controller
   def get_hidden_service_descriptor(self, address: str, default: Any = UNDEFINED, servers: Optional[Sequence[str]] = None, await_result: bool = True, timeout: Optional[float] = None) -> stem.descriptor.hidden_service.HiddenServiceDescriptorV2:
     return self._execute_async_method('get_hidden_service_descriptor', address, default, servers, await_result, timeout)
 
+  @_set_doc_from_async_controller
   def get_conf(self, param: str, default: Any = UNDEFINED, multiple: bool = False) -> Union[str, Sequence[str]]:
     return self._execute_async_method('get_conf', param, default, multiple)
 
+  @_set_doc_from_async_controller
   def get_conf_map(self, params: Union[str, Sequence[str]], default: Any = UNDEFINED, multiple: bool = True) -> Dict[str, Union[str, Sequence[str]]]:
     return self._execute_async_method('get_conf_map', params, default, multiple)
 
+  @_set_doc_from_async_controller
   def is_set(self, param: str, default: Any = UNDEFINED) -> bool:
     return self._execute_async_method('is_set', param, default)
 
+  @_set_doc_from_async_controller
   def set_conf(self, param: str, value: Union[str, Sequence[str]]) -> None:
     self._execute_async_method('set_conf', param, value)
 
+  @_set_doc_from_async_controller
   def reset_conf(self, *params: str) -> None:
     self._execute_async_method('reset_conf', *params)
 
+  @_set_doc_from_async_controller
   def set_options(self, params: Union[Mapping[str, Union[str, Sequence[str]]], Sequence[Tuple[str, Union[str, Sequence[str]]]]], reset: bool = False) -> None:
     self._execute_async_method('set_options', params, reset)
 
+  @_set_doc_from_async_controller
   def get_hidden_service_conf(self, default: Any = UNDEFINED) -> Dict[str, Any]:
     return self._execute_async_method('get_hidden_service_conf', default)
 
+  @_set_doc_from_async_controller
   def set_hidden_service_conf(self, conf: Mapping[str, Any]) -> None:
     self._execute_async_method('set_hidden_service_conf', conf)
 
+  @_set_doc_from_async_controller
   def create_hidden_service(self, path: str, port: int, target_address: Optional[str] = None, target_port: Optional[int] = None, auth_type: Optional[str] = None, client_names: Optional[Sequence[str]] = None) -> 'stem.control.CreateHiddenServiceOutput':
     return self._execute_async_method('create_hidden_service', path, port, target_address, target_port, auth_type, client_names)
 
+  @_set_doc_from_async_controller
   def remove_hidden_service(self, path: str, port: Optional[int] = None) -> bool:
     return self._execute_async_method('remove_hidden_service', path, port)
 
+  @_set_doc_from_async_controller
   def list_ephemeral_hidden_services(self, default: Any = UNDEFINED, our_services: bool = True, detached: bool = False) -> Sequence[str]:
     return self._execute_async_method('list_ephemeral_hidden_services', default, our_services, detached)
 
+  @_set_doc_from_async_controller
   def create_ephemeral_hidden_service(self, ports: Union[int, Sequence[int], Mapping[int, str]], key_type: str = 'NEW', key_content: str = 'BEST', discard_key: bool = False, detached: bool = False, await_publication: bool = False, timeout: Optional[float] = None, basic_auth: Optional[Mapping[str, str]] = None, max_streams: Optional[int] = None) -> stem.response.add_onion.AddOnionResponse:
     return self._execute_async_method('create_ephemeral_hidden_service', ports, key_type, key_content, discard_key, detached, await_publication, timeout, basic_auth, max_streams)
 
+  @_set_doc_from_async_controller
   def remove_ephemeral_hidden_service(self, service_id: str) -> bool:
     return self._execute_async_method('remove_ephemeral_hidden_service', service_id)
 
-  def add_event_listener(self, listener: Callable[[stem.response.events.Event], None], *events: 'stem.control.EventType') -> None:
+  @_set_doc_from_async_controller
+  def add_event_listener(self, listener: Callable[[stem.response.events.Event], Union[None, Awaitable[None]]], *events: 'stem.control.EventType') -> None:
     self._execute_async_method('add_event_listener', listener, *events)
 
-  def remove_event_listener(self, listener: Callable[[stem.response.events.Event], None]) -> None:
+  @_set_doc_from_async_controller
+  def remove_event_listener(self, listener: Callable[[stem.response.events.Event], Union[None, Awaitable[None]]]) -> None:
     self._execute_async_method('remove_event_listener', listener)
 
+  @_set_doc_from_async_controller
   def is_caching_enabled(self) -> bool:
     return self._wrapped_instance.is_caching_enabled()
 
+  @_set_doc_from_async_controller
   def set_caching(self, enabled: bool) -> None:
     self._wrapped_instance.set_caching(enabled)
 
+  @_set_doc_from_async_controller
   def clear_cache(self) -> None:
     self._wrapped_instance.clear_cache()
 
+  @_set_doc_from_async_controller
   def load_conf(self, configtext: str) -> None:
     self._execute_async_method('load_conf', configtext)
 
+  @_set_doc_from_async_controller
   def save_conf(self, force: bool = False) -> None:
     return self._execute_async_method('save_conf', force)
 
+  @_set_doc_from_async_controller
   def is_feature_enabled(self, feature: str) -> bool:
     return self._wrapped_instance.is_feature_enabled(feature)
 
+  @_set_doc_from_async_controller
   def enable_feature(self, features: Union[str, Sequence[str]]) -> None:
     self._wrapped_instance.enable_feature(features)
 
+  @_set_doc_from_async_controller
   def get_circuit(self, circuit_id: int, default: Any = UNDEFINED) -> stem.response.events.CircuitEvent:
     return self._execute_async_method('get_circuit', circuit_id, default)
 
+  @_set_doc_from_async_controller
   def get_circuits(self, default: Any = UNDEFINED) -> List[stem.response.events.CircuitEvent]:
     return self._execute_async_method('get_circuits', default)
 
+  @_set_doc_from_async_controller
   def new_circuit(self, path: Union[None, str, Sequence[str]] = None, purpose: str = 'general', await_build: bool = False, timeout: Optional[float] = None) -> str:
     return self._execute_async_method('new_circuit', path, purpose, await_build, timeout)
 
+  @_set_doc_from_async_controller
   def extend_circuit(self, circuit_id: str = '0', path: Union[None, str, Sequence[str]] = None, purpose: str = 'general', await_build: bool = False, timeout: Optional[float] = None) -> str:
     return self._execute_async_method('extend_circuit', circuit_id, path, purpose, await_build, timeout)
 
+  @_set_doc_from_async_controller
   def repurpose_circuit(self, circuit_id: str, purpose: str) -> None:
     self._execute_async_method('repurpose_circuit', circuit_id, purpose)
 
+  @_set_doc_from_async_controller
   def close_circuit(self, circuit_id: str, flag: str = '') -> None:
     self._execute_async_method('close_circuit', circuit_id, flag)
 
+  @_set_doc_from_async_controller
   def get_streams(self, default: Any = UNDEFINED) -> List[stem.response.events.StreamEvent]:
     return self._execute_async_method('get_streams', default)
 
+  @_set_doc_from_async_controller
   def attach_stream(self, stream_id: str, circuit_id: str, exiting_hop: Optional[int] = None) -> None:
     self._execute_async_method('attach_stream', stream_id, circuit_id, exiting_hop)
 
+  @_set_doc_from_async_controller
   def close_stream(self, stream_id: str, reason: stem.RelayEndReason = stem.RelayEndReason.MISC, flag: str = '') -> None:
     self._execute_async_method('close_stream', stream_id, reason, flag)
 
+  @_set_doc_from_async_controller
   def signal(self, signal: stem.Signal) -> None:
     self._execute_async_method('signal', signal)
 
+  @_set_doc_from_async_controller
   def is_newnym_available(self) -> bool:
     return self._wrapped_instance.is_newnym_available()
 
+  @_set_doc_from_async_controller
   def get_newnym_wait(self) -> float:
     return self._wrapped_instance.get_newnym_wait()
 
+  @_set_doc_from_async_controller
   def get_effective_rate(self, default: Any = UNDEFINED, burst: bool = False) -> int:
     return self._execute_async_method('get_effective_rate', default, burst)
 
+  @_set_doc_from_async_controller
   def map_address(self, mapping: Mapping[str, str]) -> Dict[str, str]:
     return self._execute_async_method('map_address', mapping)
 
+  @_set_doc_from_async_controller
   def drop_guards(self) -> None:
     self._execute_async_method('drop_guards')

More information about the tor-commits mailing list