Added doctring to classes and methods

pyatlan/cache/abstract_asset_cache.py

@@ -12,6 +12,10 @@
 
 
 class AbstractAssetCache(ABC):
+    """
+    Base class for reusable components that are common
+    to all caches, where a cache is populated entry-by-entry.
+    """
 
     def __init__(self, client):
         self.client = client
@@ -41,16 +45,42 @@ def lookup_by_name(self, name: Any):
     def get_name(self, asset: Asset):
         """Abstract method to get name from asset."""
 
-    def is_guid_known(self, guid: str):
+    def is_guid_known(self, guid: str) -> bool:
+        """
+        Checks whether the provided Atlan-internal UUID is known.
+        NOTE: will not refresh the cache itself to determine this.
+
+        :param guid: Atlan-internal UUID of the object
+        :returns: `True` if the object is known, `False` otherwise
+        """
         return guid in self.guid_to_asset
 
     def is_qualified_name_known(self, qualified_name: str):
+        """
+        Checks whether the provided Atlan-internal ID string is known.
+        NOTE: will not refresh the cache itself to determine this.
+
+        :param qualified_name: Atlan-internal ID string of the object
+        :returns: `True` if the object is known, `False` otherwise
+        """
         return qualified_name in self.qualified_name_to_guid
 
     def is_name_known(self, name: str):
+        """
+        Checks whether the provided Atlan-internal ID string is known.
+        NOTE: will not refresh the cache itself to determine this.
+
+        :param name: human-constructable name of the object
+        :returns: `True` if the object is known, `False` otherwise
+        """
         return name in self.name_to_guid
 
     def cache(self, asset: Asset):
+        """
+        Add an entry to the cache.
+
+        :param asset: to be cached
+        """
         name = asset and self.get_name(asset)
         if not all([name, asset.guid, asset.qualified_name]):
             return
@@ -59,6 +89,16 @@ def cache(self, asset: Asset):
         self.qualified_name_to_guid[asset.qualified_name] = asset.guid
 
     def _get_by_guid(self, guid: str, allow_refresh: bool = True):
+        """
+        Retrieve an asset from the cache by its UUID.
+        If the asset is not found, it will be looked up and added to the cache.
+
+        :param guid: UUID of the asset in Atlan
+        :returns: the asset (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the asset cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no UUID was provided for the asset to retrieve
+        """
         if not guid:
             raise ErrorCode.MISSING_ID.exception_with_parameters()
         asset = self.guid_to_asset.get(guid)
@@ -70,6 +110,16 @@ def _get_by_guid(self, guid: str, allow_refresh: bool = True):
         return asset
 
     def _get_by_qualified_name(self, qualified_name: str, allow_refresh: bool = True):
+        """
+        Retrieve an asset from the cache by its unique Atlan-internal name.
+
+        :param qualified_name: unique Atlan-internal name of the asset
+        :param allow_refresh: whether to allow a refresh of the cache (`True`) or not (`False`)
+        :returns: the asset (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the object cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no qualified_name was provided for the object to retrieve
+        """
         if not qualified_name:
             raise ErrorCode.MISSING_ID.exception_with_parameters()
         guid = self.qualified_name_to_guid.get(qualified_name)
@@ -86,6 +136,16 @@ def _get_by_qualified_name(self, qualified_name: str, allow_refresh: bool = True
         return self._get_by_guid(guid=guid, allow_refresh=False)
 
     def _get_by_name(self, name: AbstractAssetName, allow_refresh: bool = True):
+        """
+        Retrieve an asset from the cache by its uniquely identifiable name.
+
+        :param name: uniquely identifiable name of the asset in Atlan
+        :param allow_refresh: whether to allow a refresh of the cache (`True`) or not (`False`)
+        :returns: the asset (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the object cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no name was provided for the object to retrieve
+        """
         if not isinstance(name, AbstractAssetName):
             raise ErrorCode.MISSING_NAME.exception_with_parameters()
         guid = self.name_to_guid.get(str(name))
@@ -100,7 +160,12 @@ def _get_by_name(self, name: AbstractAssetName, allow_refresh: bool = True):
 
 
 class AbstractAssetName(ABC):
-    _TYPE_NAME = ""
+    """
+    Base class for reusable components common to all asset names
+    used by the cache's find methods, such as AssetCache.get_by_name().
+    """
+
+    _TYPE_NAME = str()
 
     @abstractmethod
     def __init__(self):

pyatlan/cache/connection_cache.py

@@ -19,6 +19,17 @@
 
 
 class ConnectionCache(AbstractAssetCache):
+    """
+    Lazily-loaded cache for translating between
+    a connection's simplified name its details.
+
+    - guid = UUID of the connection
+        for eg: 9c677e77-e01d-40e0-85b7-8ba4cd7d0ea9
+    - qualified_name = Atlan-internal name of the connection (with epoch)
+        for eg: default/snowflake/1234567890
+    - name = simple name of the form {{connectorType}}/{{connectorName}},
+        for eg: snowflake/development
+    """
 
     _SEARCH_FIELDS = [
         Connection.NAME,
@@ -44,12 +55,35 @@ def get_cache(cls) -> ConnectionCache:
 
     @classmethod
     def get_by_guid(cls, guid: str, allow_refresh: bool = True) -> Connection:
+        """
+        Retrieve a connection from the cache by its UUID.
+        If the asset is not found, it will be looked up and added to the cache.
+
+        :param guid: UUID of the connection in Atlan
+            for eg: 9c677e77-e01d-40e0-85b7-8ba4cd7d0ea9
+        :returns: connection (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the connection cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no UUID was provided for the connection to retrieve
+        """
         return cls.get_cache()._get_by_guid(guid=guid, allow_refresh=allow_refresh)
 
     @classmethod
     def get_by_qualified_name(
         cls, qualified_name: str, allow_refresh: bool = True
     ) -> Connection:
+        """
+        Retrieve a connection from the cache by its unique Atlan-internal name.
+
+        :param qualified_name: unique Atlan-internal name of the connection
+            for eg: default/snowflake/1234567890
+        :param allow_refresh: whether to allow a refresh of the cache (`True`) or not (`False`)
+        :param qualified_name: unique Atlan-internal name of the connection
+        :returns: connection (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the connection cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no qualified_name was provided for the connection to retrieve
+        """
         return cls.get_cache()._get_by_qualified_name(
             qualified_name=qualified_name, allow_refresh=allow_refresh
         )
@@ -58,6 +92,18 @@ def get_by_qualified_name(
     def get_by_name(
         cls, name: ConnectionName, allow_refresh: bool = True
     ) -> Connection:
+        """
+        Retrieve an connection from the cache by its uniquely identifiable name.
+
+        :param name: uniquely identifiable name of the connection in Atlan
+            In the form of {{connectorType}}/{{connectorName}}
+            for eg: snowflake/development
+        :param allow_refresh: whether to allow a refresh of the cache (`True`) or not (`False`)
+        :returns: connection (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the connection cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no name was provided for the connection to retrieve
+        """
         return cls.get_cache()._get_by_name(name=name, allow_refresh=allow_refresh)
 
     def lookup_by_guid(self, guid: str) -> None:
@@ -117,6 +163,13 @@ def get_name(self, asset: Asset):
 
 
 class ConnectionName(AbstractAssetName):
+    """
+    Unique identity for a connection,
+    in the form: {{type}}/{{name}}
+
+    - For eg: snowflake/development
+    """
+
     _TYPE_NAME = "Connection"
 
     def __init__(

pyatlan/cache/source_tag_cache.py

@@ -20,6 +20,17 @@
 
 
 class SourceTagCache(AbstractAssetCache):
+    """
+    Lazily-loaded cache for translating between
+    source-synced tags and the qualifiedName of such.
+
+    - guid = UUID of the source tag
+        for eg: 9c677e77-e01d-40e0-85b7-8ba4cd7d0ea9
+    - qualified_name = of the source tag (with epoch)
+        for eg: default/snowflake/1234567890/DB/SCHEMA/TAG_NAME
+    - name = simple name of the form {{connectorType}}/{{connectorName}}@@DB/SCHEMA/TAG_NAME
+        for eg: snowflake/development@@DB/SCHEMA/TAG_NAME
+    """
 
     _SEARCH_FIELDS = [Asset.NAME]
     SEARCH_ATTRIBUTES = [field.atlan_field_name for field in _SEARCH_FIELDS]
@@ -41,18 +52,53 @@ def get_cache(cls) -> SourceTagCache:
 
     @classmethod
     def get_by_guid(cls, guid: str, allow_refresh: bool = True) -> Tag:
+        """
+        Retrieve a source tag from the cache by its UUID.
+        If the asset is not found, it will be looked up and added to the cache.
+
+        :param guid: UUID of the source tag in Atlan
+            for eg: 9c677e77-e01d-40e0-85b7-8ba4cd7d0ea9
+        :returns: source tag (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the source tag cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no UUID was provided for the source tag to retrieve
+        """
         return cls.get_cache()._get_by_guid(guid=guid, allow_refresh=allow_refresh)
 
     @classmethod
     def get_by_qualified_name(
         cls, qualified_name: str, allow_refresh: bool = True
     ) -> Tag:
+        """
+        Retrieve a source tag from the cache by its unique Atlan-internal name.
+
+        :param qualified_name: unique Atlan-internal name of the source tag
+            for eg: default/snowflake/1234567890/DB/SCHEMA/TAG_NAME
+        :param allow_refresh: whether to allow a refresh of the cache (`True`) or not (`False`)
+        :param qualified_name: unique Atlan-internal name of the source tag
+        :returns: source tag (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the source tag cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no qualified_name was provided for the source tag to retrieve
+        """
         return cls.get_cache()._get_by_qualified_name(
             qualified_name=qualified_name, allow_refresh=allow_refresh
         )
 
     @classmethod
     def get_by_name(cls, name: SourceTagName, allow_refresh: bool = True) -> Tag:
+        """
+        Retrieve an connection from the cache by its uniquely identifiable name.
+
+        :param name: uniquely identifiable name of the connection in Atlan.
+            In the form of {{connectorType}}/{{connectorName}}@@DB/SCHEMA/TAG_NAME
+            for eg: snowflake/development@@DB/SCHEMA/TAG_NAME
+        :param allow_refresh: whether to allow a refresh of the cache (`True`) or not (`False`)
+        :returns: the connection (if found)
+        :raises AtlanError: on any API communication problem if the cache needs to be refreshed
+        :raises NotFoundError: if the object cannot be found (does not exist) in Atlan
+        :raises InvalidRequestError: if no name was provided for the object to retrieve
+        """
         return cls.get_cache()._get_by_name(name=name, allow_refresh=allow_refresh)
 
     def lookup_by_guid(self, guid: str) -> None:
@@ -130,6 +176,13 @@ def get_name(self, asset: Asset):
 
 
 class SourceTagName(AbstractAssetName):
+    """
+    Unique identity for a source tag,
+    in the form: {{connectorType}}/{{connectorName}}@@DB/SCHEMA/TAG_NAME
+
+    - For eg: snowflake/development
+    """
+
     _TYPE_NAME = "SourceTagAttachment"
     _CONNECTION_DELIMITER = "@@"
 

pyatlan/errors.py

@@ -566,9 +566,7 @@ class ErrorCode(Enum):
         400,
         "ATLAN-PYTHON-400-065",
         "No name instance was provided when attempting to retrieve an object.",
-        "You must provide the name of the object when attempting to retrieve one. "
-        + "eg: SourceTagName('snowflake/development@@DB/SCH/SENSITIVITY') OR "
-        + "ConnectionName('snowflake/development'). ",
+        "You must provide the name of the object when attempting to retrieve one.",
         InvalidRequestError,
     )
     AUTHENTICATION_PASSTHROUGH = (