You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jd...@apache.org on 2021/08/27 12:14:27 UTC
[qpid-proton] branch main updated: PROTON-2407 [python] fix
type-related documentation comments (#332)
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 <jd...@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-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org