[docs] Updated docstrings and fixed source_tag_attachments field typo

Author: Aryamanz29

pyatlan/client/atlan.py

@@ -446,6 +446,11 @@ def _call_api_internal(
                     if text_response:
                         response_ = response.text
                     else:
+                        # The response may be either a JSON object or a list of events
+                        # If it's an event stream, return the list of events directly
+                        # Otherwise, parse the JSON response using AtlanResponse,
+                        # which handles translation tasks such as converting
+                        # Atlan tag hashed IDs into human-readable strings
                         response_ = (
                             events
                             if events
@@ -631,6 +636,9 @@ def _create_params(
             params["params"] = query_params
         if request_obj is not None:
             if isinstance(request_obj, AtlanObject):
+                # Always use AtlanRequest, which accepts a Pydantic model instance and the client
+                # Behind the scenes, it handles retranslation tasks—such as converting
+                # human-readable Atlan tag names back into hashed IDs as required by the backend
                 params["data"] = AtlanRequest(instance=request_obj, client=self).json()
             elif api.consumes == APPLICATION_ENCODED_FORM:
                 params["data"] = request_obj

pyatlan/model/core.py

@@ -154,7 +154,16 @@ def from_yaml(cls, yaml_str: str):
 
 
 class AtlanResponse:
+    """
+    A wrapper class to handle and translate raw JSON responses
+    from the Atlan API into human-readable formats using registered translators.
+    """
+
     def __init__(self, raw_json: Dict[str, Any], client: AtlanClient):
+        """
+        Initialize the AtlanResponse with raw JSON and client.
+        Automatically applies translations to the raw JSON.
+        """
         self.raw_json = raw_json
         self.client = client
         self.translators = [
@@ -166,6 +175,9 @@ def __init__(self, raw_json: Dict[str, Any], client: AtlanClient):
     def _deep_translate(
         self, data: Union[Dict[str, Any], List[Any], Any]
     ) -> Union[Dict[str, Any], List[Any], Any]:
+        """
+        Recursively translate fields in a JSON structure using registered translators.
+        """
         if isinstance(data, dict):
             # Apply translators to this dict if any apply
             for translator in self.translators:
@@ -182,11 +194,25 @@ def _deep_translate(
             return data
 
     def to_dict(self) -> Union[Dict[str, Any], List[Any], Any]:
+        """
+        Returns the translated version of the raw JSON response.
+        """
         return self.translated
 
 
 class AtlanRequest:
+    """
+    A wrapper class to handle and retranslate an AtlanObject instance
+    into a backend-compatible JSON format by applying retranslators.
+    """
+
     def __init__(self, instance: AtlanObject, client: AtlanClient):
+        """
+        Initialize an AtlanRequest for a given asset/model instance.
+
+        Serializes the instance to JSON, applies retranslation logic, and prepares
+        a structure compatible with Atlan's API (e.g: converts tag names back to hashed IDs).
+        """
         self.client = client
         self.instance = instance
         self.retranslators = [
@@ -207,6 +233,9 @@ def __init__(self, instance: AtlanObject, client: AtlanClient):
         self.translated = self._deep_retranslate(parsed)
 
     def _deep_retranslate(self, data: Any) -> Any:
+        """
+        Recursively traverse and apply retranslators to JSON-like data.
+        """
         if isinstance(data, dict):
             for retranslator in self.retranslators:
                 if retranslator.applies_to(data):
@@ -217,6 +246,9 @@ def _deep_retranslate(self, data: Any) -> Any:
         return data
 
     def json(self, **kwargs) -> str:
+        """
+        Returns the fully retranslated JSON string, suitable for API calls.
+        """
         return json.dumps(self.translated, **kwargs)
 
 
@@ -287,32 +319,13 @@ class Config:
         alias="restrictPropagationThroughHierarchy",
     )
     validity_periods: Optional[List[str]] = Field(default=None, alias="validityPeriods")
-    source_tag_attachements: List[SourceTagAttachment] = Field(
+    source_tag_attachments: List[SourceTagAttachment] = Field(
         default_factory=list, exclude=True
     )
 
     attributes: Optional[Dict[str, Any]] = None
     tag_id: Optional[str] = Field(default=None, exclude=True)
 
-    # @property
-    # def source_tag_attachements(self) -> List[SourceTagAttachment]:
-    #     return self._source_tag_attachements
-
-    # def __init__(self, *args, **kwargs):
-    #     from pyatlan.client.atlan import AtlanClient
-
-    #     super().__init__(*args, **kwargs)
-    #     if self.type_name != AtlanTagName.get_deleted_sentinel():
-    #         attr_id = AtlanClient.get_current_client().atlan_tag_cache.get_source_tags_attr_id(
-    #             self.type_name.id
-    #         )
-    #     if self.attributes and attr_id in self.attributes:
-    #         self._source_tag_attachements = [
-    #             SourceTagAttachment(**source_tag["attributes"])
-    #             for source_tag in self.attributes[attr_id]
-    #             if isinstance(source_tag, dict) and source_tag.get("attributes")
-    #         ]
-
     @classmethod
     def of(
         cls,
@@ -343,7 +356,7 @@ def of(
                 tag_id or ""
             )
             tag.attributes = {source_tag_attr_id: [source_tag_attachment]}  # type: ignore[dict-item]
-            tag.source_tag_attachements.append(source_tag_attachment)
+            tag.source_tag_attachments.append(source_tag_attachment)
         return tag
 
 

pyatlan/model/fields/atlan_fields.py

@@ -3,7 +3,7 @@
 from abc import ABC
 from datetime import date
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union, overload
+from typing import Any, Dict, List, Optional, Union, overload
 
 from pydantic.v1 import StrictBool, StrictFloat, StrictInt, StrictStr
 
@@ -28,9 +28,6 @@
 from pyatlan.model.typedef import AttributeDef
 from pyatlan.utils import ComparisonCategory, is_comparable_type
 
-if TYPE_CHECKING:
-    pass
-
 
 class AtlanField(ABC):
     """

pyatlan/model/fluent_search.py

@@ -106,6 +106,7 @@ def tagged(
         provided. This will match irrespective of the Atlan tag being directly applied to the
         asset, or if it was propagated to the asset.
 
+        :param client: connectivity to an Atlan tenant
         :param with_one_of: human-readable names of the Atlan tags
         :param directly: when True, the asset must have at least one Atlan tag directly assigned, otherwise
                          even propagated tags will suffice
@@ -156,6 +157,7 @@ def tagged_with_value(
         Returns a query that will match assets that have a
         specific value for the specified tag (for source-synced tags).
 
+        :param client: connectivity to an Atlan tenant
         :param atlan_tag_name: human-readable name of the Atlan tag
         :param value: tag should have to match the query
         :param directly: when `True`, the asset must have the tag and

pyatlan/model/open_lineage/event.py

@@ -75,6 +75,7 @@ def emit(self, client: AtlanClient) -> None:
         """
         Send the OpenLineage event to Atlan to be processed.
 
+        :param client: connectivity to an Atlan tenant
         :raises AtlanError: on any API communication issues
         """
         return client.open_lineage.send(

pyatlan/model/packages/base/crawler.py

@@ -12,6 +12,7 @@ class AbstractCrawler(AbstractPackage):
     """
     Abstract class for crawlers
 
+    :param client: connectivity to an Atlan tenant
     :param connection_name: name for the connection
     :param connection_type: type of connector for the connection
     :param admin_roles: admin roles for the connection

pyatlan/model/packages/big_query_crawler.py

@@ -12,6 +12,7 @@ class BigQueryCrawler(AbstractCrawler):
     """
     Base configuration for a new BigQuery crawler.
 
+    :param client: connectivity to an Atlan tenant
     :param connection_name: name for the connection
     :param admin_roles: admin roles for the connection
     :param admin_groups: admin groups for the connection

pyatlan/model/packages/confluent_kafka_crawler.py

@@ -12,6 +12,7 @@ class ConfluentKafkaCrawler(AbstractCrawler):
     """
     Base configuration for a new Confluent Kafka crawler.
 
+    :param client: connectivity to an Atlan tenant
     :param connection_name: name for the connection
     :param admin_roles: admin roles for the connection
     :param admin_groups: admin groups for the connection

pyatlan/model/packages/databricks_crawler.py

@@ -13,6 +13,7 @@ class DatabricksCrawler(AbstractCrawler):
     """
     Base configuration for a new Databricks crawler.
 
+    :param client: connectivity to an Atlan tenant
     :param connection_name: name for the connection
     :param admin_roles: admin roles for the connection
     :param admin_groups: admin groups for the connection

pyatlan/model/packages/dbt_crawler.py

@@ -12,6 +12,7 @@ class DbtCrawler(AbstractCrawler):
     """
     Base configuration for a new Dbt crawler.
 
+    :param client: connectivity to an Atlan tenant
     :param connection_name: name for the connection
     :param admin_roles: admin roles for the connection
     :param admin_groups: admin groups for the connection