diff --git a/docs/index.rst b/docs/index.rst index e74141586..a1a7a9043 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,15 @@ Supporting classes - Admin API - :ref:`NewTopic ` - :ref:`NewPartitions ` + - :ref:`ConfigSource ` + - :ref:`ConfigEntry ` + - :ref:`ConfigResource ` + - :ref:`ResourceType ` + - :ref:`ResourcePatternType ` + - :ref:`AclOperation ` + - :ref:`AclPermissionType ` + - :ref:`AclBinding ` + - :ref:`AclBindingFilter ` Guide to the :ref:`Transactional Producer API ` @@ -89,6 +98,87 @@ NewPartitions .. autoclass:: confluent_kafka.admin.NewPartitions :members: +.. _pythonclient_config_source: + +************** +ConfigSource +************** + +.. autoclass:: confluent_kafka.admin.ConfigSource + :members: + +.. _pythonclient_config_entry: + +************** +ConfigEntry +************** + +.. autoclass:: confluent_kafka.admin.ConfigEntry + :members: + +.. _pythonclient_config_resource: + +************** +ConfigResource +************** + +.. autoclass:: confluent_kafka.admin.ConfigResource + :members: + +.. _pythonclient_resource_type: + +************** +ResourceType +************** + +.. autoclass:: confluent_kafka.admin.ResourceType + :members: + +.. _pythonclient_resource_pattern_type: + +************** +ResourcePatternType +************** + +.. autoclass:: confluent_kafka.admin.ResourcePatternType + :members: + +.. _pythonclient_acl_operation: + +************** +AclOperation +************** + +.. autoclass:: confluent_kafka.admin.AclOperation + :members: + +.. _pythonclient_acl_permission_type: + +************** +AclPermissionType +************** + +.. autoclass:: confluent_kafka.admin.AclPermissionType + :members: + +.. _pythonclient_acl_binding: + +************** +AclBinding +************** + +.. autoclass:: confluent_kafka.admin.AclBinding + :members: + +.. _pythonclient_acl_binding_filter: + +************** +AclBindingFilter +************** + +.. autoclass:: confluent_kafka.admin.AclBindingFilter + :members: + .. _pythonclient_consumer: ******** diff --git a/src/confluent_kafka/admin/__init__.py b/src/confluent_kafka/admin/__init__.py index c728dddc4..0d73bc993 100644 --- a/src/confluent_kafka/admin/__init__.py +++ b/src/confluent_kafka/admin/__init__.py @@ -364,16 +364,16 @@ def create_acls(self, acls, **kwargs): """ Create one or more ACL bindings. - :param list(AclBinding) acls: A list of ACL binding specifications (AclBinding) + :param list(AclBinding) acls: A list of ACL binding specifications (:class:`.AclBinding`) to create. :param float request_timeout: The overall request timeout in seconds, including broker lookup, request transmission, operation time on broker, and response. Default: `socket.timeout.ms*1000.0` - :returns: A dict of futures for each ACL binding, keyed by the AclBinding object. + :returns: A dict of futures for each ACL binding, keyed by the :class:`AclBinding` object. The future result() method returns None on success. - :rtype: dict() + :rtype: dict[AclBinding, future] :raises KafkaException: Operation failed locally or on broker. :raises TypeException: Invalid input. @@ -394,14 +394,16 @@ def describe_acls(self, acl_binding_filter, **kwargs): :param AclBindingFilter acl_binding_filter: a filter with attributes that must match. String attributes match exact values or any string if set to None. - Enums attributes match exact values or any value if ending with _ANY. - If ResourcePatternType is set to MATCH returns all the ACL bindings with - LITERAL, WILDCARD or PREFIXED pattern type that match the resource name. + Enums attributes match exact values or any value if ending with `_ANY`. + If :class:`ResourcePatternType` is set to :attr:`ResourcePatternType.MATCH` returns all + the ACL bindings with :attr:`ResourcePatternType.LITERAL`, + :attr:`ResourcePatternType.WILDCARD` or :attr:`ResourcePatternType.PREFIXED` pattern + type that match the resource name. :param float request_timeout: The overall request timeout in seconds, including broker lookup, request transmission, operation time on broker, and response. Default: `socket.timeout.ms*1000.0` - :returns: A future returning a list(AclBinding) as result + :returns: A future returning a list(:class:`AclBinding`) as result :rtype: future @@ -423,17 +425,19 @@ def delete_acls(self, acl_binding_filters, **kwargs): :param list(AclBindingFilter) acl_binding_filters: a list of ACL binding filters to match ACLs to delete. String attributes match exact values or any string if set to None. - Enums attributes match exact values or any value if ending with _ANY. - If ResourcePatternType is set to MATCH deletes all the ACL bindings with - LITERAL, WILDCARD or PREFIXED pattern type that match the resource name. + Enums attributes match exact values or any value if ending with `_ANY`. + If :class:`ResourcePatternType` is set to :attr:`ResourcePatternType.MATCH` + deletes all the ACL bindings with :attr:`ResourcePatternType.LITERAL`, + :attr:`ResourcePatternType.WILDCARD` or :attr:`ResourcePatternType.PREFIXED` + pattern type that match the resource name. :param float request_timeout: The overall request timeout in seconds, including broker lookup, request transmission, operation time on broker, and response. Default: `socket.timeout.ms*1000.0` - :returns: A dict of futures for each ACL binding filter, keyed by the AclBindingFilter object. - The future result() method returns a list of AclBinding. + :returns: A dict of futures for each ACL binding filter, keyed by the :class:`AclBindingFilter` object. + The future result() method returns a list of :class:`AclBinding`. - :rtype: dict() + :rtype: dict[AclBindingFilter, future] :raises KafkaException: Operation failed locally or on broker. :raises TypeException: Invalid input. diff --git a/src/confluent_kafka/admin/_acl.py b/src/confluent_kafka/admin/_acl.py index 34c1b526b..673dadbe3 100644 --- a/src/confluent_kafka/admin/_acl.py +++ b/src/confluent_kafka/admin/_acl.py @@ -27,19 +27,19 @@ class AclOperation(Enum): """ Enumerates the different types of ACL operation. """ - UNKNOWN = _cimpl.ACL_OPERATION_UNKNOWN # : Unknown - ANY = _cimpl.ACL_OPERATION_ANY # : In a filter, matches any AclOperation - ALL = _cimpl.ACL_OPERATION_ALL # : ALL operation - READ = _cimpl.ACL_OPERATION_READ # : READ operation - WRITE = _cimpl.ACL_OPERATION_WRITE # : WRITE operation - CREATE = _cimpl.ACL_OPERATION_CREATE # : CREATE operation - DELETE = _cimpl.ACL_OPERATION_DELETE # : DELETE operation - ALTER = _cimpl.ACL_OPERATION_ALTER # : ALTER operation - DESCRIBE = _cimpl.ACL_OPERATION_DESCRIBE # : DESCRIBE operation - CLUSTER_ACTION = _cimpl.ACL_OPERATION_CLUSTER_ACTION # : CLUSTER_ACTION operation - DESCRIBE_CONFIGS = _cimpl.ACL_OPERATION_DESCRIBE_CONFIGS # : DESCRIBE_CONFIGS operation - ALTER_CONFIGS = _cimpl.ACL_OPERATION_ALTER_CONFIGS # : ALTER_CONFIGS operation - IDEMPOTENT_WRITE = _cimpl.ACL_OPERATION_IDEMPOTENT_WRITE # : IDEMPOTENT_WRITE operation + UNKNOWN = _cimpl.ACL_OPERATION_UNKNOWN #: Unknown + ANY = _cimpl.ACL_OPERATION_ANY #: In a filter, matches any AclOperation + ALL = _cimpl.ACL_OPERATION_ALL #: ALL operation + READ = _cimpl.ACL_OPERATION_READ #: READ operation + WRITE = _cimpl.ACL_OPERATION_WRITE #: WRITE operation + CREATE = _cimpl.ACL_OPERATION_CREATE #: CREATE operation + DELETE = _cimpl.ACL_OPERATION_DELETE #: DELETE operation + ALTER = _cimpl.ACL_OPERATION_ALTER #: ALTER operation + DESCRIBE = _cimpl.ACL_OPERATION_DESCRIBE #: DESCRIBE operation + CLUSTER_ACTION = _cimpl.ACL_OPERATION_CLUSTER_ACTION #: CLUSTER_ACTION operation + DESCRIBE_CONFIGS = _cimpl.ACL_OPERATION_DESCRIBE_CONFIGS #: DESCRIBE_CONFIGS operation + ALTER_CONFIGS = _cimpl.ACL_OPERATION_ALTER_CONFIGS #: ALTER_CONFIGS operation + IDEMPOTENT_WRITE = _cimpl.ACL_OPERATION_IDEMPOTENT_WRITE #: IDEMPOTENT_WRITE operation def __lt__(self, other): if self.__class__ != other.__class__: @@ -51,10 +51,10 @@ class AclPermissionType(Enum): """ Enumerates the different types of ACL permission types. """ - UNKNOWN = _cimpl.ACL_PERMISSION_TYPE_UNKNOWN # : Unknown - ANY = _cimpl.ACL_PERMISSION_TYPE_ANY # : In a filter, matches any AclPermissionType - DENY = _cimpl.ACL_PERMISSION_TYPE_DENY # : Disallows access - ALLOW = _cimpl.ACL_PERMISSION_TYPE_ALLOW # : Grants access + UNKNOWN = _cimpl.ACL_PERMISSION_TYPE_UNKNOWN #: Unknown + ANY = _cimpl.ACL_PERMISSION_TYPE_ANY #: In a filter, matches any AclPermissionType + DENY = _cimpl.ACL_PERMISSION_TYPE_DENY #: Disallows access + ALLOW = _cimpl.ACL_PERMISSION_TYPE_ALLOW #: Grants access def __lt__(self, other): if self.__class__ != other.__class__: @@ -66,39 +66,31 @@ def __lt__(self, other): class AclBinding(object): """ Represents an ACL binding that specify the operation and permission type for a specific principal - over one or more resources of the same type. Used by create_acls, returned by describe_acls and delete_acls. + over one or more resources of the same type. Used by :meth:`AdminClient.create_acls`, + returned by :meth:`AdminClient.describe_acls` and :meth:`AdminClient.delete_acls`. Parameters ---------- - restype : `ResourceType` + restype : ResourceType The resource type. - name : `str` - The resource name, which depends on the resource type. For RESOURCE_BROKER, the resource name is the broker id. - resource_pattern_type : `ResourcePatternType` + name : str + The resource name, which depends on the resource type. For :attr:`ResourceType.BROKER`, + the resource name is the broker id. + resource_pattern_type : ResourcePatternType The resource pattern, relative to the name. - principal : `str` + principal : str The principal this AclBinding refers to. - host : `str` + host : str The host that the call is allowed to come from. - operation: `AclOperation` + operation: AclOperation The operation/s specified by this binding. - permission_type: `AclPermissionType` + permission_type: AclPermissionType The permission type for the specified operation. """ def __init__(self, restype, name, resource_pattern_type, principal, host, operation, permission_type): - """ - :param ResourceType restype: Resource type. - :param str name: The resource name, which depends on restype. - For RESOURCE_BROKER, the resource name is the broker id. - :param ResourcePatternType resource_pattern_type: The resource pattern, relative to the name. - :param str principal: The principal this AclBinding refers to. - :param str host: The host that the call is allowed to come from. - :param AclOperation operation: The operation/s specified by this binding. - :param AclPermissionType The permission type for the specified operation. - """ self.restype = restype self.name = name self.resource_pattern_type = resource_pattern_type @@ -204,26 +196,26 @@ def __eq__(self, other): class AclBindingFilter(AclBinding): """ Represents an ACL binding filter used to return a list of ACL bindings matching some or all of its attributes. - Used by describe_acls and delete_acls. + Used by :meth:`AdminClient.describe_acls` and :meth:`AdminClient.delete_acls`. Parameters ---------- - restype : `ResourceType` - The resource type, or ResourceType.ANY to match any value. - name : `str` + restype : ResourceType + The resource type, or :attr:`ResourceType.ANY` to match any value. + name : str The resource name to match. None matches any value. - resource_pattern_type : `ResourcePatternType` - The resource pattern, ResourcePatternType.ANY to match any value or - ResourcePatternType.MATCH to perform pattern matching. - principal : `str` + resource_pattern_type : ResourcePatternType + The resource pattern, :attr:`ResourcePatternType.ANY` to match any value or + :attr:`ResourcePatternType.MATCH` to perform pattern matching. + principal : str The principal to match, or None to match any value. - host : `str` + host : str The host to match, or None to match any value. - operation: `AclOperation` - The operation to match or AclOperation.ANY to match any value. - permission_type: `AclPermissionType` - The permission type to match or AclPermissionType.ANY to match any value. + operation: AclOperation + The operation to match or :attr:`AclOperation.ANY` to match any value. + permission_type: AclPermissionType + The permission type to match or :attr:`AclPermissionType.ANY` to match any value. """ def _not_none_args(self):