This is an automated email from the ASF dual-hosted git repository. jdanek pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/qpid-proton.git
The following commit(s) were added to refs/heads/main by this push: new 22933cb PROTON-2407 [python] fix type-related documentation comments (#332) 22933cb is described below commit 22933cb26252d134a0ff42f5213ea64f73d0c43f Author: Jiri Daněk <jda...@redhat.com> AuthorDate: Fri Aug 27 14:14:20 2021 +0200 PROTON-2407 [python] fix type-related documentation comments (#332) --- python/proton/_data.py | 19 +++++++------------ python/proton/_delivery.py | 23 ++++++----------------- python/proton/_endpoints.py | 9 ++------- python/proton/_events.py | 16 +++++----------- python/proton/_handlers.py | 33 +++++++++++---------------------- python/proton/_reactor.py | 2 +- python/proton/_transport.py | 8 ++++---- python/proton/_utils.py | 5 +++-- 8 files changed, 39 insertions(+), 76 deletions(-) diff --git a/python/proton/_data.py b/python/proton/_data.py index f88cec5..43c0d76 100644 --- a/python/proton/_data.py +++ b/python/proton/_data.py @@ -791,12 +791,11 @@ class Data: """ return pn_data_encoded_size(self._data) - def encode(self): + def encode(self) -> bytes: """ - Returns a representation of the data encoded in AMQP format. + Returns a binary representation of the data encoded in AMQP format. - :return: The size of the encoded data - :rtype: ``int`` + :return: The encoded data :raise: :exc:`DataException` if there is a Proton error. """ size = 1024 @@ -809,12 +808,11 @@ class Data: else: self._check(cd) - def decode(self, encoded): + def decode(self, encoded: bytes) -> int: """ Decodes the first value from supplied AMQP data and returns the number of bytes consumed. - :type encoded: binary :param encoded: AMQP encoded binary data :raise: :exc:`DataException` if there is a Proton error. """ @@ -878,9 +876,7 @@ class Data: >>> data.put_double(1.3) >>> data.exit() - :type described: bool :param described: specifies whether the array is described - :type element_type: int :param element_type: the type of the array elements :raise: :exc:`DataException` if there is a Proton error. """ @@ -1158,7 +1154,7 @@ class Data: """ return pn_data_get_map(self._data) - def get_array(self): + def get_array(self) -> Tuple[int, bool, Optional[int]]: """ If the current node is an array, return a tuple of the element count, a boolean indicating whether the array is described, and @@ -1175,9 +1171,8 @@ class Data: ... print "Element:", data.get_string() >>> data.exit() - :return: A tuple containing the number of array elements, the descriptor - (or ``None`` if no descriptor) and the enumerated array element type. - :rtype: ``tuple`` (``int``, ``str`` or ``None``, ``int``) + :return: A tuple containing the number of array elements, a bool indicating + whether the array is described, and the enumerated array element type. """ count = pn_data_get_array(self._data) described = pn_data_is_array_described(self._data) diff --git a/python/proton/_delivery.py b/python/proton/_delivery.py index 3fe9875..fa793c8 100644 --- a/python/proton/_delivery.py +++ b/python/proton/_delivery.py @@ -38,7 +38,7 @@ if TYPE_CHECKING: class NamedInt(int): - values: Dict[int, str] = {} + values: Dict[int, 'DispositionType'] = {} def __new__(cls: Type['DispositionType'], i: int, name: str) -> 'DispositionType': ni = super(NamedInt, cls).__new__(cls, i) @@ -119,7 +119,7 @@ class Disposition(object): self._annotations = None @property - def type(self): + def type(self) -> Union[int, DispositionType]: """ Get the type of this disposition object. @@ -130,8 +130,6 @@ class Disposition(object): * :const:`REJECTED` * :const:`RELEASED` * :const:`MODIFIED` - - :type: ``str`` """ return DispositionType.get(pn_disposition_type(self._impl)) @@ -379,22 +377,13 @@ class Delivery(Wrapper): return pn_delivery_partial(self._impl) @property - def local_state(self): - """ - A string representation of the local state of the delivery. - - :type: ``str`` - """ + def local_state(self) -> DispositionType: + """A local state of the delivery.""" return DispositionType.get(pn_delivery_local_state(self._impl)) @property - def remote_state(self): - """ - A string representation of the state of the delivery as - indicated by the remote peer. - - :type: ``str`` - """ + def remote_state(self) -> Union[int, DispositionType]: + """A remote state of the delivery as indicated by the remote peer.""" return DispositionType.get(pn_delivery_remote_state(self._impl)) @property diff --git a/python/proton/_endpoints.py b/python/proton/_endpoints.py index 3c8d8ed..a427d74 100644 --- a/python/proton/_endpoints.py +++ b/python/proton/_endpoints.py @@ -301,8 +301,6 @@ class Connection(Wrapper, Endpoint): Any (non ``None``) name returned by this operation will be valid until the connection object is unbound from a transport or freed, whichever happens sooner. - - :type: ``str`` """ return pn_connection_remote_container(self._impl) @@ -1203,11 +1201,8 @@ class Sender(Link): # treat object as bytes return self.stream(obj) - def delivery_tag(self): - """ - **HELP!** I have no idea what is going on with this! - :meth:`Link.next` returns a Link, not a Delivery. - """ + def delivery_tag(self) -> str: + """Increments and returns a counter to be used as the next message tag.""" if not hasattr(self, 'tag_generator'): def simple_tags(): count = 1 diff --git a/python/proton/_events.py b/python/proton/_events.py index edc34e3..d05c819 100644 --- a/python/proton/_events.py +++ b/python/proton/_events.py @@ -136,12 +136,8 @@ class EventBase(object): self._type = type @property - def type(self): - """ - The type name for this event - - :type: ``str`` - """ + def type(self) -> EventType: + """The type of this event.""" return self._type @property @@ -153,15 +149,13 @@ class EventBase(object): """ return None - def dispatch(self, handler, type=None): + def dispatch(self, handler: 'Handler', type: Optional[EventType] = None) -> None: """ Process this event by sending it to all known handlers that are valid for this event type. :param handler: Parent handler to process this event - :type handler: :class:`Handler` :param type: Event type - :type type: :class:`EventType` """ type = type or self._type _dispatch(handler, type.method, self) @@ -581,7 +575,7 @@ class Event(EventBase): """ The sender link associated with the event, or ``None`` if none is associated with it. This is essentially an alias for - link(), that does an additional check on the type of the + ``link`` property, that does an additional check on the type of the link. """ l = self.link @@ -595,7 +589,7 @@ class Event(EventBase): """ The receiver link associated with the event, or ``None`` if none is associated with it. This is essentially an alias for - link(), that does an additional check on the type of the link. + ``link`` property, that does an additional check on the type of the link. """ l = self.link if l and l.is_receiver: diff --git a/python/proton/_handlers.py b/python/proton/_handlers.py index 7ec1c6b..1a7849c 100644 --- a/python/proton/_handlers.py +++ b/python/proton/_handlers.py @@ -322,74 +322,64 @@ class EndpointStateHandler(Handler): self.peer_close_is_error = peer_close_is_error @classmethod - def is_local_open(cls, endpoint): + def is_local_open(cls, endpoint: Endpoint) -> bool: """ Test if local ``endpoint`` is open (ie has state :const:`proton.Endpoint.LOCAL_ACTIVE`). :param endpoint: The local endpoint to be tested. - :type endpoint: Any child of :class:`proton.Endpoint` :return: ``True`` if local endpoint is in state :const:`proton.Endpoint.LOCAL_ACTIVE`, ``False`` otherwise. - :rtype: ``bool`` """ - return endpoint.state & Endpoint.LOCAL_ACTIVE + return bool(endpoint.state & Endpoint.LOCAL_ACTIVE) @classmethod - def is_local_uninitialised(cls, endpoint): + def is_local_uninitialised(cls, endpoint: Endpoint) -> bool: """ Test if local ``endpoint`` is uninitialised (ie has state :const:`proton.Endpoint.LOCAL_UNINIT`). :param endpoint: The local endpoint to be tested. - :type endpoint: Any child of :class:`proton.Endpoint` :return: ``True`` if local endpoint is in state :const:`proton.Endpoint.LOCAL_UNINIT`, ``False`` otherwise. - :rtype: ``bool`` """ - return endpoint.state & Endpoint.LOCAL_UNINIT + return bool(endpoint.state & Endpoint.LOCAL_UNINIT) @classmethod - def is_local_closed(cls, endpoint): + def is_local_closed(cls, endpoint: Endpoint) -> bool: """ Test if local ``endpoint`` is closed (ie has state :const:`proton.Endpoint.LOCAL_CLOSED`). :param endpoint: The local endpoint to be tested. - :type endpoint: Any child of :class:`proton.Endpoint` :return: ``True`` if local endpoint is in state :const:`proton.Endpoint.LOCAL_CLOSED`, ``False`` otherwise. - :rtype: ``bool`` """ - return endpoint.state & Endpoint.LOCAL_CLOSED + return bool(endpoint.state & Endpoint.LOCAL_CLOSED) @classmethod - def is_remote_open(cls, endpoint): + def is_remote_open(cls, endpoint: Endpoint) -> bool: """ - Test if remote ``enpoint`` is open (ie has state + Test if remote ``endpoint`` is open (ie has state :const:`proton.Endpoint.LOCAL_ACTIVE`). :param endpoint: The remote endpoint to be tested. - :type endpoint: Any child of :class:`proton.Endpoint` :return: ``True`` if remote endpoint is in state :const:`proton.Endpoint.LOCAL_ACTIVE`, ``False`` otherwise. - :rtype: ``bool`` """ - return endpoint.state & Endpoint.REMOTE_ACTIVE + return bool(endpoint.state & Endpoint.REMOTE_ACTIVE) @classmethod - def is_remote_closed(cls, endpoint): + def is_remote_closed(cls, endpoint: Endpoint) -> bool: """ Test if remote ``endpoint`` is closed (ie has state :const:`proton.Endpoint.REMOTE_CLOSED`). :param endpoint: The remote endpoint to be tested. - :type endpoint: Any child of :class:`proton.Endpoint` :return: ``True`` if remote endpoint is in state :const:`proton.Endpoint.REMOTE_CLOSED`, ``False`` otherwise. - :rtype: ``bool`` """ - return endpoint.state & Endpoint.REMOTE_CLOSED + return bool(endpoint.state & Endpoint.REMOTE_CLOSED) @classmethod def print_error(cls, endpoint: Endpoint, endpoint_type: str) -> None: @@ -476,7 +466,6 @@ class EndpointStateHandler(Handler): :param event: The underlying event object. Use this to obtain further information on the event. - :type event: :class:`proton.Event` """ if self.delegate is not None: _dispatch(self.delegate, 'on_connection_opened', event) diff --git a/python/proton/_reactor.py b/python/proton/_reactor.py index a71328f..ec01deb 100644 --- a/python/proton/_reactor.py +++ b/python/proton/_reactor.py @@ -1400,7 +1400,7 @@ class Container(Reactor): def _get_id(self, container: str, remote: Optional[str], local: Optional[str]) -> str: if local and remote: - "%s-%s-%s" % (container, remote, local) + return "%s-%s-%s" % (container, remote, local) elif local: return "%s-%s" % (container, local) elif remote: diff --git a/python/proton/_transport.py b/python/proton/_transport.py index be90b23..89a18f6 100644 --- a/python/proton/_transport.py +++ b/python/proton/_transport.py @@ -550,7 +550,7 @@ class SASL(Wrapper): return err @property - def user(self): + def user(self) -> Optional[str]: """ Retrieve the authenticated user. This is usually used at the the server end to find the name of the authenticated user. @@ -559,7 +559,7 @@ class SASL(Wrapper): there will be no user to return. The returned value is only reliable after the ``PN_TRANSPORT_AUTHENTICATED`` event has been received. - :rtype: * If the SASL layer was not negotiated then ``0`` is returned. + :rtype: * If the SASL layer was not negotiated then ``None`` is returned. * If the ``ANONYMOUS`` mechanism is used then the user will be ``"anonymous"``. * Otherwise a string containing the user is @@ -568,7 +568,7 @@ class SASL(Wrapper): return pn_sasl_get_user(self._sasl) @property - def authorization(self): + def authorization(self) -> Optional[str]: """ Retrieve the requested authorization user. This is usually used at the the server end to find the name of any requested authorization user. @@ -584,7 +584,7 @@ class SASL(Wrapper): there will be no user to return. The returned value is only reliable after the ``PN_TRANSPORT_AUTHENTICATED`` event has been received. - :rtype: * If the SASL layer was not negotiated then ``0`` is returned. + :rtype: * If the SASL layer was not negotiated then ``None`` is returned. * If the ``ANONYMOUS`` mechanism is used then the user will be ``"anonymous"``. * Otherwise a string containing the user is diff --git a/python/proton/_utils.py b/python/proton/_utils.py index bdc1b34..1d24741 100644 --- a/python/proton/_utils.py +++ b/python/proton/_utils.py @@ -30,7 +30,8 @@ from ._url import Url from ._reactor import Container from ._handlers import MessagingHandler, IncomingMessageHandler -from typing import Callable, Optional, Union, TYPE_CHECKING, List +from typing import Callable, Optional, Union, TYPE_CHECKING, List, Any + try: from typing import Literal except ImportError: @@ -83,7 +84,7 @@ class BlockingLink: msg="Closing link %s" % self.link.name) # Access to other link attributes. - def __getattr__(self, name): + def __getattr__(self, name: str) -> Any: return getattr(self.link, name) --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org