Skip to content

Commit

Permalink
improved sphinx documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@emasab
emasab committed Apr 1, 2022
1 parent f725016 commit 0f7cc50
Show file tree
Hide file tree
Showing 3 changed files with 148 additions and 62 deletions.
90 changes: 90 additions & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,15 @@ Supporting classes
- Admin API
- :ref:`NewTopic <pyclient_admin_newtopic>`
- :ref:`NewPartitions <pyclient_admin_newpartitions>`
- :ref:`ConfigSource <pythonclient_config_source>`
- :ref:`ConfigEntry <pythonclient_config_entry>`
- :ref:`ConfigResource <pythonclient_config_resource>`
- :ref:`ResourceType <pythonclient_resource_type>`
- :ref:`ResourcePatternType <pythonclient_resource_pattern_type>`
- :ref:`AclOperation <pythonclient_acl_operation>`
- :ref:`AclPermissionType <pythonclient_acl_permission_type>`
- :ref:`AclBinding <pythonclient_acl_binding>`
- :ref:`AclBindingFilter <pythonclient_acl_binding_filter>`

Guide to the :ref:`Transactional Producer API <pythonclient_transactional>`

Expand Down Expand Up @@ -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:

********
Expand Down
30 changes: 17 additions & 13 deletions src/confluent_kafka/admin/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(<AclBinding, future>)
:rtype: dict[AclBinding, future]
:raises KafkaException: Operation failed locally or on broker.
:raises TypeException: Invalid input.
Expand All @@ -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
Expand All @@ -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(<AclBindingFilter, future>)
:rtype: dict[AclBindingFilter, future]
:raises KafkaException: Operation failed locally or on broker.
:raises TypeException: Invalid input.
Expand Down
90 changes: 41 additions & 49 deletions src/confluent_kafka/admin/_acl.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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__:
Expand All @@ -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__:
Expand All @@ -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
Expand Down Expand Up @@ -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):
Expand Down

0 comments on commit 0f7cc50

Please sign in to comment.