aoc_mod.utilities
=================

.. py:module:: aoc_mod.utilities

.. autoapi-nested-parse::

   Utility functionality and AocMod class definitions



Attributes
----------

.. autoapisummary::

   aoc_mod.utilities.URL_PUZZLE_MAIN
   aoc_mod.utilities.URL_PUZZLE_INPUT
   aoc_mod.utilities.URL_PUZZLE_ANSWER


Exceptions
----------

.. autoapisummary::

   aoc_mod.utilities.AocModError


Classes
-------

.. autoapisummary::

   aoc_mod.utilities.AocMod


Functions
---------

.. autoapisummary::

   aoc_mod.utilities.get_year_and_day
   aoc_mod.utilities.parse_input


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

.. py:data:: URL_PUZZLE_MAIN
   :value: 'https://adventofcode.com/{YEAR}/day/{DAY}'


.. py:data:: URL_PUZZLE_INPUT
   :value: 'https://adventofcode.com/{YEAR}/day/{DAY}/input'


.. py:data:: URL_PUZZLE_ANSWER
   :value: 'https://adventofcode.com/{YEAR}/day/{DAY}/answer'


.. py:exception:: AocModError(msg)

   Bases: :py:obj:`Exception`


   General exception for an AOC_MOD library error


.. py:class:: AocMod(session_id: str = '')

   Main utility class for the AOC_MOD library


   .. py:attribute:: curr_time


   .. py:attribute:: user_agent
      :value: 'https://github.com/cosmos1255/aoc_mod by cosmos1255'



   .. py:attribute:: _cache_file


   .. py:attribute:: _cache_data


   .. py:attribute:: _time_to_wait_after_pull
      :value: 120



   .. py:method:: _get_auth_data() -> str

      will return the SESSION_ID environment variable, if set

      :return: the SESSION_ID env variable or empty string
      :rtype: str



   .. py:method:: _get_current_time() -> time.struct_time

      get current local time

      :return: current local time
      :rtype: time.struct_time



   .. py:method:: _get_cache_data() -> dict

      get the cache data from the cache file

      :return: the cache data as a dictionary
      :rtype: dict



   .. py:method:: _set_cache_data(cache_data: dict) -> None

      set the cache data in the cache file

      :param cache_data: the cache data to set
      :type cache_data: dict



   .. py:method:: _is_request_timed_out(last_pull_time: float) -> tuple[bool, int]

      check if the last pull time is within the timeout period

      :param last_pull_time: the time of the last pull in seconds since epoch
      :type last_pull_time: float
      :return: a tuple of (is_timed_out, timed_out_seconds_left) where is_timed_out is a boolean indicating
          if the request is timed out and timed_out_seconds_left is the number of seconds left until the timeout expires
      :rtype: tuple[bool, int]



   .. py:method:: get_puzzle_instructions(year: int, day: int) -> str

      get puzzle instructions for the entered (or current) year and day

      :param year: year of AoC puzzle, defaults to current
      :type year: int
      :param day: day of AoC puzzle, defaults to current
      :type day: int
      :raises AocModError: exception if we http request throws an error
      :return: markdownify output string of puzzle instructions
      :rtype: str



   .. py:method:: get_puzzle_input(year: int = 0, day: int = 0) -> str

      get puzzle input for specified year and day

      :param year: yeah of the puzzle, defaults to 0
      :type year: int, optional
      :param day: day of the puzzle, defaults to 0
      :type day: int, optional
      :raises AocModError: will raise for http request error or a
          request exception
      :return: the puzzle input as a string
      :rtype: str



   .. py:method:: submit_answer(year: int, day: int, level: int, answer: int) -> str

      submit puzzle answer for the year, day and level (part)

      :param year: year of the puzzle
      :type year: int
      :param day: day of the puzzle
      :type day: int
      :param level: puzzle level or part (either 1 or 2)
      :type level: int
      :param answer: the answer to be submitted
      :type answer: int
      :raises AocModError: will raise for http request error or a
          request exception
      :return: the result from the http post request
      :rtype: str



.. py:function:: get_year_and_day(filepath: pathlib.Path) -> tuple[int, int]

   utility function to get current year and day from the
   path to this file

   :param filepath: path to this file
   :type filepath: Path
   :return: a tuple with (year, day) as int values. will return (0, 0) on a failure
   :rtype: tuple[int, int]


.. py:function:: parse_input(input_path: pathlib.Path) -> list[str]

   utility function to read in puzzle input and
   place it into a list of str values

   :param input_path: path to the input file
   :type input_path: Path
   :return: a list of strings representing the input
   :rtype: list[str]