pynamer.validators
==================

.. py:module:: pynamer.validators

.. autoapi-nested-parse::

   Collection of functions to test availability of a package name on PyPI



Functions
---------

.. autoapisummary::

   pynamer.validators.is_valid_package_name
   pynamer.validators.get_homepage
   pynamer.validators.github_meta
   pynamer.validators.ping_project
   pynamer.validators.ping_json
   pynamer.validators.pypi_search_index
   pynamer.validators.pypi_search
   pynamer.validators.final_analysis


Module Contents
---------------

.. py:function:: is_valid_package_name(project_name: str) -> bool

   Function does a basic check of project name validity.

   :param project_name: the name of the project to test.

   :returns: If the name passes the basic check
             False:          If the name fails the basic check
   :rtype: True


.. py:function:: get_homepage(project_json: dict, project_name: str) -> tuple[str, str]

   Finds the GitHub homepage from the PyPI json data.

   With this function we are trying to ultimately find the GitHub 'homepage':
   https://github.com/{username}/{project_name}.
   Unfortunately not everyone agrees what the homepage should be. Some people for
   example use 'readthedocs' or 'github.io' etc.

   :param project_json: json data from PyPI json URL.
   :param project_name: package name under test.

   :returns: strings containing found homepage URL.
   :rtype: tuple[str, str]


.. py:function:: github_meta(url: str) -> str

   Finds GitHub statistics given a GitHub Homepage URL.

   :param url: GitHub homepage URL.

   :returns: a string containing all the pertinent statistics:
   :rtype: str


.. py:function:: ping_project(project_name: str) -> bool

   Determines if the URL to the project exists in PyPIs project area.

   :param project_name: the name of the project to test.

   :returns: if the URLs response code is 200.
             False:          if the URLs response code is not 200.
   :rtype: True

   :raises SystemExit: if any requests.RequestException occurs.


.. py:function:: ping_json(project_name: str, stats: bool = False) -> str

   Collects some PyPI details about the project if it exists.

   :param project_name: the name of the project to test.
   :param stats: display stats from github json url.

   :raises SystemExit: if any requests.RequestException occurs.


.. py:function:: pypi_search_index(project_name: str) -> bool

   Open the generated index file and search for the project name.

   :param project_name: the name of the project currently under test.

   :returns: a match was found.
             False:          a match was not found.
   :rtype: True


.. py:function:: pypi_search(search_project: str) -> tuple[list[list[Union[str, Any]]], list[list[Union[str, Any]]], str]

   Performs a get request to PyPI's search API for the project name.

   :param search_project: the name of the project currently under test.

   :returns:

             a list of projects matching name comprising:
                                 [project_name, version, released, description]
             others:         a list of projects not matching but PyPI thinks are relevant.
                                 [project_name, version, released, description]
             others_total:   a str representation of total projects found (minus matches).
   :rtype: match


.. py:function:: final_analysis(pattern: list[int]) -> None

   Displays a rich console table displaying the conclusion of the test results

   :param pattern: a list of the test results:
                   1 - a 'negative' result, indicating the project has been found.
                   0 - a 'positive' result, indicating the project was not found.