Source code for censys.asm.assets.assets
"""Base for interacting with the Censys Assets API."""
import re
from typing import Iterator, Optional
from ..api import CensysAsmAPI
from censys.common.exceptions import CensysInvalidColorException
HEX_REGEX = re.compile(r"^#(?:[0-9a-fA-F]{3}){1,2}$")
[docs]class Assets(CensysAsmAPI):
"""Assets API class."""
def __init__(self, asset_type: str, *args, **kwargs):
"""Inits Assets.
Args:
asset_type (str): Type of asset to interact with.
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
"""
CensysAsmAPI.__init__(self, *args, **kwargs)
self.base_path = f"assets/{asset_type}"
[docs] def get_assets(
self, page_number: int = 1, page_size: Optional[int] = None
) -> Iterator[dict]:
"""Requests assets data.
Args:
page_number (int): Optional; Page number to begin at when searching.
page_size (int): Optional; Page size for retrieving assets.
Yields:
dict: The assets result returned.
"""
yield from self._get_page(
self.base_path, page_number=page_number, page_size=page_size
)
[docs] def get_asset_by_id(self, asset_id: str) -> dict:
"""Requests asset data by ID.
Args:
asset_id (str): Requested asset ID.
Returns:
dict: Asset search result.
"""
path = f"{self.base_path}/{asset_id}"
return self._get(path)
[docs] def get_comments(
self,
asset_id: str,
page_number: int = 1,
page_size: Optional[int] = None,
) -> Iterator[dict]:
"""Requests comments on a specified asset.
Args:
asset_id (str): Asset ID for requested comments.
page_number (int): Optional; Page number to begin at when searching.
page_size (int): Optional; Page size for retrieving comments.
Returns:
generator: Comment search results.
"""
path = f"{self.base_path}/{asset_id}/comments"
return self._get_page(
path, page_number=page_number, page_size=page_size, keyword="comments"
)
[docs] def get_comment_by_id(self, asset_id: str, comment_id: int) -> dict:
"""Requests a comment on a specified asset by comment ID.
Args:
asset_id (str): Asset ID for requested comments.
comment_id (int): Requested comment ID.
Returns:
dict: Comment search result.
"""
path = f"{self.base_path}/{asset_id}/comments/{comment_id}"
return self._get(path)
[docs] def add_comment(self, asset_id: str, comment: str) -> dict:
"""Adds a comment to a specified asset on the ASM platform.
Args:
asset_id (str): Asset ID to add comment to.
comment (str): New comment text.
Returns:
dict: Added comment results.
"""
path = f"{self.base_path}/{asset_id}/comments"
data = {"markdown": str(comment)}
return self._post(path, data=data)
[docs] def delete_comment(self, asset_id: str, comment_id: int) -> dict:
"""Deletes a comment from a specified asset on the ASM platform by comment ID.
Args:
asset_id (str): Asset ID to delete comment from.
comment_id (int): Comment ID to delete.
Returns:
dict: Deleted comment results.
"""
path = f"{self.base_path}/{asset_id}/comments/{comment_id}"
return self._delete(path)
[docs] def add_tag(self, asset_id: str, name: str, color: Optional[str] = None) -> dict:
"""Adds a tag to a specified asset on the ASM platform.
Args:
asset_id (str): Asset ID to add tag to.
name (str): New tag name.
color (str): Optional; New tag color (hex).
Returns:
dict: Added tag results.
"""
path = f"{self.base_path}/{asset_id}/tags"
data = format_tag(name, color)
return self._post(path, data=data)
[docs] def delete_tag(self, asset_id: str, name: str) -> dict:
"""Deletes a tag from a specified asset on the ASM platform by tag name.
Args:
asset_id (str): Asset ID to delete tag from.
name (str): Tag name to delete.
Returns:
dict: Deleted tag results.
"""
path = f"{self.base_path}/{asset_id}/tags/{name}"
return self._delete(path)
def format_tag(name: str, color: Optional[str] = None) -> dict:
"""Formats tag name and color request data.
Args:
name (str): Tag name.
color (str): Optional; Tag color (hex).
Raises:
CensysInvalidColorException: Raised if color is not a valid hex color.
Returns:
dict: Formatted tag request data.
"""
if color:
if not HEX_REGEX.match(color):
raise CensysInvalidColorException(10037, f"{color} is not a valid color.")
return {"name": str(name), "color": str(color)}
return {"name": str(name)}