[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] Implement setting docstrings of `stem.control.Controller` methods
commit 26d2222480d6b10ef57097c9f40e44112408d1c1
Author: Illia Volochii <illia.volochii@xxxxxxxxx>
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')
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits