Changed docstrings to fit numpy docstyle (#102)

Co-authored-by: somehybrid <somehybrid@space>

src/letsbuilda/pypi/async_client.py

@@ -20,7 +20,18 @@ def __init__(self: Self, http_client: AsyncClient) -> None:
         self.http_client = http_client
 
     async def get_rss_feed(self: Self, feed_url: str) -> list[RSSPackageMetadata]:
-        """Get the new packages RSS feed."""
+        """Get the new packages RSS feed.
+
+        Parameters
+        ----------
+        feed_url
+            The URL of the RSS feed.
+
+        Returns
+        -------
+        list[RSSPackageMetadata]
+            The list of new packages.
+        """
         response = await self.http_client.get(feed_url)
         rss_data = xmltodict.parse(response.text)["rss"]["channel"]["item"]
         return [RSSPackageMetadata.build_from(package_data) for package_data in rss_data]
@@ -30,7 +41,26 @@ async def get_package_json_metadata(
         package_title: str,
         package_version: str | None = None,
     ) -> JSONPackageMetadata:
-        """Get metadata for a package."""
+        """
+        Retrieve metadata for a package.
+
+        Raises
+        ------
+        PackageNotFoundError
+            If the package is not found.
+
+        Parameters
+        ----------
+        package_title
+            The title of the package.
+        package_version
+            The version of the package.
+
+        Returns
+        -------
+        JSONPackageMetadata
+            The metadata for the package.
+        """
         if package_version is not None:
             url = f"https://pypi.org/pypi/{package_title}/{package_version}/json"
         else:
@@ -45,5 +75,18 @@ async def get_package_metadata(
         package_title: str,
         package_version: str | None = None,
     ) -> Package:
-        """Get metadata for a package."""
+        """Create a `Package` object from its metadata.
+
+        Parameters
+        ----------
+        package_title
+            The title of the package.
+        package_version
+            The version of the package.
+
+        Returns
+        -------
+        Package
+            The package object.
+        """
         return Package.from_json_api_data(await self.get_package_json_metadata(package_title, package_version))

src/letsbuilda/pypi/models/models_json.py

@@ -20,7 +20,19 @@ class Vulnerability:
 
     @classmethod
     def from_dict(cls: type[Self], data: dict) -> Self:  # type: ignore[type-arg]
-        """Build an instance from a dictionary."""
+        """
+        Build an instance from a dictionary.
+
+        Parameters
+        ----------
+        data
+            The data for a vulnerability.
+
+        Returns
+        -------
+        Vulnerability
+            An object storing the details of a security vulnerability.
+        """
         if data["withdrawn"] is not None:
             data["withdrawn"] = datetime.fromisoformat(data["withdrawn"])
 
@@ -37,7 +49,19 @@ class Downloads:
 
     @classmethod
     def from_dict(cls: type[Self], data: dict) -> Self:  # type: ignore[type-arg]
-        """Build an instance from a dictionary."""
+        """
+        Build an instance from a dictionary.
+
+        Parameters
+        ----------
+        data
+            A dictionary containing download statistics.
+
+        Returns
+        -------
+        Downloads
+            An object storing download statistics.
+        """
         return cls(**data)
 
 
@@ -51,7 +75,19 @@ class Digests:
 
     @classmethod
     def from_dict(cls: type[Self], data: dict) -> Self:  # type: ignore[type-arg]
-        """Build an instance from a dictionary."""
+        """
+        Build an instance from a dictionary.
+
+        Parameters
+        ----------
+        data
+            A dictionary containing checksums of a package release.
+
+        Returns
+        -------
+        Digests
+            An object storing checksums.
+        """
         return cls(**data)
 
 
@@ -77,7 +113,19 @@ class URL:
 
     @classmethod
     def from_dict(cls: type[Self], data: dict) -> Self:  # type: ignore[type-arg]
-        """Build an instance from a dictionary."""
+        """
+        Build an instance from a dictionary.
+
+        Parameters
+        ----------
+        data
+            The JSON API metadata for a package release.
+
+        Returns
+        -------
+        URL
+            An object representing a package release.
+        """
         data["upload_time"] = datetime.fromisoformat(data["upload_time"])
         data["upload_time_iso_8601"] = datetime.fromisoformat(data["upload_time_iso_8601"])
 
@@ -150,7 +198,19 @@ class Info:
 
     @classmethod
     def from_dict(cls: type[Self], data: dict) -> Self:  # type: ignore[type-arg]
-        """Build an instance from a dictionary."""
+        """
+        Build an instance from a dictionary.
+
+        Parameters
+        ----------
+        data
+            The JSON API metadata for a package.
+
+        Returns
+        -------
+        Info
+            An object storing a package's metadata.
+        """
         if "dynamic" not in data:
             data["dynamic"] = None
         if "provides_extra" not in data:
@@ -169,7 +229,19 @@ class JSONPackageMetadata:
 
     @classmethod
     def from_dict(cls: type[Self], data: dict) -> Self:  # type: ignore[type-arg]
-        """Build an instance from a dictionary."""
+        """
+        Build an instance from a dictionary.
+
+        Parameters
+        ----------
+        data
+            Package metadata from the JSON API.
+
+        Returns
+        -------
+        JSONPackageMetadata
+            An object storing package metadata.
+        """
         info = Info.from_dict(data["info"])
         return cls(
             info=info,

src/letsbuilda/pypi/models/models_package.py

@@ -15,7 +15,18 @@ class Distribution:
 
     @classmethod
     def from_json_api_data(cls: type[Self], data: URL) -> Self:
-        """Build an instance from the JSON API data."""
+        """Build an instance from the JSON API data.
+
+        Parameters
+        ----------
+        data
+            The URL of the file hosting the distribution.
+
+        Returns
+        -------
+        Distribution
+            An object representing a distribution.
+        """
         return cls(
             filename=data.filename,
             url=data.url,
@@ -31,7 +42,19 @@ class Release:
 
     @classmethod
     def from_json_api_data(cls: type[Self], data: JSONPackageMetadata) -> Self:
-        """Build an instance from the JSON API data."""
+        """
+        Build an instance from the JSON API data.
+
+        Parameters
+        ----------
+        data
+            The JSON API metadata for a package release.
+
+        Returns
+        -------
+        Release
+            An object representing a package release.
+        """
         return cls(
             version=data.info.version,
             distributions=[Distribution.from_json_api_data(json_api_data) for json_api_data in data.urls],
@@ -47,7 +70,19 @@ class Package:
 
     @classmethod
     def from_json_api_data(cls: type[Self], data: JSONPackageMetadata) -> Self:
-        """Build an instance from the JSON API data."""
+        """
+        Build an instance from the JSON API data.
+
+        Parameters
+        ----------
+        data
+            The JSON API metadata for a package.
+
+        Returns
+        -------
+        Package
+            An object representing a package.
+        """
         return cls(
             title=data.info.name,
             releases=[Release.from_json_api_data(data)],

src/letsbuilda/pypi/models/models_rss.py

@@ -20,7 +20,19 @@ class RSSPackageMetadata:
 
     @classmethod
     def build_from(cls: type[Self], data: dict[str, str]) -> Self:
-        """Build an instance from raw data."""
+        """
+        Build an instance from raw data.
+
+        Parameters
+        ----------
+        data
+            Parsed RSS data from PyPI's RSS API.
+
+        Returns
+        -------
+        RSSPackageMetadata
+            The pacckage metadata from the RSS API.
+        """
         split_title = data["title"].removesuffix(" added to PyPI").split()
         title = split_title[0]
         version = split_title[1] if len(split_title) == 2 else None  # noqa: PLR2004 - is not magic

src/letsbuilda/pypi/sync_client.py

@@ -20,7 +20,18 @@ def __init__(self: Self, http_client: Client) -> None:
         self.http_client = http_client
 
     def get_rss_feed(self: Self, feed_url: str) -> list[RSSPackageMetadata]:
-        """Get the new packages RSS feed."""
+        """Get the new packages RSS feed.
+
+        Parameters
+        ----------
+        feed_url
+            The URL of the RSS feed.
+
+        Returns
+        -------
+        list[RSSPackageMetadata]
+            The list of new packages.
+        """
         response_text = self.http_client.get(feed_url).text
         rss_data = xmltodict.parse(response_text)["rss"]["channel"]["item"]
         return [RSSPackageMetadata.build_from(package_data) for package_data in rss_data]
@@ -30,7 +41,26 @@ def get_package_json_metadata(
         package_title: str,
         package_version: str | None = None,
     ) -> JSONPackageMetadata:
-        """Get metadata for a package."""
+        """
+        Retrieve metadata for a package.
+
+        Raises
+        ------
+        PackageNotFoundError
+            If the package is not found.
+
+        Parameters
+        ----------
+        package_title
+            The title of the package.
+        package_version
+            The version of the package.
+
+        Returns
+        -------
+        JSONPackageMetadata
+            The metadata for the package.
+        """
         if package_version is not None:
             url = f"https://pypi.org/pypi/{package_title}/{package_version}/json"
         else:
@@ -45,5 +75,18 @@ def get_package_metadata(
         package_title: str,
         package_version: str | None = None,
     ) -> Package:
-        """Get metadata for a package."""
+        """Create a `Package` object from its metadata.
+
+        Parameters
+        ----------
+        package_title
+            The title of the package.
+        package_version
+            The version of the package.
+
+        Returns
+        -------
+        Package
+            The package object.
+        """
         return Package.from_json_api_data(self.get_package_json_metadata(package_title, package_version))