pynamer.utils
=============

.. py:module:: pynamer.utils

.. autoapi-nested-parse::

   Collection of package support utilities.



Functions
---------

.. autoapisummary::

   pynamer.utils.check_integrity
   pynamer.utils.reset
   pynamer.utils.feedback
   pynamer.utils.search_json
   pynamer.utils.find_pypirc_file
   pynamer.utils.generate_pypi_index
   pynamer.utils.check_version
   pynamer.utils.process_input_file
   pynamer.utils.write_output_file


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

.. py:function:: check_integrity() -> None

.. py:function:: reset() -> None

.. py:function:: feedback(message: str, feedback_type: str) -> None

   Generates a formatted messages appropriate to the message type.

   :param message: text to be echoed.
   :param feedback_type: identifies type of message to display.


.. py:function:: search_json(json_data: dict, project_name: str) -> str

   Searches a json data structure for a GitHub project URL.

   The json data is found from the PyPI json URL: "https://pypi.org/pypi/package_name".
   The function searches for the GitHub homepage URL:
    "https://github.com/{owner}/{package_name} and returns upon first match.

    Args:
        json_data:     json found from PyPI.
        project_name:  the package name under test.

   :returns: the GitHub homepage URL if found else an empty string.
   :rtype: str


.. py:function:: find_pypirc_file(filename: str = '.pypirc') -> None

   Function to iterate over paths in the PATH environment variable to find a file.

    Designed to find a .pypirc file starting with the current working directory.
    If identified will update the config.pypirc variable, so it can be used elsewhere.

   :param filename: filename to find.


.. py:function:: generate_pypi_index() -> None

   Generates a list of projects in PyPI's simple index - writes results to a file.

   :raises SystemExit: if any requests.RequestException occurs.

   .. rubric:: Notes

   A potentially expensive operation as there are almost 500,000 projects to
   process. Can take 2-3 seconds. Look to improve performance at a later date:
   look at asyncio, asyncio.http etc.
   An improvement is to automatically periodically run this in the background.


.. py:function:: check_version() -> None

   Utility function to compare package version against latest version on PyPI.

   :returns: version of the installed package.
             str:                message concerning the result of the comparison.
             bool:               True: if the installed package is up-to-date.
                                 False: if there is a newer version on PyPI.
   :rtype: current_version

   :raises SystemExit: if any requests.RequestException occurs.


.. py:function:: process_input_file(file: str) -> list[Union[str, Any]]

   Processes the contents of the file to a list of strings.

   :param file: simple string for the file.

   :raises SystemExit: if there is an error opening the file.

   .. rubric:: Notes

   File contents should contain any number of space separated strings on any
   number of lines.


.. py:function:: write_output_file(file_name: str, results: dict) -> None

   Write the results to a file.

   :param file_name: name of file to save as a simple string.
   :param results: dictionary containing the test results e.g.
                   {"pynball": [1, 1, 1]}

   :raises SystemExit: if there is an error opening the file.