.. bbss.py documentation master file, created by
   sphinx-quickstart on Tue Dec  5 20:26:05 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. role:: python(code)
   :language: python

=======
bbss.py
=======

For more information on BBSS itself, look `here <https://forum.melonland.net/index.php?topic=2047.0>`_.
This is a simple python module to allow for quickly scraping or exploring BBSS directories on sites.

bbss.site
=========

.. py:module:: bbss.site

   .. py:class:: Site(domain, path, *, scheme = 'https')

      A representation of some BBSS directory. On construction, all information about an individual site
      is downloaded.

      :param str domain: The domain to check for BBSS files

      :param path: An optional subdirectory to treat as the root of the BBSS directory
      :type path: str or None
      :param scheme: What protocol to download over
      :type scheme: 'http' | 'https'

      .. py:attribute:: default_path
         :type: bool

         Whether the site was generated from a default directory, or a user-supplied one

      .. py:attribute:: root
         :type: str

         The base URL of the BBSS directory

      .. py:attribute:: has_sizes_txt
         :type: bool

         Whether the BBSS directory contains a ``sizes.txt`` file

      .. py:attribute:: sizes
         :type: bbss.sizes.SizeListFile

         A list of the sizes found at the site

      .. py:attribute:: friends
         :type: Optional[bbss.friends.FriendListFile]

         A list of friend sites found at the site

     .. doctest::

       >>> site = bbss.site.Site('aleteoryx.me')
       >>> for size in site.sizes:
       ...   print(f"{size.entry} @ {size.url()}")
       ...   if size.exists():
       ...     for button in size.get():
       ...       print(f"===> {button.entry} @ {button.url()}")
       ...   else:
       ...     print("...doesn't seem to exist!")
       ...
       88x31 @ https://aleteoryx.me/BBSS/88x31/list.txt
       ===> ame.gif @ https://aleteoryx.me/BBSS/88x31/ame.gif
       ===> amev2.gif @ https://aleteoryx.me/BBSS/88x31/amev2.gif

bbss.lists
==========

.. py:module:: bbss.lists

   .. py:function:: parse_listfile[T](contents, ctor)

      Parses in the text of a listfile, and calls the passed constructor
      function repeatedly to generate datastructures.

      :param str contents: The contents of the listfile
      :param ctor: The constructor for the internal datastructures
      :type ctor: (str, str or None) -> T
      :return: A list of T, containing the contents of the file
      :rtype: list[T]

      .. doctest::

         >>> listfile = """
         ... entry 1
         ... ## this is a comment on entry two
         ... entry 2
         ... # omitted
         ... entry 3
         ... ## trailing comments are ignored
         ... """
         >>> bbss.lists.parse_listfile(listfile, lambda x, y: (x, y))
         [('entry 1', None), ('entry 2', 'this is a comment on entry two'), ('entry 3', None)]

   .. py:class:: ListFileEntry(entry, comment)

      The base class for all listfile entries

      :param str entry: The main content of the entry
      :param comment: The comment, if present
      :type comment: str or None

   .. py:class:: BaseListFile(contents)

      The base class for all listfile representations

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``.

         :param str url: The URL to download from.
         :return: A representation of the remote file, if available
         :rtype: BaseListFile | None

   .. py:class:: ListFile(contents)

      A representation of an arbitrary listfile

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. doctest::

         >>> contents = """
         ... entry 1
         ... ## this is a comment on entry two
         ... entry 2
         ... # omitted
         ... entry 3
         ... ## trailing comments are ignored
         ... """
         >>> listfile = bbss.lists.ListFile(contents)
         >>> for entry in listfile:
         ...   print(">", entry.entry)
         ...   if entry.comment is not None:
         ...     print(f"  ``{entry.comment}''")
         ...
         > entry 1
         > entry 2
           ``this is a comment on entry two''
         > entry 3

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``.

         :param str url: The URL to download from.
         :return: A representation of the remote file, if available
         :rtype: BaseListFile | None

bbss.buttons
============

.. py:module:: bbss.buttons

   .. py:class:: ButtonListFileEntry(entry, comment, root)

      A representation of a button image

      :param str entry: The button's filename
      :param comment: The comment for this button
      :type comment: str or None
      :param str root: The URL that this button is a child of

      .. py:method:: url()

         :return: The URL of the button file
         :rtype: str

      .. py:method:: exists()

         :return: Whether the button actually exists on the server
         :rtype: bool

      .. py:method:: get()

         :return: The HTTP response from trying to ``GET`` the button
         :rtype: requests.Response

   .. py:class:: ButtonListFile(contents)

      A representation of a list of buttons

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``.

         :param str url: The URL to download from.
         :return: A representation of the remote button list, if available
         :rtype: ButtonListFile | None

         .. doctest::

            >>> buttons = bbss.buttons.ButtonListFile \
            ...             .from_url("https://aleteoryx.me/BBSS/88x31/list.txt")
            >>> for button in buttons:
            ...   print(button.url())
            ...
            https://aleteoryx.me/BBSS/88x31/ame.gif
            https://aleteoryx.me/BBSS/88x31/amev2.gif

bbss.sizes
============

.. py:module:: bbss.sizes

   .. py:class:: SizeListFileEntry(entry, comment, root)

      A representation of a given size for buttons

      :param str entry: The actual size
      :param comment: The comment for this size
      :type comment: str or None
      :param str root: The BBSS directory that this size is within

      .. py:method:: url()

         :return: The URL of the size's button list
         :rtype: str

      .. py:method:: exists()

         :return: Whether the size's button list file exists
         :rtype: bool

      .. py:method:: get()

         :return: The actual button list, if available
         :rtype: bbss.buttons.ButtonListFile

      .. py:method:: dims()

         :return: The dimensions of the size, ``(x, y)``, if they can be parsed from the name
         :rtype: (int, int) or None

   .. py:class:: SizeListFile(contents)

      A representation of a list of button sizes

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``

         :param str url: The URL to download from.
         :return: A representation of the remote size list, if available
         :rtype: ButtonListFile | None

bbss.friends
============

.. py:module:: bbss.friends

   .. py:class:: FriendListFileEntry(entry, comment)

      A representation of a friend site

      :param str entry: The actual size
      :param comment: The comment for this size
      :type comment: str or None

      .. py:attribute:: url
         :type: str

         The URL of the size's button list

      .. py:attribute:: domain
         :type: str

         The domain of the friend site

      .. py:attribute:: scheme
         :type: str

         The scheme of the friend site

      .. py:attribute:: path
         :type: str

         The optional path of the remote BBSS directory

      .. py:method:: exists()

         :return: Whether the size's button list file exists
         :rtype: bool

      .. py:method:: get()

         :return: The remote site
         :rtype: bbss.site.Size

   .. py:class:: FriendListFile(contents)

      A representation of a list of friend sites

      It supports all the :py:class:`collections.abc.Sequence` operations, meaning it can be used like a list in most cases.

      :param str contents: The contents of the source listfile

      .. py:classmethod:: from_url(url)

         Alternate constructor, which will attempt to download the listfile at ``url``

         :param str url: The URL to download from.
         :return: A representation of the remote friend list, if available
         :rtype: ButtonListFile | None

==================
Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`